- cleaned up 'bin' directory

- several smaller fixes
- added first version of the Overview document for the doc toolchain

6 files changed, 80 insertions, 642 deletions

diff --git a/bin/SConsExamples.py b/bin/SConsExamples.py
index cba248b9..9823a052 100644
--- a/bin/SConsExamples.py
+++ b/bin/SConsExamples.py
@@ -1,7 +1,7 @@
-#!/usr/bin/env python
-#
+# !/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
@@ -9,10 +9,10 @@
 # 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
@@ -21,18 +21,18 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-#
-#
+# 
+# 
 # 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()
@@ -42,7 +42,7 @@
 #           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
@@ -50,41 +50,41 @@
 # 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
@@ -94,10 +94,10 @@ import time
 import SConsDoc
 from SConsDoc import tf as stf
 
-#
+# 
 # The available types for ExampleFile entries
-#
-FT_FILE = 0     # a physical file (=<file>)
+# 
+FT_FILE = 0  # a physical file (=<file>)
 FT_FILEREF = 1  # a reference     (=<scons_example_file>)
 
 class ExampleFile:
@@ -155,7 +155,7 @@ def readExampleInfos(fpath, examples):
     t.parseXmlFile(fpath)
     
     # Parse scons_examples
-    for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid, 
+    for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid,
                          t.xpath_context, t.nsmap):
         n = ''
         if stf.hasAttribute(e, 'name'):
@@ -166,7 +166,7 @@ def readExampleInfos(fpath, examples):
             examples[n] = i
             
         # Parse file and directory entries
