Imported Upstream version 2.3.1upstream/2.3.1

1 files changed, 5120 insertions, 0 deletions

diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
new file mode 100644
index 0000000..072b91c
--- /dev/null
+++ b/doc/generated/functions.gen
@@ -0,0 +1,5120 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sconsdoc [
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+    <!ENTITY % builders-mod SYSTEM "builders.mod">
+    %builders-mod;
+    <!ENTITY % functions-mod SYSTEM "functions.mod">
+    %functions-mod;
+    <!ENTITY % tools-mod SYSTEM "tools.mod">
+    %tools-mod;
+    <!ENTITY % variables-mod SYSTEM "variables.mod">
+    %variables-mod;
+]>
+
+<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="f-Action">
+    <term>
+      <literal>Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])</literal>
+    </term>
+    <term>
+      <literal>env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Creates an Action object for
+the specified
+<varname>action</varname>.
+See the section "Action Objects,"
+below, for a complete explanation of the arguments and behavior.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the
+<function>env.Action</function>()
+form of the invocation will expand
+construction variables in any argument strings,
+including the
+<varname>action</varname>
+argument, at the time it is called
+using the construction variables in the
+<varname>env</varname>
+construction environment through which
+<function>env.Action</function>()
+was called.
+The
+<function>Action</function>()
+form delays all variable expansion
+until the Action object is actually used.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-AddMethod">
+    <term>
+      <literal>AddMethod(object, function, [name])</literal>
+    </term>
+    <term>
+      <literal>env.AddMethod(function, [name])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+When called with the
+<function>AddMethod</function>()
+form,
+adds the specified
+<varname>function</varname>
+to the specified
+<varname>object</varname>
+as the specified method
+<varname>name</varname>.
+When called with the
+<function>env.AddMethod</function>()
+form,
+adds the specified
+<varname>function</varname>
+to the construction environment
+<varname>env</varname>
+as the specified method
+<varname>name</varname>.
+In both cases, if
+<varname>name</varname>
+is omitted or
+<literal>None</literal>,
+the name of the
+specified
+<varname>function</varname>
+itself is used for the method name.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Note that the first argument to the function to
+# be attached as a method must be the object through
+# which the method will be called; the Python
+# convention is to call it 'self'.
+def my_method(self, arg):
+    print "my_method() got", arg
+
+# Use the global AddMethod() function to add a method
+# to the Environment class.  This
+AddMethod(Environment, my_method)
+env = Environment()
+env.my_method('arg')
+
+# Add the function as a method, using the function
+# name for the method call.
+env = Environment()
+env.AddMethod(my_method, 'other_method_name')
+env.other_method_name('another arg')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-AddOption">
+    <term>
+      <literal>AddOption(arguments)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function adds a new command-line option to be recognized.
+The specified
+<varname>arguments</varname>
+are the same as supported by the standard Python
+<function>optparse.add_option</function>()
+method (with a few additional capabilities noted below);
+see the documentation for
+<literal>optparse</literal>
+for a thorough discussion of its option-processing capabities.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+In addition to the arguments and values supported by the
+<function>optparse.add_option</function>()
+method,
+the SCons
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function>
+function allows you to set the
+<literal>nargs</literal>
+keyword value to
+<literal>'?'</literal>
+(a string with just the question mark)
+to indicate that the specified long option(s) take(s) an
+<emphasis>optional</emphasis>
+argument.
+When
+<literal>nargs = '?'</literal>
+is passed to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function>
+function, the
+<literal>const</literal>
+keyword argument
+may be used to supply the "default"
+value that should be used when the
+option is specified on the command line
+without an explicit argument.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If no
+<literal>default=</literal>
+keyword argument is supplied when calling
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function>,
+the option will have a default value of
+<literal>None</literal>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Once a new command-line option has been added with
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function>,
+the option value may be accessed using
+<function xmlns="http://www.scons.org/dbxsd/v1.0">GetOption</function>
+or
+<function>env.GetOption</function>().
+The value may also be set, using
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SetOption</function>
+or
+<function>env.SetOption</function>(),
+if conditions in a
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+require overriding any default value.
+Note, however, that a
+value specified on the command line will
+<emphasis>always</emphasis>
+override a value set by any SConscript file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Any specified
+<literal>help=</literal>
+strings for the new option(s)
+will be displayed by the
+<option>-H</option>
+or
+<option>-h</option>
+options
+(the latter only if no other help text is
+specified in the SConscript files).
+The help text for the local options specified by
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function>
+will appear below the SCons options themselves,
+under a separate
+<literal>Local Options</literal>
+heading.
+The options will appear in the help text
+in the order in which the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function>
+calls occur.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+AddOption('--prefix',
+          dest='prefix',
+          nargs=1, type='string',
+          action='store',
+          metavar='DIR',
+          help='installation prefix')
+env = Environment(PREFIX = GetOption('prefix'))
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-AddPostAction">
+    <term>
+      <literal>AddPostAction(target, action)</literal>
+    </term>
+    <term>
+      <literal>env.AddPostAction(target, action)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Arranges for the specified
+<varname>action</varname>
+to be performed
+after the specified
+<varname>target</varname>
+has been built.
+The specified action(s) may be
+an Action object, or anything that
+can be converted into an Action object
+(see below).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+When multiple targets are supplied,
+the action may be called multiple times,
+once after each action that generates
+one or more targets in the list.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-AddPreAction">
+    <term>
+      <literal>AddPreAction(target, action)</literal>
+    </term>
+    <term>
+      <literal>env.AddPreAction(target, action)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Arranges for the specified
+<varname>action</varname>
+to be performed
+before the specified
+<varname>target</varname>
+is built.
+The specified action(s) may be
+an Action object, or anything that
+can be converted into an Action object
+(see below).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+When multiple targets are specified,
+the action(s) may be called multiple times,
+once before each action that generates
+one or more targets in the list.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that if any of the targets are built in multiple steps,
+the action will be invoked just
+before the "final" action that specifically
+generates the specified target(s).
+For example, when building an executable program
+from a specified source
+<filename>.c</filename>
+file via an intermediate object file:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+foo = Program('foo.c')
+AddPreAction(foo, 'pre_action')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The specified
+<literal>pre_action</literal>
+would be executed before
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+calls the link command that actually
+generates the executable program binary
+<filename>foo</filename>,
+not before compiling the
+<filename>foo.c</filename>
+file into an object file.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Alias">
+    <term>
+      <literal>Alias(alias, [targets, [action]])</literal>
+    </term>
+    <term>
+      <literal>env.Alias(alias, [targets, [action]])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Creates one or more phony targets that
+expand to one or more other targets.
+An optional
+<varname>action</varname>
+(command)
+or list of actions
+can be specified that will be executed
+whenever the any of the alias targets are out-of-date.
+Returns the Node object representing the alias,
+which exists outside of any file system.
+This Node object, or the alias name,
+may be used as a dependency of any other target,
+including another alias.
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Alias</function>
+can be called multiple times for the same
+alias to add additional targets to the alias,
+or additional actions to the list for this alias.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Alias('install')
+Alias('install', '/usr/bin')
+Alias(['install', 'install-lib'], '/usr/local/lib')
+
+env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
+env.Alias('install', ['/usr/local/man'])
+
+env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-AllowSubstExceptions">
+    <term>
+      <literal>AllowSubstExceptions([exception, ...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Specifies the exceptions that will be allowed
+when expanding construction variables.
+By default,
+any construction variable expansions that generate a
+<literal>NameError</literal>
+or
+<literal>IndexError</literal>
+exception will expand to a
+<literal>''</literal>
+(a null string) and not cause scons to fail.
+All exceptions not in the specified list
+will generate an error message
+and terminate processing.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AllowSubstExceptions</function>
+is called multiple times,
+each call completely overwrites the previous list
+of allowed exceptions.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Requires that all construction variable names exist.
+# (You may wish to do this if you want to enforce strictly
+# that all construction variables must be defined before use.)
+AllowSubstExceptions()
+
+# Also allow a string containing a zero-division expansion
+# like '${1 / 0}' to evalute to ''.
+AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-AlwaysBuild">
+    <term>
+      <literal>AlwaysBuild(target, ...)</literal>
+    </term>
+    <term>
+      <literal>env.AlwaysBuild(target, ...)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Marks each given
+<varname>target</varname>
+so that it is always assumed to be out of date,
+and will always be rebuilt if needed.
+Note, however, that
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AlwaysBuild</function>
+does not add its target(s) to the default target list,
+so the targets will only be built
+if they are specified on the command line,
+or are a dependent of a target specified on the command line--but
+they will
+<emphasis>always</emphasis>
+be built if so specified.
+Multiple targets can be passed in to a single call to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">AlwaysBuild</function>.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Append">
+    <term>
+      <literal>env.Append(key=val, [...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Appends the specified keyword arguments
+to the end of construction variables in the environment.
+If the Environment does not have
+the specified construction variable,
+it is simply added to the environment.
+If the values of the construction variable
+and the keyword argument are the same type,
+then the two values will be simply added together.
+Otherwise, the construction variable
+and the value of the keyword argument
+are both coerced to lists,
+and the lists are added together.
+(See also the Prepend method, below.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-AppendENVPath">
+    <term>
+      <literal>env.AppendENVPath(name, newpath, [envname, sep, delete_existing])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This appends new path elements to the given path in the
+specified external environment
+(<literal>ENV</literal>
+by default).
+This will only add
+any particular path once (leaving the last one it encounters and
+ignoring the rest, to preserve path order),
+and to help assure this,
+will normalize all paths (using
+<function>os.path.normpath</function>
+and
+<function>os.path.normcase</function>).
+This can also handle the
+case where the given old path variable is a list instead of a
+string, in which case a list will be returned instead of a string.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If 
+<varname>delete_existing</varname>
+is 0, then adding a path that already exists
+will not move it to the end; it will stay where it is in the list.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+print 'before:',env['ENV']['INCLUDE']
+include_path = '/foo/bar:/foo'
+env.AppendENVPath('INCLUDE', include_path)
+print 'after:',env['ENV']['INCLUDE']
+
+yields:
+before: /foo:/biz
+after: /biz:/foo/bar:/foo
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-AppendUnique">
+    <term>
+      <literal>env.AppendUnique(key=val, [...], delete_existing=0)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Appends the specified keyword arguments
+to the end of construction variables in the environment.
+If the Environment does not have
+the specified construction variable,
+it is simply added to the environment.
+If the construction variable being appended to is a list,
+then any value(s) that already exist in the
+construction variable will
+<emphasis>not</emphasis>
+be added again to the list.
+However, if delete_existing is 1, 
+existing matching values are removed first, so
+existing values in the arg list move to the end of the list.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-BitKeeper">
+    <term>
+      <literal>env.BitKeeper()</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A factory function that
+returns a Builder object
+to be used to fetch source files
+using BitKeeper.
+The returned Builder
+is intended to be passed to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function is deprecated.  For details, see the entry for the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SourceCode('.', env.BitKeeper())
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-BuildDir">
+    <term>
+      <literal>BuildDir(build_dir, src_dir, [duplicate])</literal>
+    </term>
+    <term>
+      <literal>env.BuildDir(build_dir, src_dir, [duplicate])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Deprecated synonyms for
+<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function>
+and
+<function>env.VariantDir</function>().
+The
+<varname>build_dir</varname>
+argument becomes the
+<varname>variant_dir</varname>
+argument of
+<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function>
+or
+<function>env.VariantDir</function>().
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Builder">
+    <term>
+      <literal>Builder(action, [arguments])</literal>
+    </term>
+    <term>
+      <literal>env.Builder(action, [arguments])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Creates a Builder object for
+the specified
+<varname>action</varname>.
+See the section "Builder Objects,"
+below, for a complete explanation of the arguments and behavior.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the
+<function>env.Builder</function>()
+form of the invocation will expand
+construction variables in any arguments strings,
+including the
+<varname>action</varname>
+argument,
+at the time it is called
+using the construction variables in the
+<varname>env</varname>
+construction environment through which
+<function>env.Builder</function>()
+was called.
+The
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Builder</function>
+form delays all variable expansion
+until after the Builder object is actually called.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-CacheDir">
+    <term>
+      <literal>CacheDir(cache_dir)</literal>
+    </term>
+    <term>
+      <literal>env.CacheDir(cache_dir)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Specifies that
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will maintain a cache of derived files in
+<varname>cache_dir</varname>.
+The derived files in the cache will be shared
+among all the builds using the same
+<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function>
+call.
+Specifying a
+<varname>cache_dir</varname>
+of
+<literal>None</literal>
+disables derived file caching.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Calling
+<function>env.CacheDir</function>()
+will only affect targets built
+through the specified construction environment.
+Calling
+<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function>
+sets a global default
+that will be used by all targets built
+through construction environments
+that do
+<emphasis>not</emphasis>
+have an
+<function>env.CacheDir</function>()
+specified.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+When a
+<function>CacheDir</function>()
+is being used and
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+finds a derived file that needs to be rebuilt,
+it will first look in the cache to see if a
+derived file has already been built
+from identical input files and an identical build action
+(as incorporated into the MD5 build signature).
+If so,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will retrieve the file from the cache.
+If the derived file is not present in the cache,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will rebuild it and
+then place a copy of the built file in the cache
+(identified by its MD5 build signature),
+so that it may be retrieved by other
+builds that need to build the same derived file
+from identical inputs.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Use of a specified
+<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function>
+may be disabled for any invocation
+by using the
+<option>--cache-disable</option>
+option.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the
+<option>--cache-force</option>
+option is used,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will place a copy of
+<emphasis>all</emphasis>
+derived files in the cache,
+even if they already existed
+and were not built by this invocation.
+This is useful to populate a cache
+the first time
+<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function>
+is added to a build,
+or after using the
+<option>--cache-disable</option>
+option.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+When using
+<function xmlns="http://www.scons.org/dbxsd/v1.0">CacheDir</function>,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will report,
+"Retrieved `file' from cache,"
+unless the
+<option>--cache-show</option>
+option is being used.
+When the
+<option>--cache-show</option>
+option is used,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will print the action that
+<emphasis>would</emphasis>
+have been used to build the file,
+without any indication that
+the file was actually retrieved from the cache.
+This is useful to generate build logs
+that are equivalent regardless of whether
+a given derived file has been built in-place
+or retrieved from the cache.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-NoCache"><function>NoCache</function></link>
+method can be used to disable caching of specific files.  This can be
+useful if inputs and/or outputs of some tool are impossible to
+predict or prohibitively large.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Clean">
+    <term>
+      <literal>Clean(targets, files_or_dirs)</literal>
+    </term>
+    <term>
+      <literal>env.Clean(targets, files_or_dirs)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This specifies a list of files or directories which should be removed
+whenever the targets are specified with the
+<option>-c</option>
+command line option.
+The specified targets may be a list
+or an individual target.
+Multiple calls to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Clean</function>
+are legal,
+and create new targets or add files and directories to the
+clean list for the specified targets.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Multiple files or directories should be specified
+either as separate arguments to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Clean</function>
+method, or as a list.
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Clean</function>
+will also accept the return value of any of the construction environment
+Builder methods.
+Examples:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The related
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-NoClean"><function>NoClean</function></link>
+function overrides calling
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Clean</function>
+for the same target,
+and any targets passed to both functions will
+<emphasis>not</emphasis>
+be removed by the
+<option>-c</option>
+option.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Clean('foo', ['bar', 'baz'])
+Clean('dist', env.Program('hello', 'hello.c'))
+Clean(['foo', 'bar'], 'something_else_to_clean')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+In this example,
+installing the project creates a subdirectory for the documentation.
+This statement causes the subdirectory to be removed
+if the project is deinstalled.
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Clean(docdir, os.path.join(docdir, projectname))
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Clone">
+    <term>
+      <literal>env.Clone([key=val, ...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns a separate copy of a construction environment.
+If there are any keyword arguments specified,
+they are added to the returned copy,
+overwriting any existing values
+for the keywords.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env2 = env.Clone()
+env3 = env.Clone(CCFLAGS = '-g')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Additionally, a list of tools and a toolpath may be specified, as in
+the Environment constructor:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+def MyTool(env): env['FOO'] = 'bar'
+env4 = env.Clone(tools = ['msvc', MyTool])
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<varname>parse_flags</varname>
+keyword argument is also recognized:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# create an environment for compiling programs that use wxWidgets
+wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Command">
+    <term>
+      <literal>Command(target, source, action, [key=val, ...])</literal>
+    </term>
+    <term>
+      <literal>env.Command(target, source, action, [key=val, ...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Executes a specific action
+(or list of actions)
+to build a target file or files.
+This is more convenient
+than defining a separate Builder object
+for a single special-case build.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+As a special case, the
+<varname>source_scanner</varname>
+keyword argument can
+be used to specify
+a Scanner object
+that will be used to scan the sources.
+(The global
+<literal>DirScanner</literal>
+object can be used
+if any of the sources will be directories
+that must be scanned on-disk for
+changes to files that aren't
+already specified in other Builder of function calls.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Any other keyword arguments specified override any
+same-named existing construction variables.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+An action can be an external command,
+specified as a string,
+or a callable Python object;
+see "Action Objects," below,
+for more complete information.
+Also note that a string specifying an external command
+may be preceded by an
+<literal>@</literal>
+(at-sign)
+to suppress printing the command in question,
+or by a
+<literal>-</literal>
+(hyphen)
+to ignore the exit status of the external command.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Command('foo.out', 'foo.in',
+            "$FOO_BUILD &lt; $SOURCES &gt; $TARGET")
+
+env.Command('bar.out', 'bar.in',
+            ["rm -f $TARGET",
+             "$BAR_BUILD &lt; $SOURCES &gt; $TARGET"],
+            ENV = {'PATH' : '/usr/local/bin/'})
+
+def rename(env, target, source):
+    import os
+    os.rename('.tmp', str(target[0]))
+
+env.Command('baz.out', 'baz.in',
+            ["$BAZ_BUILD &lt; $SOURCES &gt; .tmp",
+	     rename ])
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Command</function>
+function will usually assume, by default,
+that the specified targets and/or sources are Files,
+if no other part of the configuration
+identifies what type of entry it is.
+If necessary, you can explicitly specify
+that targets or source nodes should
+be treated as directoriese
+by using the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Dir"><function>Dir</function></link>
+or
+<function>env.Dir</function>()
+functions.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE &gt; $TARGET')
+
+env['DISTDIR'] = 'destination/directory'
+env.Command(env.Dir('$DISTDIR')), None, make_distdir)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+(Also note that SCons will usually
+automatically create any directory necessary to hold a target file,
+so you normally don't need to create directories by hand.)
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Configure">
+    <term>
+      <literal>Configure(env, [custom_tests, conf_dir, log_file, config_h])</literal>
+    </term>
+    <term>
+      <literal>env.Configure([custom_tests, conf_dir, log_file, config_h])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Creates a Configure object for integrated
+functionality similar to GNU autoconf.
+See the section "Configure Contexts,"
+below, for a complete explanation of the arguments and behavior.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Copy">
+    <term>
+      <literal>env.Copy([key=val, ...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A now-deprecated synonym for
+<function>env.Clone</function>().
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-CVS">
+    <term>
+      <literal>env.CVS(repository, module)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from the specified
+CVS
+<varname>repository</varname>.
+The returned Builder
+is intended to be passed to the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SourceCode"><function>SourceCode</function></link>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function is deprecated.  For details, see the entry for the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The optional specified
+<varname>module</varname>
+will be added to the beginning
+of all repository path names;
+this can be used, in essence,
+to strip initial directory names
+from the repository path names,
+so that you only have to
+replicate part of the repository
+directory hierarchy in your
+local build directory.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Will fetch foo/bar/src.c
+# from /usr/local/CVSROOT/foo/bar/src.c.
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
+
+# Will fetch bar/src.c
+# from /usr/local/CVSROOT/foo/bar/src.c.
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
+
+# Will fetch src.c
+# from /usr/local/CVSROOT/foo/bar/src.c.
+env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Decider">
+    <term>
+      <literal>Decider(function)</literal>
+    </term>
+    <term>
+      <literal>env.Decider(function)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Specifies that all up-to-date decisions for
+targets built through this construction environment
+will be handled by the specified
+<varname>function</varname>.
+The
+<varname>function</varname>
+can be one of the following strings
+that specify the type of decision function
+to be performed:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<variablelist>
+<varlistentry>
+<term><literal>timestamp-newer</literal></term>
+<listitem>
+<para>
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's timestamp is newer than the target file's timestamp.
+This is the behavior of the classic Make utility,
+and
+<literal>make</literal>
+can be used a synonym for
+<literal>timestamp-newer</literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>timestamp-match</literal></term>
+<listitem>
+<para>
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's timestamp is different than the
+timestamp recorded the last time the target was built.
+This provides behavior very similar to the classic Make utility
+(in particular, files are not opened up so that their
+contents can be checksummed)
+except that the target will also be rebuilt if a
+dependency file has been restored to a version with an
+<emphasis>earlier</emphasis>
+timestamp, such as can happen when restoring files from backup archives.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>MD5</literal></term>
+<listitem>
+<para>
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's content has changed sine the last time
+the target was built,
+as determined be performing an MD5 checksum
+on the dependency's contents
+and comparing it to the checksum recorded the
+last time the target was built.
+<literal>content</literal>
+can be used as a synonym for
+<literal>MD5</literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>MD5-timestamp</literal></term>
+<listitem>
+<para>
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's content has changed sine the last time
+the target was built,
+except that dependencies with a timestamp that matches
+the last time the target was rebuilt will be
+assumed to be up-to-date and
+<emphasis>not</emphasis>
+rebuilt.
+This provides behavior very similar
+to the
+<literal>MD5</literal>
+behavior of always checksumming file contents,
+with an optimization of not checking
+the contents of files whose timestamps haven't changed.
+The drawback is that SCons will
+<emphasis>not</emphasis>
+detect if a file's content has changed
+but its timestamp is the same,
+as might happen in an automated script
+that runs a build,
+updates a file,
+and runs the build again,
+all within a single second.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Use exact timestamp matches by default.
+Decider('timestamp-match')
+
+# Use MD5 content signatures for any targets built
+# with the attached construction environment.
+env.Decider('content')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+In addition to the above already-available functions,
+the
+<varname>function</varname>
+argument may be an actual Python function
+that takes the following three arguments:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<variablelist>
+<varlistentry>
+<term><parameter>dependency</parameter></term>
+<listitem>
+<para>
+The Node (file) which
+should cause the
+<varname>target</varname>
+to be rebuilt
+if it has "changed" since the last tme
+<varname>target</varname>
+was built.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><parameter>target</parameter></term>
+<listitem>
+<para>
+The Node (file) being built.
+In the normal case,
+this is what should get rebuilt
+if the
+<varname>dependency</varname>
+has "changed."
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><parameter>prev_ni</parameter></term>
+<listitem>
+<para>
+Stored information about the state of the
+<varname>dependency</varname>
+the last time the
+<varname>target</varname>
+was built.
+This can be consulted to match various
+file characteristics
+such as the timestamp,
+size, or content signature.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<varname>function</varname>
+should return a
+<literal>True</literal>
+(non-zero)
+value if the
+<varname>dependency</varname>
+has "changed" since the last time
+the
+<varname>target</varname>
+was built
+(indicating that the target
+<emphasis>should</emphasis>
+be rebuilt),
+and
+<literal>False</literal>
+(zero)
+otherwise
+(indicating that the target should
+<emphasis>not</emphasis>
+be rebuilt).
+Note that the decision can be made
+using whatever criteria are appopriate.
+Ignoring some or all of the function arguments
+is perfectly normal.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+def my_decider(dependency, target, prev_ni):
+    return not os.path.exists(str(target))
+
+env.Decider(my_decider)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Default">
+    <term>
+      <literal>Default(targets)</literal>
+    </term>
+    <term>
+      <literal>env.Default(targets)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This specifies a list of default targets,
+which will be built by
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+if no explicit targets are given on the command line.
+Multiple calls to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function>
+are legal,
+and add to the list of default targets.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Multiple targets should be specified as
+separate arguments to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function>
+method, or as a list.
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function>
+will also accept the Node returned by any
+of a construction environment's
+builder methods.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Default('foo', 'bar', 'baz')
+env.Default(['a', 'b', 'c'])
+hello = env.Program('hello', 'hello.c')
+env.Default(hello)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+An argument to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function>
+of
+<literal>None</literal>
+will clear all default targets.
+Later calls to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function>
+will add to the (now empty) default-target list
+like normal.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The current list of targets added using the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Default</function>
+function or method is available in the
+<literal>DEFAULT_TARGETS</literal>
+list;
+see below.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-DefaultEnvironment">
+    <term>
+      <literal>DefaultEnvironment([args])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Creates and returns a default construction environment object.
+This construction environment is used internally by SCons
+in order to execute many of the global functions in this list,
+and to fetch source files transparently
+from source code management systems.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Depends">
+    <term>
+      <literal>Depends(target, dependency)</literal>
+    </term>
+    <term>
+      <literal>env.Depends(target, dependency)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Specifies an explicit dependency;
+the
+<varname>target</varname>
+will be rebuilt
+whenever the
+<varname>dependency</varname>
+has changed.
+Both the specified
+<varname>target</varname>
+and
+<varname>dependency</varname>
+can be a string
+(usually the path name of a file or directory)
+or Node objects,
+or a list of strings or Node objects
+(such as returned by a Builder call).
+This should only be necessary
+for cases where the dependency
+is not caught by a Scanner
+for the file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Depends('foo', 'other-input-file-for-foo')
+
+mylib = env.Library('mylib.c')
+installed_lib = env.Install('lib', mylib)
+bar = env.Program('bar.c')
+
+# Arrange for the library to be copied into the installation
+# directory before trying to build the "bar" program.
+# (Note that this is for example only.  A "real" library
+# dependency would normally be configured through the $LIBS
+# and $LIBPATH variables, not using an env.Depends() call.)
+
+env.Depends(bar, installed_lib)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Dictionary">
+    <term>
+      <literal>env.Dictionary([vars])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns a dictionary object
+containing copies of all of the
+construction variables in the environment.
+If there are any variable names specified,
+only the specified construction
+variables are returned in the dictionary.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+dict = env.Dictionary()
+cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Dir">
+    <term>
+      <literal>Dir(name, [directory])</literal>
+    </term>
+    <term>
+      <literal>env.Dir(name, [directory])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This returns a Directory Node,
+an object that represents the specified directory
+<varname>name</varname>.
+<varname>name</varname>
+can be a relative or absolute path.
+<varname>directory</varname>
+is an optional directory that will be used as the parent directory.
+If no
+<varname>directory</varname>
+is specified, the current script's directory is used as the parent.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If
+<varname>name</varname>
+is a list, SCons returns a list of Dir nodes.
+Construction variables are expanded in
+<varname>name</varname>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Directory Nodes can be used anywhere you
+would supply a string as a directory name
+to a Builder method or function.
+Directory Nodes have attributes and methods
+that are useful in many situations;
+see "File and Directory Nodes," below.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Dump">
+    <term>
+      <literal>env.Dump([key])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns a pretty printable representation of the environment.
+<varname>key</varname>,
+if not
+<literal>None</literal>,
+should be a string containing the name of the variable of interest.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This SConstruct:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env=Environment()
+print env.Dump('CCCOM')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+will print:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+While this SConstruct:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env=Environment()
+print env.Dump()
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+will print:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+{ 'AR': 'ar',
+  'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
+  'ARFLAGS': ['r'],
+  'AS': 'as',
+  'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
+  'ASFLAGS': [],
+  ...
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-EnsurePythonVersion">
+    <term>
+      <literal>EnsurePythonVersion(major, minor)</literal>
+    </term>
+    <term>
+      <literal>env.EnsurePythonVersion(major, minor)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Ensure that the Python version is at least
+<varname>major</varname>.<varname>minor</varname>.
+This function will
+print out an error message and exit SCons with a non-zero exit code if the
+actual Python version is not late enough.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+EnsurePythonVersion(2,2)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-EnsureSConsVersion">
+    <term>
+      <literal>EnsureSConsVersion(major, minor, [revision])</literal>
+    </term>
+    <term>
+      <literal>env.EnsureSConsVersion(major, minor, [revision])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Ensure that the SCons version is at least
+<varname>major.minor</varname>,
+or
+<varname>major.minor.revision</varname>.
+if
+<varname>revision</varname>
+is specified.
+This function will
+print out an error message and exit SCons with a non-zero exit code if the
+actual SCons version is not late enough.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+EnsureSConsVersion(0,14)
+
+EnsureSConsVersion(0,96,90)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Environment">
+    <term>
+      <literal>Environment([key=value, ...])</literal>
+    </term>
+    <term>
+      <literal>env.Environment([key=value, ...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Return a new construction environment
+initialized with the specified
+<varname>key</varname><literal>=</literal><varname>value</varname>
+pairs.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Execute">
+    <term>
+      <literal>Execute(action, [strfunction, varlist])</literal>
+    </term>
+    <term>
+      <literal>env.Execute(action, [strfunction, varlist])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Executes an Action object.
+The specified
+<varname>action</varname>
+may be an Action object
+(see the section "Action Objects,"
+below, for a complete explanation of the arguments and behavior),
+or it may be a command-line string,
+list of commands,
+or executable Python function,
+each of which will be converted
+into an Action object
+and then executed.
+The exit value of the command
+or return value of the Python function
+will be returned.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will print an error message if the executed
+<varname>action</varname>
+fails--that is,
+exits with or returns a non-zero value.
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will
+<emphasis>not</emphasis>,
+however,
+automatically terminate the build
+if the specified
+<varname>action</varname>
+fails.
+If you want the build to stop in response to a failed
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Execute</function>
+call,
+you must explicitly check for a non-zero return value:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Execute(Copy('file.out', 'file.in'))
+
+if Execute("mkdir sub/dir/ectory"):
+    # The mkdir failed, don't try to build.
+    Exit(1)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Exit">
+    <term>
+      <literal>Exit([value])</literal>
+    </term>
+    <term>
+      <literal>env.Exit([value])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This tells
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+to exit immediately
+with the specified
+<varname>value</varname>.
+A default exit value of
+<literal>0</literal>
+(zero)
+is used if no value is specified.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Export">
+    <term>
+      <literal>Export(vars)</literal>
+    </term>
+    <term>
+      <literal>env.Export(vars)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This tells
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+to export a list of variables from the current
+SConscript file to all other SConscript files.
+The exported variables are kept in a global collection,
+so subsequent calls to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Export</function>
+will over-write previous exports that have the same name.
+Multiple variable names can be passed to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Export</function>
+as separate arguments or as a list.
+Keyword arguments can be used to provide names and their values.
+A dictionary can be used to map variables to a different name when exported.
+Both local variables and global variables can be exported.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env = Environment()
+# Make env available for all SConscript files to Import().
+Export("env")
+
+package = 'my_name'
+# Make env and package available for all SConscript files:.
+Export("env", "package")
+
+# Make env and package available for all SConscript files:
+Export(["env", "package"])
+
+# Make env available using the name debug:
+Export(debug = env)
+
+# Make env available using the name debug:
+Export({"debug":env})
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function>
+function supports an
+<varname>exports</varname>
+argument that makes it easier to to export a variable or
+set of variables to a single SConscript file.
+See the description of the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function>
+function, below.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-File">
+    <term>
+      <literal>File(name, [directory])</literal>
+    </term>
+    <term>
+      <literal>env.File(name, [directory])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This returns a
+File Node,
+an object that represents the specified file
+<varname>name</varname>.
+<varname>name</varname>
+can be a relative or absolute path.
+<varname>directory</varname>
+is an optional directory that will be used as the parent directory.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If
+<varname>name</varname>
+is a list, SCons returns a list of File nodes.
+Construction variables are expanded in
+<varname>name</varname>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+File Nodes can be used anywhere you
+would supply a string as a file name
+to a Builder method or function.
+File Nodes have attributes and methods
+that are useful in many situations;
+see "File and Directory Nodes," below.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-FindFile">
+    <term>
+      <literal>FindFile(file, dirs)</literal>
+    </term>
+    <term>
+      <literal>env.FindFile(file, dirs)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Search for
+<varname>file</varname>
+in the path specified by
+<varname>dirs</varname>.
+<varname>dirs</varname>
+may be a list of directory names or a single directory name.
+In addition to searching for files that exist in the filesystem,
+this function also searches for derived files
+that have not yet been built.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+foo = env.FindFile('foo', ['dir1', 'dir2'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-FindInstalledFiles">
+    <term>
+      <literal>FindInstalledFiles()</literal>
+    </term>
+    <term>
+      <literal>env.FindInstalledFiles()</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns the list of targets set up by the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Install"><function>Install</function></link>
+or
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-InstallAs"><function>InstallAs</function></link>
+builders.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function serves as a convenient method to select the contents of
+a binary package.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Install( '/bin', [ 'executable_a', 'executable_b' ] )
+
+# will return the file node list
+# [ '/bin/executable_a', '/bin/executable_b' ]
+FindInstalledFiles()
+
+Install( '/lib', [ 'some_library' ] )
+
+# will return the file node list
+# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
+FindInstalledFiles()
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-FindPathDirs">
+    <term>
+      <literal>FindPathDirs(variable)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns a function
+(actually a callable Python object)
+intended to be used as the
+<varname>path_function</varname>
+of a Scanner object.
+The returned object will look up the specified
+<varname>variable</varname>
+in a construction environment
+and treat the construction variable's value as a list of
+directory paths that should be searched
+(like
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CPPPATH"><envar>$CPPPATH</envar></link>,
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LIBPATH"><envar>$LIBPATH</envar></link>,
+etc.).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that use of
+<function xmlns="http://www.scons.org/dbxsd/v1.0">FindPathDirs</function>
+is generally preferable to
+writing your own
+<varname>path_function</varname>
+for the following reasons:
+1) The returned list will contain all appropriate directories
+found in source trees
+(when
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-VariantDir"><function>VariantDir</function></link>
+is used)
+or in code repositories
+(when
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Repository</function>
+or the
+<option>-Y</option>
+option are used).
+2) scons will identify expansions of
+<varname>variable</varname>
+that evaluate to the same list of directories as,
+in fact, the same list,
+and avoid re-scanning the directories for files,
+when possible.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+def my_scan(node, env, path, arg):
+    # Code to scan file contents goes here...
+    return include_files
+
+scanner = Scanner(name = 'myscanner',
+                  function = my_scan,
+                  path_function = FindPathDirs('MYPATH'))
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-FindSourceFiles">
+    <term>
+      <literal>FindSourceFiles(node='"."')</literal>
+    </term>
+    <term>
+      <literal>env.FindSourceFiles(node='"."')</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns the list of nodes which serve as the source of the built files.
+It does so by inspecting the dependency tree starting at the optional
+argument
+<varname>node</varname>
+which defaults to the '"."'-node. It will then return all leaves of
+<varname>node</varname>.
+These are all children which have no further children.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function is a convenient method to select the contents of a Source
+Package.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Program( 'src/main_a.c' )
+Program( 'src/main_b.c' )
+Program( 'main_c.c' )
+
+# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
+FindSourceFiles()
+
+# returns ['src/main_b.c', 'src/main_a.c' ]
+FindSourceFiles( 'src' )
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+As you can see build support files (SConstruct in the above example)
+will also be returned by this function.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Flatten">
+    <term>
+      <literal>Flatten(sequence)</literal>
+    </term>
+    <term>
+      <literal>env.Flatten(sequence)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Takes a sequence (that is, a Python list or tuple)
+that may contain nested sequences
+and returns a flattened list containing
+all of the individual elements in any sequence.
+This can be helpful for collecting
+the lists returned by calls to Builders;
+other Builders will automatically
+flatten lists specified as input,
+but direct Python manipulation of
+these lists does not.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+foo = Object('foo.c')
+bar = Object('bar.c')
+
+# Because `foo' and `bar' are lists returned by the Object() Builder,
+# `objects' will be a list containing nested lists:
+objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
+
+# Passing such a list to another Builder is all right because
+# the Builder will flatten the list automatically:
+Program(source = objects)
+
+# If you need to manipulate the list directly using Python, you need to
+# call Flatten() yourself, or otherwise handle nested lists:
+for object in Flatten(objects):
+    print str(object)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-GetBuildFailures">
+    <term>
+      <literal>GetBuildFailures()</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns a list of exceptions for the
+actions that failed while
+attempting to build targets.
+Each element in the returned list is a
+<classname>BuildError</classname>
+object
+with the following attributes
+that record various aspects
+of the build failure:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>.node</literal>
+The node that was being built
+when the build failure occurred.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>.status</literal>
+The numeric exit status
+returned by the command or Python function
+that failed when trying to build the
+specified Node.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>.errstr</literal>
+The SCons error string
+describing the build failure.
+(This is often a generic
+message like "Error 2"
+to indicate that an executed
+command exited with a status of 2.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>.filename</literal>
+The name of the file or
+directory that actually caused the failure.
+This may be different from the
+<literal>.node</literal>
+attribute.
+For example,
+if an attempt to build a target named
+<filename>sub/dir/target</filename>
+fails because the
+<filename>sub/dir</filename>
+directory could not be created,
+then the
+<literal>.node</literal>
+attribute will be
+<filename>sub/dir/target</filename>
+but the
+<literal>.filename</literal>
+attribute will be
+<filename>sub/dir</filename>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>.executor</literal>
+The SCons Executor object
+for the target Node
+being built.
+This can be used to retrieve
+the construction environment used
+for the failed action.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>.action</literal>
+The actual SCons Action object that failed.
+This will be one specific action
+out of the possible list of
+actions that would have been
+executed to build the target.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>.command</literal>
+The actual expanded command that was executed and failed,
+after expansion of
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-TARGET"><envar>$TARGET</envar></link>,
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SOURCE"><envar>$SOURCE</envar></link>,
+and other construction variables.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">GetBuildFailures</function>
+function
+will always return an empty list
+until any build failure has occurred,
+which means that
+<function xmlns="http://www.scons.org/dbxsd/v1.0">GetBuildFailures</function>
+will always return an empty list
+while the
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+files are being read.
+Its primary intended use is
+for functions that will be
+executed before SCons exits
+by passing them to the
+standard Python
+<function>atexit.register</function>()
+function.
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+import atexit
+
+def print_build_failures():
+    from SCons.Script import GetBuildFailures
+    for bf in GetBuildFailures():
+        print "%s failed: %s" % (bf.node, bf.errstr)
+
+atexit.register(print_build_failures)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-GetBuildPath">
+    <term>
+      <literal>GetBuildPath(file, [...])</literal>
+    </term>
+    <term>
+      <literal>env.GetBuildPath(file, [...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns the
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+path name (or names) for the specified
+<varname>file</varname>
+(or files).
+The specified
+<varname>file</varname>
+or files
+may be
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+Nodes or strings representing path names.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-GetLaunchDir">
+    <term>
+      <literal>GetLaunchDir()</literal>
+    </term>
+    <term>
+      <literal>env.GetLaunchDir()</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns the absolute path name of the directory from which
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+was initially invoked.
+This can be useful when using the
+<option>-u</option>,
+<option>-U</option>
+or
+<option>-D</option>
+options, which internally
+change to the directory in which the
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename>
+file is found.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-GetOption">
+    <term>
+      <literal>GetOption(name)</literal>
+    </term>
+    <term>
+      <literal>env.GetOption(name)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function provides a way to query the value of
+SCons options set on scons command line
+(or set using the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SetOption"><function>SetOption</function></link>
+function).
+The options supported are:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<variablelist>
+<varlistentry>
+<term><literal>cache_debug</literal></term>
+<listitem>
+<para>
+which corresponds to --cache-debug;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>cache_disable</literal></term>
+<listitem>
+<para>
+which corresponds to --cache-disable;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>cache_force</literal></term>
+<listitem>
+<para>
+which corresponds to --cache-force;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>cache_show</literal></term>
+<listitem>
+<para>
+which corresponds to --cache-show;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>clean</literal></term>
+<listitem>
+<para>
+which corresponds to -c, --clean and --remove;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>config</literal></term>
+<listitem>
+<para>
+which corresponds to --config;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>directory</literal></term>
+<listitem>
+<para>
+which corresponds to -C and --directory;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>diskcheck</literal></term>
+<listitem>
+<para>
+which corresponds to --diskcheck
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>duplicate</literal></term>
+<listitem>
+<para>
+which corresponds to --duplicate;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>file</literal></term>
+<listitem>
+<para>
+which corresponds to -f, --file, --makefile and --sconstruct;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>help</literal></term>
+<listitem>
+<para>
+which corresponds to -h and --help;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>ignore_errors</literal></term>
+<listitem>
+<para>
+which corresponds to --ignore-errors;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>implicit_cache</literal></term>
+<listitem>
+<para>
+which corresponds to --implicit-cache;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>implicit_deps_changed</literal></term>
+<listitem>
+<para>
+which corresponds to --implicit-deps-changed;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>implicit_deps_unchanged</literal></term>
+<listitem>
+<para>
+which corresponds to --implicit-deps-unchanged;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>interactive</literal></term>
+<listitem>
+<para>
+which corresponds to --interact and --interactive;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>keep_going</literal></term>
+<listitem>
+<para>
+which corresponds to -k and --keep-going;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>max_drift</literal></term>
+<listitem>
+<para>
+which corresponds to --max-drift;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>no_exec</literal></term>
+<listitem>
+<para>
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>no_site_dir</literal></term>
+<listitem>
+<para>
+which corresponds to --no-site-dir;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>num_jobs</literal></term>
+<listitem>
+<para>
+which corresponds to -j and --jobs;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>profile_file</literal></term>
+<listitem>
+<para>
+which corresponds to --profile;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>question</literal></term>
+<listitem>
+<para>
+which corresponds to -q and --question;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>random</literal></term>
+<listitem>
+<para>
+which corresponds to --random;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>repository</literal></term>
+<listitem>
+<para>
+which corresponds to -Y, --repository and --srcdir;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>silent</literal></term>
+<listitem>
+<para>
+which corresponds to -s, --silent and --quiet;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>site_dir</literal></term>
+<listitem>
+<para>
+which corresponds to --site-dir;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>stack_size</literal></term>
+<listitem>
+<para>
+which corresponds to --stack-size;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>taskmastertrace_file</literal></term>
+<listitem>
+<para>
+which corresponds to --taskmastertrace; and
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>warn</literal></term>
+<listitem>
+<para>
+which corresponds to --warn and --warning.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+See the documentation for the
+corresponding command line object for information about each specific
+option.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Glob">
+    <term>
+      <literal>Glob(pattern, [ondisk, source, strings])</literal>
+    </term>
+    <term>
+      <literal>env.Glob(pattern, [ondisk, source, strings])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns Nodes (or strings) that match the specified
+<varname>pattern</varname>,
+relative to the directory of the current
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+file.
+The
+<function>env.Glob</function>()
+form performs string substition on
+<varname>pattern</varname>
+and returns whatever matches
+the resulting expanded pattern.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The specified
+<varname>pattern</varname>
+uses Unix shell style metacharacters for matching:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  *       matches everything
+  ?       matches any single character
+  [seq]   matches any character in seq
+  [!seq]  matches any char not in seq
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the first character of a filename is a dot,
+it must be matched explicitly.
+Character matches do
+<emphasis>not</emphasis>
+span directory separators.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Glob</function>
+knows about
+repositories
+(see the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Repository"><function>Repository</function></link>
+function)
+and source directories
+(see the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-VariantDir"><function>VariantDir</function></link>
+function)
+and
+returns a Node (or string, if so configured)
+in the local (SConscript) directory
+if matching Node is found
+anywhere in a corresponding
+repository or source directory.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<varname>ondisk</varname>
+argument may be set to
+<literal>False</literal>
+(or any other non-true value)
+to disable the search for matches on disk,
+thereby only returning matches among
+already-configured File or Dir Nodes.
+The default behavior is to
+return corresponding Nodes
+for any on-disk matches found.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<varname>source</varname>
+argument may be set to
+<literal>True</literal>
+(or any equivalent value)
+to specify that,
+when the local directory is a
+<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function>,
+the returned Nodes should be from the
+corresponding source directory,
+not the local directory.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<varname>strings</varname>
+argument may be set to
+<literal>True</literal>
+(or any equivalent value)
+to have the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Glob</function>
+function return strings, not Nodes,
+that represent the matched files or directories.
+The returned strings will be relative to
+the local (SConscript) directory.
+(Note that This may make it easier to perform
+arbitrary manipulation of file names,
+but if the returned strings are
+passed to a different
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+file,
+any Node translation will be relative
+to the other
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+directory,
+not the original
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+directory.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Program('foo', Glob('*.c'))
+Zip('/tmp/everything', Glob('.??*') + Glob('*'))
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Help">
+    <term>
+      <literal>Help(text)</literal>
+    </term>
+    <term>
+      <literal>env.Help(text)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This specifies help text to be printed if the
+<option>-h</option>
+argument is given to
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>.
+If
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Help</function>
+is called multiple times, the text is appended together in the order
+that
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Help</function>
+is called.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Ignore">
+    <term>
+      <literal>Ignore(target, dependency)</literal>
+    </term>
+    <term>
+      <literal>env.Ignore(target, dependency)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The specified dependency file(s)
+will be ignored when deciding if
+the target file(s) need to be rebuilt.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+You can also use
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Ignore</function>
+to remove a target from the default build.
+In order to do this you must specify the directory the target will
+be built in as the target, and the file you want to skip building
+as the dependency.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that this will only remove the dependencies listed from 
+the files built by default.  It will still be built if that 
+dependency is needed by another object being built. 
+See the third and forth examples below.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Ignore('foo', 'foo.c')
+env.Ignore('bar', ['bar1.h', 'bar2.h'])
+env.Ignore('.','foobar.obj')
+env.Ignore('bar','bar/foobar.obj')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Import">
+    <term>
+      <literal>Import(vars)</literal>
+    </term>
+    <term>
+      <literal>env.Import(vars)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This tells
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+to import a list of variables into the current SConscript file. This
+will import variables that were exported with
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Export</function>
+or in the
+<varname>exports</varname>
+argument to
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SConscript"><function>SConscript</function></link>.
+Variables exported by
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function>
+have precedence.
+Multiple variable names can be passed to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Import</function>
+as separate arguments or as a list. The variable "*" can be used
+to import all variables.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Import("env")
+Import("env", "variable")
+Import(["env", "variable"])
+Import("*")
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Literal">
+    <term>
+      <literal>Literal(string)</literal>
+    </term>
+    <term>
+      <literal>env.Literal(string)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The specified
+<varname>string</varname>
+will be preserved as-is
+and not have construction variables expanded.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Local">
+    <term>
+      <literal>Local(targets)</literal>
+    </term>
+    <term>
+      <literal>env.Local(targets)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The specified
+<varname>targets</varname>
+will have copies made in the local tree,
+even if an already up-to-date copy
+exists in a repository.
+Returns a list of the target Node or Nodes.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-MergeFlags">
+    <term>
+      <literal>env.MergeFlags(arg, [unique])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Merges the specified
+<varname>arg</varname>
+values to the construction environment's construction variables.
+If the
+<varname>arg</varname>
+argument is not a dictionary,
+it is converted to one by calling
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-ParseFlags"><function>env.ParseFlags</function></link>
+on the argument
+before the values are merged.
+Note that
+<varname>arg</varname>
+must be a single value,
+so multiple strings must
+be passed in as a list,
+not as separate arguments to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">env.MergeFlags</function>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+By default,
+duplicate values are eliminated;
+you can, however, specify
+<literal>unique=0</literal>
+to allow duplicate
+values to be added.
+When eliminating duplicate values,
+any construction variables that end with
+the string
+<literal>PATH</literal>
+keep the left-most unique value.
+All other construction variables keep
+the right-most unique value.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Add an optimization flag to $CCFLAGS.
+env.MergeFlags('-O3')
+
+# Combine the flags returned from running pkg-config with an optimization
+# flag and merge the result into the construction variables.
+env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
+
+# Combine an optimization flag with the flags returned from running pkg-config
+# twice and merge the result into the construction variables.
+env.MergeFlags(['-O3',
+               '!pkg-config gtk+-2.0 --cflags --libs',
+               '!pkg-config libpng12 --cflags --libs'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-NoCache">
+    <term>
+      <literal>NoCache(target, ...)</literal>
+    </term>
+    <term>
+      <literal>env.NoCache(target, ...)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Specifies a list of files which should
+<emphasis>not</emphasis>
+be cached whenever the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-CacheDir"><function>CacheDir</function></link>
+method has been activated.
+The specified targets may be a list
+or an individual target.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Multiple files should be specified
+either as separate arguments to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">NoCache</function>
+method, or as a list.
+<function xmlns="http://www.scons.org/dbxsd/v1.0">NoCache</function>
+will also accept the return value of any of the construction environment
+Builder methods.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Calling
+<function xmlns="http://www.scons.org/dbxsd/v1.0">NoCache</function>
+on directories and other non-File Node types has no effect because
+only File Nodes are cached.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+NoCache('foo.elf')
+NoCache(env.Program('hello', 'hello.c'))
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-NoClean">
+    <term>
+      <literal>NoClean(target, ...)</literal>
+    </term>
+    <term>
+      <literal>env.NoClean(target, ...)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Specifies a list of files or directories which should
+<emphasis>not</emphasis>
+be removed whenever the targets (or their dependencies)
+are specified with the
+<option>-c</option>
+command line option.
+The specified targets may be a list
+or an individual target.
+Multiple calls to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">NoClean</function>
+are legal,
+and prevent each specified target
+from being removed by calls to the
+<option>-c</option>
+option.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Multiple files or directories should be specified
+either as separate arguments to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">NoClean</function>
+method, or as a list.
+<function xmlns="http://www.scons.org/dbxsd/v1.0">NoClean</function>
+will also accept the return value of any of the construction environment
+Builder methods.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Calling
+<function xmlns="http://www.scons.org/dbxsd/v1.0">NoClean</function>
+for a target overrides calling
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Clean"><function>Clean</function></link>
+for the same target,
+and any targets passed to both functions will
+<emphasis>not</emphasis>
+be removed by the
+<option>-c</option>
+option.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+NoClean('foo.elf')
+NoClean(env.Program('hello', 'hello.c'))
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-ParseConfig">
+    <term>
+      <literal>env.ParseConfig(command, [function, unique])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Calls the specified
+<varname>function</varname>
+to modify the environment as specified by the output of
+<varname>command</varname>.
+The default
+<varname>function</varname>
+is
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-MergeFlags"><function>env.MergeFlags</function></link>,
+which expects the output of a typical
+<application>*-config</application>
+command
+(for example,
+<application>gtk-config</application>)
+and adds the options
+to the appropriate construction variables.
+By default,
+duplicate values are not
+added to any construction variables;
+you can specify
+<literal>unique=0</literal>
+to allow duplicate
+values to be added.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Interpreted options
+and the construction variables they affect
+are as specified for the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-ParseFlags"><function>env.ParseFlags</function></link>
+method (which this method calls).
+See that method's description, below,
+for a table of options and construction variables.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-ParseDepends">
+    <term>
+      <literal>ParseDepends(filename, [must_exist, only_one])</literal>
+    </term>
+    <term>
+      <literal>env.ParseDepends(filename, [must_exist, only_one])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Parses the contents of the specified
+<varname>filename</varname>
+as a list of dependencies in the style of
+<application xmlns="http://www.scons.org/dbxsd/v1.0">Make</application>
+or
+<application>mkdep</application>,
+and explicitly establishes all of the listed dependencies.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+By default,
+it is not an error
+if the specified
+<varname>filename</varname>
+does not exist.
+The optional
+<varname>must_exist</varname>
+argument may be set to a non-zero
+value to have
+scons
+throw an exception and
+generate an error if the file does not exist,
+or is otherwise inaccessible.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The optional
+<varname>only_one</varname>
+argument may be set to a non-zero
+value to have
+scons
+thrown an exception and
+generate an error
+if the file contains dependency
+information for more than one target.
+This can provide a small sanity check
+for files intended to be generated
+by, for example, the
+<literal>gcc -M</literal>
+flag,
+which should typically only
+write dependency information for
+one output file into a corresponding
+<filename>.d</filename>
+file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<varname>filename</varname>
+and all of the files listed therein
+will be interpreted relative to
+the directory of the
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+file which calls the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">ParseDepends</function>
+function.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-ParseFlags">
+    <term>
+      <literal>env.ParseFlags(flags, ...)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Parses one or more strings containing
+typical command-line flags for GCC tool chains
+and returns a dictionary with the flag values
+separated into the appropriate SCons construction variables.
+This is intended as a companion to the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-MergeFlags"><function>env.MergeFlags</function></link>
+method, but allows for the values in the returned dictionary
+to be modified, if necessary,
+before merging them into the construction environment.
+(Note that
+<function xmlns="http://www.scons.org/dbxsd/v1.0">env.MergeFlags</function>
+will call this method if its argument is not a dictionary,
+so it is usually not necessary to call
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-ParseFlags"><function>env.ParseFlags</function></link>
+directly unless you want to manipulate the values.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the first character in any string is
+an exclamation mark (!),
+the rest of the string is executed as a command,
+and the output from the command is
+parsed as GCC tool chain command-line flags
+and added to the resulting dictionary.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Flag values are translated accordig to the prefix found,
+and added to the following construction variables:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+-arch               CCFLAGS, LINKFLAGS
+-D                  CPPDEFINES
+-framework          FRAMEWORKS
+-frameworkdir=      FRAMEWORKPATH
+-include            CCFLAGS
+-isysroot           CCFLAGS, LINKFLAGS
+-I                  CPPPATH
+-l                  LIBS
+-L                  LIBPATH
+-mno-cygwin         CCFLAGS, LINKFLAGS
+-mwindows           LINKFLAGS
+-pthread            CCFLAGS, LINKFLAGS
+-std=               CFLAGS
+-Wa,                ASFLAGS, CCFLAGS
+-Wl,-rpath=         RPATH
+-Wl,-R,             RPATH
+-Wl,-R              RPATH
+-Wl,                LINKFLAGS
+-Wp,                CPPFLAGS
+-                   CCFLAGS
++                   CCFLAGS, LINKFLAGS
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Any other strings not associated with options
+are assumed to be the names of libraries
+and added to the
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$LIBS</envar>
+construction variable.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples (all of which produce the same result):
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
+dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
+dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
+dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Perforce">
+    <term>
+      <literal>env.Perforce()</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from the Perforce source code management system.
+The returned Builder
+is intended to be passed to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function is deprecated.  For details, see the entry for the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SourceCode('.', env.Perforce())
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Perforce uses a number of external
+environment variables for its operation.
+Consequently, this function adds the
+following variables from the user's external environment
+to the construction environment's
+ENV dictionary:
+P4CHARSET,
+P4CLIENT,
+P4LANGUAGE,
+P4PASSWD,
+P4PORT,
+P4USER,
+SystemRoot,
+USER,
+and
+USERNAME.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Platform">
+    <term>
+      <literal>Platform(string)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Platform</function>
+form returns a callable object
+that can be used to initialize
+a construction environment using the
+platform keyword of the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Environment</function>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env = Environment(platform = Platform('win32'))
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<function xmlns="http://www.scons.org/dbxsd/v1.0">env.Platform</function>
+form applies the callable object for the specified platform
+<varname>string</varname>
+to the environment through which the method was called.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Platform('posix')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the
+<literal>win32</literal>
+platform adds the
+<literal>SystemDrive</literal>
+and
+<literal>SystemRoot</literal>
+variables from the user's external environment
+to the construction environment's
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-ENV"><envar>$ENV</envar></link>
+dictionary.
+This is so that any executed commands
+that use sockets to connect with other systems
+(such as fetching source files from
+external CVS repository specifications like
+<literal>:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</literal>)
+will work on Windows systems.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Precious">
+    <term>
+      <literal>Precious(target, ...)</literal>
+    </term>
+    <term>
+      <literal>env.Precious(target, ...)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Marks each given
+<varname>target</varname>
+as precious so it is not deleted before it is rebuilt. Normally
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+deletes a target before building it.
+Multiple targets can be passed in to a single call to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Precious</function>.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Prepend">
+    <term>
+      <literal>env.Prepend(key=val, [...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Appends the specified keyword arguments
+to the beginning of construction variables in the environment.
+If the Environment does not have
+the specified construction variable,
+it is simply added to the environment.
+If the values of the construction variable
+and the keyword argument are the same type,
+then the two values will be simply added together.
+Otherwise, the construction variable
+and the value of the keyword argument
+are both coerced to lists,
+and the lists are added together.
+(See also the Append method, above.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-PrependENVPath">
+    <term>
+      <literal>env.PrependENVPath(name, newpath, [envname, sep, delete_existing])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This appends new path elements to the given path in the
+specified external environment
+(<envar xmlns="http://www.scons.org/dbxsd/v1.0">$ENV</envar>
+by default).
+This will only add
+any particular path once (leaving the first one it encounters and
+ignoring the rest, to preserve path order),
+and to help assure this,
+will normalize all paths (using
+<literal>os.path.normpath</literal>
+and
+<literal>os.path.normcase</literal>).
+This can also handle the
+case where the given old path variable is a list instead of a
+string, in which case a list will be returned instead of a string.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If
+<varname>delete_existing</varname>
+is 0, then adding a path that already exists
+will not move it to the beginning;
+it will stay where it is in the list.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+print 'before:',env['ENV']['INCLUDE']
+include_path = '/foo/bar:/foo'
+env.PrependENVPath('INCLUDE', include_path)
+print 'after:',env['ENV']['INCLUDE']
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The above example will print:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+before: /biz:/foo
+after: /foo/bar:/foo:/biz
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-PrependUnique">
+    <term>
+      <literal>env.PrependUnique(key=val, delete_existing=0, [...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Appends the specified keyword arguments
+to the beginning of construction variables in the environment.
+If the Environment does not have
+the specified construction variable,
+it is simply added to the environment.
+If the construction variable being appended to is a list,
+then any value(s) that already exist in the
+construction variable will
+<emphasis>not</emphasis>
+be added again to the list.
+However, if delete_existing is 1, 
+existing matching values are removed first, so
+existing values in the arg list move to the front of the list.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Progress">
+    <term>
+      <literal>Progress(callable, [interval])</literal>
+    </term>
+    <term>
+      <literal>Progress(string, [interval, file, overwrite])</literal>
+    </term>
+    <term>
+      <literal>Progress(list_of_strings, [interval, file, overwrite])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Allows SCons to show progress made during the build
+by displaying a string or calling a function while
+evaluating Nodes (e.g. files).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the first specified argument is a Python callable
+(a function or an object that has a
+<function>__call__</function>()
+method),
+the function will be called
+once every
+<varname>interval</varname>
+times a Node is evaluated.
+The callable will be passed the evaluated Node
+as its only argument.
+(For future compatibility,
+it's a good idea to also add
+<literal>*args</literal>
+and
+<literal>**kw</literal>
+as arguments to your function or method.
+This will prevent the code from breaking
+if SCons ever changes the interface
+to call the function with additional arguments in the future.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+An example of a simple custom progress function
+that prints a string containing the Node name
+every 10 Nodes:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+def my_progress_function(node, *args, **kw):
+    print 'Evaluating node %s!' % node
+Progress(my_progress_function, interval=10)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A more complicated example of a custom progress display object
+that prints a string containing a count
+every 100 evaluated Nodes.
+Note the use of
+<literal>\r</literal>
+(a carriage return)
+at the end so that the string
+will overwrite itself on a display:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+import sys
+class ProgressCounter(object):
+    count = 0
+    def __call__(self, node, *args, **kw):
+        self.count += 100
+        sys.stderr.write('Evaluated %s nodes\r' % self.count)
+Progress(ProgressCounter(), interval=100)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the first argument
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Progress"><function>Progress</function></link>
+is a string,
+the string will be displayed
+every
+<varname>interval</varname>
+evaluated Nodes.
+The default is to print the string on standard output;
+an alternate output stream
+may be specified with the
+<literal>file=</literal>
+argument.
+The following will print a series of dots
+on the error output,
+one dot for every 100 evaluated Nodes:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+import sys
+Progress('.', interval=100, file=sys.stderr)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the string contains the verbatim substring
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$TARGET</envar>,
+it will be replaced with the Node.
+Note that, for performance reasons, this is
+<emphasis>not</emphasis>
+a regular SCons variable substition,
+so you can not use other variables
+or use curly braces.
+The following example will print the name of
+every evaluated Node,
+using a
+<literal>\r</literal>
+(carriage return) to cause each line to overwritten by the next line,
+and the
+<literal>overwrite=</literal>
+keyword argument to make sure the previously-printed
+file name is overwritten with blank spaces:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+import sys
+Progress('$TARGET\r', overwrite=True)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the first argument to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Progress</function>
+is a list of strings,
+then each string in the list will be displayed
+in rotating fashion every
+<varname>interval</varname>
+evaluated Nodes.
+This can be used to implement a "spinner"
+on the user's screen as follows:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Pseudo">
+    <term>
+      <literal>Pseudo(target, ...)</literal>
+    </term>
+    <term>
+      <literal>env.Pseudo(target, ...)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This indicates that each given
+<varname>target</varname>
+should not be created by the build rule, and if the target is created,
+an error will be generated. This is similar to the gnu make .PHONY
+target. However, in the vast majority of cases, an
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Alias</function>
+is more appropriate.
+
+Multiple targets can be passed in to a single call to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Pseudo</function>.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-RCS">
+    <term>
+      <literal>env.RCS()</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from RCS.
+The returned Builder
+is intended to be passed to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+function:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function is deprecated.  For details, see the entry for the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SourceCode('.', env.RCS())
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will fetch source files
+from RCS subdirectories automatically,
+so configuring RCS
+as demonstrated in the above example
+should only be necessary if
+you are fetching from
+RCS,v
+files in the same
+directory as the source files,
+or if you need to explicitly specify RCS
+for a specific subdirectory.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Replace">
+    <term>
+      <literal>env.Replace(key=val, [...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Replaces construction variables in the Environment
+with the specified keyword arguments.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Repository">
+    <term>
+      <literal>Repository(directory)</literal>
+    </term>
+    <term>
+      <literal>env.Repository(directory)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Specifies that
+<varname>directory</varname>
+is a repository to be searched for files.
+Multiple calls to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Repository</function>
+are legal,
+and each one adds to the list of
+repositories that will be searched.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+To
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>,
+a repository is a copy of the source tree,
+from the top-level directory on down,
+which may contain
+both source files and derived files
+that can be used to build targets in
+the local source tree.
+The canonical example would be an
+official source tree maintained by an integrator.
+If the repository contains derived files,
+then the derived files should have been built using
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>,
+so that the repository contains the necessary
+signature information to allow
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+to figure out when it is appropriate to
+use the repository copy of a derived file,
+instead of building one locally.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that if an up-to-date derived file
+already exists in a repository,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will
+<emphasis>not</emphasis>
+make a copy in the local directory tree.
+In order to guarantee that a local copy
+will be made,
+use the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Local"><function>Local</function></link>
+method.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Requires">
+    <term>
+      <literal>Requires(target, prerequisite)</literal>
+    </term>
+    <term>
+      <literal>env.Requires(target, prerequisite)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Specifies an order-only relationship
+between the specified target file(s)
+and the specified prerequisite file(s).
+The prerequisite file(s)
+will be (re)built, if necessary,
+<emphasis>before</emphasis>
+the target file(s),
+but the target file(s) do not actually
+depend on the prerequisites
+and will not be rebuilt simply because
+the prerequisite file(s) change.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Requires('foo', 'file-that-must-be-built-before-foo')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Return">
+    <term>
+      <literal>Return([vars..., stop=])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+By default,
+this stops processing the current SConscript
+file and returns to the calling SConscript file
+the values of the variables named in the
+<varname>vars</varname>
+string arguments.
+Multiple strings contaning variable names may be passed to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Return</function>.
+Any strings that contain white space
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The optional
+<literal>stop=</literal>
+keyword argument may be set to a false value
+to continue processing the rest of the SConscript
+file after the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Return</function>
+call.
+This was the default behavior prior to SCons 0.98.
+However, the values returned
+are still the values of the variables in the named
+<varname>vars</varname>
+at the point
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Return</function>
+is called.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Returns without returning a value.
+Return()
+
+# Returns the value of the 'foo' Python variable.
+Return("foo")
+
+# Returns the values of the Python variables 'foo' and 'bar'.
+Return("foo", "bar")
+
+# Returns the values of Python variables 'val1' and 'val2'.
+Return('val1 val2')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Scanner">
+    <term>
+      <literal>Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive])</literal>
+    </term>
+    <term>
+      <literal>env.Scanner(function, [argument, keys, path_function, node_class, node_factory, scan_check, recursive])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Creates a Scanner object for
+the specified
+<varname>function</varname>.
+See the section "Scanner Objects,"
+below, for a complete explanation of the arguments and behavior.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SCCS">
+    <term>
+      <literal>env.SCCS()</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A factory function that
+returns a Builder object
+to be used to fetch source files
+from SCCS.
+The returned Builder
+is intended to be passed to the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SourceCode"><function>SourceCode</function></link>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SourceCode('.', env.SCCS())
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will fetch source files
+from SCCS subdirectories automatically,
+so configuring SCCS
+as demonstrated in the above example
+should only be necessary if
+you are fetching from
+<filename>s.SCCS</filename>
+files in the same
+directory as the source files,
+or if you need to explicitly specify SCCS
+for a specific subdirectory.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SConscript">
+    <term>
+      <literal>SConscript(scripts, [exports, variant_dir, duplicate])</literal>
+    </term>
+    <term>
+      <literal>env.SConscript(scripts, [exports, variant_dir, duplicate])</literal>
+    </term>
+    <term>
+      <literal>SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate])</literal>
+    </term>
+    <term>
+      <literal>env.SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This tells
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+to execute
+one or more subsidiary SConscript (configuration) files.
+Any variables returned by a called script using
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Return"><function>Return</function></link>
+will be returned by the call to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function>.
+There are two ways to call the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function>
+function.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The first way you can call
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function>
+is to explicitly specify one or more
+<varname>scripts</varname>
+as the first argument.
+A single script may be specified as a string;
+multiple scripts must be specified as a list
+(either explicitly or as created by
+a function like
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Split</function>).
+Examples:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+SConscript('SConscript')      # run SConscript in the current directory
+SConscript('src/SConscript')  # run SConscript in the src directory
+SConscript(['src/SConscript', 'doc/SConscript'])
+config = SConscript('MyConfig.py')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The second way you can call
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</function>
+is to specify a list of (sub)directory names
+as a
+<literal>dirs=</literal><varname>subdirs</varname>
+keyword argument.
+In this case,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will, by default,
+execute a subsidiary configuration file named
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+in each of the specified directories.
+You may specify a name other than
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+by supplying an optional
+<literal>name=</literal><varname>script</varname>
+keyword argument.
+The first three examples below have the same effect
+as the first three examples above:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+SConscript(dirs='.')      # run SConscript in the current directory
+SConscript(dirs='src')    # run SConscript in the src directory
+SConscript(dirs=['src', 'doc'])
+SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The optional
+<varname>exports</varname>
+argument provides a list of variable names or a dictionary of
+named values to export to the
+<varname>script(s)</varname>.
+These variables are locally exported only to the specified
+<varname>script(s)</varname>,
+and do not affect the global pool of variables used by the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Export</function>
+function.
+<!-- If multiple dirs are provided, each script gets a fresh export. -->
+The subsidiary
+<varname>script(s)</varname>
+must use the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Import"><function>Import</function></link>
+function to import the variables.
+Examples:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+foo = SConscript('sub/SConscript', exports='env')
+SConscript('dir/SConscript', exports=['env', 'variable'])
+SConscript(dirs='subdir', exports='env variable')
+SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the optional
+<varname>variant_dir</varname>
+argument is present, it causes an effect equivalent to the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-VariantDir"><function>VariantDir</function></link>
+method described below.
+(If
+<varname>variant_dir</varname>
+is not present, the
+<!-- <varname>src_dir</varname> and -->
+<varname>duplicate</varname>
+<!-- arguments are ignored.) -->
+argument is ignored.)
+The
+<varname>variant_dir</varname>
+<!--
+and
+<varname>src_dir</varname>
+arguments are interpreted relative to the directory of the calling
+-->
+argument is interpreted relative to the directory of the calling
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+file.
+See the description of the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function>
+function below for additional details and restrictions.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If
+<varname>variant_dir</varname>
+is present,
+<!--
+but
+<varname>src_dir</varname>
+is not,
+-->
+the source directory is the directory in which the
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+file resides and the
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename>
+file is evaluated as if it were in the
+<varname>variant_dir</varname>
+directory:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+SConscript('src/SConscript', variant_dir = 'build')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+is equivalent to
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+VariantDir('build', 'src')
+SConscript('build/SConscript')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This later paradigm is often used when the sources are
+in the same directory as the
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename>:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+SConscript('SConscript', variant_dir = 'build')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+is equivalent to
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+VariantDir('build', '.')
+SConscript('build/SConscript')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<!--
+If
+<varname>variant_dir</varname>
+and"
+<varname>src_dir</varname>
+are both present,
+xxxxx everything is in a state of confusion.
+</para>
+<example_commands>
+SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
+runs src/SConscript in build/src, but
+SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
+runs lib/SConscript (in lib!).  However,
+SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
+runs src/SConscript in build.  Moreover,
+SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
+runs src/lib/SConscript in build/lib.  Moreover,
+SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
+can't find build/src/lib/SConscript, even though it ought to exist.
+</example_commands>
+<para>
+is equivalent to
+</para>
+<example_commands>
+????????????????
+</example_commands>
+<para>
+and what about this alternative?
+TODO??? SConscript('build/SConscript', src_dir='src')
+-->
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Here are some composite examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# collect the configuration information and use it to build src and doc
+shared_info = SConscript('MyConfig.py')
+SConscript('src/SConscript', exports='shared_info')
+SConscript('doc/SConscript', exports='shared_info')
+</example_commands>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# build debugging and production versions.  SConscript
+# can use Dir('.').path to determine variant.
+SConscript('SConscript', variant_dir='debug', duplicate=0)
+SConscript('SConscript', variant_dir='prod', duplicate=0)
+</example_commands>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# build debugging and production versions.  SConscript
+# is passed flags to use.
+opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
+SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
+opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
+SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
+</example_commands>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# build common documentation and compile for different architectures
+SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
+SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
+SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SConscriptChdir">
+    <term>
+      <literal>SConscriptChdir(value)</literal>
+    </term>
+    <term>
+      <literal>env.SConscriptChdir(value)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+By default,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+changes its working directory
+to the directory in which each
+subsidiary SConscript file lives.
+This behavior may be disabled
+by specifying either:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+SConscriptChdir(0)
+env.SConscriptChdir(0)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+in which case
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will stay in the top-level directory
+while reading all SConscript files.
+(This may be necessary when building from repositories,
+when all the directories in which SConscript files may be found
+don't necessarily exist locally.)
+You may enable and disable
+this ability by calling
+SConscriptChdir()
+multiple times.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env = Environment()
+SConscriptChdir(0)
+SConscript('foo/SConscript')	# will not chdir to foo
+env.SConscriptChdir(1)
+SConscript('bar/SConscript')	# will chdir to bar
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SConsignFile">
+    <term>
+      <literal>SConsignFile([file, dbm_module])</literal>
+    </term>
+    <term>
+      <literal>env.SConsignFile([file, dbm_module])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This tells
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+to store all file signatures
+in the specified database
+<varname>file</varname>.
+If the
+<varname>file</varname>
+name is omitted,
+<filename>.sconsign</filename>
+is used by default.
+(The actual file name(s) stored on disk
+may have an appropriated suffix appended
+by the
+<varname> dbm_module</varname>.)
+If
+<varname>file</varname>
+is not an absolute path name,
+the file is placed in the same directory as the top-level
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename>
+file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If
+<varname>file</varname>
+is
+<literal>None</literal>,
+then
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will store file signatures
+in a separate
+<filename>.sconsign</filename>
+file in each directory,
+not in one global database file.
+(This was the default behavior
+prior to SCons 0.96.91 and 0.97.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The optional
+<varname>dbm_module</varname>
+argument can be used to specify
+which Python database module
+The default is to use a custom
+<filename>SCons.dblite</filename>
+module that uses pickled
+Python data structures,
+and which works on all Python versions.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Explicitly stores signatures in ".sconsign.dblite"
+# in the top-level SConstruct directory (the
+# default behavior).
+SConsignFile()
+
+# Stores signatures in the file "etc/scons-signatures"
+# relative to the top-level SConstruct directory.
+SConsignFile("etc/scons-signatures")
+
+# Stores signatures in the specified absolute file name.
+SConsignFile("/home/me/SCons/signatures")
+
+# Stores signatures in a separate .sconsign file
+# in each directory.
+SConsignFile(None)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SetDefault">
+    <term>
+      <literal>env.SetDefault(key=val, [...])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Sets construction variables to default values specified with the keyword
+arguments if (and only if) the variables are not already set.
+The following statements are equivalent:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SetDefault(FOO = 'foo')
+
+if 'FOO' not in env: env['FOO'] = 'foo'
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SetOption">
+    <term>
+      <literal>SetOption(name, value)</literal>
+    </term>
+    <term>
+      <literal>env.SetOption(name, value)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function provides a way to set a select subset of the scons command
+line options from a SConscript file. The options supported are:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<variablelist>
+<varlistentry>
+<term><literal>clean</literal></term>
+<listitem>
+<para>
+which corresponds to -c, --clean and --remove;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>duplicate</literal></term>
+<listitem>
+<para>
+which corresponds to --duplicate;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>help</literal></term>
+<listitem>
+<para>
+which corresponds to -h and --help;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>implicit_cache</literal></term>
+<listitem>
+<para>
+which corresponds to --implicit-cache;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>max_drift</literal></term>
+<listitem>
+<para>
+which corresponds to --max-drift;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>no_exec</literal></term>
+<listitem>
+<para>
+which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>num_jobs</literal></term>
+<listitem>
+<para>
+which corresponds to -j and --jobs;
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>random</literal></term>
+<listitem>
+<para>
+which corresponds to --random; and
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>stack_size</literal></term>
+<listitem>
+<para>
+which corresponds to --stack-size.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+See the documentation for the
+corresponding command line object for information about each specific
+option.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+SetOption('max_drift', 1)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SideEffect">
+    <term>
+      <literal>SideEffect(side_effect, target)</literal>
+    </term>
+    <term>
+      <literal>env.SideEffect(side_effect, target)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Declares
+<varname>side_effect</varname>
+as a side effect of building
+<varname>target</varname>.
+Both
+<varname>side_effect</varname>
+and
+<varname>target</varname>
+can be a list, a file name, or a node.
+A side effect is a target file that is created or updated
+as a side effect of building other targets.
+For example, a Windows PDB
+file is created as a side effect of building the .obj
+files for a static library,
+and various log files are created updated
+as side effects of various TeX commands.
+If a target is a side effect of multiple build commands,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will ensure that only one set of commands
+is executed at a time.
+Consequently, you only need to use this method
+for side-effect targets that are built as a result of
+multiple build commands.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Because multiple build commands may update
+the same side effect file,
+by default the
+<varname>side_effect</varname>
+target is
+<emphasis>not</emphasis>
+automatically removed
+when the
+<varname>target</varname>
+is removed by the
+<option>-c</option>
+option.
+(Note, however, that the
+<varname>side_effect</varname>
+might be removed as part of
+cleaning the directory in which it lives.)
+If you want to make sure the
+<varname>side_effect</varname>
+is cleaned whenever a specific
+<varname>target</varname>
+is cleaned,
+you must specify this explicitly
+with the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Clean"><function>Clean</function></link>
+or
+<function xmlns="http://www.scons.org/dbxsd/v1.0">env.Clean</function>
+function.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SourceCode">
+    <term>
+      <literal>SourceCode(entries, builder)</literal>
+    </term>
+    <term>
+      <literal>env.SourceCode(entries, builder)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This function and its associate factory functions are deprecated.
+There is no replacement.
+The intended use was to keep a local tree in sync with an archive,
+but in actuality the function only causes the archive
+to be fetched on the first run.
+Synchronizing with the archive is best done external to <application xmlns="http://www.scons.org/dbxsd/v1.0">SCons</application>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Arrange for non-existent source files to
+be fetched from a source code management system
+using the specified
+<varname>builder</varname>.
+The specified
+<varname>entries</varname>
+may be a Node, string or list of both,
+and may represent either individual
+source files or directories in which
+source files can be found.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+For any non-existent source files,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will search up the directory tree
+and use the first
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+builder it finds.
+The specified
+<varname>builder</varname>
+may be
+<literal>None</literal>,
+in which case
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will not use a builder to fetch
+source files for the specified
+<varname>entries</varname>,
+even if a
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceCode</function>
+builder has been specified
+for a directory higher up the tree.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will, by default,
+fetch files from SCCS or RCS subdirectories
+without explicit configuration.
+This takes some extra processing time
+to search for the necessary
+source code management files on disk.
+You can avoid these extra searches
+and speed up your build a little
+by disabling these searches as follows:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SourceCode('.', None)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that if the specified
+<varname>builder</varname>
+is one you create by hand,
+it must have an associated
+construction environment to use
+when fetching a source file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+provides a set of canned factory
+functions that return appropriate
+Builders for various popular
+source code management systems.
+Canonical examples of invocation include:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
+env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
+env.SourceCode('/', env.RCS())
+env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
+env.SourceCode('no_source.c', None)
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<!-- env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) -->
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-SourceSignatures">
+    <term>
+      <literal>SourceSignatures(type)</literal>
+    </term>
+    <term>
+      <literal>env.SourceSignatures(type)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note:  Although it is not yet officially deprecated,
+use of this function is discouraged.
+See the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Decider"><function>Decider</function></link>
+function for a more flexible and straightforward way
+to configure SCons' decision-making.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function>
+function tells
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+how to decide if a source file
+(a file that is not built from any other files)
+has changed since the last time it
+was used to build a particular target file.
+Legal values are
+<literal>MD5</literal>
+or
+<literal>timestamp</literal>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the environment method is used,
+the specified type of source signature
+is only used when deciding whether targets
+built with that environment are up-to-date or must be rebuilt.
+If the global function is used,
+the specified type of source signature becomes the default
+used for all decisions
+about whether targets are up-to-date.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>MD5</literal>
+means
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+decides that a source file has changed
+if the MD5 checksum of its contents has changed since
+the last time it was used to rebuild a particular target file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>timestamp</literal>
+means
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+decides that a source file has changed
+if its timestamp (modification time) has changed since
+the last time it was used to rebuild a particular target file.
+(Note that although this is similar to the behavior of Make,
+by default it will also rebuild if the dependency is
+<emphasis>older</emphasis>
+than the last time it was used to rebuild the target file.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+There is no different between the two behaviors
+for Python
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Value</function>
+node objects.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>MD5</literal>
+signatures take longer to compute,
+but are more accurate than
+<literal>timestamp</literal>
+signatures.
+The default value is
+<literal>MD5</literal>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the default
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-TargetSignatures"><function>TargetSignatures</function></link>
+setting (see below)
+is to use this
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function>
+setting for any target files that are used
+to build other target files.
+Consequently, changing the value of
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function>
+will, by default,
+affect the up-to-date decision for all files in the build
+(or all files built with a specific construction environment
+when
+<function xmlns="http://www.scons.org/dbxsd/v1.0">env.SourceSignatures</function>
+is used).
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Split">
+    <term>
+      <literal>Split(arg)</literal>
+    </term>
+    <term>
+      <literal>env.Split(arg)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns a list of file names or other objects.
+If arg is a string,
+it will be split on strings of white-space characters
+within the string,
+making it easier to write long lists of file names.
+If arg is already a list,
+the list will be returned untouched.
+If arg is any other type of object,
+it will be returned as a list
+containing just the object.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+files = Split("f1.c f2.c f3.c")
+files = env.Split("f4.c f5.c f6.c")
+files = Split("""
+	f7.c
+	f8.c
+	f9.c
+""")
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-subst">
+    <term>
+      <literal>env.subst(input, [raw, target, source, conv])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Performs construction variable interpolation
+on the specified string or sequence argument
+<varname>input</varname>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+By default,
+leading or trailing white space will
+be removed from the result.
+and all sequences of white space
+will be compressed to a single space character.
+Additionally, any
+<literal>$(</literal>
+and
+<literal>$)</literal>
+character sequences will be stripped from the returned string,
+The optional
+<varname>raw</varname>
+argument may be set to
+<literal>1</literal>
+if you want to preserve white space and
+<literal>$(</literal>-<literal>$)</literal>
+sequences.
+The
+<varname>raw</varname>
+argument may be set to
+<literal>2</literal>
+if you want to strip
+all characters between
+any
+<literal>$(</literal>
+and
+<literal>$)</literal>
+pairs
+(as is done for signature calculation).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the input is a sequence
+(list or tuple),
+the individual elements of
+the sequence will be expanded,
+and the results will be returned as a list.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The optional
+<varname>target</varname>
+and
+<varname>source</varname>
+keyword arguments
+must be set to lists of
+target and source nodes, respectively,
+if you want the
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$TARGET</envar>,
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$TARGETS</envar>,
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$SOURCE</envar>
+and
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$SOURCES</envar>
+to be available for expansion.
+This is usually necessary if you are
+calling
+<function xmlns="http://www.scons.org/dbxsd/v1.0">env.subst</function>
+from within a Python function used
+as an SCons action.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returned string values or sequence elements
+are converted to their string representation by default.
+The optional
+<varname>conv</varname>
+argument
+may specify a conversion function
+that will be used in place of
+the default.
+For example, if you want Python objects
+(including SCons Nodes)
+to be returned as Python objects,
+you can use the Python
+Λ
+idiom to pass in an unnamed function
+that simply returns its unconverted argument.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+print env.subst("The C compiler is: $CC")
+
+def compile(target, source, env):
+    sourceDir = env.subst("${SOURCE.srcdir}",
+                          target=target,
+                          source=source)
+
+source_nodes = env.subst('$EXPAND_TO_NODELIST',
+                         conv=lambda x: x)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Tag">
+    <term>
+      <literal>Tag(node, tags)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Annotates file or directory Nodes with
+information about how the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Package"><function>Package</function></link>
+Builder should package those files or directories.
+All tags are optional.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# makes sure the built library will be installed with 0644 file
+# access mode
+Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
+
+# marks file2.txt to be a documentation file
+Tag( 'file2.txt', DOC )
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-TargetSignatures">
+    <term>
+      <literal>TargetSignatures(type)</literal>
+    </term>
+    <term>
+      <literal>env.TargetSignatures(type)</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note:  Although it is not yet officially deprecated,
+use of this function is discouraged.
+See the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Decider"><function>Decider</function></link>
+function for a more flexible and straightforward way
+to configure SCons' decision-making.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function>
+function tells
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+how to decide if a target file
+(a file that
+<emphasis>is</emphasis>
+built from any other files)
+has changed since the last time it
+was used to build some other target file.
+Legal values are
+<literal>"build"</literal>;
+<literal>"content"</literal>
+(or its synonym
+<literal>"MD5"</literal>);
+<literal>"timestamp"</literal>;
+or
+<literal>"source"</literal>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the environment method is used,
+the specified type of target signature is only used
+for targets built with that environment.
+If the global function is used,
+the specified type of signature becomes the default
+used for all target files that
+don't have an explicit target signature type
+specified for their environments.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>"content"</literal>
+(or its synonym
+<literal>"MD5"</literal>)
+means
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+decides that a target file has changed
+if the MD5 checksum of its contents has changed since
+the last time it was used to rebuild some other target file.
+This means
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will open up
+MD5 sum the contents
+of target files after they're built,
+and may decide that it does not need to rebuild
+"downstream" target files if a file was
+rebuilt with exactly the same contents as the last time.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>"timestamp"</literal>
+means
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+decides that a target file has changed
+if its timestamp (modification time) has changed since
+the last time it was used to rebuild some other target file.
+(Note that although this is similar to the behavior of Make,
+by default it will also rebuild if the dependency is
+<emphasis>older</emphasis>
+than the last time it was used to rebuild the target file.)
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>"source"</literal>
+means
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+decides that a target file has changed
+as specified by the corresponding
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function>
+setting
+(<literal>"MD5"</literal>
+or
+<literal>"timestamp"</literal>).
+This means that
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will treat all input files to a target the same way,
+regardless of whether they are source files
+or have been built from other files.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>"build"</literal>
+means
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+decides that a target file has changed
+if it has been rebuilt in this invocation
+or if its content or timestamp have changed
+as specified by the corresponding
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function>
+setting.
+This "propagates" the status of a rebuilt file
+so that other "downstream" target files
+will always be rebuilt,
+even if the contents or the timestamp
+have not changed.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>"build"</literal>
+signatures are fastest because
+<literal>"content"</literal>
+(or
+<literal>"MD5"</literal>)
+signatures take longer to compute,
+but are more accurate than
+<literal>"timestamp"</literal>
+signatures,
+and can prevent unnecessary "downstream" rebuilds
+when a target file is rebuilt to the exact same contents
+as the previous build.
+The
+<literal>"source"</literal>
+setting provides the most consistent behavior
+when other target files may be rebuilt from
+both source and target input files.
+The default value is
+<literal>"source"</literal>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Because the default setting is
+<literal>"source"</literal>,
+using
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function>
+is generally preferable to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function>,
+so that the up-to-date decision
+will be consistent for all files
+(or all files built with a specific construction environment).
+Use of
+<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function>
+provides specific control for how built target files
+affect their "downstream" dependencies.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Tool">
+    <term>
+      <literal>Tool(string, [toolpath, **kw])</literal>
+    </term>
+    <term>
+      <literal>env.Tool(string, [toolpath, **kw])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Tool</function>
+form of the function
+returns a callable object
+that can be used to initialize
+a construction environment using the
+tools keyword of the Environment() method.
+The object may be called with a construction
+environment as an argument,
+in which case the object will
+add the necessary variables
+to the construction environment
+and the name of the tool will be added to the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-TOOLS"><envar>$TOOLS</envar></link>
+construction variable.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Additional keyword arguments are passed to the tool's
+<function>generate</function>()
+method.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env = Environment(tools = [ Tool('msvc') ])
+
+env = Environment()
+t = Tool('msvc')
+t(env)  # adds 'msvc' to the TOOLS variable
+u = Tool('opengl', toolpath = ['tools'])
+u(env)  # adds 'opengl' to the TOOLS variable
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The
+<function xmlns="http://www.scons.org/dbxsd/v1.0">env.Tool</function>
+form of the function
+applies the callable object for the specified tool
+<varname>string</varname>
+to the environment through which the method was called.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Additional keyword arguments are passed to the tool's
+<function>generate</function>()
+method.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Tool('gcc')
+env.Tool('opengl', toolpath = ['build/tools'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-Value">
+    <term>
+      <literal>Value(value, [built_value])</literal>
+    </term>
+    <term>
+      <literal>env.Value(value, [built_value])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Returns a Node object representing the specified Python value.  Value
+Nodes can be used as dependencies of targets.  If the result of
+calling
+<function>str</function>(<varname>value</varname>)
+changes between SCons runs, any targets depending on
+<function>Value</function>(<varname>value</varname>)
+will be rebuilt.
+(This is true even when using timestamps to decide if
+files are up-to-date.)
+When using timestamp source signatures, Value Nodes'
+timestamps are equal to the system time when the Node is created.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The returned Value Node object has a
+<function>write</function>()
+method that can be used to "build" a Value Node
+by setting a new value.
+The optional
+<varname>built_value</varname>
+argument can be specified
+when the Value Node is created
+to indicate the Node should already be considered
+"built."
+There is a corresponding
+<function>read</function>()
+method that will return the built value of the Node.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env = Environment()
+
+def create(target, source, env):
+    # A function that will write a 'prefix=$SOURCE'
+    # string into the file name specified as the
+    # $TARGET.
+    f = open(str(target[0]), 'wb')
+    f.write('prefix=' + source[0].get_contents())
+
+# Fetch the prefix= argument, if any, from the command
+# line, and use /usr/local as the default.
+prefix = ARGUMENTS.get('prefix', '/usr/local')
+
+# Attach a .Config() builder for the above function action
+# to the construction environment.
+env['BUILDERS']['Config'] = Builder(action = create)
+env.Config(target = 'package-config', source = Value(prefix))
+
+def build_value(target, source, env):
+    # A function that "builds" a Python Value by updating
+    # the the Python value with the contents of the file
+    # specified as the source of the Builder call ($SOURCE).
+    target[0].write(source[0].get_contents())
+
+output = env.Value('before')
+input = env.Value('after')
+
+# Attach a .UpdateValue() builder for the above function
+# action to the construction environment.
+env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
+env.UpdateValue(target = Value(output), source = Value(input))
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-VariantDir">
+    <term>
+      <literal>VariantDir(variant_dir, src_dir, [duplicate])</literal>
+    </term>
+    <term>
+      <literal>env.VariantDir(variant_dir, src_dir, [duplicate])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Use the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function>
+function to create a copy of your sources in another location:
+if a name under
+<varname>variant_dir</varname>
+is not found but exists under
+<varname>src_dir</varname>,
+the file or directory is copied to
+<varname>variant_dir</varname>.
+Target files can be built in a different directory
+than the original sources by simply refering to the sources (and targets)
+within the variant tree.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function>
+can be called multiple times with the same
+<varname>src_dir</varname>
+to set up multiple builds with different options
+(<varname>variants</varname>).
+The
+<varname>src_dir</varname>
+location must be in or underneath the SConstruct file's directory, and
+<varname>variant_dir</varname>
+may not be underneath
+<varname>src_dir</varname>.
+<!--
+TODO: Can the above restrictions be clarified or relaxed?
+TODO: The latter restriction is clearly not completely right;
+TODO: src_dir = '.' works fine with a build dir under it.
+-->
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The default behavior is for
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+to physically duplicate the source files in the variant tree.
+Thus, a build performed in the variant tree is guaranteed to be identical
+to a build performed in the source tree even if
+intermediate source files are generated during the build,
+or preprocessors or other scanners search for included files
+relative to the source file,
+or individual compilers or other invoked tools are hard-coded
+to put derived files in the same directory as source files.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If possible on the platform,
+the duplication is performed by linking rather than copying;
+see also the
+<option>--duplicate</option>
+command-line option.
+Moreover, only the files needed for the build are duplicated;
+files and directories that are not used are not present in
+<varname>variant_dir</varname>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Duplicating the source tree may be disabled by setting the
+<literal>duplicate</literal>
+argument to
+<literal>0</literal>
+(zero).
+This will cause
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+to invoke Builders using the path names of source files in
+<varname>src_dir</varname>
+and the path names of derived files within
+<varname>variant_dir</varname>.
+This is always more efficient than
+<literal>duplicate=1</literal>,
+and is usually safe for most builds
+(but see above for cases that may cause problems).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that
+<function xmlns="http://www.scons.org/dbxsd/v1.0">VariantDir</function>
+works most naturally with a subsidiary SConscript file.
+However, you would then call the subsidiary SConscript file
+not in the source directory, but in the
+<varname>variant_dir</varname>,
+regardless of the value of
+<literal>duplicate</literal>.
+This is how you tell
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+which variant of a source tree to build:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# run src/SConscript in two variant directories
+VariantDir('build/variant1', 'src')
+SConscript('build/variant1/SConscript')
+VariantDir('build/variant2', 'src')
+SConscript('build/variant2/SConscript')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+See also the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-SConscript"><function>SConscript</function></link>
+function, described above,
+for another way to specify a variant directory
+in conjunction with calling a subsidiary SConscript file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# use names in the build directory, not the source directory
+VariantDir('build', 'src', duplicate=0)
+Program('build/prog', 'build/source.c')
+</example_commands>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# this builds both the source and docs in a separate subtree
+VariantDir('build', '.', duplicate=0)
+SConscript(dirs=['build/src','build/doc'])
+</example_commands>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# same as previous example, but only uses SConscript
+SConscript(dirs='src', variant_dir='build/src', duplicate=0)
+SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="f-WhereIs">
+    <term>
+      <literal>WhereIs(program, [path, pathext, reject])</literal>
+    </term>
+    <term>
+      <literal>env.WhereIs(program, [path, pathext, reject])</literal>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Searches for the specified executable
+<varname>program</varname>,
+returning the full path name to the program
+if it is found,
+and returning None if not.
+Searches the specified
+<varname>path</varname>,
+the value of the calling environment's PATH
+(<literal>env['ENV']['PATH']</literal>),
+or the user's current external PATH
+(<literal>os.environ['PATH']</literal>)
+by default.
+On Windows systems, searches for executable
+programs with any of the file extensions
+listed in the specified
+<varname>pathext</varname>,
+the calling environment's PATHEXT
+(<literal>env['ENV']['PATHEXT']</literal>)
+or the user's current PATHEXT
+(<literal>os.environ['PATHEXT']</literal>)
+by default.
+Will not select any
+path name or names
+in the specified
+<varname>reject</varname>
+list, if any.
+</para>
+</listitem>
+  </varlistentry>
+</variablelist>