Commits

dirkbaechle committed 24aaa3c

- removed suffix= from 'scons_output_command ' and moved it
one up in the hierarchy to the 'scons_output' tag

Comments (0)

Files changed (40)

 #!/usr/bin/env python
 #
+# Copyright (c) 2010 The SCons Foundation
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+#
 # Module for handling SCons documentation processing.
 #
 
 
     <builder name="BUILDER">
     <summary>
-    This is the summary description of an SCons Builder.
+    <para>This is the summary description of an SCons Builder.
     It will get placed in the man page,
     and in the appropriate User's Guide appendix.
     The name of any builder may be interpolated
     anywhere in the document by specifying the
-    &b-BUILDER;
-    element.  It need not be on a line by itself.
+    &b-BUILDER; element.  It need not be on a line by itself.</para>
 
     Unlike normal XML, blank lines are significant in these
     descriptions and serve to separate paragraphs.
     (arg1, arg2, key=value)
     </arguments>
     <summary>
-    This is the summary description of an SCons function.
+    <para>This is the summary description of an SCons function.
     It will get placed in the man page,
     and in the appropriate User's Guide appendix.
     The name of any builder may be interpolated
     anywhere in the document by specifying the
-    &f-FUNCTION;
-    element.  It need not be on a line by itself.
-
-    Unlike normal XML, blank lines are significant in these
-    descriptions and serve to separate paragraphs.
-    They'll get replaced in DocBook output with appropriate tags
-    to indicate a new paragraph.
+    &f-FUNCTION; element.  It need not be on a line by itself.</para>
 
     <example>
     print "this is example code, it will be offset and indented"
 
     <cvar name="VARIABLE">
     <summary>
-    This is the summary description of a construction variable.
+    <para>This is the summary description of a construction variable.
     It will get placed in the man page,
     and in the appropriate User's Guide appendix.
     The name of any construction variable may be interpolated
     anywhere in the document by specifying the
-    &t-VARIABLE;
-    element.  It need not be on a line by itself.
-
-    Unlike normal XML, blank lines are significant in these
-    descriptions and serve to separate paragraphs.
-    They'll get replaced in DocBook output with appropriate tags
-    to indicate a new paragraph.
+    &t-VARIABLE; element.  It need not be on a line by itself.</para>
 
     <example>
     print "this is example code, it will be offset and indented"
 
     <tool name="TOOL">
     <summary>
-    This is the summary description of an SCons Tool.
+    <para>This is the summary description of an SCons Tool.
     It will get placed in the man page,
     and in the appropriate User's Guide appendix.
     The name of any tool may be interpolated
     anywhere in the document by specifying the
-    &t-TOOL;
-    element.  It need not be on a line by itself.
-
-    Unlike normal XML, blank lines are significant in these
-    descriptions and serve to separate paragraphs.
-    They'll get replaced in DocBook output with appropriate tags
-    to indicate a new paragraph.
+    &t-TOOL; element. It need not be on a line by itself.</para>
 
     <example>
     print "this is example code, it will be offset and indented"
         f = open(fpath,'r')
         content = f.read()
         f.close()
-        if content.find(dbxsd) >= 0:
+        if content.find('xmlns="%s"' % dbxsd) >= 0:
             return True
     except:
         pass
         
         def newNode(self, tag):
             return etree.Element(tag)
+
+        def newEtreeNode(self, tag, init_ns=False):
+            if init_ns:
+                NSMAP = {None: dbxsd,
+                         'xsi' : xsi}
+                return etree.Element(tag, nsmap=NSMAP)
+
+            return etree.Element(tag)
         
         def copyNode(self, node):
             return copy.deepcopy(node)
                                     encoding="UTF-8", pretty_print=True, 
                                     doctype=dt.createDoctype()))
 
+        def writeTree(self, root, fpath):
+            fp = open(fpath, 'w')
+            fp.write(etree.tostring(root, xml_declaration=True, 
+                                    encoding="UTF-8", pretty_print=True))            
+            fp.close()
+
         def prettyPrintFile(self, fpath):
             fin = open(fpath,'r')
             tree = etree.parse(fin)
             fout = open(fpath,'w')
             fout.write(pretty_content)
             fout.close()
+
+        def decorateWithCommentHeader(self, root, comment=generated_comment):
+            root.attrib["{"+xsi+"}schemaLocation"] = "%s scons.xsd" % dbxsd
+            
+            c = etree.Comment(comment)
+            root.insert(0, c)
+            
+            return root
             
         def newXmlTree(self, root, comment=generated_comment):
             """ Return a XML file tree with the correct namespaces set,
             """
             NSMAP = {None: dbxsd,
                      'xsi' : xsi}
-        
-            t = etree.Element(root,
-                              nsmap = NSMAP,
-                              attrib = {"{"+xsi+"}schemaLocation" : "%s scons.xsd" % dbxsd})
-        
-            c = etree.Comment(comment)
-            t.append(c)
-        
-            return t
+            t = etree.Element(root, nsmap=NSMAP)
+            return self.decorateWithCommentHeader(t, comment)
         
         def validateXml(self, fpath, xmlschema_context):
             # Use lxml
                 expression = "./%s/*" % tag
             return root.findall(expression)
 
+        def convertElementTree(self, root):
+            """ Convert the given tree of etree.Element
+                entries to a list of tree nodes for the
+                current XML toolkit.
+            """
+            return [root]
+        
 else:        
     class TreeFactory:
         def __init__(self):
         
         def newNode(self, tag):
             return libxml2.newNode(tag)
+
+        def newEtreeNode(self, tag, init_ns=False):
+            return etree.Element(tag)
         
         def copyNode(self, node):
             return node.copyNode(1)
             fp.write(content)
             doc.freeDoc()
 
+        def writeTree(self, root, fpath):
+            fp = open(fpath, 'w')
+            doc = libxml2.newDoc('1.0')
+            doc.setRootElement(root)
+            fp.write(doc.serialize("UTF-8", 1))
+            doc.freeDoc()
+            fp.close()
+
         def prettyPrintFile(self, fpath):
             # Read file and resolve entities
             doc = libxml2.readFile(fpath, None, libxml2d.XML_PARSE_NOENT)
             # Cleanup
             doc.freeDoc()
 
+        def decorateWithCommentHeader(self, root, comment=generated_comment):
+            # Register the namespaces
+            ns = root.newNs(dbxsd, None)
+            xi = root.newNs(xsi, 'xsi')
+            root.setNs(ns)  #put this node in the target namespace
+    
+            root.setNsProp(xi, 'schemaLocation', "%s scons.xsd" % dbxsd)
+        
+            c = libxml2.newComment(comment)
+            root.addChild(c)
+            
+            return root
+
         def newXmlTree(self, root, comment=generated_comment):
             """ Return a XML file tree with the correct namespaces set,
                 the element root as top entry and the given header comment.
             """
             t = libxml2.newNode(root)
-            # Register the namespaces
-            ns = t.newNs(dbxsd, None)
-            xi = t.newNs(xsi, 'xsi')
-            t.setNs(ns)  #put this node in the target namespace
-    
-            t.setNsProp(xi, 'schemaLocation', "%s scons.xsd" % dbxsd)
-        
-            c = libxml2.newComment(comment)
-            t.addChild(c)
-        
-            return t
+            return self.decorateWithCommentHeader(t, comment)
 
         def validateXml(self, fpath, xmlschema_context):
             # Create validation context
                     expression = "./%s/node()" % tag
                 return root.findall(expression)
 
