- cleaned up 'bin' directory

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

11 files changed, 858 insertions, 903 deletions

diff --git a/bin/SConsExamples.py b/bin/SConsExamples.py
index cba248b..9823a05 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 d9e5cf6..30dc0ee 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 e689903..66b22c0 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 fc90ee7..1ed0da0 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 95da5f3..0000000
--- 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 36176f1..5be1f00 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)
diff --git a/doc/editor_configs/xmlmind/addon/config/scons/common.incl b/doc/editor_configs/xmlmind/addon/config/scons/common.incl
index eafa0a4..d03f74c 100644
--- a/doc/editor_configs/xmlmind/addon/config/scons/common.incl
+++ b/doc/editor_configs/xmlmind/addon/config/scons/common.incl
@@ -11,7 +11,9 @@
 
   <cfg:preserveSpace xmlns="" 
     elements="address funcsynopsisinfo classsynopsisinfo 
-              literallayout programlisting screen synopsis" />
+              literallayout programlisting screen synopsis
+              sconstruct scons_example_file example_commands
+              scons_output_command file directory" />
 
   <cfg:documentResources xmlns="">
     <cfg:resource path="//@fileref" />
diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
index 2b033e4..0e3073e 100644
--- a/doc/generated/builders.gen
+++ b/doc/generated/builders.gen
@@ -15,12 +15,10 @@
 <variablelist xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd">
   <varlistentry id="b-CFile">
     <term>
-      <synopsis>
-        <function>CFile()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.CFile()</function>
-      </synopsis>
+      <function>CFile()</function>
+    </term>
+    <term>
+      <function>env.CFile()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -43,12 +41,10 @@ env.CFile(target = 'bar', source = 'bar.y')
   </varlistentry>
   <varlistentry id="b-Command">
     <term>
-      <synopsis>
-        <function>Command()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Command()</function>
-      </synopsis>
+      <function>Command()</function>
+    </term>
+    <term>
+      <function>env.Command()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -63,12 +59,10 @@ for the calling syntax and details.
   </varlistentry>
   <varlistentry id="b-CXXFile">
     <term>
-      <synopsis>
-        <function>CXXFile()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.CXXFile()</function>
-      </synopsis>
+      <function>CXXFile()</function>
+    </term>
+    <term>
+      <function>env.CXXFile()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -92,12 +86,10 @@ env.CXXFile(target = 'bar', source = 'bar.yy')
   </varlistentry>
   <varlistentry id="b-DVI">
     <term>
-      <synopsis>
-        <function>DVI()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.DVI()</function>
-      </synopsis>
+      <function>DVI()</function>
+    </term>
+    <term>
+      <function>env.DVI()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -153,12 +145,10 @@ env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
   </varlistentry>
   <varlistentry id="b-Install">
     <term>
-      <synopsis>
-        <function>Install()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Install()</function>
-      </synopsis>
+      <function>Install()</function>
+    </term>
+    <term>
+      <function>env.Install()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -178,12 +168,10 @@ env.Install('/usr/local/bin', source = ['foo', 'bar'])
   </varlistentry>
   <varlistentry id="b-InstallAs">
     <term>
-      <synopsis>
-        <function>InstallAs()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.InstallAs()</function>
-      </synopsis>
+      <function>InstallAs()</function>
+    </term>
+    <term>
+      <function>env.InstallAs()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -201,12 +189,10 @@ arguments list different numbers of files or directories.
   </varlistentry>
   <varlistentry id="b-InstallVersionedLib">
     <term>
-      <synopsis>
-        <function>InstallVersionedLib()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.InstallVersionedLib()</function>
-      </synopsis>
+      <function>InstallVersionedLib()</function>
+    </term>
+    <term>
+      <function>env.InstallVersionedLib()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -226,12 +212,10 @@ env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
   </varlistentry>
   <varlistentry id="b-Jar">
     <term>