-        for f in stf.findAll(e, "file", SConsDoc.dbxid, 
+        for f in stf.findAll(e, "file", SConsDoc.dbxid,
                              t.xpath_context, t.nsmap):
             fi = ExampleFile()
             if stf.hasAttribute(f, 'name'):
@@ -175,7 +175,7 @@ def readExampleInfos(fpath, examples):
                 fi.chmod = stf.getAttribute(f, 'chmod')
             fi.content = stf.getText(f)
             examples[n].files.append(fi)
-        for d in stf.findAll(e, "directory", SConsDoc.dbxid, 
+        for d in stf.findAll(e, "directory", SConsDoc.dbxid,
                              t.xpath_context, t.nsmap):
             di = ExampleFolder()
             if stf.hasAttribute(d, 'name'):
@@ -186,7 +186,7 @@ def readExampleInfos(fpath, examples):
 
 
     # Parse scons_example_files
-    for f in stf.findAll(t.root, "scons_example_file", SConsDoc.dbxid, 
+    for f in stf.findAll(t.root, "scons_example_file", SConsDoc.dbxid,
                          t.xpath_context, t.nsmap):
         if stf.hasAttribute(f, 'example'):
             e = stf.getAttribute(f, 'example')
@@ -202,7 +202,7 @@ def readExampleInfos(fpath, examples):
         
     
     # Parse scons_output
-    for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid, 
+    for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid,
                          t.xpath_context, t.nsmap):
         if stf.hasAttribute(o, 'example'):
             n = stf.getAttribute(o, 'example')
@@ -219,7 +219,7 @@ def readExampleInfos(fpath, examples):
         if stf.hasAttribute(o, 'suffix'):
             eout.suffix = stf.getAttribute(o, 'suffix')
 
-        for c in stf.findAll(o, "scons_output_command", SConsDoc.dbxid, 
+        for c in stf.findAll(o, "scons_output_command", SConsDoc.dbxid,
                          t.xpath_context, t.nsmap):
             oc = ExampleCommand()
             if stf.hasAttribute(c, 'edit'):
@@ -252,7 +252,7 @@ def readAllExampleInfos(dpath):
                    
     return examples
 
-generated_examples = os.path.join('doc','generated','examples')
+generated_examples = os.path.join('doc', 'generated', 'examples')
 
 def ensureExampleOutputsExist(dpath):
     """ Scan for XML files in the given directory and 
@@ -268,8 +268,8 @@ def ensureExampleOutputsExist(dpath):
     for key, value in examples.iteritems():
         # Process all scons_output tags
         for o in value.outputs:
-            cpath = os.path.join(generated_examples, 
-                                 key+'_'+o.suffix+'.xml')
+            cpath = os.path.join(generated_examples,
+                                 key + '_' + o.suffix + '.xml')
             if not os.path.isfile(cpath):
                 # Start new XML file
                 s = stf.newXmlTree("screen")
@@ -282,8 +282,8 @@ def ensureExampleOutputsExist(dpath):
             if r.isFileRef():
                 # Get file's content
                 content = value.getFileContents(r.name)
-                fpath = os.path.join(generated_examples, 
-                                     key+'_'+r.name.replace("/","_"))
+                fpath = os.path.join(generated_examples,
+                                     key + '_' + r.name.replace("/", "_"))
                 # Write file
                 f = open(fpath, 'w')
                 f.write("%s\n" % content)
@@ -305,8 +305,8 @@ def createAllExampleOutputs(dpath):
     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)
+        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
@@ -314,8 +314,8 @@ def createAllExampleOutputs(dpath):
             if r.isFileRef():
                 # Get file's content
                 content = value.getFileContents(r.name)
-                fpath = os.path.join(generated_examples, 
-                                     key+'_'+r.name.replace("/","_"))
+                fpath = os.path.join(generated_examples,
+                                     key + '_' + r.name.replace("/", "_"))
                 # Write file
                 f = open(fpath, 'w')
                 f.write("%s\n" % content)
@@ -334,7 +334,7 @@ def collectSConsExampleNames(fpath):
     t.parseXmlFile(fpath)
     
     # Parse it
-    for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid, 
+    for e in stf.findAll(t.root, "scons_example", SConsDoc.dbxid,
                          t.xpath_context, t.nsmap):
         n = ''
         if stf.hasAttribute(e, 'name'):
@@ -347,7 +347,7 @@ def collectSConsExampleNames(fpath):
             print "Error: Example in file '%s' is missing a name!" % fpath
             failed_suffixes = True
     
-    for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid, 
+    for o in stf.findAll(t.root, "scons_output", SConsDoc.dbxid,
                          t.xpath_context, t.nsmap):
         n = ''
         if stf.hasAttribute(o, 'example'):
@@ -399,15 +399,15 @@ def exampleNamesAreUnique(dpath):
                    
     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'))
@@ -430,7 +430,7 @@ Prompt = {
 }
 
 # 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
@@ -438,7 +438,7 @@ Prompt = {
 # 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.
@@ -676,16 +676,16 @@ def command_scons(args, c, test, dict):
             except KeyError:
                 delete_keys.append(key)
             os.environ[key] = val
-    test.run(interpreter = sys.executable,
-             program = scons_py,
+    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)
+             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])
@@ -697,8 +697,8 @@ def command_scons(args, c, test, dict):
     if lines:
         while lines[-1] == '':
             lines = lines[:-1]
-    #err = test.stderr()
-    #if err:
+    # err = test.stderr()
+    # if err:
     #    sys.stderr.write(err)
     return lines
 
@@ -783,10 +783,10 @@ def create_scons_output(e):
         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
@@ -883,10 +883,10 @@ def create_scons_output(e):
                 sroot.text = content
    
         # Construct filename
-        fpath = os.path.join(generated_examples, 
-                             e.name+'_'+o.suffix+'.xml')
+        fpath = os.path.join(generated_examples,
+                             e.name + '_' + o.suffix + '.xml')
         # Expand Element tree
-        s = stf.decorateWithCommentHeader(stf.convertElementTree(sroot)[0])
+        s = stf.decorateWithHeader(stf.convertElementTree(sroot)[0])
         # Write it to file
         stf.writeTree(s, fpath)
 
diff --git a/bin/docs-check-unique-examples.py b/bin/docs-create-example-outputs.py
index d9e5cf6d..30dc0eef 100644
--- a/bin/docs-check-unique-examples.py
+++ b/bin/docs-create-example-outputs.py
@@ -1,17 +1,19 @@
 #!/usr/bin/env python
 #
-# Searches through the whole doc/user tree and verifies
-# that the names of the single examples are unique over
-# all *.xml files.
-# Additionally, the suffix entries have to be unique
-# within each scons_command_output.
+# Searches through the whole doc/user tree and creates
+# all output files for the single examples.
 #
 
 import os
+import sys
 import SConsExamples
 
 if __name__ == "__main__":
+    print "Checking whether all example names are unique..."
     if SConsExamples.exampleNamesAreUnique(os.path.join('doc','user')):
         print "OK"
     else:
         print "Not all example names and suffixes are unique! Please correct the errors listed above and try again."
+        sys.exit(0)
+    
+    SConsExamples.createAllExampleOutputs(os.path.join('doc','user'))
diff --git a/bin/docs-update-generated.py b/bin/docs-update-generated.py
index e6899035..66b22c0b 100644
--- a/bin/docs-update-generated.py
+++ b/bin/docs-update-generated.py
@@ -11,7 +11,7 @@ import os
 import SConsDoc
 
 # Directory where all generated files are stored
-gen_folder = 'doc/generated'
+gen_folder = os.path.join('doc','generated')
 
 def argpair(key):
     """ Return the argument pair *.gen,*.mod for the given key. """
@@ -41,8 +41,9 @@ def generate_all():
                 print "Couldn't create destination folder %s! Exiting..." % gen_folder
                 return
         # Call scons-proc.py
-        os.system('python bin/scons-proc.py -b %s -f %s -t %s -v %s %s' %
-                  (argpair('builders'), argpair('functions'),
+        os.system('python %s -b %s -f %s -t %s -v %s %s' %
+                  (os.path.join('bin','scons-proc.py'),
+                   argpair('builders'), argpair('functions'),
                    argpair('tools'), argpair('variables'), ' '.join(flist)))
     
     
diff --git a/bin/docs-validate.py b/bin/docs-validate.py
index fc90ee7f..1ed0da04 100644
--- a/bin/docs-validate.py
+++ b/bin/docs-validate.py
@@ -2,10 +2,6 @@
 #
 # Searches through the whole source tree and validates all
 # documentation files against our own XSD in docs/xsd.
-# Additionally, it rewrites all files such that the XML gets
-# pretty-printed in a consistent way. This is done to ensure that
-# merging and diffing doesn't get too hard when people start to
-# use different XML editors...
 #
 
 import os
diff --git a/bin/scons-doc.py b/bin/scons-doc.py
deleted file mode 100644
index 95da5f30..00000000
--- a/bin/scons-doc.py
+++ /dev/null
@@ -1,555 +0,0 @@
-#!/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.
-
-#
-#
-# 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
-
-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):
-    try:
-        add_string = c.edit[:]
-    except AttributeError:
-        add_string = 'void edit(void) { ; }\n'
-    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 for_display(contents):
-    contents = contents.replace('__ROOT__', '')
-    contents = contents.replace('<', '&lt;')
-    contents = contents.replace('>', '&gt;')
-    return contents
-
-
-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
-            # 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'):
-                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+)')
-    
-        for c in o.commandlist:
-            # 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'.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 = for_display(content)
-                outfp.write(content + '\n')
-            outfp.close()
-    
-# Local Variables:
-# tab-width:4
-# indent-tabs-mode:nil
-# End:
-# vim: set expandtab tabstop=4 shiftwidth=4:
diff --git a/bin/scons-proc.py b/bin/scons-proc.py
index 36176f1d..5be1f00f 100644
--- a/bin/scons-proc.py
+++ b/bin/scons-proc.py
@@ -134,7 +134,8 @@ class SCons_XML(object):
             
             ve = stf.newNode("varlistentry")
             stf.setAttribute(ve, 'id', '%s%s' % (v.prefix, v.idfunc()))
-            stf.appendNode(ve, v.xml_term())
+            for t in v.xml_terms():
+                stf.appendNode(ve, t)
             vl = stf.newNode("listitem")
             added = False
             if v.summary is not None:
@@ -237,29 +238,26 @@ class SConsThing(Proxy):
     def idfunc(self):
         return self.name
     
-    def xml_term(self):
+    def xml_terms(self):
         e = stf.newNode("term")
         stf.setText(e, self.name)
-        return e
+        return [e]
 
 class Builder(SConsThing):
     description = 'builder'
     prefix = 'b-'
     tag = 'function'
     
-    def xml_term(self):
-        t = stf.newNode("term")
-        s = stf.newNode("synopsis")
+    def xml_terms(self):
+        ta = stf.newNode("term")
         b = stf.newNode(self.tag)
         stf.setText(b, self.name+'()')
-        stf.appendNode(s, b)
-        stf.appendNode(t, s)
-        s = stf.newNode("synopsis")
+        stf.appendNode(ta, b)
+        tb = stf.newNode("term")
         b = stf.newNode(self.tag)
         stf.setText(b, 'env.'+self.name+'()')
-        stf.appendNode(s, b)
-        stf.appendNode(t, s)
-        return t
+        stf.appendNode(tb, b)
+        return [ta, tb]
             
     def entityfunc(self):
         return self.name
@@ -345,18 +343,14 @@ h = parse_docs(args, False)
 write_output_files(h, buildersfiles, functionsfiles, toolsfiles,
                    variablesfiles, SCons_XML.write_mod)
 
-# Step 2: Patching the include paths for entity definitions in XML files
-print "Patching include paths..."
-os.system('python bin/docs-correct-mod-paths.py')
-
-# Step 3: Validating all input files
+# Step 2: Validating all input files
 print "Validating files against SCons XSD..."
 if SConsDoc.validate_all_xml(['src']):
     print "OK"
 else:
     print "Validation failed! Please correct the errors above and try again."
 
-# Step 4: Creating actual documentation snippets, using the
+# Step 3: Creating actual documentation snippets, using the
 #         fully resolved and updated entities from the *.mod files.
 print "Updating documentation for builders, tools and functions..."
 h = parse_docs(args, True)