+        def expandChildElements(self, child):
+            """ Helper function for convertElementTree,
+                converts a single child recursively.
+            """
+            nchild = self.newNode(child.tag)
+            # Copy attributes
+            for key, val in child.attrib:
+                self.setAttribute(nchild, key, val)
+            elements = []
+            # Add text
+            if child.text:
+                t = libxml2.newText(child.text)
+                self.appendNode(nchild, t)
+            # Add children
+            for c in child:
+                for n in self.expandChildElements(c):
+                    self.appendNode(nchild, n)
+            elements.append(nchild)
+            # Add tail
+            if child.tail:
+                tail = libxml2.newText(child.tail)
+                elements.append(tail)
+                
+            return elements
+
+        def convertElementTree(self, root):
+            """ Convert the given tree of etree.Element
+                entries to a list of tree nodes for the
+                current XML toolkit.
+            """
+            nroot = self.newNode(root.tag)
+            # Copy attributes
+            for key, val in root.attrib:
+                self.setAttribute(nroot, key, val)
+            elements = []
+            # Add text
+            if root.text:
+                t = libxml2.newText(root.text)
+                self.appendNode(nroot, t)
+            # Add children
+            for c in root:
+                for n in self.expandChildElements(c):
+                    self.appendNode(nroot, n)
+            elements.append(nroot)
+            # Add tail
+            if root.tail:
+                tail = libxml2.newText(root.tail)
+                elements.append(tail)
+                
+            return elements
 
 tf = TreeFactory()
 

bin/SConsExamples.py

 #!/usr/bin/env python
 #
-# Module for handling SCons examples processing.
+# Copyright (c) 2010 The SCons Foundation
 #
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-__doc__ = """
-"""
+#
+#
+# This script looks for some XML tags that describe SCons example
+# configurations and commands to execute in those configurations, and
+# uses TestCmd.py to execute the commands and insert the output from
+# those commands into the XML that we output.  This way, we can run a
+# script and update all of our example documentation output without
+# a lot of laborious by-hand checking.
+#
+# An "SCons example" looks like this, and essentially describes a set of
+# input files (program source files as well as SConscript files):
+#
+#       <scons_example name="ex1">
+#         <file name="SConstruct" printme="1">
+#           env = Environment()
+#           env.Program('foo')
+#         </file>
+#         <file name="foo.c">
+#           int main() { printf("foo.c\n"); }
+#         </file>
+#       </scons_example>
+#
+# The <file> contents within the <scons_example> tag will get written
+# into a temporary directory whenever example output needs to be
+# generated.  By default, the <file> contents are not inserted into text
+# directly, unless you set the "printme" attribute on one or more files,
+# in which case they will get inserted within a <programlisting> tag.
+# This makes it easy to define the example at the appropriate
+# point in the text where you intend to show the SConstruct file.
+#
+# Note that you should usually give the <scons_example> a "name"
+# attribute so that you can refer to the example configuration later to
+# run SCons and generate output.
+#
+# If you just want to show a file's contents without worry about running
+# SCons, there's a shorter <sconstruct> tag:
+#
+#       <sconstruct>
+#         env = Environment()
+#         env.Program('foo')
+#       </sconstruct>
+#
+# This is essentially equivalent to <scons_example><file printme="1">,
+# but it's more straightforward.
+#
+# SCons output is generated from the following sort of tag:
+#
+#       <scons_output example="ex1" os="posix">
+#         <scons_output_command suffix="1">scons -Q foo</scons_output_command>
+#         <scons_output_command suffix="2">scons -Q foo</scons_output_command>
+#       </scons_output>
+#
+# You tell it which example to use with the "example" attribute, and then
+# give it a list of <scons_output_command> tags to execute.  You can also
+# supply an "os" tag, which specifies the type of operating system this
+# example is intended to show; if you omit this, default value is "posix".
+#
+# The generated XML will show the command line (with the appropriate
+# command-line prompt for the operating system), execute the command in
+# a temporary directory with the example files, capture the standard
+# output from SCons, and insert it into the text as appropriate.
+# Error output gets passed through to your error output so you
+# can see if there are any problems executing the command.
+#
 
 import os
 import re
+import sys
+import time
+
 import SConsDoc
 from SConsDoc import tf as stf
 
 
 class ExampleCommand:
     def __init__(self):
-        self.edit = ''
+        self.edit = None
         self.environment = ''
         self.output = ''
         self.cmd = ''
-        self.suffix = ''
 
 class ExampleOutput:
     def __init__(self):
         self.name = ''
         self.tools = ''
-        self.os = ''
+        self.os = 'posix'
+        self.preserve = None
+        self.suffix = ''
         self.commands = []
         
 class ExampleInfo:
             eout.tools = stf.getAttribute(o, 'tools')
         if stf.hasAttribute(o, 'os'):
             eout.os = stf.getAttribute(o, 'os')
+        if stf.hasAttribute(o, 'suffix'):
+            eout.suffix = stf.getAttribute(o, 'suffix')
 
         for c in stf.findAll(o, "scons_output_command", SConsDoc.dbxid, 
                          t.xpath_context, t.nsmap):
-            if stf.hasAttribute(c, 'suffix'):
-                s = stf.getAttribute(c, 'suffix')
-            else:
-                continue
-
             oc = ExampleCommand()
-            oc.suffix = s
             if stf.hasAttribute(c, 'edit'):
                 oc.edit = stf.getAttribute(c, 'edit')
             if stf.hasAttribute(c, 'environment'):
                 oc.output = stf.getAttribute(c, 'output')
             if stf.hasAttribute(c, 'cmd'):
                 oc.cmd = stf.getAttribute(c, 'cmd')
+            else:
+                oc.cmd = stf.getText(c)
 
             eout.commands.append(oc)
 
     for key, value in examples.iteritems():
         # Process all scons_output tags
         for o in value.outputs:
-            for c in o.commands:
-                cpath = os.path.join(generated_examples, 
-                                     key+'_'+c.suffix+'.out')
-                if not os.path.isfile(cpath):
-                    content = c.output
-                    if not content:
-                        content = "NO OUTPUT YET! Run the script to generate/update all examples."
-
-                    f = open(cpath, 'w')
-                    f.write("%s\n" % content)
-                    f.close()
+            cpath = os.path.join(generated_examples, 
+                                 key+'_'+o.suffix+'.xml')
+            if not os.path.isfile(cpath):
+                # Start new XML file
+                s = stf.newXmlTree("screen")
+                stf.setText(s, "NO OUTPUT YET! Run the script to generate/update all examples.")
+                # Write file
+                stf.writeTree(s, cpath)
+                
         # Process all scons_example_file tags
         for r in value.files:
             if r.isFileRef():
                 f.write("%s\n" % content)
                 f.close()
 
+perc = "%"
+
+def createAllExampleOutputs(dpath):
+    """ Scan for XML files in the given directory and 
+        creates all output files for every example in
+        the 'generated/examples' folder.
+    """
+    # Ensure that the output folder exists
+    if not os.path.isdir(generated_examples):
+        os.mkdir(generated_examples)
+        
+    examples = readAllExampleInfos(dpath)
+    total = len(examples)
+    idx = 0
+    for key, value in examples.iteritems():
+        # Process all scons_output tags
+        print "%.2f%s (%d/%d) %s" % (float(idx+1)*100.0/float(total),
+                                     perc, idx+1, total, key)
+        
+        create_scons_output(value)
+        # Process all scons_example_file tags
+        for r in value.files:
+            if r.isFileRef():
+                # Get file's content
+                content = value.getFileContents(r.name)
+                fpath = os.path.join(generated_examples, 
+                                     key+'_'+r.name.replace("/","_"))
+                # Write file
+                f = open(fpath, 'w')
+                f.write("%s\n" % content)
+                f.close()
+        idx += 1
+
 def collectSConsExampleNames(fpath):
     """ Return a set() of example names, used in the given file fpath.
     """
             failed_suffixes = True
             continue
             
-        for c in stf.findAll(o, "scons_output_command", SConsDoc.dbxid, 
-                         t.xpath_context, t.nsmap):
-            s = ''
-            if stf.hasAttribute(c, 'suffix'):
-                s = stf.getAttribute(c, 'suffix')
-            else:
-                print "Error: scons_output_command in file '%s' (example '%s') is missing a suffix!" % (fpath, n)
-                failed_suffixes = True
-            
-            if s not in suffixes[n]:
-                suffixes[n].append(s)
-            else:
-                print "Error: scons_output_command in file '%s' (example '%s') is using a duplicate suffix '%s'!" % (fpath, n, s)
-                failed_suffixes = True
+        s = ''
+        if stf.hasAttribute(o, 'suffix'):
+            s = stf.getAttribute(o, 'suffix')
+        else:
+            print "Error: scons_output in file '%s' (example '%s') is missing a suffix!" % (fpath, n)
+            failed_suffixes = True
+        
+        if s not in suffixes[n]:
+            suffixes[n].append(s)
+        else:
+            print "Error: scons_output in file '%s' (example '%s') is using a duplicate suffix '%s'!" % (fpath, n, s)
+            failed_suffixes = True
     
     return names, failed_suffixes
 
                    
     return unique
 