-      <synopsis>
-        <function>Jar()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Jar()</function>
-      </synopsis>
+      <function>Jar()</function>
+    </term>
+    <term>
+      <function>env.Jar()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -277,12 +261,10 @@ env.Jar(target = 'bar.jar',
   </varlistentry>
   <varlistentry id="b-Java">
     <term>
-      <synopsis>
-        <function>Java()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Java()</function>
-      </synopsis>
+      <function>Java()</function>
+    </term>
+    <term>
+      <function>env.Java()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -357,12 +339,10 @@ env['ENV']['LANG'] = 'en_GB.UTF-8'
   </varlistentry>
   <varlistentry id="b-JavaH">
     <term>
-      <synopsis>
-        <function>JavaH()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.JavaH()</function>
-      </synopsis>
+      <function>JavaH()</function>
+    </term>
+    <term>
+      <function>env.JavaH()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -415,12 +395,10 @@ env.JavaH(target = 'export',
   </varlistentry>
   <varlistentry id="b-Library">
     <term>
-      <synopsis>
-        <function>Library()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Library()</function>
-      </synopsis>
+      <function>Library()</function>
+    </term>
+    <term>
+      <function>env.Library()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -432,12 +410,10 @@ builder method.
   </varlistentry>
   <varlistentry id="b-LoadableModule">
     <term>
-      <synopsis>
-        <function>LoadableModule()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.LoadableModule()</function>
-      </synopsis>
+      <function>LoadableModule()</function>
+    </term>
+    <term>
+      <function>env.LoadableModule()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -451,12 +427,10 @@ this creates a loadable module bundle.
   </varlistentry>
   <varlistentry id="b-M4">
     <term>
-      <synopsis>
-        <function>M4()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.M4()</function>
-      </synopsis>
+      <function>M4()</function>
+    </term>
+    <term>
+      <function>env.M4()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -476,12 +450,10 @@ env.M4(target = 'foo.c', source = 'foo.c.m4')
   </varlistentry>
   <varlistentry id="b-Moc">
     <term>
-      <synopsis>
-        <function>Moc()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Moc()</function>
-      </synopsis>
+      <function>Moc()</function>
+    </term>
+    <term>
+      <function>env.Moc()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -499,12 +471,10 @@ env.Moc('foo.cpp') # generates foo.moc
   </varlistentry>
   <varlistentry id="b-MOFiles">
     <term>
-      <synopsis>
-        <function>MOFiles()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.MOFiles()</function>
-      </synopsis>
+      <function>MOFiles()</function>
+    </term>
+    <term>
+      <function>env.MOFiles()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -556,12 +526,10 @@ Compile files for languages defined in <filename>LINGUAS</filename> file
   </varlistentry>
   <varlistentry id="b-MSVSProject">
     <term>
-      <synopsis>
-        <function>MSVSProject()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.MSVSProject()</function>
-      </synopsis>
+      <function>MSVSProject()</function>
+    </term>
+    <term>
+      <function>env.MSVSProject()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -739,12 +707,10 @@ env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
   </varlistentry>
   <varlistentry id="b-MSVSSolution">
     <term>
-      <synopsis>
-        <function>MSVSSolution()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.MSVSSolution()</function>
-      </synopsis>
+      <function>MSVSSolution()</function>
+    </term>
+    <term>
+      <function>env.MSVSSolution()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -813,12 +779,10 @@ env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
   </varlistentry>
   <varlistentry id="b-Object">
     <term>
-      <synopsis>
-        <function>Object()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Object()</function>
-      </synopsis>
+      <function>Object()</function>
+    </term>
+    <term>
+      <function>env.Object()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -830,12 +794,10 @@ builder method.
   </varlistentry>
   <varlistentry id="b-Package">
     <term>
-      <synopsis>
-        <function>Package()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Package()</function>
-      </synopsis>
+      <function>Package()</function>
+    </term>
+    <term>
+      <function>env.Package()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -905,12 +867,10 @@ env.Package( NAME           = 'foo',
   </varlistentry>
   <varlistentry id="b-PCH">
     <term>
-      <synopsis>
-        <function>PCH()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.PCH()</function>
-      </synopsis>
+      <function>PCH()</function>
+    </term>
+    <term>
+      <function>env.PCH()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -932,12 +892,10 @@ env['PCH'] = env.PCH('StdAfx.cpp')[0]
   </varlistentry>
   <varlistentry id="b-PDF">
     <term>
-      <synopsis>
-        <function>PDF()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.PDF()</function>
-      </synopsis>
+      <function>PDF()</function>
+    </term>
+    <term>
+      <function>env.PDF()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -963,12 +921,10 @@ env.PDF(target = 'bbb', source = 'bbb.dvi')
   </varlistentry>
   <varlistentry id="b-POInit">
     <term>
-      <synopsis>
-        <function>POInit()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.POInit()</function>
-      </synopsis>
+      <function>POInit()</function>
+    </term>
+    <term>
+      <function>env.POInit()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1071,12 +1027,10 @@ which has same efect as:
   </varlistentry>
   <varlistentry id="b-PostScript">
     <term>
-      <synopsis>
-        <function>PostScript()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.PostScript()</function>
-      </synopsis>
+      <function>PostScript()</function>
+    </term>
+    <term>
+      <function>env.PostScript()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1102,12 +1056,10 @@ env.PostScript(target = 'bbb', source = 'bbb.dvi')
   </varlistentry>
   <varlistentry id="b-POTUpdate">
     <term>
-      <synopsis>
-        <function>POTUpdate()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.POTUpdate()</function>
-      </synopsis>
+      <function>POTUpdate()</function>
+    </term>
+    <term>
+      <function>env.POTUpdate()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1274,12 +1226,10 @@ then the <filename>messages.pot</filename> will contain
   </varlistentry>
   <varlistentry id="b-POUpdate">
     <term>
-      <synopsis>
-        <function>POUpdate()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.POUpdate()</function>
-      </synopsis>
+      <function>POUpdate()</function>
+    </term>
+    <term>
+      <function>env.POUpdate()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1393,12 +1343,10 @@ pre-configured via environment.
   </varlistentry>
   <varlistentry id="b-Program">
     <term>
-      <synopsis>
-        <function>Program()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Program()</function>
-      </synopsis>
+      <function>Program()</function>
+    </term>
+    <term>
+      <function>env.Program()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1429,12 +1377,10 @@ env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
   </varlistentry>
   <varlistentry id="b-RES">
     <term>
-      <synopsis>
-        <function>RES()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.RES()</function>
-      </synopsis>
+      <function>RES()</function>
+    </term>
+    <term>
+      <function>env.RES()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1457,12 +1403,10 @@ env.RES('resource.rc')
   </varlistentry>
   <varlistentry id="b-RMIC">
     <term>
-      <synopsis>
-        <function>RMIC()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.RMIC()</function>
-      </synopsis>
+      <function>RMIC()</function>
+    </term>
+    <term>
+      <function>env.RMIC()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1506,12 +1450,10 @@ env.RMIC(target = 'outdir3',
   </varlistentry>
   <varlistentry id="b-RPCGenClient">
     <term>
-      <synopsis>
-        <function>RPCGenClient()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.RPCGenClient()</function>
-      </synopsis>
+      <function>RPCGenClient()</function>
+    </term>
+    <term>
+      <function>env.RPCGenClient()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1531,12 +1473,10 @@ env.RPCGenClient('src/rpcif.x')
   </varlistentry>
   <varlistentry id="b-RPCGenHeader">
     <term>
-      <synopsis>
-        <function>RPCGenHeader()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.RPCGenHeader()</function>
-      </synopsis>
+      <function>RPCGenHeader()</function>
+    </term>
+    <term>
+      <function>env.RPCGenHeader()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1556,12 +1496,10 @@ env.RPCGenHeader('src/rpcif.x')
   </varlistentry>
   <varlistentry id="b-RPCGenService">
     <term>
-      <synopsis>
-        <function>RPCGenService()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.RPCGenService()</function>
-      </synopsis>
+      <function>RPCGenService()</function>
+    </term>
+    <term>
+      <function>env.RPCGenService()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1581,12 +1519,10 @@ env.RPCGenClient('src/rpcif.x')
   </varlistentry>
   <varlistentry id="b-RPCGenXDR">
     <term>
-      <synopsis>
-        <function>RPCGenXDR()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.RPCGenXDR()</function>
-      </synopsis>
+      <function>RPCGenXDR()</function>
+    </term>
+    <term>
+      <function>env.RPCGenXDR()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1606,12 +1542,10 @@ env.RPCGenClient('src/rpcif.x')
   </varlistentry>
   <varlistentry id="b-SharedLibrary">
     <term>
-      <synopsis>
-        <function>SharedLibrary()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.SharedLibrary()</function>
-      </synopsis>
+      <function>SharedLibrary()</function>
+    </term>
+    <term>
+      <function>env.SharedLibrary()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1716,12 +1650,10 @@ when it is done linking it.
   </varlistentry>
   <varlistentry id="b-SharedObject">
     <term>
-      <synopsis>
-        <function>SharedObject()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.SharedObject()</function>
-      </synopsis>
+      <function>SharedObject()</function>
+    </term>
+    <term>
+      <function>env.SharedObject()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1770,12 +1702,10 @@ below, for more information.
   </varlistentry>
   <varlistentry id="b-StaticLibrary">
     <term>
-      <synopsis>
-        <function>StaticLibrary()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.StaticLibrary()</function>
-      </synopsis>
+      <function>StaticLibrary()</function>
+    </term>
+    <term>
+      <function>env.StaticLibrary()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1816,12 +1746,10 @@ will raise an error if there is any mismatch.
   </varlistentry>
   <varlistentry id="b-StaticObject">
     <term>
-      <synopsis>
-        <function>StaticObject()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.StaticObject()</function>
-      </synopsis>
+      <function>StaticObject()</function>
+    </term>
+    <term>
+      <function>env.StaticObject()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1890,12 +1818,10 @@ below, for more information.
   </varlistentry>
   <varlistentry id="b-Substfile">
     <term>
-      <synopsis>
-        <function>Substfile()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Substfile()</function>
-      </synopsis>
+      <function>Substfile()</function>
+    </term>
+    <term>
+      <function>env.Substfile()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -1985,12 +1911,10 @@ subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
   </varlistentry>
   <varlistentry id="b-Tar">
     <term>
-      <synopsis>
-        <function>Tar()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Tar()</function>
-      </synopsis>
+      <function>Tar()</function>
+    </term>
+    <term>
+      <function>env.Tar()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -2033,12 +1957,10 @@ env.Tar('foo')
   </varlistentry>
   <varlistentry id="b-Textfile">
     <term>
-      <synopsis>
-        <function>Textfile()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Textfile()</function>
-      </synopsis>
+      <function>Textfile()</function>
+    </term>
+    <term>
+      <function>env.Textfile()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -2106,12 +2028,10 @@ blob.txt
   </varlistentry>
   <varlistentry id="b-Translate">
     <term>
-      <synopsis>
-        <function>Translate()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Translate()</function>
-      </synopsis>
+      <function>Translate()</function>
+    </term>
+    <term>
+      <function>env.Translate()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -2246,12 +2166,10 @@ running <command>scons '.'</command>.</para></note>
   </varlistentry>
   <varlistentry id="b-TypeLibrary">
     <term>
-      <synopsis>
-        <function>TypeLibrary()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.TypeLibrary()</function>
-      </synopsis>
+      <function>TypeLibrary()</function>
+    </term>
+    <term>
+      <function>env.TypeLibrary()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -2280,12 +2198,10 @@ files.
   </varlistentry>
   <varlistentry id="b-Uic">
     <term>
-      <synopsis>
-        <function>Uic()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Uic()</function>
-      </synopsis>
+      <function>Uic()</function>
+    </term>
+    <term>
+      <function>env.Uic()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -2311,12 +2227,10 @@ env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
   </varlistentry>
   <varlistentry id="b-Zip">
     <term>
-      <synopsis>
-        <function>Zip()</function>
-      </synopsis>
-      <synopsis>
-        <function>env.Zip()</function>
-      </synopsis>
+      <function>Zip()</function>
+    </term>
+    <term>
+      <function>env.Zip()</function>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
diff --git a/doc/images/overview.graphml b/doc/images/overview.graphml
new file mode 100644
index 0000000..74f80d7
--- /dev/null
+++ b/doc/images/overview.graphml
@@ -0,0 +1,418 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:y="http://www.yworks.com/xml/graphml" xmlns:yed="http://www.yworks.com/xml/yed/3" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://www.yworks.com/xml/schema/graphml/1.1/ygraphml.xsd">
+  <!--Created by yFiles for Java 2.9-->
+  <key for="graphml" id="d0" yfiles.type="resources"/>
+  <key for="port" id="d1" yfiles.type="portgraphics"/>
+  <key for="port" id="d2" yfiles.type="portgeometry"/>
+  <key for="port" id="d3" yfiles.type="portuserdata"/>
+  <key attr.name="url" attr.type="string" for="node" id="d4"/>
+  <key attr.name="description" attr.type="string" for="node" id="d5"/>
+  <key for="node" id="d6" yfiles.type="nodegraphics"/>
+  <key attr.name="Beschreibung" attr.type="string" for="graph" id="d7"/>
+  <key attr.name="url" attr.type="string" for="edge" id="d8"/>
+  <key attr.name="description" attr.type="string" for="edge" id="d9"/>
+  <key for="edge" id="d10" yfiles.type="edgegraphics"/>
+  <graph edgedefault="directed" id="G">
+    <data key="d7"/>
+    <node id="n0" yfiles.foldertype="group">
+      <data key="d4"/>
+      <data key="d6">
+        <y:ProxyAutoBoundsNode>
+          <y:Realizers active="0">
+            <y:GroupNode>
+              <y:Geometry height="269.01233212809916" width="204.95703125" x="100.521484375" y="53.0390625"/>
+              <y:Fill color="#F5F5F5" transparent="false"/>
+              <y:BorderStyle color="#000000" type="dashed" width="1.0"/>
+              <y:NodeLabel alignment="right" autoSizePolicy="node_width" backgroundColor="#EBEBEB" borderDistance="0.0" fontFamily="Dialog" fontSize="15" fontStyle="plain" hasLineColor="false" height="21.4609375" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="204.95703125" x="0.0" y="0.0">User's view</y:NodeLabel>
+              <y:Shape type="roundrectangle"/>
+              <y:State closed="false" closedHeight="50.0" closedWidth="50.0" innerGraphDisplayEnabled="false"/>
+              <y:Insets bottom="15" bottomF="15.0" left="15" leftF="15.0" right="15" rightF="15.0" top="15" topF="15.0"/>
+              <y:BorderInsets bottom="0" bottomF="0.0" left="0" leftF="0.0" right="0" rightF="0.0" top="3" topF="3.0"/>
+            </y:GroupNode>
+            <y:GroupNode>
+              <y:Geometry height="50.0" width="50.0" x="0.0" y="60.0"/>
+              <y:Fill color="#F5F5F5" transparent="false"/>
+              <y:BorderStyle color="#000000" type="dashed" width="1.0"/>
+              <y:NodeLabel alignment="right" autoSizePolicy="node_width" backgroundColor="#EBEBEB" borderDistance="0.0" fontFamily="Dialog" fontSize="15" fontStyle="plain" hasLineColor="false" height="21.4609375" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="65.201171875" x="-7.6005859375" y="0.0">Folder 1</y:NodeLabel>
+              <y:Shape type="roundrectangle"/>
+              <y:State closed="true" closedHeight="50.0" closedWidth="50.0" innerGraphDisplayEnabled="false"/>
+              <y:Insets bottom="5" bottomF="5.0" left="5" leftF="5.0" right="5" rightF="5.0" top="5" topF="5.0"/>
+              <y:BorderInsets bottom="0" bottomF="0.0" left="0" leftF="0.0" right="0" rightF="0.0" top="0" topF="0.0"/>
+            </y:GroupNode>
+          </y:Realizers>
+        </y:ProxyAutoBoundsNode>
+      </data>
+      <graph edgedefault="directed" id="n0:">
+        <node id="n0::n0">
+          <data key="d6">
+            <y:ShapeNode>
+              <y:Geometry height="30.0" width="174.95703125" x="115.521484375" y="185.05694731404958"/>
+              <y:Fill color="#FFCC00" transparent="false"/>
+              <y:BorderStyle color="#000000" type="line" width="1.0"/>
+              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="164.95703125" x="5.0" y="6.015625">XML files (src/user/man/...)<y:LabelModel>
+                  <y:SmartNodeLabelModel distance="4.0"/>
+                </y:LabelModel>
+                <y:ModelParameter>
+                  <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+                </y:ModelParameter>
+              </y:NodeLabel>
+              <y:Shape type="rectangle"/>
+            </y:ShapeNode>
+          </data>
+        </node>
+        <node id="n0::n1">
+          <data key="d6">
+            <y:ShapeNode>
+              <y:Geometry height="41.9375" width="158.357421875" x="123.8212890625" y="265.11389462809916"/>
+              <y:Fill color="#FFCC00" transparent="false"/>
+              <y:BorderStyle color="#000000" type="line" width="1.0"/>
+              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="92.154296875" x="33.1015625" y="11.984375">XML validation<y:LabelModel>
+                  <y:SmartNodeLabelModel distance="4.0"/>
+                </y:LabelModel>
+                <y:ModelParameter>
+                  <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+                </y:ModelParameter>
+              </y:NodeLabel>
+              <y:Shape type="rectangle"/>
+            </y:ShapeNode>
+          </data>
+        </node>
+        <node id="n0::n2">
+          <data key="d6">
+            <y:SVGNode>
+              <y:Geometry height="52.0" width="51.154296875" x="177.4228515625" y="92.5"/>
+              <y:Fill color="#CCCCFF" transparent="false"/>
+              <y:BorderStyle color="#000000" type="line" width="1.0"/>
+              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="41.154296875" x="42.63675428695848" y="20.570887005532427">Writer<y:LabelModel>
+                  <y:SmartNodeLabelModel distance="4.0"/>
+                </y:LabelModel>
+                <y:ModelParameter>
+                  <y:SmartNodeLabelModelParameter labelRatioX="-0.2930339421443093" labelRatioY="0.5" nodeRatioX="0.5" nodeRatioY="0.24114686549100794" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+                </y:ModelParameter>
+              </y:NodeLabel>
+              <y:SVGNodeProperties usingVisualBounds="true"/>
+              <y:SVGModel svgBoundsPolicy="0">
+                <y:SVGContent refid="1"/>
+              </y:SVGModel>
+            </y:SVGNode>
+          </data>
+        </node>
+      </graph>
+    </node>
+    <node id="n1">
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="41.9375" width="225.341796875" x="90.3291015625" y="339.03125"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="121.650390625" x="51.845703125" y="11.984375">Creating entity lists
+<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n2">
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="41.9375" width="134.7734375" x="382.61328125" y="339.03125"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="124.7734375" x="5.0" y="5.0">Check that example
+names are unique<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n3">
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="41.9375" width="163.35546875" x="368.322265625" y="410.96875"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="149.458984375" x="6.9482421875" y="11.984375">Create example outputs<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n4">
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="41.9375" width="171.125" x="117.4375" y="410.96875"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="161.125" x="5.0" y="5.0">Resolve XIncludes for text
+and examples<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n5">
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="30.0" width="155.29296875" x="125.353515625" y="497.09375"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="145.29296875" x="5.0" y="6.015625">Create HTML, PDF, Man<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n6">
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="41.9375" width="144.6171875" x="130.69140625" y="563.21875"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="134.6171875" x="5.0" y="5.0">Install in proper place
+for packaging<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n7">
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="41.9375" width="102.306640625" x="398.8466796875" y="491.125"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="92.306640625" x="5.0" y="5.0">Create API doc
+(Epydoc)<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <edge id="n0::e0" source="n0::n0" target="n0::n1">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" visible="true" width="83.318359375" x="2.0" y="16.04410017029312">get validated</y:EdgeLabel>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e0" source="n0::n1" target="n1">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e1" source="n1" target="n4">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e2" source="n1" target="n2">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e3" source="n2" target="n3">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e4" source="n3" target="n4">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e5" source="n5" target="n6">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e6" source="n4" target="n5">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" visible="true" width="132.970703125" x="2.0" y="13.109375">switching to Docbook</y:EdgeLabel>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e7" source="n5" target="n7">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e8" source="n7" target="n6">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0">
+            <y:Point x="450.0" y="584.1875"/>
+          </y:Path>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="n0::e1" source="n0::n2" target="n0::n0">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="standard"/>
+          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" visible="true" width="81.94140625" x="2.0" y="11.289856713665415">edits/creates</y:EdgeLabel>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+  </graph>
+  <data key="d0">
+    <y:Resources>
+      <y:Resource id="1">&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;!-- Generator: Adobe Illustrator 15.0.2, SVG Export Plug-In . SVG Version: 6.00 Build 0)  --&gt;
+&lt;!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"&gt;
+&lt;svg version="1.1" id="Ebene_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="57px" height="65px" viewBox="0 0 57 65" enable-background="new 0 0 57 65" xml:space="preserve"&gt;
+&lt;g&gt;
+	
+		&lt;linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="26.5396" y1="-732.5005" x2="27.7805" y2="-762.2984" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)"&gt;
+		&lt;stop  offset="0.2711" style="stop-color:#FFAB4F"/&gt;
+		&lt;stop  offset="1" style="stop-color:#FFD28F"/&gt;
+	&lt;/linearGradient&gt;
+	&lt;path fill="url(#SVGID_1_)" stroke="#ED9135" stroke-miterlimit="10" d="M49.529,51.225c-4.396-4.396-10.951-5.884-12.063-6.109
+		V37.8H19.278c0,0,0.038,6.903,0,6.868c0,0-6.874,0.997-12.308,6.432C1.378,56.691,0.5,62.77,0.5,62.77
+		c0,1.938,1.575,3.492,3.523,3.492h48.51c1.947,0,3.521-1.558,3.521-3.492C56.055,62.768,54.211,55.906,49.529,51.225z"/&gt;
+	
+		&lt;radialGradient id="face_x5F_white_1_" cx="27.7827" cy="-734.2632" r="23.424" fx="23.2131" fy="-736.753" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)" gradientUnits="userSpaceOnUse"&gt;
+		&lt;stop  offset="0" style="stop-color:#FFD28F"/&gt;
+		&lt;stop  offset="1" style="stop-color:#FFAB4F"/&gt;
+	&lt;/radialGradient&gt;
+	&lt;path id="face_x5F_white_3_" fill="url(#face_x5F_white_1_)" stroke="#ED9135" stroke-miterlimit="10" d="M43.676,23.357
+		c0.086,10.2-6.738,18.52-15.246,18.586c-8.503,0.068-15.467-8.146-15.553-18.344C12.794,13.4,19.618,5.079,28.123,5.012
+		C36.627,4.945,43.59,13.158,43.676,23.357z"/&gt;
+	
+		&lt;linearGradient id="face_highlight_1_" gradientUnits="userSpaceOnUse" x1="2941.4297" y1="5677.457" x2="2965.0596" y2="5770.9087" gradientTransform="matrix(0.275 0 0 0.2733 -783.3976 -1543.4047)"&gt;
+		&lt;stop  offset="0" style="stop-color:#FFFFFF;stop-opacity:0.42"/&gt;
+		&lt;stop  offset="1" style="stop-color:#FFFFFF;stop-opacity:0.2067"/&gt;
+	&lt;/linearGradient&gt;
+	&lt;path id="face_highlight_3_" fill="url(#face_highlight_1_)" d="M27.958,6.333c-6.035,0.047-10.747,4.493-12.787,10.386
+		c-0.664,1.919-0.294,4.043,0.98,5.629c2.73,3.398,5.729,6.283,9.461,8.088c3.137,1.518,7.535,2.385,11.893,1.247
+		c2.274-0.592,3.988-2.459,4.375-4.766c0.183-1.094,0.293-2.289,0.283-3.553C42.083,13.952,36.271,6.268,27.958,6.333z"/&gt;
+	&lt;path fill="#CC9869" stroke="#99724F" stroke-linecap="round" stroke-linejoin="round" d="M32.215,9.938
+		c0,0,5.688,2.75,7.688,8.125c2.104,5.652,4.123,8.232,4.188,8c1.875-6.794,1.063-21.438-10.17-21.587
+		c-20.455-7.663-25.58,11.962-23.893,19.65c1.078,4.911,2.234,6.686,3.938,8.08C13.966,32.205,15.028,17.563,32.215,9.938z"/&gt;
+	
+		&lt;radialGradient id="collar_x5F_body_2_" cx="15.1587" cy="-765.7056" r="32.4004" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)" gradientUnits="userSpaceOnUse"&gt;
+		&lt;stop  offset="0" style="stop-color:#B0E8FF"/&gt;
+		&lt;stop  offset="1" style="stop-color:#74AEEE"/&gt;
+	&lt;/radialGradient&gt;
+	&lt;path id="collar_x5F_body_1_" fill="url(#collar_x5F_body_2_)" stroke="#5491CF" d="M0.5,62.768c0,1.938,1.575,3.494,3.523,3.494
+		h48.51c1.947,0,3.521-1.559,3.521-3.494c0,0-1.844-6.861-6.525-11.543c-4.815-4.813-11.244-6.146-11.244-6.146
+		c-1.771,1.655-5.61,2.802-10.063,2.802c-4.453,0-8.292-1.146-10.063-2.802c0,0-5.755,0.586-11.189,6.021
+		C1.378,56.689,0.5,62.768,0.5,62.768z"/&gt;
+	
+		&lt;radialGradient id="collar_x5F_r_2_" cx="31.5" cy="-755.832" r="9.2834" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)" gradientUnits="userSpaceOnUse"&gt;
+		&lt;stop  offset="0" style="stop-color:#80CCFF"/&gt;
+		&lt;stop  offset="1" style="stop-color:#74AEEE"/&gt;
+	&lt;/radialGradient&gt;
+	&lt;path id="collar_x5F_r_1_" fill="url(#collar_x5F_r_2_)" stroke="#5491CF" d="M38.159,41.381c0,0-0.574,2.369-3.013,4.441
+		c-2.108,1.795-5.783,2.072-5.783,2.072l3.974,6.217c0,0,2.957-1.637,5.009-3.848c1.922-2.072,1.37-5.479,1.37-5.479L38.159,41.381z
+		"/&gt;
+	
+		&lt;radialGradient id="collar_x5F_l_2_" cx="19.1377" cy="-755.873" r="9.2837" gradientTransform="matrix(1 0 0 -1 0.1201 -708.5371)" gradientUnits="userSpaceOnUse"&gt;
+		&lt;stop  offset="0" style="stop-color:#80CCFF"/&gt;
+		&lt;stop  offset="1" style="stop-color:#74AEEE"/&gt;
+	&lt;/radialGradient&gt;
+	&lt;path id="collar_x5F_l_1_" fill="url(#collar_x5F_l_2_)" stroke="#5491CF" d="M18.63,41.422c0,0,0.576,2.369,3.012,4.441
+		c2.109,1.793,5.785,2.072,5.785,2.072l-3.974,6.217c0,0-2.957-1.637-5.007-3.85c-1.922-2.072-1.37-5.48-1.37-5.48L18.63,41.422z"/&gt;
+	
+		&lt;radialGradient id="Knob2_2_" cx="27.8872" cy="7.9414" r="0.9669" gradientTransform="matrix(1 0 0 -1 0.04 64.1543)" gradientUnits="userSpaceOnUse"&gt;
+		&lt;stop  offset="0" style="stop-color:#80CCFF"/&gt;
+		&lt;stop  offset="1" style="stop-color:#74AEEE"/&gt;
+	&lt;/radialGradient&gt;
+	&lt;circle id="Knob2_1_" fill="url(#Knob2_2_)" stroke="#5491CF" cx="28.258" cy="56.254" r="0.584"/&gt;
+	
+		&lt;radialGradient id="Knob1_2_" cx="27.9253" cy="1.6973" r="0.9669" gradientTransform="matrix(1 0 0 -1 0.04 64.1543)" gradientUnits="userSpaceOnUse"&gt;
+		&lt;stop  offset="0" style="stop-color:#80CCFF"/&gt;
+		&lt;stop  offset="1" style="stop-color:#74AEEE"/&gt;
+	&lt;/radialGradient&gt;
+	&lt;circle id="Knob1_1_" fill="url(#Knob1_2_)" stroke="#5491CF" cx="28.296" cy="62.499" r="0.584"/&gt;
+&lt;/g&gt;
+&lt;/svg&gt;
+</y:Resource>
+    </y:Resources>
+  </data>
+</graphml>
diff --git a/doc/overview.rst b/doc/overview.rst
new file mode 100644
index 0000000..612fbba
--- /dev/null
+++ b/doc/overview.rst
@@ -0,0 +1,174 @@
+=============================
+SCons Documentation Toolchain
+=============================
+
+
+Introduction
+============
+
+This text tries to give an overview of the current SCons documentation toolchain.
+The interested user should be able to better understand where and how the text he writes
+is processed.
+It is also a reference for core developers and the release team.
+
+.. image:: images/overview.png
+
+The diagram above roughly shows the steps that we currently need for creating all the MAN pages, User manuals and 
+reference documents. You may think: "Geeez, that looks so complicated. Why can't they
+simply convert XML files to PDF with Docbook, or use reST?" Please be patient, and
+continue reading. Things will get a little clearer soon.
+
+Our toolchain doesn't only produce HTML and PDF files that are nice to look at, it also performs a lot
+of processing under the covers. We try to have our documentation as consistent as possible to the
+current behaviour of the source code, but this requires some extra steps.
+
+So let's start right at the top...
+
+Writer's view
+=============
+
+The toolchain is set up, such that the User has a very restricted view on this whole "document
+processing thingy". All he should be concerned about is to edit existing text or write new sections
+and paragraphs.
+Sometimes even a completely new chapter has to be added, in general he can fire up his XML editor of choice
+and type away.
+
+If he is a really nice user, he cares about validating his XML files against our special
+"SCons Docbook DTD/XSD". Either during typing, supported by his XML editor, or by executing a special
+script 
+
+::
+
+    python bin/docs-validate.py
+
+
+from the top source folder afterwards. Preferably both.
+
+Everything's looking okay, all validation passed? Good, then he simply commits his new work, and
+creates a pull request on Bitbucket. That's it!
+
+Additionally, he can create the single documents on his side if he wants to get a feel for how the
+final result looks (and who doesn't?). Each of the document folders (``design``, ``developer``, ``man``,
+``python10``, ``reference``, and ``user``) contains an ``SConstruct`` file along with the actual
+XML files. You can call
+
+::
+
+    python ../../src/script/scons.py
+
+from within the directory, and have the MAN pages or HTML created...even PDF, if you have a
+renderer installed (``fop``, ``xep`` or ``jw``).
+
+Validation
+==========
+
+Just a few more words about the validation step.
+We are using our own DTD/XSD as a kind of hook, which only exists to link our own
+SCons documentation tags into the normal Docbook XSD. For the output, we always
+have an intermediary step (see diagram above), where we rewrite tags like ``cvar``
+into a block of Docbook formatting elements representing it.
+
+The toolchain, and all the Python scripts supporting it, are based on the prerequisite that
+all documents are valid against the SCons Docbook XSD. This step guarantees that we can
+accept the pull request of a user/writer with all his changes, and can create the documentation
+for a new release of SCons without any problems at a later time.
+
+
+Entities
+========
+
+We are using entities for special keywords like ``SCons`` that should appear with the same
+formatting throughout the text. These are kept in a single file ``doc/scons.mod`` which gets
+included by the documents.
+
+Additionally, for each Tool, Builder, Cvar and Function, a bunch of linkends in the form of
+entities get defined. They can be used in the MAN page and the User manual.
+
+When you add an XML file in the ``src/engine/Tools`` folder, e.g. for a tool named ``foobar``,
+you can use the two entities 
+  
+*t-foobar*
+    which prints the name of the Tool, and
+    
+*t-link-foobar*
+    which is a link to the description of the Tool in the Appendix
+    
+of the User guide's text.
+
+By calling the script
+
+::
+
+    python bin/docs-update-generated.py
+    
+you can recreate the lists of entities (``*.mod``) in the ``generated`` folder, if required. 
+At the same time, this will generate the ``*.gen`` files, which list the full
+description of all the Builders, Tools, Functions and CVars for the MAN page
+and the guide's appendix.
+
+For more information about how to properly describe these elements, refer to
+the start of the Python script ``bin/SConsDoc.py``. It explains the available
+tags and the exact syntax in detail.
+
+
+Examples
+========
+
+In the User Guide, we support automatically created examples. This means that the output of the specified
+source files and SConstructs, is generated by running them with the current SCons version. 
+We do this to ensure that the output displayed in the manual, is identical to what you get when you run
+the example on the command-line.
+
+A short description about how these examples have to be defined, can be found at the start of the file
+``bin/SConsExamples.py``. Call
+
+::
+
+    python bin/docs-create-example-outputs.py
+
+from the top level source folder, to run all examples through SCons.
+
+Before this script starts to generate any output, it checks whether the names of all defined examples are
+unique. Another important prerequisite is, that for every example all the single ``scons_output`` blocks need to have
+a ``suffix`` attribute defined. These suffixes also have to be unique, within each example.
+
+All example output files (``*.xml``) get written to the folder ``doc/generated/examples``, together with all files defined
+via the ``scons_example_file`` tag. They are put under version control, too. Like this, it is easier to compare
+whether the output got broken for a new version of SCons.
+
+Note, that these output files are not actually needed for editing the documents. When loading the User manual into an XML
+editor, you will always see the example's definition. Only when you create some output, the files from
+``doc/generated/examples`` get XIncluded and all special ``scons*`` tags are transformed into Docbook elements.
+
+
+Directories
+===========
+
+Documents are in the folders ``design``, ``developer``, ``man``,
+``python10``, ``reference``, and ``user``.
+
+*editor_configs*
+    Prepared configuration sets for the validating WYSIWYG XML editors
+    XmlMind and Serna. You'll probably want to try the latter, because
+    the XXE config requires you to have a full version (costing a few
+    hundred bucks) and is therefore untested. For installing the Serna
+    config, simply copy the ``scons`` folder into the ``plugins``
+    directory of your installation. Likewise, the XXE files from the
+    ``xmlmind`` folder have to be copied into ``~/.xxe4/`` under Linux.
+
+*generated*
+    Entity lists and outputs of the UserGuide examples. They get generated
+    by the update scripts ``bin/docs-update-generated.py`` 
+    and ``bin/docs-create-example-outputs.py``.
+
+*images*
+    Images for the ``overview.rst`` document.
+  
+*xsd*
+    The SCons Docbook schema (XSD), based on the Docbook v4.5 DTD/XSD.
+  
+*xslt*
+    XSLT transformation scripts for converting the special SCons
+    tags like ``scons_output`` to valid Docbook during document
+    processing.
+  
diff --git a/doc/user/pdf.xsl b/doc/user/pdf.xsl
index cda0644..652975f 100644
--- a/doc/user/pdf.xsl
+++ b/doc/user/pdf.xsl
@@ -36,6 +36,8 @@
 <xsl:param name="paper.type" select="'letter'"></xsl:param>

 <xsl:param name="body.start.indent">0pt</xsl:param>

 <xsl:param name="shade.verbatim" select="1"></xsl:param>

+<xsl:param name="variablelist.term.break.after" select="1"></xsl:param>

+

 <xsl:param name="generate.toc">

 /appendix toc,title

 article/appendix  nop

@@ -54,8 +56,15 @@ reference toc,title
 set       toc,title

 </xsl:param>

 

-<xsl:template match="varlistentry/term">

-	<xsl:call-template name="inline.boldseq"/>

+<xsl:attribute-set name="variablelist.term.properties">

+  <xsl:attribute name="font-weight">bold</xsl:attribute>

+</xsl:attribute-set>

+

+<xsl:template match="variablelist">

+  <xsl:variable name="presentation">

+    <xsl:call-template name="pi.dbfo_list-presentation"/>

+  </xsl:variable>

+  <xsl:apply-templates select="." mode="vl.as.blocks"/>

 </xsl:template>

 

 </xsl:stylesheet>