+################################################################
+#
+# In the second half of this module (starting here)
+# we define the variables and functions that are required
+# to actually run the examples, collect their output and
+# write it into the files in doc/generated/examples...
+# which then get included by our UserGuide.
+#
+################################################################
+
+sys.path.append(os.path.join(os.getcwd(), 'QMTest'))
+sys.path.append(os.path.join(os.getcwd(), 'build', 'QMTest'))
+
+scons_py = os.path.join('bootstrap', 'src', 'script', 'scons.py')
+if not os.path.exists(scons_py):
+    scons_py = os.path.join('src', 'script', 'scons.py')
+
+scons_lib_dir = os.path.join(os.getcwd(), 'bootstrap', 'src', 'engine')
+if not os.path.exists(scons_lib_dir):
+    scons_lib_dir = os.path.join(os.getcwd(), 'src', 'engine')
+
+os.environ['SCONS_LIB_DIR'] = scons_lib_dir
+
+import TestCmd
+
+Prompt = {
+    'posix' : '% ',
+    'win32' : 'C:\\>'
+}
+
+# The magick SCons hackery that makes this work.
+#
+# So that our examples can still use the default SConstruct file, we
+# actually feed the following into SCons via stdin and then have it
+# SConscript() the SConstruct file.  This stdin wrapper creates a set
+# of ToolSurrogates for the tools for the appropriate platform.  These
+# Surrogates print output like the real tools and behave like them
+# without actually having to be on the right platform or have the right
+# tool installed.
+#
+# The upshot:  The wrapper transparently changes the world out from
+# under the top-level SConstruct file in an example just so we can get
+# the command output.
+
+Stdin = """\
+import os
+import re
+import SCons.Action
+import SCons.Defaults
+import SCons.Node.FS
+
+platform = '%(osname)s'
+
+Sep = {
+    'posix' : '/',
+    'win32' : '\\\\',
+}[platform]
+
+
+#  Slip our own __str__() method into the EntryProxy class used to expand
+#  $TARGET{S} and $SOURCE{S} to translate the path-name separators from
+#  what's appropriate for the system we're running on to what's appropriate
+#  for the example system.
+orig = SCons.Node.FS.EntryProxy
+class MyEntryProxy(orig):
+    def __str__(self):
+        return str(self._subject).replace(os.sep, Sep)
+SCons.Node.FS.EntryProxy = MyEntryProxy
+
+# Slip our own RDirs() method into the Node.FS.File class so that the
+# expansions of $_{CPPINC,F77INC,LIBDIR}FLAGS will have the path-name
+# separators translated from what's appropriate for the system we're
+# running on to what's appropriate for the example system.
+orig_RDirs = SCons.Node.FS.File.RDirs
+def my_RDirs(self, pathlist, orig_RDirs=orig_RDirs):
+    return [str(x).replace(os.sep, Sep) for x in orig_RDirs(self, pathlist)]
+SCons.Node.FS.File.RDirs = my_RDirs
+
+class Curry(object):
+    def __init__(self, fun, *args, **kwargs):
+        self.fun = fun
+        self.pending = args[:]
+        self.kwargs = kwargs.copy()
+
+    def __call__(self, *args, **kwargs):
+        if kwargs and self.kwargs:
+            kw = self.kwargs.copy()
+            kw.update(kwargs)
+        else:
+            kw = kwargs or self.kwargs
+
+        return self.fun(*self.pending + args, **kw)
+
+def Str(target, source, env, cmd=""):
+    result = []
+    for cmd in env.subst_list(cmd, target=target, source=source):
+        result.append(' '.join(map(str, cmd)))
+    return '\\n'.join(result)
+
+class ToolSurrogate(object):
+    def __init__(self, tool, variable, func, varlist):
+        self.tool = tool
+        if not isinstance(variable, list):
+            variable = [variable]
+        self.variable = variable
+        self.func = func
+        self.varlist = varlist
+    def __call__(self, env):
+        t = Tool(self.tool)
+        t.generate(env)
+        for v in self.variable:
+            orig = env[v]
+            try:
+                strfunction = orig.strfunction
+            except AttributeError:
+                strfunction = Curry(Str, cmd=orig)
+            # Don't call Action() through its global function name, because
+            # that leads to infinite recursion in trying to initialize the
+            # Default Environment.
+            env[v] = SCons.Action.Action(self.func,
+                                         strfunction=strfunction,
+                                         varlist=self.varlist)
+    def __repr__(self):
+        # This is for the benefit of printing the 'TOOLS'
+        # variable through env.Dump().
+        return repr(self.tool)
+
+def Null(target, source, env):
+    pass
+
+def Cat(target, source, env):
+    target = str(target[0])
+    f = open(target, "wb")
+    for src in map(str, source):
+        f.write(open(src, "rb").read())
+    f.close()
+
+def CCCom(target, source, env):
+    target = str(target[0])
+    fp = open(target, "wb")
+    def process(source_file, fp=fp):
+        for line in open(source_file, "rb").readlines():
+            m = re.match(r'#include\s[<"]([^<"]+)[>"]', line)
+            if m:
+                include = m.group(1)
+                for d in [str(env.Dir('$CPPPATH')), '.']:
+                    f = os.path.join(d, include)
+                    if os.path.exists(f):
+                        process(f)
+                        break
+            elif line[:11] != "STRIP CCCOM":
+                fp.write(line)
+    for src in map(str, source):
+        process(src)
+        fp.write('debug = ' + ARGUMENTS.get('debug', '0') + '\\n')
+    fp.close()
+
+public_class_re = re.compile('^public class (\S+)', re.MULTILINE)
+
+def JavaCCom(target, source, env):
+    # This is a fake Java compiler that just looks for
+    #   public class FooBar
+    # lines in the source file(s) and spits those out
+    # to .class files named after the class.
+    tlist = list(map(str, target))
+    not_copied = {}
+    for t in tlist:
+       not_copied[t] = 1
+    for src in map(str, source):
+        contents = open(src, "rb").read()
+        classes = public_class_re.findall(contents)
+        for c in classes:
+            for t in [x for x in tlist if x.find(c) != -1]:
+                open(t, "wb").write(contents)
+                del not_copied[t]
+    for t in not_copied.keys():
+        open(t, "wb").write("\\n")
+
+def JavaHCom(target, source, env):
+    tlist = map(str, target)
+    slist = map(str, source)
+    for t, s in zip(tlist, slist):
+        open(t, "wb").write(open(s, "rb").read())
+
+def JarCom(target, source, env):
+    target = str(target[0])
+    class_files = []
+    for src in map(str, source):
+        for dirpath, dirnames, filenames in os.walk(src):
+            class_files.extend([ os.path.join(dirpath, f)
+                                 for f in filenames if f.endswith('.class') ])
+    f = open(target, "wb")
+    for cf in class_files:
+        f.write(open(cf, "rb").read())
+    f.close()
+
+# XXX Adding COLOR, COLORS and PACKAGE to the 'cc' varlist(s) by hand
+# here is bogus.  It's for the benefit of doc/user/command-line.in, which
+# uses examples that want  to rebuild based on changes to these variables.
+# It would be better to figure out a way to do it based on the content of
+# the generated command-line, or else find a way to let the example markup
+# language in doc/user/command-line.in tell this script what variables to
+# add, but that's more difficult than I want to figure out how to do right
+# now, so let's just use the simple brute force approach for the moment.
+
+ToolList = {
+    'posix' :   [('cc', ['CCCOM', 'SHCCCOM'], CCCom, ['CCFLAGS', 'CPPDEFINES', 'COLOR', 'COLORS', 'PACKAGE']),
+                 ('link', ['LINKCOM', 'SHLINKCOM'], Cat, []),
+                 ('ar', ['ARCOM', 'RANLIBCOM'], Cat, []),
+                 ('tar', 'TARCOM', Null, []),
+                 ('zip', 'ZIPCOM', Null, []),
+                 ('BitKeeper', 'BITKEEPERCOM', Cat, []),
+                 ('CVS', 'CVSCOM', Cat, []),
+                 ('RCS', 'RCS_COCOM', Cat, []),
+                 ('SCCS', 'SCCSCOM', Cat, []),
+                 ('javac', 'JAVACCOM', JavaCCom, []),
+                 ('javah', 'JAVAHCOM', JavaHCom, []),
+                 ('jar', 'JARCOM', JarCom, []),
+                 ('rmic', 'RMICCOM', Cat, []),
+                ],
+    'win32' :   [('msvc', ['CCCOM', 'SHCCCOM', 'RCCOM'], CCCom, ['CCFLAGS', 'CPPDEFINES', 'COLOR', 'COLORS', 'PACKAGE']),
+                 ('mslink', ['LINKCOM', 'SHLINKCOM'], Cat, []),
+                 ('mslib', 'ARCOM', Cat, []),
+                 ('tar', 'TARCOM', Null, []),
+                 ('zip', 'ZIPCOM', Null, []),
+                 ('BitKeeper', 'BITKEEPERCOM', Cat, []),
+                 ('CVS', 'CVSCOM', Cat, []),
+                 ('RCS', 'RCS_COCOM', Cat, []),
+                 ('SCCS', 'SCCSCOM', Cat, []),
+                 ('javac', 'JAVACCOM', JavaCCom, []),
+                 ('javah', 'JAVAHCOM', JavaHCom, []),
+                 ('jar', 'JARCOM', JarCom, []),
+                 ('rmic', 'RMICCOM', Cat, []),
+                ],
+}
+
+toollist = ToolList[platform]
+filter_tools = '%(tools)s'.split()
+if filter_tools:
+    toollist = [x for x in toollist if x[0] in filter_tools]
+
+toollist = [ToolSurrogate(*t) for t in toollist]
+
+toollist.append('install')
+
+def surrogate_spawn(sh, escape, cmd, args, env):
+    pass
+
+def surrogate_pspawn(sh, escape, cmd, args, env, stdout, stderr):
+    pass
+
+SCons.Defaults.ConstructionEnvironment.update({
+    'PLATFORM' : platform,
+    'TOOLS'    : toollist,
+    'SPAWN'    : surrogate_spawn,
+    'PSPAWN'   : surrogate_pspawn,
+})
+
+SConscript('SConstruct')
+"""
+
+# "Commands" that we will execute in our examples.
+def command_scons(args, c, test, dict):
+    save_vals = {}
+    delete_keys = []
+    try:
+        ce = c.environment
+    except AttributeError:
+        pass
+    else:
+        for arg in c.environment.split():
+            key, val = arg.split('=')
+            try:
+                save_vals[key] = os.environ[key]
+            except KeyError:
+                delete_keys.append(key)
+            os.environ[key] = val
+    test.run(interpreter = sys.executable,
+             program = scons_py,
+             # We use ToolSurrogates to capture win32 output by "building"
+             # examples using a fake win32 tool chain.  Suppress the
+             # warnings that come from the new revamped VS support so
+             # we can build doc on (Linux) systems that don't have
+             # Visual C installed.
+             arguments = '--warn=no-visual-c-missing -f - ' + ' '.join(args),
+             chdir = test.workpath('WORK'),
+             stdin = Stdin % dict)
+    os.environ.update(save_vals)
+    for key in delete_keys:
+        del(os.environ[key])
+    out = test.stdout()
+    out = out.replace(test.workpath('ROOT'), '')
+    out = out.replace(test.workpath('WORK/SConstruct'),
+                              '/home/my/project/SConstruct')
+    lines = out.split('\n')
+    if lines:
+        while lines[-1] == '':
+            lines = lines[:-1]
+    #err = test.stderr()
+    #if err:
+    #    sys.stderr.write(err)
+    return lines
+
+def command_touch(args, c, test, dict):
+    if args[0] == '-t':
+        t = int(time.mktime(time.strptime(args[1], '%Y%m%d%H%M')))
+        times = (t, t)
+        args = args[2:]
+    else:
+        time.sleep(1)
+        times = None
+    for file in args:
+        if not os.path.isabs(file):
+            file = os.path.join(test.workpath('WORK'), file)
+        if not os.path.exists(file):
+            open(file, 'wb')
+        os.utime(file, times)
+    return []
+
+def command_edit(args, c, test, dict):
+    if c.edit is None:
+        add_string = 'void edit(void) { ; }\n'
+    else:
+        add_string = c.edit[:]
+    if add_string[-1] != '\n':
+        add_string = add_string + '\n'
+    for file in args:
+        if not os.path.isabs(file):
+            file = os.path.join(test.workpath('WORK'), file)
+        contents = open(file, 'rb').read()
+        open(file, 'wb').write(contents + add_string)
+    return []
+
+def command_ls(args, c, test, dict):
+    def ls(a):
+        return ['  '.join(sorted([x for x in os.listdir(a) if x[0] != '.']))]
+    if args:
+        l = []
+        for a in args:
+            l.extend(ls(test.workpath('WORK', a)))
+        return l
+    else:
+        return ls(test.workpath('WORK'))
+
+def command_sleep(args, c, test, dict):
+    time.sleep(int(args[0]))
+
+CommandDict = {
+    'scons' : command_scons,
+    'touch' : command_touch,
+    'edit'  : command_edit,
+    'ls'    : command_ls,
+    'sleep' : command_sleep,
+}
+
+def ExecuteCommand(args, c, t, dict):
+    try:
+        func = CommandDict[args[0]]
+    except KeyError:
+        func = lambda args, c, t, dict: []
+    return func(args[1:], c, t, dict)
+
+
+def create_scons_output(e):
+    # The real raison d'etre for this script, this is where we
+    # actually execute SCons to fetch the output.
+    
+    # Loop over all outputs for the example
+    for o in e.outputs:
+        # Create new test directory
+        t = TestCmd.TestCmd(workdir='', combine=1)
+        if o.preserve:
+            t.preserve()
+        t.subdir('ROOT', 'WORK')
+        t.rootpath = t.workpath('ROOT').replace('\\', '\\\\')
+    
+        for d in e.folders:
+            dir = t.workpath('WORK', d.name)
+            if not os.path.exists(dir):
+                os.makedirs(dir)
+    
+        for f in e.files:
+            if f.isFileRef():
+                continue
+            #
+            # Left-align file's contents, starting on the first
+            # non-empty line
+            #
+            data = f.content.split('\n')
+            i = 0
+            # Skip empty lines
+            while data[i] == '':
+                i = i + 1
+            lines = data[i:]
+            i = 0
+            # Scan first line for the number of spaces
+            # that this block is indented
+            while lines[0][i] == ' ':
+                i = i + 1
+            # Left-align block
+            lines = [l[i:] for l in lines]
+            path = f.name.replace('__ROOT__', t.rootpath)
+            if not os.path.isabs(path):
+                path = t.workpath('WORK', path)
+            dir, name = os.path.split(path)
+            if dir and not os.path.exists(dir):
+                os.makedirs(dir)
+            content = '\n'.join(lines)
+            content = content.replace('__ROOT__', t.rootpath)
+            path = t.workpath('WORK', path)
+            t.write(path, content)
+            if hasattr(f, 'chmod'):
+                if len(f.chmod):
+                    os.chmod(path, int(f.chmod, 0))
+    
+        # Regular expressions for making the doc output consistent,
+        # regardless of reported addresses or Python version.
+    
+        # Massage addresses in object repr strings to a constant.
+        address_re = re.compile(r' at 0x[0-9a-fA-F]*\>')
+    
+        # Massage file names in stack traces (sometimes reported as absolute
+        # paths) to a consistent relative path.
+        engine_re = re.compile(r' File ".*/src/engine/SCons/')
+    
+        # Python 2.5 changed the stack trace when the module is read
+        # from standard input from read "... line 7, in ?" to
+        # "... line 7, in <module>".
+        file_re = re.compile(r'^( *File ".*", line \d+, in) \?$', re.M)
+    
+        # Python 2.6 made UserList a new-style class, which changes the
+        # AttributeError message generated by our NodeList subclass.
+        nodelist_re = re.compile(r'(AttributeError:) NodeList instance (has no attribute \S+)')
+  
+        # Root element for our subtree
+        sroot = stf.newEtreeNode("screen", True)
+        curchild = None
+        content = ""
+        for c in o.commands:
+            content += Prompt[o.os]
+            if curchild is not None:
+                if not c.output:
+                    # Append content as tail
+                    curchild.tail = content
+                    content = "\n"
+                    # Add new child for userinput tag
+                    curchild = stf.newEtreeNode("userinput")
+                    d = c.cmd.replace('__ROOT__', '')
+                    curchild.text = d
+                    sroot.append(curchild)
+                else:
+                    content += c.output + '\n'
+            else:
+                if not c.output:
+                    # Add first text to root
+                    sroot.text = content
+                    content = "\n"
+                    # Add new child for userinput tag
+                    curchild = stf.newEtreeNode("userinput")
+                    d = c.cmd.replace('__ROOT__', '')
+                    curchild.text = d
+                    sroot.append(curchild)
+                else:
+                    content += c.output + '\n'
+            # Execute command and capture its output
+            cmd_work = c.cmd.replace('__ROOT__', t.workpath('ROOT'))
+            args = cmd_work.split()
+            lines = ExecuteCommand(args, c, t, {'osname':o.os, 'tools':o.tools})
+            if not c.output and lines:
+                ncontent = '\n'.join(lines)
+                ncontent = address_re.sub(r' at 0x700000&gt;', ncontent)
+                ncontent = engine_re.sub(r' File "bootstrap/src/engine/SCons/', ncontent)
+                ncontent = file_re.sub(r'\1 <module>', ncontent)
+                ncontent = nodelist_re.sub(r"\1 'NodeList' object \2", ncontent)
+                ncontent = ncontent.replace('__ROOT__', '')
+                content += ncontent + '\n'
+        # Add last piece of content
+        if len(content):
+            if curchild is not None:
+                curchild.tail = content
+            else:
+                sroot.text = content
+   
+        # Construct filename
+        fpath = os.path.join(generated_examples, 
+                             e.name+'_'+o.suffix+'.xml')
+        # Expand Element tree
+        s = stf.decorateWithCommentHeader(stf.convertElementTree(sroot)[0])
+        # Write it to file
+        stf.writeTree(s, fpath)
+
+
 # Local Variables:
 # tab-width:4
 # indent-tabs-mode:nil
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #
-# scons-doc.py -    an SGML preprocessor for capturing SCons output
-#                   and inserting it into examples in our DocBook
-#                   documentation
 #
-# Synopsis:
-#
-#  scons-doc [OPTIONS] [.in files]
-#
-#   When no input files are given, the folder doc/user/* is searched for .in files.
-#
-# Available options:
-#
-#   -d, --diff            create examples for the .in file and output a unified
-#                         diff against the related .xml file
-#   -r, --run             create examples for the .in file, but do not change
-#                         any files
-#   -s, --simple_diff     use a simpler output for the diff mode (no unified
-#                         diff!)
-#   -u, --update          create examples for the .in file and update the
-#                         related .xml file
-#
-# This script looks for some SGML tags that describe SCons example
+# This script looks for some XML tags that describe SCons example
 # configurations and commands to execute in those configurations, and
 # uses TestCmd.py to execute the commands and insert the output from
-# those commands into the SGML that we output.  This way, we can run a
+# those commands into the XML that we output.  This way, we can run a
 # script and update all of our example documentation output without
 # a lot of laborious by-hand checking.
 #
 # SCons output is generated from the following sort of tag:
 #
 #       <scons_output example="ex1" os="posix">
-#         <scons_output_command>scons -Q foo</scons_output_command>
-#         <scons_output_command>scons -Q foo</scons_output_command>
+#         <scons_output_command suffix="1">scons -Q foo</scons_output_command>
+#         <scons_output_command suffix="2">scons -Q foo</scons_output_command>
 #       </scons_output>
 #
 # You tell it which example to use with the "example" attribute, and then
 # supply an "os" tag, which specifies the type of operating system this
 # example is intended to show; if you omit this, default value is "posix".
 #
-# The generated SGML will show the command line (with the appropriate
+# The generated XML will show the command line (with the appropriate
 # command-line prompt for the operating system), execute the command in
 # a temporary directory with the example files, capture the standard
 # output from SCons, and insert it into the text as appropriate.
 # can see if there are any problems executing the command.
 #
 
-import optparse
 import os
 import re
-import sgmllib
 import sys
 import time
-import glob
 
 sys.path.append(os.path.join(os.getcwd(), 'QMTest'))
 sys.path.append(os.path.join(os.getcwd(), 'build', 'QMTest'))
 
 import TestCmd
 
-# The regular expression that identifies entity references in the
-# standard sgmllib omits the underscore from the legal characters.
-# Override it with our own regular expression that adds underscore.
-sgmllib.entityref = re.compile('&([a-zA-Z][-_.a-zA-Z0-9]*)[^-_a-zA-Z0-9]')
-
-# Classes for collecting different types of data we're interested in.
-class DataCollector(object):
-    """Generic class for collecting data between a start tag and end
-    tag.  We subclass for various types of tags we care about."""
-    def __init__(self):
-        self.data = ""
-    def afunc(self, data):
-        self.data = self.data + data
-
-class Example(DataCollector):
-    """An SCons example.  This is essentially a list of files that
-    will get written to a temporary directory to collect output
-    from one or more SCons runs."""
-    def __init__(self):
-        DataCollector.__init__(self)
-        self.files = []
-        self.dirs = []
-
-class File(DataCollector):
-    """A file, that will get written out to a temporary directory
-    for one or more SCons runs."""
-    def __init__(self, name):
-        DataCollector.__init__(self)
-        self.name = name
-
-class Directory(DataCollector):
-    """A directory, that will get created in a temporary directory
-    for one or more SCons runs."""
-    def __init__(self, name):
-        DataCollector.__init__(self)
-        self.name = name
-
-class Output(DataCollector):
-    """Where the command output goes.  This is essentially
-    a list of commands that will get executed."""
-    def __init__(self):
-        DataCollector.__init__(self)
-        self.commandlist = []
-
-class Command(DataCollector):
-    """A tag for where the command output goes.  This is essentially
-    a list of commands that will get executed."""
-    def __init__(self):
-        DataCollector.__init__(self)
-        self.output = None
 
 Prompt = {
     'posix' : '% ',
         func = lambda args, c, t, dict: []
     return func(args[1:], c, t, dict)
 
-class MySGML(sgmllib.SGMLParser):
-    """A subclass of the standard Python sgmllib SGML parser.
 
-    This extends the standard sgmllib parser to recognize, and do cool
-    stuff with, the added tags that describe our SCons examples,
-    commands, and other stuff.
-    """
-    def __init__(self, outfp):
-        sgmllib.SGMLParser.__init__(self)
-        self.examples = {}
-        self.afunclist = []
-        self.outfp = outfp
+def for_display(contents):
+    contents = contents.replace('__ROOT__', '')
+    contents = contents.replace('<', '&lt;')
+    contents = contents.replace('>', '&gt;')
+    return contents
 
-    # The first set of methods here essentially implement pass-through
-    # handling of most of the stuff in an SGML file.  We're really
-    # only concerned with the tags specific to SCons example processing,
-    # the methods for which get defined below.
 
-    def handle_data(self, data):
-        try:
-            f = self.afunclist[-1]
-        except IndexError:
-            self.outfp.write(data)
-        else:
-            f(data)
-
-    def handle_comment(self, data):
-        self.outfp.write('<!--' + data + '-->')
-
-    def handle_decl(self, data):
-        self.outfp.write('<!' + data + '>')
-
-    def unknown_starttag(self, tag, attrs):
-        try:
-            f = self.example.afunc
-        except AttributeError:
-            f = self.outfp.write
-        if not attrs:
-            f('<' + tag + '>')
-        else:
-            f('<' + tag)
-            for name, value in attrs:
-                f(' ' + name + '=' + '"' + value + '"')
-            f('>')
-
-    def unknown_endtag(self, tag):
-        self.outfp.write('</' + tag + '>')
-
-    def unknown_entityref(self, ref):
-        self.outfp.write('&' + ref + ';')
-
-    def unknown_charref(self, ref):
-        self.outfp.write('&#' + ref + ';')
-
-    # Here is where the heavy lifting begins.  The following methods
-    # handle the begin-end tags of our SCons examples.
-
-    def for_display(self, contents):
-        contents = contents.replace('__ROOT__', '')
-        contents = contents.replace('<', '&lt;')
-        contents = contents.replace('>', '&gt;')
-        return contents
-
-
-    def start_scons_output(self, attrs):
-        t = [t for t in attrs if t[0] == 'example']
-        if not t:
-            self.error("no <scons_output> example attribute found")
-        exname = t[0][1]
-        try:
-            e = self.examples[exname]
-        except KeyError:
-            self.error("unknown example name '%s'" % exname)
-        # Default values for an example.
-        o = Output()
-        o.preserve = None
-        o.os = 'posix'
-        o.tools = ''
-        o.e = e
-        # Locally-set.
-        for name, value in attrs:
-            setattr(o, name, value)
-        self.o = o
-        self.afunclist.append(o.afunc)
-
-    def end_scons_output(self):
-        # The real raison d'etre for this script, this is where we
-        # actually execute SCons to fetch the output.
-        o = self.o
-        e = o.e
+def create_scons_output(e):
+    # The real raison d'etre for this script, this is where we
+    # actually execute SCons to fetch the output.
+    
+    # Loop over all outputs for the example
+    for o in e.outputs:
+        # Create new test directory
         t = TestCmd.TestCmd(workdir='', combine=1)
         if o.preserve:
             t.preserve()
         t.subdir('ROOT', 'WORK')
         t.rootpath = t.workpath('ROOT').replace('\\', '\\\\')
-
+    
         for d in e.dirs:
             dir = t.workpath('WORK', d.name)
             if not os.path.exists(dir):
                 os.makedirs(dir)
-
+    
         for f in e.files:
+            if f.isFileRef():
+                continue
+            #
+            # Left-align file's contents, starting on the first
+            # non-empty line
+            #
+            data = f.content.split('\n')
             i = 0
-            while f.data[i] == '\n':
+            # Skip empty lines
+            while data[i] == '':
                 i = i + 1
-            lines = f.data[i:].split('\n')
+            lines = data[i:]
             i = 0
+            # Scan first line for the number of spaces
+            # that this block is indented
             while lines[0][i] == ' ':
                 i = i + 1
+            # Left-align block
             lines = [l[i:] for l in lines]
             path = f.name.replace('__ROOT__', t.rootpath)
             if not os.path.isabs(path):
             t.write(path, content)
             if hasattr(f, 'chmod'):
                 os.chmod(path, int(f.chmod, 0))
-
-        i = len(o.prefix)
-        while o.prefix[i-1] != '\n':
-            i = i - 1
-
-        self.outfp.write('<screen>' + o.prefix[:i])
-        p = o.prefix[i:]
-
+    
         # Regular expressions for making the doc output consistent,
         # regardless of reported addresses or Python version.
-
+    
         # Massage addresses in object repr strings to a constant.
         address_re = re.compile(r' at 0x[0-9a-fA-F]*\>')
-
+    
         # Massage file names in stack traces (sometimes reported as absolute
         # paths) to a consistent relative path.
         engine_re = re.compile(r' File ".*/src/engine/SCons/')
-
+    
         # Python 2.5 changed the stack trace when the module is read
         # from standard input from read "... line 7, in ?" to
         # "... line 7, in <module>".
         file_re = re.compile(r'^( *File ".*", line \d+, in) \?$', re.M)
-
+    
         # Python 2.6 made UserList a new-style class, which changes the
         # AttributeError message generated by our NodeList subclass.
         nodelist_re = re.compile(r'(AttributeError:) NodeList instance (has no attribute \S+)')
-
+    
         for c in o.commandlist:
-            self.outfp.write(p + Prompt[o.os])
-            d = c.data.replace('__ROOT__', '')
-            self.outfp.write('<userinput>' + d + '</userinput>\n')
-
-            e = c.data.replace('__ROOT__', t.workpath('ROOT'))
-            args = e.split()
+            # Open new output file
+            fpath = os.path.join(SConsExamples.generated_examples, 
+                                 e.name+'_'+c.suffix+'.out','w')
+            outfp = open(fpath)
+            outfp.write(Prompt[o.os])
+            d = c.cmd.replace('__ROOT__', '')
+            outfp.write('<userinput>' + d + '</userinput>\n')
+    
+            cmd_work = c.cmd.replace('__ROOT__', t.workpath('ROOT'))
+            args = cmd_work.split()
             lines = ExecuteCommand(args, c, t, {'osname':o.os, 'tools':o.tools})
             content = None
             if c.output:
                 content = c.output
             elif lines:
-                content = ( '\n' + p).join(lines)
+                content = '\n'.join(lines)
             if content:
                 content = address_re.sub(r' at 0x700000&gt;', content)
                 content = engine_re.sub(r' File "bootstrap/src/engine/SCons/', content)
                 content = file_re.sub(r'\1 <module>', content)
                 content = nodelist_re.sub(r"\1 'NodeList' object \2", content)
-                content = self.for_display(content)
-                self.outfp.write(p + content + '\n')
-
-        if o.data[0] == '\n':
-            o.data = o.data[1:]
-        self.outfp.write(o.data + '</screen>')
-        delattr(self, 'o')
-        self.afunclist = self.afunclist[:-1]
-
-    def start_scons_output_command(self, attrs):
-        try:
-            o = self.o
-        except AttributeError:
-            self.error("<scons_output_command> tag outside of <scons_output>")
-        try:
-            o.prefix
-        except AttributeError:
-            o.prefix = o.data
-            o.data = ""
-        c = Command()
-        for name, value in attrs:
-            setattr(c, name, value)
-        o.commandlist.append(c)
-        self.afunclist.append(c.afunc)
-
-    def end_scons_output_command(self):
-        self.o.data = ""
-        self.afunclist = self.afunclist[:-1]
-
-
-
-def main():
-    argv = sys.argv
-
-
-if __name__ == "__main__":
-    sys.exit(main())
-
+                content = for_display(content)
+                outfp.write(content + '\n')
+            outfp.close()
+    
 # Local Variables:
 # tab-width:4
 # indent-tabs-mode:nil

doc/user/add-method.xml

   This produces the following:
   </para>
 
-  <scons_output example="addmethod_ex1">
-    <scons_output_command suffix="1">scons -Q /</scons_output_command>
+  <scons_output example="addmethod_ex1" suffix="1">
+    <scons_output_command>scons -Q /</scons_output_command>
   </scons_output>
 
   <para>
 
   </para>
 
-  <scons_example name="ex2">
+  <scons_example name="addmethod_ex2">
      <file name="SConstruct" printme="1">
      def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
          """Build the test program;
   This produces the following on Linux:
   </para>
 
-  <scons_output example="ex2">
-    <scons_output_command suffix="1">scons -Q</scons_output_command>
+  <scons_output example="addmethod_ex2" suffix="1">
+    <scons_output_command>scons -Q</scons_output_command>
   </scons_output>
 
   <para>
   And the following on Windows:
   </para>
 
-  <scons_output example="ex2" os="win32">
-    <scons_output_command suffix="2">scons -Q</scons_output_command>
+  <scons_output example="addmethod_ex2" os="win32" suffix="2">
+    <scons_output_command>scons -Q</scons_output_command>
   </scons_output>
 
   <para>

doc/user/alias.xml

 
   </para>
 
-  <scons_output example="alias_ex1" os="posix">
-     <scons_output_command suffix="1">scons -Q install</scons_output_command>
+  <scons_output example="alias_ex1" os="posix" suffix="1">
+     <scons_output_command>scons -Q install</scons_output_command>
   </scons_output>
 
   <para>
 
   </para>
 
-  <scons_output example="alias_ex2" os="posix">
-     <scons_output_command suffix="1">scons -Q install-bin</scons_output_command>
-     <scons_output_command suffix="2">scons -Q install-lib</scons_output_command>
-     <scons_output_command suffix="3">scons -Q -c __ROOT__/</scons_output_command>
-     <scons_output_command suffix="4">scons -Q install</scons_output_command>
+  <scons_output example="alias_ex2" os="posix" suffix="1">
+     <scons_output_command>scons -Q install-bin</scons_output_command>
+     <scons_output_command>scons -Q install-lib</scons_output_command>
+     <scons_output_command>scons -Q -c __ROOT__/</scons_output_command>
+     <scons_output_command>scons -Q install</scons_output_command>
   </scons_output>
 
 </chapter>

doc/user/build-install.xml

 <?xml version='1.0'?>
 <!DOCTYPE sconsdoc [
+
+    <!ENTITY % version SYSTEM "../version.xml">
+    %version;
+
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
     
       </para>
 
       <screen>
-        # <userinput>rpm -Uvh scons-__VERSION__-1.noarch.rpm</userinput>
+        # <userinput>rpm -Uvh scons-&buildversion;-1.noarch.rpm</userinput>
       </screen>
 
       <para>
 
       &SCons; provides a Windows installer
       that makes installation extremely easy.
-      Download the <filename>scons-__VERSION__.win32.exe</filename>
+      Download the <filename>scons-&buildversion;.win32.exe</filename>
       file from the &SCons; download page at
       <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>.
       Then all you need to do is execute the file
     <para>
 
     The first step is to download either the
-    <filename>scons-__VERSION__.tar.gz</filename>
-    or <filename>scons-__VERSION__.zip</filename>,
+    <filename>scons-&buildversion;.tar.gz</filename>
+    or <filename>scons-&buildversion;.zip</filename>,
     which are available from the SCons download page at
     <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
 
     on Linux or UNIX,
     or <application>WinZip</application> on Windows.
     This will create a directory called
-    <filename>scons-__VERSION__</filename>,
+    <filename>scons-&buildversion;</filename>,
     usually in your local directory.
     Then change your working directory to that directory
     and install &SCons; by executing the following commands:
     </para>
 
     <screen>
-      # <userinput>cd scons-__VERSION__</userinput>
+      # <userinput>cd scons-&buildversion;</userinput>
       # <userinput>python setup.py install</userinput>
     </screen>
 
 
       This will install the &SCons; build engine
       in the
-      <filename>/usr/lib/scons-__VERSION__</filename>
+      <filename>/usr/lib/scons-&buildversion;</filename>
       or
-      <filename>C:\Python25\scons-__VERSION__</filename>
+      <filename>C:\Python25\scons-&buildversion;</filename>
       directory, for example.
 
       </para>
       relative to the specified prefix.
       Adding <option>--version-lib</option> to the
       above example would install the build engine in
-      <filename>/opt/scons/lib/scons-__VERSION__</filename>.
+      <filename>/opt/scons/lib/scons-&buildversion;</filename>.
 
       </para>
 

doc/user/builders-built-in.xml

 
     </para>
 
-    <scons_output example="buildersbuiltin_libs" os="posix">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="buildersbuiltin_libs" os="posix" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="buildersbuiltin_libs" os="win32">
-      <scons_output_command suffix="2">scons -Q</scons_output_command>
+    <scons_output example="buildersbuiltin_libs" os="win32" suffix="2">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
         </file>
       </scons_example>
 
-      <scons_output example="buildersbuiltin_ex1" os="posix">
-        <scons_output_command suffix="1">scons -Q .</scons_output_command>
+      <scons_output example="buildersbuiltin_ex1" os="posix" suffix="1">
+        <scons_output_command>scons -Q .</scons_output_command>
       </scons_output>
 
       <para>
         </file>
       </scons_example>
 
-      <scons_output example="buildersbuiltin_ex2" os="posix">
-        <scons_output_command suffix="1">scons -Q .</scons_output_command>
+      <scons_output example="buildersbuiltin_ex2" os="posix" suffix="1">
+        <scons_output_command>scons -Q .</scons_output_command>
       </scons_output>
 
       <para>
         </file>
       </scons_example>
 
-      <scons_output example="buildersbuiltin_ex3" os="posix">
-        <scons_output_command suffix="1">scons -Q .</scons_output_command>
+      <scons_output example="buildersbuiltin_ex3" os="posix" suffix="1">
+        <scons_output_command>scons -Q .</scons_output_command>
       </scons_output>
 
     </section>
 
       </para>
 
-      <scons_output example="buildersbuiltin_ex4" os="posix">
-        <scons_output_command suffix="1">scons -Q .</scons_output_command>
+      <scons_output example="buildersbuiltin_ex4" os="posix" suffix="1">
+        <scons_output_command>scons -Q .</scons_output_command>
       </scons_output>
 
     </section>

doc/user/builders-commands.xml

 
   </para>
 
-  <scons_output example="builderscommands_ex1">
-    <scons_output_command suffix="1">scons -Q</scons_output_command>
+  <scons_output example="builderscommands_ex1" suffix="1">
+    <scons_output_command>scons -Q</scons_output_command>
   </scons_output>
 
   <para>
 
   </para>
 
-  <scons_output example="builderscommands_ex2">
-    <scons_output_command suffix="1">scons -Q</scons_output_command>
+  <scons_output example="builderscommands_ex2" suffix="1">
+    <scons_output_command>scons -Q</scons_output_command>
   </scons_output>
 
   <para>

doc/user/builders-writing.xml

 
     </para>
 
-    <scons_output example="builderswriting_ex1">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_ex1" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
        </file>
     </scons_example>
 
-    <scons_output example="builderswriting_ex2">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_ex2" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="builderswriting_ex3">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_ex3" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
   </section>
        env.Foo('file2')
     </sconstruct>
 
-    <scons_output example="builderswriting_ex4">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_ex4" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="builderswriting_ex5">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_ex5" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
   </section>
        env.Foo('file')
     </sconstruct>
 
-    <scons_output example="builderswriting_ex6">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_ex6" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="builderswriting_ex7">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_ex7" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="builderswriting_MY_EMITTER">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_MY_EMITTER" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
   </section>
     </para>
 
     <!-- 
-    <scons_output example="builderswriting_site1" os="posix">
-       <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_site1" os="posix" suffix="1">
+       <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
     -->
 
        </file>
     </scons_example>
 
-    <scons_output example="builderswriting_ex8">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="builderswriting_ex8" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
   </section>

doc/user/caching.xml

 
     </para>
 
-    <scons_output example="caching_ex1">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
-      <scons_output_command suffix="2">scons -Q -c</scons_output_command>
-      <scons_output_command suffix="3">scons -Q</scons_output_command>
+    <scons_output example="caching_ex1" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="caching_ex1">
-      <scons_output_command suffix="4">scons -Q</scons_output_command>
-      <scons_output_command suffix="5">scons -Q -c</scons_output_command>
-      <scons_output_command suffix="6">scons -Q --cache-show</scons_output_command>
+    <scons_output example="caching_ex1" suffix="2">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q --cache-show</scons_output_command>
     </scons_output>
 
     <para>
 
     <!--
 
-    <scons_output example="caching_ex1">
-      <scons_output_command suffix="7">scons -Q</scons_output_command>
-      <scons_output_command suffix="8">scons -Q -c</scons_output_command>
-      <scons_output_command suffix="9">scons -Q</scons_output_command>
+    <scons_output example="caching_ex1" suffix="3">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     -->
 
     </para>
 
-    <scons_output example="caching_ex1">
-      <scons_output_command suffix="10">scons -Q</scons_output_command>
-      <scons_output_command suffix="11">scons -Q -c</scons_output_command>
-      <scons_output_command suffix="12">scons -Q</scons_output_command>
-      <scons_output_command suffix="13">scons -Q -c</scons_output_command>
-      <scons_output_command suffix="14">scons -Q --cache-disable</scons_output_command>
+    <scons_output example="caching_ex1" suffix="4">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q --cache-disable</scons_output_command>
     </scons_output>
 
   </section>
 
     </para>
 
-    <scons_output example="caching_ex1">
-      <scons_output_command suffix="15">scons -Q --cache-disable</scons_output_command>
-      <scons_output_command suffix="16">scons -Q -c</scons_output_command>
-      <scons_output_command suffix="17">scons -Q --cache-disable</scons_output_command>
-      <scons_output_command suffix="18">scons -Q --cache-force</scons_output_command>
-      <scons_output_command suffix="19">scons -Q</scons_output_command>
+    <scons_output example="caching_ex1" suffix="5">
+      <scons_output_command>scons -Q --cache-disable</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q --cache-disable</scons_output_command>
+      <scons_output_command>scons -Q --cache-force</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="caching_ex-random">
-      <scons_output_command suffix="1">scons -Q</scons_output_command>
+    <scons_output example="caching_ex-random" suffix="1">
+      <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
     <para>
 
     The following <screen> output was generated by this:
 
-    <scons_output example="caching_ex-random">
-      <scons_output_command suffix="2">scons -Q - -random</scons_output_command>
+    <scons_output example="caching_ex-random" suffix="2">
+      <scons_output_command>scons -Q - -random</scons_output_command>
     </scons_output>
 
     We captured it directly here to guarantee a "random" order,

doc/user/command-line.xml

         </file>
       </scons_example>
 
-      <scons_output example="commandline_SCONSFLAGS">
-        <scons_output_command suffix="1">scons</scons_output_command>
-        <scons_output_command suffix="2">export SCONSFLAGS="-Q"</scons_output_command>
-        <scons_output_command environment="SCONSFLAGS=-Q" suffix="3">scons</scons_output_command>
+      <scons_output example="commandline_SCONSFLAGS" suffix="1">
+        <scons_output_command>scons</scons_output_command>
+        <scons_output_command>export SCONSFLAGS="-Q"</scons_output_command>
+        <scons_output_command environment="SCONSFLAGS=-Q">scons</scons_output_command>
       </scons_output>
 
       <para>
 
       </para>
 
-      <scons_output example="commandline_SetOption">
-        <scons_output_command suffix="1">scons -Q</scons_output_command>
+      <scons_output example="commandline_SetOption" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
       </scons_output>
 
       <para>
 
       </para>
 
-      <scons_output example="commandline_SetOption">
-        <scons_output_command suffix="2">export NUM_CPU="4"</scons_output_command>
-        <scons_output_command environment="NUM_CPU=4" suffix="3">scons -Q</scons_output_command>
+      <scons_output example="commandline_SetOption" suffix="2">
+        <scons_output_command>export NUM_CPU="4"</scons_output_command>
+        <scons_output_command environment="NUM_CPU=4">scons -Q</scons_output_command>
       </scons_output>
 
       <para>
 
       </para>
 
-      <scons_output example="commandline_SetOption">
-        <scons_output_command suffix="4">scons -Q -j 7</scons_output_command>
-        <scons_output_command suffix="5">export NUM_CPU="4"</scons_output_command>
-        <scons_output_command environment="NUM_CPU=4" suffix="6">scons -Q -j 3</scons_output_command>
+      <scons_output example="commandline_SetOption" suffix="3">
+        <scons_output_command>scons -Q -j 7</scons_output_command>
+        <scons_output_command>export NUM_CPU="4"</scons_output_command>
+        <scons_output_command environment="NUM_CPU=4">scons -Q -j 3</scons_output_command>
       </scons_output>
 
     </section>
 
       </para>
 
-      <scons_output example="commandline_AddOption">
-        <scons_output_command suffix="1">scons -Q -n</scons_output_command>
+      <scons_output example="commandline_AddOption" suffix="1">
+        <scons_output_command>scons -Q -n</scons_output_command>
       </scons_output>
 
       <para>
 
       </para>
 
-      <scons_output example="commandline_AddOption">
-        <scons_output_command suffix="2">scons -Q -n --prefix=/tmp/install</scons_output_command>
+      <scons_output example="commandline_AddOption" suffix="2">
+        <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command>
       </scons_output>
 
     </section>
 
     </para>
 
-    <scons_output example="commandline_ARGUMENTS">
-       <scons_output_command suffix="1">scons -Q debug=0</scons_output_command>
-       <scons_output_command suffix="2">scons -Q debug=0</scons_output_command>
-       <scons_output_command suffix="3">scons -Q debug=1</scons_output_command>
-       <scons_output_command suffix="4">scons -Q debug=1</scons_output_command>
+    <scons_output example="commandline_ARGUMENTS" suffix="1">
+       <scons_output_command>scons -Q debug=0</scons_output_command>
+       <scons_output_command>scons -Q debug=0</scons_output_command>
+       <scons_output_command>scons -Q debug=1</scons_output_command>
+       <scons_output_command>scons -Q debug=1</scons_output_command>
     </scons_output>
 
     <para>
 
     </para>
 
-    <scons_output example="commandline_ARGLIST">
-       <scons_output_command suffix="1">scons -Q define=FOO</scons_output_command>
-       <scons_output_command suffix="2">scons -Q define=FOO define=BAR</scons_output_command>
+    <scons_output example="commandline_ARGLIST" suffix="1">
+       <scons_output_command>scons -Q define=FOO</scons_output_command>
+       <scons_output_command>scons -Q define=FOO define=BAR</scons_output_command>
     </scons_output>
 
     <para>
 
       </para>
 
-      <scons_output example="commandline_Variables1">
-        <scons_output_command suffix="1">scons -Q RELEASE=1</scons_output_command>
+      <scons_output example="commandline_Variables1" suffix="1">
+        <scons_output_command>scons -Q RELEASE=1</scons_output_command>
       </scons_output>
 
       <para>
 
       </para>
 
-      <scons_output example="commandline_Variables_Help">
-        <scons_output_command suffix="1">scons -Q -h</scons_output_command>
+      <scons_output example="commandline_Variables_Help" suffix="1">
+        <scons_output_command>scons -Q -h</scons_output_command>
       </scons_output>
 
       <para>
 
       </para>
 
-      <scons_output example="commandline_Variables_custom_py_1">
-        <scons_output_command suffix="1">scons -Q</scons_output_command>
+      <scons_output example="commandline_Variables_custom_py_1" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
       </scons_output>
 
       <para>
 
       </para>
 
-      <scons_output example="commandline_Variables_custom_py_2">
-        <scons_output_command suffix="1">scons -Q</scons_output_command>
+      <scons_output example="commandline_Variables_custom_py_2" suffix="1">
+        <scons_output_command>scons -Q</scons_output_command>
       </scons_output>
 
       <para>
 
         </para>
 
-        <scons_output example="commandline_BoolVariable">
-          <scons_output_command suffix="1">scons -Q RELEASE=yes foo.o</scons_output_command>
+        <scons_output example="commandline_BoolVariable" suffix="1">
+          <scons_output_command>scons -Q RELEASE=yes foo.o</scons_output_command>
         </scons_output>
 
-        <scons_output example="commandline_BoolVariable">
-          <scons_output_command suffix="2">scons -Q RELEASE=t foo.o</scons_output_command>
+        <scons_output example="commandline_BoolVariable" suffix="2">
+          <scons_output_command>scons -Q RELEASE=t foo.o</scons_output_command>
         </scons_output>
 
         <para>
 
         </para>
 
-        <scons_output example="commandline_BoolVariable">
-          <scons_output_command suffix="3">scons -Q RELEASE=no foo.o</scons_output_command>
+        <scons_output example="commandline_BoolVariable" suffix="3">