Merged revisions 1826-1882 via svnmerge from

http://scons.tigris.org/svn/scons/branches/core ........ r1828 | stevenknight | 2007-02-12 13:29:17 -0600 (Mon, 12 Feb 2007) | 1 line 0.96.D588 - Speed up Builder suffix-matching. ........ r1829 | stevenknight | 2007-02-14 08:12:32 -0600 (Wed, 14 Feb 2007) | 1 line 0.96.D589 - The scons command, branch 0.96.94. ........ r1830 | stevenknight | 2007-02-14 09:49:44 -0600 (Wed, 14 Feb 2007) | 1 line 0.96.D590 - Fix the scons-doc .tar.gz file packaging. ........ r1835 | stevenknight | 2007-02-15 11:03:20 -0600 (Thu, 15 Feb 2007) | 1 line 0.96.D591 - Update the release HOWTO. ........ r1836 | stevenknight | 2007-02-15 13:39:24 -0600 (Thu, 15 Feb 2007) | 1 line 0.96.D592 - The scons command, branch 0.96.95. ........ r1837 | stevenknight | 2007-02-15 18:34:18 -0600 (Thu, 15 Feb 2007) | 1 line 0.96.D593 - Back out (comment out) Windows registry installer changes. ........ r1838 | stevenknight | 2007-02-16 10:37:28 -0600 (Fri, 16 Feb 2007) | 1 line 0.96.D594 - Update Debian packaging to remove hard-coded references to Python 2.2. (Jean-Baptiste Lab) ........ r1839 | stevenknight | 2007-02-20 09:34:23 -0600 (Tue, 20 Feb 2007) | 1 line 0.96.D595 - Documentation fixes. In the construction variable appendix, use cross-referenced links to entries. ........ r1840 | stevenknight | 2007-02-21 05:11:35 -0600 (Wed, 21 Feb 2007) | 1 line 0.96.D596 - Handle Java '.class' attributes after non-word tokens without assuming it introduces an inner class. ........ r1841 | stevenknight | 2007-02-21 22:33:28 -0600 (Wed, 21 Feb 2007) | 1 line 0.96.D597 - CPPDEFINES regression ........ r1842 | stevenknight | 2007-02-22 14:19:10 -0600 (Thu, 22 Feb 2007) | 1 line 0.96.D598 - Do not detect a Java anonymous class when the first non-skipped token after "new" is a closing brace. ........ r1843 | stevenknight | 2007-02-23 10:45:06 -0600 (Fri, 23 Feb 2007) | 1 line 0.96.D599 - Better [Errno 21] Is a directory error message. ........ r1844 | stevenknight | 2007-02-23 13:32:11 -0600 (Fri, 23 Feb 2007) | 1 line 0.96.D600 - Fix expansion of non-Node objects within a PathList (maximum recursion / unhashable type bug). ........ r1847 | stevenknight | 2007-03-02 00:12:27 -0600 (Fri, 02 Mar 2007) | 1 line 0.96.D601 - Generate SCons API documentation from the docstrings using epydoc. ........ r1848 | stevenknight | 2007-03-02 14:10:06 -0600 (Fri, 02 Mar 2007) | 1 line 0.96.D602 - Fix use of custom include and lib paths with Visual Studio 8. (Richard Viney) ........ r1849 | stevenknight | 2007-03-03 01:00:22 -0600 (Sat, 03 Mar 2007) | 1 line 0.96.D603 - Man page fix: ParseDepends(). User's Guide updates: NoCache(), Clean(), fix CPPDEFINES output, markers for to-be-documented features, white space clean-up. ........ r1850 | stevenknight | 2007-03-06 02:29:08 -0600 (Tue, 06 Mar 2007) | 1 line 0.96.D604 - Fix use of --debug=presub with the Actions for our out-of-the-box Builders. ........ r1851 | stevenknight | 2007-03-06 09:10:43 -0600 (Tue, 06 Mar 2007) | 1 line 0.96.D605 - User Guide updates: --random, AlwaysBuild(), --tree=, --debug=presub, --debug=stacktrace. ........ r1852 | stevenknight | 2007-03-06 15:38:06 -0600 (Tue, 06 Mar 2007) | 1 line 0.96.D606 - Have the Intel toolchain use the default smart linking logic. (Dmitry Grigorenko and Gary Oberbrunner) ........ r1853 | stevenknight | 2007-03-06 17:56:44 -0600 (Tue, 06 Mar 2007) | 1 line 0.96.D607 - Fix tests: ActionTests.py for presub change, command detection in test/Intel/icpc-link.py. ........ r1854 | stevenknight | 2007-03-08 09:35:25 -0600 (Thu, 08 Mar 2007) | 1 line 0.96.D608 - Better selection of .NET Framework SDK paths. (Richard Viney) ........ r1855 | stevenknight | 2007-03-08 10:34:37 -0600 (Thu, 08 Mar 2007) | 1 line 0.96.D609 - Don't re-run TeX if the triggering strings (\makeindex, \bibliography, \tableofcontents) are commented out. (Matthias Troffaes) ........ r1856 | stevenknight | 2007-03-09 16:18:36 -0600 (Fri, 09 Mar 2007) | 1 line 0.96.D610 - Teach the new PathList module to handle nested lists within CPPPATH and the like. ........ r1857 | stevenknight | 2007-03-10 23:30:29 -0600 (Sat, 10 Mar 2007) | 1 line 0.96.D611 - Qt builders_used failure. ........ r1858 | stevenknight | 2007-03-11 15:33:34 -0500 (Sun, 11 Mar 2007) | 1 line 0.96.D612 - Document limitations of --implicit-cache w.r.t. CPPPATH/LIBPATH/etc. ........ r1859 | stevenknight | 2007-03-11 21:11:26 -0500 (Sun, 11 Mar 2007) | 1 line 0.96.D613 - Document --debug=findlibs and --taskmastertrace in the User's Guide. ........ r1860 | stevenknight | 2007-03-12 13:28:42 -0500 (Mon, 12 Mar 2007) | 1 line 0.96.D614 - Remove deleted cons file from the User's Guide MANIFEST. Fix epydoc API build if the build directory is outside the current directory. ........ r1861 | stevenknight | 2007-03-13 13:03:56 -0500 (Tue, 13 Mar 2007) | 2 lines Ignore '*.pyc' files in the compat/ subdirectory. ........ r1862 | stevenknight | 2007-03-13 19:08:19 -0500 (Tue, 13 Mar 2007) | 1 line 0.96.D615 - Fix use of $VAR expansions within CPPPATH/LIBPATH values when the expansion is itself a Dir node concatenated with a string. ........ r1866 | stevenknight | 2007-03-16 01:46:10 -0500 (Fri, 16 Mar 2007) | 1 line 0.96.D616 - Back off to the 0.96.94 of Builder.py (with some performance improvements). ........ r1867 | stevenknight | 2007-03-16 11:20:39 -0500 (Fri, 16 Mar 2007) | 1 line 0.96.D617 - Fix an unnamed variable error if we can't map the Visual Studio version to a default framework version. ........ r1868 | stevenknight | 2007-03-16 12:08:18 -0500 (Fri, 16 Mar 2007) | 1 line 0.96.D618 - Quote the MSVS build target in command lines to handle spaces target name. (Jeff Mahovsky) ........ r1869 | stevenknight | 2007-03-16 13:30:06 -0500 (Fri, 16 Mar 2007) | 1 line 0.96.D619 - Portability fixes for tests run on Windows. ........ r1870 | stevenknight | 2007-03-20 00:18:04 -0500 (Tue, 20 Mar 2007) | 1 line 0.96.D620 - Windows portability fixes: test scripts and infrastructure, detect vcexpress.exe. ........ r1871 | garyo | 2007-03-21 18:32:54 -0500 (Wed, 21 Mar 2007) | 1 line Fix bug where site_scons dir was added to sys.path as relative, not absolute. Added test case. Bug reported by Timothy Woods; thanks for the test case! ........ r1872 | stevenknight | 2007-03-22 09:43:23 -0500 (Thu, 22 Mar 2007) | 1 line 0.96.D622 - Add mention of site_scons fix to src/CHANGES.txt. ........ r1873 | stevenknight | 2007-04-02 23:49:36 -0500 (Mon, 02 Apr 2007) | 1 line 0.96.D623 - Parallel build dependencies with multiple entries in children. (Adam Simpkins) ........ r1874 | stevenknight | 2007-04-04 07:45:05 -0500 (Wed, 04 Apr 2007) | 1 line 0.96.D624 - Make all necessary LaTeX auxiliary files Precious, so bibliography contents aren't affected by whether the auxiliary files exist or not. (Joel B. Mohler) ........ r1875 | stevenknight | 2007-04-04 13:15:39 -0500 (Wed, 04 Apr 2007) | 1 line 0.96.D625 - Fix --debug-time value when -j option is used. ........ r1876 | stevenknight | 2007-04-09 19:40:08 -0500 (Mon, 09 Apr 2007) | 1 line 0.96.D626 - Fix man page example of propagating external user environment. Eliminate cut-and-paste sentence in NoCache() description. (Helmut Grohne, Joe Bloggs) [Issue 1626] [Issue 1627] ........ r1877 | stevenknight | 2007-04-09 23:20:14 -0500 (Mon, 09 Apr 2007) | 1 line 0.96.D627 - Re-run latex after bibtex runs. (Rob Managan) ........ r1878 | stevenknight | 2007-04-11 23:38:17 -0500 (Wed, 11 Apr 2007) | 1 line 0.96.D628 - Fix typo in the User's Guide. [issue 1600] ........ r1879 | stevenknight | 2007-04-12 01:06:35 -0500 (Thu, 12 Apr 2007) | 1 line 0.96.D629 - Avoid name conflicts with compat/ modules (specifically _subprocess.py). ........ r1880 | stevenknight | 2007-04-12 01:33:42 -0500 (Thu, 12 Apr 2007) | 1 line 0.96.D630 - Portability fixes and other improvements in test scripts. ........ r1882 | stevenknight | 2007-04-13 16:42:02 -0500 (Fri, 13 Apr 2007) | 1 line 0.96.D631 - The scons command, branch 0.96.96. ........
author: Steven Knight <knight@baldmt.com> 2007-04-13 23:36:39 (GMT)
committer: Steven Knight <knight@baldmt.com> 2007-04-13 23:36:39 (GMT)
commit: 43e86764943c659f53bf0d1d101708bbdf7d07e6 (patch)
tree: 7b0e2eadcaf969c35e8bab578471b404a5a7d380 /doc
parent: 2174f491d8e103b7af77aa089070503a7b0863c1 (diff)
download: SCons-43e86764943c659f53bf0d1d101708bbdf7d07e6.zip
SCons-43e86764943c659f53bf0d1d101708bbdf7d07e6.tar.gz
SCons-43e86764943c659f53bf0d1d101708bbdf7d07e6.tar.bz2
39 files changed, 2817 insertions, 472 deletions
diff --git a/doc/SConscript b/doc/SConscript
index bf62024..7617974 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -49,6 +49,7 @@ doc_tar_gz = os.path.join(build_dir,
 # if lynx is available to do the dump.
 #
 fig2dev = whereis('fig2dev')
+epydoc = whereis('epydoc')
 groff = whereis('groff')
 lynx = whereis('lynx')
 man2html = whereis('man2html')
@@ -447,12 +448,63 @@ for man_1 in man_page_list:
         tar_deps.append(html)
         tar_list.append(html)
 
+if epydoc:
+    # XXX Should be in common with reading the same thing in
+    # the SConstruct file.
+    e = os.path.join('#src', 'engine')
+    manifest_in = File(os.path.join(e, 'MANIFEST.in')).rstr()
+    sources = map(lambda x: x[:-1], open(manifest_in).readlines())
+    sources = filter(lambda x: string.find(x, 'Optik') == -1, sources)
+    sources = filter(lambda x: string.find(x, 'Platform') == -1, sources)
+    sources = filter(lambda x: string.find(x, 'Tool') == -1, sources)
+    # XXX
+    sources = filter(lambda x: string.find(x, 'Options') == -1, sources)
+
+    e = os.path.join(build, '..', 'scons', 'engine')
+    sources = map(lambda x, e=e: os.path.join(e, x), sources)
+
+    epydoc_commands = [
+        Delete('$OUTDIR'),
+        '$EPYDOC $EPYDOCFLAGS --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES',
+        Touch('$TARGET'),
+    ]
+
+    htmldir = os.path.join(build, 'HTML', 'scons-api')
+    env.Command('${OUTDIR}/index.html', sources, epydoc_commands,
+                EPYDOC=epydoc, EPYDOCFLAGS='--html', OUTDIR=htmldir)
+    tar_deps.append(htmldir)
+    tar_list.append(htmldir)
+
+    # PDF and PostScript and TeX are built from the
+    # same invocation.
+    api_dir = os.path.join(build, 'scons-api')
+    api_pdf = os.path.join(api_dir, 'api.pdf')
+    api_ps = os.path.join(api_dir, 'api.ps')
+    api_tex = os.path.join(api_dir, 'api.tex')
+    api_targets = [api_pdf, api_ps, api_tex]
+    env.Command(api_targets, sources, epydoc_commands,
+                EPYDOC=epydoc, EPYDOCFLAGS='--pdf', OUTDIR=api_dir)
+    Local(api_targets)
+
+    pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf')
+    env.InstallAs(pdf_install, api_pdf)
+    tar_deps.append(pdf_install)
+    tar_list.append(pdf_install)
+    Local(pdf_install)
+
+    ps_install = os.path.join(build, 'PS', 'scons-api.ps')
+    env.InstallAs(ps_install, api_ps)
+    tar_deps.append(ps_install)
+    tar_list.append(ps_install)
+    Local(ps_install)
+
 #
 # Now actually create the tar file of the documentation,
 # for easy distribution to the web site.
 #
 if tar_deps:
-    tar_list = string.join(map(lambda x: x[11:], tar_list))
+    tar_list = string.join(map(lambda x, b=build+'/': string.replace(x, b, ''),
+                           tar_list))
     env.Command(doc_tar_gz, tar_deps,
-                "tar cf${TAR_HFLAG} - -C build/doc %s | gzip > $TARGET" % tar_list)
+                "tar cf${TAR_HFLAG} - -C %s %s | gzip > $TARGET" % (build, tar_list))
     Local(doc_tar_gz)
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 862cde5..73e3df9 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -184,7 +184,7 @@ complete external environment:
 
 .ES
 import os
-env = Environment(ENV = os.environ['PATH'])
+env = Environment(ENV = os.environ)
 .EE
 
 This comes at the expense of making your build
@@ -681,10 +681,38 @@ and ultimately removed.
 
 .TP
 --debug=time
-Prints various time profiling information: the time spent
-executing each build command, the total build time, the total time spent
-executing build commands, the total time spent executing SConstruct and
-SConscript files, and the total time spent executing SCons itself.
+Prints various time profiling information:
+the time spent executing each individual build command;
+the total build time (time SCons ran from beginning to end);
+the total time spent reading and executing SConscript files;
+the total time spent SCons itself spend running
+(that is, not counting reading and executing SConscript files);
+and both the total time spent executing all build commands
+and the elapsed wall-clock time spent executing those build commands.
+(When
+.B scons
+is executed without the
+.B -j
+option,
+the elapsed wall-clock time will typically
+be slightly longer than the total time spent
+executing all the build commands,
+due to the SCons processing that takes place
+in between executing each command.
+When
+.B scons
+is executed
+.I with
+the
+.B -j
+option,
+and your build configuration allows good parallelization,
+the elapsed wall-clock time should
+be significantly smaller than the
+total time spent executing all the build commands,
+since multiple build commands and
+intervening SCons processing
+should take place in parallel.)
 
 .TP
 --debug=tree
@@ -735,6 +763,24 @@ found in SCCS or RCS, for example,
 or if a file really does exist
 where the SCons configuration expects a directory).
 
+.TP
+.RI --duplicate= ORDER
+There are three ways to duplicate files in a build tree: hard links,
+soft (symbolic) links and copies. The default behaviour of SCons is to 
+prefer hard links to soft links to copies. You can specify different
+behaviours with this option.
+.IR ORDER 
+must be one of 
+.IR hard-soft-copy
+(the default),
+.IR soft-hard-copy ,
+.IR hard-copy ,
+.IR soft-copy
+or
+.IR copy .
+SCons will attempt to duplicate files using
+the mechanisms in the specified order.
+
 .\" .TP
 .\" -e, --environment-overrides
 .\" Variables from the execution environment override construction
@@ -774,29 +820,35 @@ imported Python modules.  If several
 options
 are used, the directories are searched in the order specified.
 
-.TP 
-.RI --no-site-dir
-Prevents the automatic addition of the standard
-.I site_scons
-dir to
-.IR sys.path .
-Also prevents loading the
-.I site_scons/site_init.py
-module if it exists, and prevents adding
-.I site_scons/site_tools
-to the toolpath.
-
 .TP
 --implicit-cache
-Cache implicit dependencies. This can cause 
+Cache implicit dependencies.
+This causes
+.B scons
+to use the implicit (scanned) dependencies
+from the last time it was run
+instead of scanning the files for implicit dependencies.
+This can significantly speed up SCons,
+but with the following limitations:
+.IP
 .B scons
-to miss changes in the implicit dependencies in cases where a new implicit
+will not detect changes to implicit dependency search paths
+(e.g.
+.BR CPPPATH ", " LIBPATH )
+that would ordinarily
+cause different versions of same-named files to be used.
+.IP
+.B scons
+will miss changes in the implicit dependencies
+in cases where a new implicit
 dependency is added earlier in the implicit dependency search path
-(e.g. CPPPATH) than a current implicit dependency with the same name.
+(e.g.
+.BR CPPPATH ", " LIBPATH )
+than a current implicit dependency with the same name.
 
 .TP
 --implicit-deps-changed
-Force SCons to ignore the cached implicit dependencies. This causes the
+Forces SCons to ignore the cached implicit dependencies. This causes the
 implicit dependencies to be rescanned and recached. This implies
 .BR --implicit-cache .
 
@@ -835,24 +887,6 @@ targets specified on the command line will still be processed.
 .\" .I N
 .\" (a floating-point number).
 
-.TP
-.RI --duplicate= ORDER
-There are three ways to duplicate files in a build tree: hard links,
-soft (symbolic) links and copies. The default behaviour of SCons is to 
-prefer hard links to soft links to copies. You can specify different
-behaviours with this option.
-.IR ORDER 
-must be one of 
-.IR hard-soft-copy
-(the default),
-.IR soft-hard-copy ,
-.IR hard-copy ,
-.IR soft-copy
-or
-.IR copy .
-SCons will attempt to duplicate files using
-the mechanisms in the specified order.
-
 .\"
 .\" .TP
 .\" --list-derived
@@ -902,6 +936,18 @@ no matter how old the file is.
 No execute.  Print the commands that would be executed to build
 any out-of-date target files, but do not execute the commands.
 
+.TP 
+.RI --no-site-dir
+Prevents the automatic addition of the standard
+.I site_scons
+dir to
+.IR sys.path .
+Also prevents loading the
+.I site_scons/site_init.py
+module if it exists, and prevents adding
+.I site_scons/site_tools
+to the toolpath.
+
 .\" .TP
 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
 .\" Do not rebuild 
@@ -3214,13 +3260,6 @@ be cached whenever the
 method has been activated.
 The specified targets may be a list
 or an individual target.
-Multiple calls to
-.BR NoCache ()
-are legal,
-and prevent each specified target
-from being removed by calls to the
-.B -c
-option.
 
 Multiple files should be specified
 either as separate arguments to the
@@ -3324,9 +3363,9 @@ for a table of options and construction variables.
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .TP
-.RI ParseDepends( filename ", [" must_exist ])
+.RI ParseDepends( filename ", [" must_exist ", " only_one ])
 .TP
-.RI env.ParseDepends( filename ", [" must_exist " " only_one ])
+.RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
 Parses the contents of the specified
 .I filename
 as a list of dependencies in the style of
@@ -3341,7 +3380,7 @@ if the specified
 .I filename
 does not exist.
 The optional
-.I must_exit
+.I must_exist
 argument may be set to a non-zero
 value to have
 scons
diff --git a/doc/scons.mod b/doc/scons.mod
index 975f445..aa1a0b9 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -79,10 +79,18 @@
 
 -->
 
+<!ENTITY config "<literal>--config</literal>">
 <!ENTITY debug-explain "<literal>--debug=explain</literal>">
+<!ENTITY debug-findlibs "<literal>--debug=findlibs</literal>">
+<!ENTITY debug-includes "<literal>--debug=includes</literal>">
+<!ENTITY debug-presub "<literal>--debug=presub</literal>">
+<!ENTITY debug-stacktrace "<literal>--debug=stacktrace</literal>">
 <!ENTITY implicit-cache "<literal>--implicit-cache</literal>">
 <!ENTITY implicit-deps-changed "<literal>--implicit-deps-changed</literal>">
 <!ENTITY implicit-deps-unchanged "<literal>--implicit-deps-unchanged</literal>">
+<!ENTITY profile "<literal>--profile</literal>">
+<!ENTITY taskmastertrace "<literal>--taskmastertrace</literal>">
+<!ENTITY tree "<literal>--tree</literal>">
 <!ENTITY Q "<literal>-Q</literal>">
 
 <!--
@@ -123,10 +131,15 @@
 -->
 
 <!ENTITY Add "<function>Add</function>">
+<!ENTITY AddPostAction "<function>AddPostAction</function>">
+<!ENTITY AddPreAction "<function>AddPreAction</function>">
 <!ENTITY AddOptions "<function>AddOptions</function>">
 <!ENTITY Alias "<function>Alias</function>">
 <!ENTITY Aliases "<function>Aliases</function>">
+<!ENTITY AlwaysBuild "<function>AlwaysBuild</function>">
 <!ENTITY Append "<function>Append</function>">
+<!ENTITY AppendENVPath "<function>AppendENVPath</function>">
+<!ENTITY AppendUnique "<function>AppendUnique</function>">
 <!ENTITY BoolOption "<function>BoolOption</function>">
 <!ENTITY Build "<function>Build</function>">
 <!ENTITY CacheDir "<function>CacheDir</function>">
@@ -148,6 +161,7 @@
 <!ENTITY Execute "<function>Execute</function>">
 <!ENTITY Export "<function>Export</function>">
 <!ENTITY File "<function>File</function>">
+<!ENTITY FindFile "<function>FindFile</function>">
 <!ENTITY Finish "<function>Finish</function>">
 <!ENTITY GenerateHelpText "<function>GenerateHelpText</function>">
 <!ENTITY GetOption "<function>GetOption</function>">
@@ -163,6 +177,7 @@
 <!ENTITY Module "<function>Module</function>">
 <!ENTITY Move "<function>Move</function>">
 <!ENTITY NoClean "<function>NoClean</function>">
+<!ENTITY NoCache "<function>NoCache</function>">
 <!ENTITY Objects "<function>Objects</function>">
 <!ENTITY Options "<function>Options</function>">
 <!ENTITY PackageOption "<function>PackageOption</function>">
@@ -175,6 +190,8 @@
 <!ENTITY PathOption_PathIsFile "<function>PathOption.PathIsFile</function>">
 <!ENTITY Precious "<function>Precious</function>">
 <!ENTITY Prepend "<function>Prepend</function>">
+<!ENTITY PrependENVPath "<function>PrependENVPath</function>">
+<!ENTITY PrependUnique "<function>PrependUnique</function>">
 <!ENTITY Replace "<function>Replace</function>">
 <!ENTITY Repository "<function>Repository</function>">
 <!ENTITY Return "<function>Return</function>">
@@ -182,6 +199,7 @@
 <!ENTITY Salt "<function>Salt</function>">
 <!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>">
 <!ENTITY SetContentSignatureType "<function>SetContentSignatureType</function>">
+<!ENTITY SideEffect "<function>SideEffect</function>">
 <!ENTITY SourceSignature "<function>SourceSignature</function>">
 <!ENTITY SourceSignatures "<function>SourceSignatures</function>">
 <!ENTITY Split "<function>Split</function>">
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 04c293b..cc7dc1e 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -9,7 +9,6 @@ build-install.sgml
 caching.sgml
 command-line.sgml
 cons.pl
-cons.sgml
 copyright.sgml
 depends.sgml
 ENV.sgml
diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in
index 8b0f16f..c7516a6 100644
--- a/doc/user/builders-built-in.in
+++ b/doc/user/builders-built-in.in
@@ -214,7 +214,7 @@
 
     &SCons; provides separate Builder objects
     to create static and shared object files.
-    The distinction becomes especially important when 
+    The distinction becomes especially important when
     archiving object files into different types of libraries.
 
     </para>
@@ -568,7 +568,7 @@
 
     <para>
 
-    XXX
+    XXX PCH()
 
     </para>
 
@@ -579,7 +579,7 @@
 
     <para>
 
-    XXX
+    XXX RES()
 
     </para>
 
@@ -604,16 +604,16 @@
 
       <para>
 
-      XXX
+      XXX CFile()
 
       </para>
 
       <programlisting>
-        XXX
+        XXX CFile() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX CFile() screen
       </screen>
 
     </section>
@@ -623,16 +623,16 @@
 
       <para>
 
-      XXX
+      XXX CXXFILE()
 
       </para>
 
       <programlisting>
-        XXX
+        XXX CXXFILE() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX CXXFILE() screen
       </screen>
 
     </section>
@@ -654,16 +654,16 @@
 
       <para>
 
-      XXX
+      XXX DVI() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX DVI() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX DVI() screen
       </screen>
 
     </section>
@@ -673,7 +673,7 @@
 
       <para>
 
-      XXX
+      XXX PDF() para
 
       </para>
 
@@ -684,16 +684,16 @@
 
       <para>
 
-      XXX
+      XXX PostScript() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX PostScript() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX PostScript() screen
       </screen>
 
     </section>
@@ -896,7 +896,7 @@
       </para>
 
       <screen>
-        XXX
+        XXX Java() screen
       </screen>
 
     </section>
@@ -906,7 +906,7 @@
 
       <para>
 
-      The &Jar; builder object XXX
+      XXX The &Jar; builder object
 
       </para>
 
@@ -917,7 +917,7 @@
       </programlisting>
 
       <screen>
-        XXX
+        XXX Jar() screen
       </screen>
 
     </section>
@@ -927,16 +927,16 @@
 
       <para>
 
-      XXX
+      XXX JavaH() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX JavaH() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX JavaH() screen
       </screen>
 
     </section>
@@ -946,16 +946,16 @@
 
       <para>
 
-      XXX
+      XXX RMIC() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX RMIC() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX RMIC() screen
       </screen>
 
     </section>
diff --git a/doc/user/builders-built-in.sgml b/doc/user/builders-built-in.sgml
index 9c0a3b8..cf09fd5 100644
--- a/doc/user/builders-built-in.sgml
+++ b/doc/user/builders-built-in.sgml
@@ -212,7 +212,7 @@
 
     &SCons; provides separate Builder objects
     to create static and shared object files.
-    The distinction becomes especially important when 
+    The distinction becomes especially important when
     archiving object files into different types of libraries.
 
     </para>
@@ -566,7 +566,7 @@
 
     <para>
 
-    XXX
+    XXX PCH()
 
     </para>
 
@@ -577,7 +577,7 @@
 
     <para>
 
-    XXX
+    XXX RES()
 
     </para>
 
@@ -602,16 +602,16 @@
 
       <para>
 
-      XXX
+      XXX CFile()
 
       </para>
 
       <programlisting>
-        XXX
+        XXX CFile() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX CFile() screen
       </screen>
 
     </section>
@@ -621,16 +621,16 @@
 
       <para>
 
-      XXX
+      XXX CXXFILE()
 
       </para>
 
       <programlisting>
-        XXX
+        XXX CXXFILE() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX CXXFILE() screen
       </screen>
 
     </section>
@@ -652,16 +652,16 @@
 
       <para>
 
-      XXX
+      XXX DVI() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX DVI() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX DVI() screen
       </screen>
 
     </section>
@@ -671,7 +671,7 @@
 
       <para>
 
-      XXX
+      XXX PDF() para
 
       </para>
 
@@ -682,16 +682,16 @@
 
       <para>
 
-      XXX
+      XXX PostScript() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX PostScript() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX PostScript() screen
       </screen>
 
     </section>
@@ -870,7 +870,7 @@
       </para>
 
       <screen>
-        XXX
+        XXX Java() screen
       </screen>
 
     </section>
@@ -880,7 +880,7 @@
 
       <para>
 
-      The &Jar; builder object XXX
+      XXX The &Jar; builder object
 
       </para>
 
@@ -891,7 +891,7 @@
       </programlisting>
 
       <screen>
-        XXX
+        XXX Jar() screen
       </screen>
 
     </section>
@@ -901,16 +901,16 @@
 
       <para>
 
-      XXX
+      XXX JavaH() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX JavaH() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX JavaH() screen
       </screen>
 
     </section>
@@ -920,16 +920,16 @@
 
       <para>
 
-      XXX
+      XXX RMIC() para
 
       </para>
 
       <programlisting>
-        XXX
+        XXX RMIC() programlisting
       </programlisting>
 
       <screen>
-        XXX
+        XXX RMIC() screen
       </screen>
 
     </section>
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index ebfef5d..62717aa 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -594,7 +594,7 @@ This functionality could be invoked as in the following example:
       generator is being called to contribute to a build signature,
       as opposed to actually executing the command.
 
-      <!-- XXX NEED MORE HERE -->
+      <!-- XXX NEED MORE HERE, describe generators use in signatures -->
 
       </para>
       </listitem>
@@ -720,7 +720,7 @@ This functionality could be invoked as in the following example:
     </scons_output>
 
     <programlisting>
-       bld = Builder(action = 'XXX',
+       bld = Builder(action = 'my_command',
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = 'MY_EMITTER')
@@ -745,14 +745,14 @@ This functionality could be invoked as in the following example:
 
     <para>
 
-    XXX
+    XXX para
 
     </para>
 
     <scons_example name="ex8">
        <file name="SConstruct" printme="1">
        env = Environment()
-       #env.SourceCode('.', env.BitKeeper('XXX'))
+       #env.SourceCode('.', env.BitKeeper('my_command'))
        env.Program('hello.c')
        </file>
        <file name="hello.c">
diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml
index 327650a..412d431 100644
--- a/doc/user/builders-writing.sgml
+++ b/doc/user/builders-writing.sgml
@@ -538,7 +538,7 @@ This functionality could be invoked as in the following example:
       generator is being called to contribute to a build signature,
       as opposed to actually executing the command.
 
-      <!-- XXX NEED MORE HERE -->
+      <!-- XXX NEED MORE HERE, describe generators use in signatures -->
 
       </para>
       </listitem>
@@ -624,7 +624,7 @@ This functionality could be invoked as in the following example:
     </screen>
 
     <programlisting>
-       bld = Builder(action = 'XXX',
+       bld = Builder(action = 'my_command',
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = 'MY_EMITTER')
@@ -649,14 +649,14 @@ This functionality could be invoked as in the following example:
 
     <para>
 
-    XXX
+    XXX para
 
     </para>
 
     <scons_example name="ex8">
        <file name="SConstruct" printme="1">
        env = Environment()
-       #env.SourceCode('.', env.BitKeeper('XXX'))
+       #env.SourceCode('.', env.BitKeeper('my_command'))
        env.Program('hello.c')
        </file>
        <file name="hello.c">
diff --git a/doc/user/caching.in b/doc/user/caching.in
index 0195c43..015407b 100644
--- a/doc/user/caching.in
+++ b/doc/user/caching.in
@@ -80,6 +80,12 @@
     every time a file is built,
     it is stored in the shared cache directory
     along with its MD5 build signature.
+      <footnote>
+      <para>
+      Actually, the MD5 signature is used as the name of the file
+      in the shared cache directory in which the contents are stored.
+      </para>
+      </footnote>
     On subsequent builds,
     before an action is invoked to build a file,
     &SCons; will check the shared cache directory
@@ -106,8 +112,8 @@
     <para>
 
     One potential drawback to using a shared cache
-    is that your build output can be inconsistent
-    from invocation to invocation,
+    is that the output printed by &SCons;
+    can be inconsistent from invocation to invocation,
     because any given file may be rebuilt one time
     and retrieved from the shared cache the next time.
     This can make analyzing build output more difficult,
@@ -146,7 +152,74 @@
   </section>
 
   <section>
-  <title>Not Retrieving Files From a Shared Cache</title>
+  <title>Not Using the Shared Cache for Specific Files</title>
+
+    <para>
+
+    You may want to disable caching for certain
+    specific files in your configuration.
+    For example, if you only want to put
+    executable files in a central cache,
+    but not the intermediate object files,
+    you can use the &NoCache;
+    function to specify that the
+    object files should not be cached:
+
+    </para>
+
+    <scons_example name="ex-NoCache">
+       <file name="SConstruct" printme="1">
+       env = Environment()
+       obj = env.Object('hello.c')
+       env.Program('hello.c')
+       CacheDir('cache')
+       NoCache('hello.o')
+       </file>
+       <file name="hello.c">
+       hello.c
+       </file>
+       <directory name="cache">
+       </directory>
+    </scons_example>
+
+    <para>
+
+    Then when you run &scons; after cleaning
+    the built targets,
+    it will recompile the object file locally
+    (since it doesn't exist in the shared cache directory),
+    but still realize that the shared cache directory
+    contains an up-to-date executable program
+    that can be retrieved instead of re-linking:
+
+    </para>
+
+    <!--
+
+    <scons_output example="ex1">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q -c</userinput>
+      Removed hello.o
+      Removed hello
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      Retrieved `hello' from cache
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Disabling the Shared Cache</title>
 
     <para>
 
@@ -211,8 +284,8 @@
     In this case, you can use the
     the <literal>--cache-force</literal> option
     to tell &SCons; to put all derived files in the cache,
-    even if the files had already been built
-    by a previous invocation:
+    even if the files already exist in your local tree
+    from having been built by a previous invocation:
 
     </para>
 
@@ -221,7 +294,6 @@
       <scons_output_command>scons -Q -c</scons_output_command>
       <scons_output_command>scons -Q --cache-disable</scons_output_command>
       <scons_output_command>scons -Q --cache-force</scons_output_command>
-      <scons_output_command>scons -Q -c</scons_output_command>
       <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
@@ -231,7 +303,7 @@
     demonstrates that the <literal>--cache-disable</literal>
     option avoids putting the built
     <filename>hello.o</filename>
-    and 
+    and
     <filename>hello</filename> files in the cache,
     but after using the <literal>--cache-force</literal> option,
     the files have been put in the cache
@@ -240,3 +312,152 @@
     </para>
 
   </section>
+
+  <section>
+  <title>Minimizing Cache Contention:  the <literal>--random</literal> Option</title>
+
+    <para>
+
+    If you allow multiple builds to update the
+    shared cache directory simultaneously,
+    two builds that occur at the same time
+    can sometimes start "racing"
+    with one another to build the same files
+    in the same order.
+    If, for example,
+    you are linking multiple files into an executable program:
+
+    </para>
+
+    <scons_example name="ex-random">
+       <file name="SConstruct" printme="1">
+       Program('prog',
+               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+       </file>
+       <file name="f1.c">f1.c</file>
+       <file name="f2.c">f2.c</file>
+       <file name="f3.c">f3.c</file>
+       <file name="f4.c">f4.c</file>
+       <file name="f5.c">f5.c</file>
+       <file name="f6.c">f6.c</file>
+    </scons_example>
+
+    <para>
+
+    &SCons; will normally build the input object files
+    on which the program depends in their normal, sorted order:
+
+    </para>
+
+    <scons_output example="ex-random">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    But if two such builds take place simultaneously,
+    they may each look in the cache at nearly the same
+    time and both decide that <filename>f1.o</filename>
+    must be rebuilt and pushed into the shared cache directory,
+    then both decide that <filename>f2.o</filename>
+    must be rebuilt (and pushed into the shared cache directory),
+    then both decide that <filename>f3.o</filename>
+    must be rebuilt...
+    This won't cause any actual build problems--both
+    builds will succeed,
+    generate correct output files,
+    and populate the cache--but
+    it does represent wasted effort.
+
+    </para>
+
+    <para>
+
+    To alleviate such contention for the cache,
+    you can use the <literal>--random</literal> command-line option
+    to tell &SCons; to build dependencies
+    in a random order:
+
+    </para>
+
+    <!--
+
+    The following <screen> output was generated by this:
+
+    <scons_output example="ex-random">
+      <scons_output_command>scons -Q - -random</scons_output_command>
+    </scons_output>
+
+    We captured it directly here to guarantee a "random" order,
+    guarding against the potential for - -random to happen
+    to return things in the original sorted order.
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q --random</userinput>
+      cc -o f3.o -c f3.c
+      cc -o f1.o -c f1.c
+      cc -o f5.o -c f5.c
+      cc -o f2.o -c f2.c
+      cc -o f4.o -c f4.c
+      cc -o prog f1.o f2.o f3.o f4.o f5.o
+    </screen>
+
+    <para>
+
+    Multiple builds using the <literal>--random</literal> option
+    will usually build their dependencies in different,
+    random orders,
+    which minimizes the chances for a lot of
+    contention for same-named files
+    in the shared cache directory.
+    Multiple simultaneous builds might still race to try to build
+    the same target file on occasion,
+    but long sequences of inefficient contention
+    should be rare.
+
+    </para>
+
+    <para>
+
+    Note, of course,
+    the <literal>--random</literal> option
+    will cause the output that &SCons; prints
+    to be inconsistent from invocation to invocation,
+    which may be an issue when
+    trying to compare output from different build runs.
+
+    </para>
+
+  </section>
+
+  <!--
+
+  <section>
+  <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
+
+    <para>
+
+    XXX describe the - - cache-debug option
+    XXX maybe point to the troubleshooting appendix?
+
+    </para>
+
+  </section>
+
+  -->
+
+  <!--
+
+  <section>
+
+    <para>
+
+    XXX describe CacheDir management:  monitoring, deleting, etc.
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/caching.sgml b/doc/user/caching.sgml
index d87e493..02c3597 100644
--- a/doc/user/caching.sgml
+++ b/doc/user/caching.sgml
@@ -68,6 +68,12 @@
     every time a file is built,
     it is stored in the shared cache directory
     along with its MD5 build signature.
+      <footnote>
+      <para>
+      Actually, the MD5 signature is used as the name of the file
+      in the shared cache directory in which the contents are stored.
+      </para>
+      </footnote>
     On subsequent builds,
     before an action is invoked to build a file,
     &SCons; will check the shared cache directory
@@ -100,8 +106,8 @@
     <para>
 
     One potential drawback to using a shared cache
-    is that your build output can be inconsistent
-    from invocation to invocation,
+    is that the output printed by &SCons;
+    can be inconsistent from invocation to invocation,
     because any given file may be rebuilt one time
     and retrieved from the shared cache the next time.
     This can make analyzing build output more difficult,
@@ -146,7 +152,67 @@
   </section>
 
   <section>
-  <title>Not Retrieving Files From a Shared Cache</title>
+  <title>Not Using the Shared Cache for Specific Files</title>
+
+    <para>
+
+    You may want to disable caching for certain
+    specific files in your configuration.
+    For example, if you only want to put
+    executable files in a central cache,
+    but not the intermediate object files,
+    you can use the &NoCache;
+    function to specify that the
+    object files should not be cached:
+
+    </para>
+
+    <programlisting>
+       env = Environment()
+       obj = env.Object('hello.c')
+       env.Program('hello.c')
+       CacheDir('cache')
+       NoCache('hello.o')
+    </programlisting>
+
+    <para>
+
+    Then when you run &scons; after cleaning
+    the built targets,
+    it will recompile the object file locally
+    (since it doesn't exist in the shared cache directory),
+    but still realize that the shared cache directory
+    contains an up-to-date executable program
+    that can be retrieved instead of re-linking:
+
+    </para>
+
+    <!--
+
+    <scons_output example="ex1">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q -c</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q -c</userinput>
+      Removed hello.o
+      Removed hello
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      Retrieved `hello' from cache
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Disabling the Shared Cache</title>
 
     <para>
 
@@ -221,8 +287,8 @@
     In this case, you can use the
     the <literal>--cache-force</literal> option
     to tell &SCons; to put all derived files in the cache,
-    even if the files had already been built
-    by a previous invocation:
+    even if the files already exist in your local tree
+    from having been built by a previous invocation:
 
     </para>
 
@@ -238,12 +304,8 @@
       cc -o hello hello.o
       % <userinput>scons -Q --cache-force</userinput>
       scons: `.' is up to date.
-      % <userinput>scons -Q -c</userinput>
-      Removed hello.o
-      Removed hello
       % <userinput>scons -Q</userinput>
-      Retrieved `hello.o' from cache
-      Retrieved `hello' from cache
+      scons: `.' is up to date.
     </screen>
 
     <para>
@@ -252,7 +314,7 @@
     demonstrates that the <literal>--cache-disable</literal>
     option avoids putting the built
     <filename>hello.o</filename>
-    and 
+    and
     <filename>hello</filename> files in the cache,
     but after using the <literal>--cache-force</literal> option,
     the files have been put in the cache
@@ -261,3 +323,150 @@
     </para>
 
   </section>
+
+  <section>
+  <title>Minimizing Cache Contention:  the <literal>--random</literal> Option</title>
+
+    <para>
+
+    If you allow multiple builds to update the
+    shared cache directory simultaneously,
+    two builds that occur at the same time
+    can sometimes start "racing"
+    with one another to build the same files
+    in the same order.
+    If, for example,
+    you are linking multiple files into an executable program:
+
+    </para>
+
+    <programlisting>
+       Program('prog',
+               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+    </programlisting>
+
+    <para>
+
+    &SCons; will normally build the input object files
+    on which the program depends in their normal, sorted order:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o f1.o -c f1.c
+      cc -o f2.o -c f2.c
+      cc -o f3.o -c f3.c
+      cc -o f4.o -c f4.c
+      cc -o f5.o -c f5.c
+      cc -o prog f1.o f2.o f3.o f4.o f5.o
+    </screen>
+
+    <para>
+
+    But if two such builds take place simultaneously,
+    they may each look in the cache at nearly the same
+    time and both decide that <filename>f1.o</filename>
+    must be rebuilt and pushed into the shared cache directory,
+    then both decide that <filename>f2.o</filename>
+    must be rebuilt (and pushed into the shared cache directory),
+    then both decide that <filename>f3.o</filename>
+    must be rebuilt...
+    This won't cause any actual build problems--both
+    builds will succeed,
+    generate correct output files,
+    and populate the cache--but
+    it does represent wasted effort.
+
+    </para>
+
+    <para>
+
+    To alleviate such contention for the cache,
+    you can use the <literal>--random</literal> command-line option
+    to tell &SCons; to build dependencies
+    in a random order:
+
+    </para>
+
+    <!--
+
+    The following <screen> output was generated by this:
+
+    <scons_output example="ex-random">
+      <scons_output_command>scons -Q - -random</scons_output_command>
+    </scons_output>
+
+    We captured it directly here to guarantee a "random" order,
+    guarding against the potential for - -random to happen
+    to return things in the original sorted order.
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q --random</userinput>
+      cc -o f3.o -c f3.c
+      cc -o f1.o -c f1.c
+      cc -o f5.o -c f5.c
+      cc -o f2.o -c f2.c
+      cc -o f4.o -c f4.c
+      cc -o prog f1.o f2.o f3.o f4.o f5.o
+    </screen>
+
+    <para>
+
+    Multiple builds using the <literal>--random</literal> option
+    will usually build their dependencies in different,
+    random orders,
+    which minimizes the chances for a lot of
+    contention for same-named files
+    in the shared cache directory.
+    Multiple simultaneous builds might still race to try to build
+    the same target file on occasion,
+    but long sequences of inefficient contention
+    should be rare.
+
+    </para>
+
+    <para>
+
+    Note, of course,
+    the <literal>--random</literal> option
+    will cause the output that &SCons; prints
+    to be inconsistent from invocation to invocation,
+    which may be an issue when
+    trying to compare output from different build runs.
+
+    </para>
+
+  </section>
+
+  <!--
+
+  <section>
+  <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
+
+    <para>
+
+    XXX describe the - - cache-debug option
+    XXX maybe point to the troubleshooting appendix?
+
+    </para>
+
+  </section>
+
+  -->
+
+  <!--
+
+  <section>
+
+    <para>
+
+    XXX describe CacheDir management:  monitoring, deleting, etc.
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml
index 1953690..66de79c 100644
--- a/doc/user/command-line.sgml
+++ b/doc/user/command-line.sgml
@@ -808,8 +808,8 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -o bar.o -c -D['RELEASE_BUILD=', 1] bar.c
-      cc -o foo.o -c -D['RELEASE_BUILD=', 1] foo.c
+      cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
+      cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
       cc -o foo foo.o bar.o
     </screen>
 
@@ -832,8 +832,8 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      cc -o bar.o -c -D['RELEASE_BUILD=', 0] bar.c
-      cc -o foo.o -c -D['RELEASE_BUILD=', 0] foo.c
+      cc -o bar.o -c -DRELEASE_BUILD=0 bar.c
+      cc -o foo.o -c -DRELEASE_BUILD=0 foo.c
       cc -o foo foo.o bar.o
     </screen>
 
@@ -898,12 +898,12 @@
 
       <screen>
         % <userinput>scons -Q RELEASE=yes foo.o</userinput>
-        cc -o foo.o -c -D['RELEASE_BUILD=', True] foo.c
+        cc -o foo.o -c -DRELEASE_BUILD=True foo.c
       </screen>
 
       <screen>
         % <userinput>scons -Q RELEASE=t foo.o</userinput>
-        cc -o foo.o -c -D['RELEASE_BUILD=', True] foo.c
+        cc -o foo.o -c -DRELEASE_BUILD=True foo.c
       </screen>
 
       <para>
@@ -929,12 +929,12 @@
 
       <screen>
         % <userinput>scons -Q RELEASE=no foo.o</userinput>
-        cc -o foo.o -c -D['RELEASE_BUILD=', False] foo.c
+        cc -o foo.o -c -DRELEASE_BUILD=False foo.c
       </screen>
 
       <screen>
         % <userinput>scons -Q RELEASE=f foo.o</userinput>
-        cc -o foo.o -c -D['RELEASE_BUILD=', False] foo.c
+        cc -o foo.o -c -DRELEASE_BUILD=False foo.c
       </screen>
 
       <para>
@@ -1430,9 +1430,9 @@
         % <userinput>scons -Q PACKAGE=/usr/local/location foo.o</userinput>
         cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c
         % <userinput>scons -Q PACKAGE=yes foo.o</userinput>
-        cc -o foo.o -c -D['PACKAGE="', True, '"'] foo.c
+        cc -o foo.o -c -DPACKAGE="True" foo.c
         % <userinput>scons -Q PACKAGE=no foo.o</userinput>
-        cc -o foo.o -c -D['PACKAGE="', False, '"'] foo.c
+        cc -o foo.o -c -DPACKAGE="False" foo.c
       </screen>
 
     </section>
diff --git a/doc/user/cons.in b/doc/user/cons.in
deleted file mode 100644
index 6967b42..0000000
--- a/doc/user/cons.in
+++ /dev/null
@@ -1,52 +0,0 @@
-<!--
-
-  __COPYRIGHT__
-
-  Permission is hereby granted, free of charge, to any person obtaining
-  a copy of this software and associated documentation files (the
-  "Software"), to deal in the Software without restriction, including
-  without limitation the rights to use, copy, modify, merge, publish,
-  distribute, sublicense, and/or sell copies of the Software, and to
-  permit persons to whom the Software is furnished to do so, subject to
-  the following conditions:
-
-  The above copyright notice and this permission notice shall be included
-  in all copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
-  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
--->
-
- <para>
-
-   XXX
-
- </para>
-
- <section>
- <title>Differences Between &Cons; and &SCons;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>
-
- <section>
- <title>Advantages of &SCons; Over &Cons;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>
diff --git a/doc/user/cons.sgml b/doc/user/cons.sgml
deleted file mode 100644
index 6967b42..0000000
--- a/doc/user/cons.sgml
+++ /dev/null
@@ -1,52 +0,0 @@
-<!--
-
-  __COPYRIGHT__
-
-  Permission is hereby granted, free of charge, to any person obtaining
-  a copy of this software and associated documentation files (the
-  "Software"), to deal in the Software without restriction, including
-  without limitation the rights to use, copy, modify, merge, publish,
-  distribute, sublicense, and/or sell copies of the Software, and to
-  permit persons to whom the Software is furnished to do so, subject to
-  the following conditions:
-
-  The above copyright notice and this permission notice shall be included
-  in all copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
-  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
--->
-
- <para>
-
-   XXX
-
- </para>
-
- <section>
- <title>Differences Between &Cons; and &SCons;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>
-
- <section>
- <title>Advantages of &SCons; Over &Cons;</title>
-
-   <para>
-
-   XXX
-
-   </para>
-
- </section>
diff --git a/doc/user/depends.in b/doc/user/depends.in
index 0262924..e0d5e92 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -23,27 +23,6 @@
 
 -->
 
-<!--
-
-=head2 The C<Salt> method
-
-The C<Salt> method adds a constant value to the signature calculation
-for every derived file.  It is invoked as follows:
-
-  Salt $string;
-
-Changing the Salt value will force a complete rebuild of every derived
-file.  This can be used to force rebuilds in certain desired
-circumstances.  For example,
-
-  Salt `uname -s`;
-
-Would force a complete rebuild of every derived file whenever the
-operating system on which the build is performed (as reported by C<uname
--s>) changes.
-
--->
-
   <para>
 
   So far we've seen how &SCons; handles one-time builds.
@@ -224,7 +203,7 @@ operating system on which the build is performed (as reported by C<uname
     <para>
 
     As you've just seen,
-    &SCons; uses signatures to decide whether a 
+    &SCons; uses signatures to decide whether a
     target file is up to date or must be rebuilt.
     When a target file depends on another target file,
     &SCons; allows you to configure separately
@@ -415,7 +394,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
-    The &cv-CPPPATH; value
+    The &cv-link-CPPPATH; value
     tells &SCons; to look in the current directory
     (<literal>'.'</literal>)
     for any files included by C source files
@@ -462,7 +441,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
-    Like the &cv-LIBPATH; variable,
+    Like the &cv-link-LIBPATH; variable,
     the &cv-CPPPATH; variable
     may be a list of directories,
     or a string separated by
@@ -572,22 +551,46 @@ operating system on which the build is performed (as reported by C<uname
        SetOption('implicit_cache', 1)
     </sconstruct>
 
-    <!--
-
     <para>
-    
-    XXX
 
-    </para>
+    &SCons; does not cache implicit dependencies like this by default
+    because the &implicit-cache; causes &SCons; to simply use the implicit
+    dependencies stored during the last run, without any checking
+    for whether or not those dependencies are still correct.
+    Specifically, this means &implicit-cache; instructs &SCons;
+    to <emphasis>not</emphasis> rebuild "correctly" in the
+    following cases:
 
-    <para>
 
-    &SCons; does not cache implicit dependencies like this by default
-    because XXX
-    
     </para>
 
-    -->
+    <itemizedlist>
+
+      <listitem>
+        <para>
+
+        When &implicit-cache; is used, &SCons; will ignore any changes that
+        may have been made to search paths
+        (like &cv-CPPPATH; or &cv-LIBPATH;,).
+        This can lead to &SCons; not rebuilding a file if a change to
+        &cv-CPPPATH; would normally cause a different, same-named file from
+        a different directory to be used.
+
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+
+        When &implicit-cache; is used, &SCons; will not detect if a
+        same-named file has been added to a directory that is earlier in
+        the search path than the directory in which the file was found
+        last time.
+
+        </para>
+      </listitem>
+
+    </itemizedlist>
 
     <section>
     <title>The &implicit-deps-changed; Option</title>
@@ -633,7 +636,7 @@ operating system on which the build is performed (as reported by C<uname
       and re-scans the file for any updated
       implicit dependency information.
       Sometimes, however, you may want
-      to force &SCons; to use the cached implicit dependencies, 
+      to force &SCons; to use the cached implicit dependencies,
       even if the source files changed.
       This can speed up a build for example,
       when you have changed your source files
@@ -665,6 +668,17 @@ operating system on which the build is performed (as reported by C<uname
 
     </section>
 
+    <!--
+
+    <section>
+    <title>XXX max drift</title>
+
+      XXX SetOption('max_drift')
+
+    </section>
+
+    -->
+
   </section>
 
   <section>
@@ -672,7 +686,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
-    Sometimes it makes sense 
+    Sometimes it makes sense
     to not rebuild a program,
     even if a dependency file changes.
     In this case,
@@ -687,7 +701,7 @@ operating system on which the build is performed (as reported by C<uname
       Ignore(hello, 'hello.h')
       </file>
       <file name="hello.c">
-      #include "hello.h" 
+      #include "hello.h"
       int main() { printf("Hello, %s!\n", string); }
       </file>
       <file name="hello.h">
@@ -785,14 +799,103 @@ operating system on which the build is performed (as reported by C<uname
 
   </section>
 
-  <!-->
+  <section>
+  <title>The &AlwaysBuild; Method</title>
+
+    <para>
+
+    How &SCons; handles dependencies can also be affected
+    by the &AlwaysBuild; method.
+    When a file is passed to the &AlwaysBuild; method,
+    like so:
+
+    </para>
+
+    <scons_example name="AlwaysBuild">
+      <file name="SConstruct" printme="1">
+      hello = Program('hello.c')
+      AlwaysBuild(hello)
+      </file>
+      <file name="hello.c">
+      int main() { printf("Hello, %s!\n", string); }
+      </file>
+    </scons_example>
+
+    <para>
+
+    Then the specified target file (&hello; in our example)
+    will always be considered out-of-date and
+    rebuilt whenever that target file is evaluated
+    while walking the dependency graph:
+
+    </para>
+
+    <scons_output example="AlwaysBuild">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    The &AlwaysBuild; function has a somewhat misleading name,
+    because it does not actually mean the target file will
+    be rebuilt every single time &SCons; is invoked.
+    Instead, it means that the target will, in fact,
+    be rebuilt whenever the target file is encountered
+    while evaluating the targets specified on
+    the command line (and their dependencies).
+    So specifying some other target on the command line,
+    a target that does <emphasis>not</emphasis>
+    itself depend on the &AlwaysBuild; target,
+    will still be rebuilt only if it's out-of-date
+    with respect to its dependencies:
+
+    </para>
+
+    <scons_output example="AlwaysBuild">
+      <scons_output_command>scons -Q</scons_output_command>
+      <scons_output_command>scons -Q hello.o</scons_output_command>
+    </scons_output>
+
+    <!--
+
+      XXX AlwaysBuild() and Alias Nodes
+
+      XXX AlwaysBuild() and Dir Nodes
+
+      XXX AlwaysBuild() with no sources
+
+    -->
+
+  </section>
+
+  <!--
 
   <section>
   <title>The &Salt; Method</title>
 
     <para>
 
-    XXX
+    XXX Salt() (are we going to implement this ?)
+
+        original Cons classic POD documentation:
+
+=head2 The C<Salt> method
+
+The C<Salt> method adds a constant value to the signature calculation
+for every derived file.  It is invoked as follows:
+
+  Salt $string;
+
+Changing the Salt value will force a complete rebuild of every derived
+file.  This can be used to force rebuilds in certain desired
+circumstances.  For example,
+
+  Salt `uname -s`;
+
+Would force a complete rebuild of every derived file whenever the
+operating system on which the build is performed (as reported by C<uname
+-s>) changes.
 
     </para>
 
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index 10a93b6..9e055ee 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -23,27 +23,6 @@
 
 -->
 
-<!--
-
-=head2 The C<Salt> method
-
-The C<Salt> method adds a constant value to the signature calculation
-for every derived file.  It is invoked as follows:
-
-  Salt $string;
-
-Changing the Salt value will force a complete rebuild of every derived
-file.  This can be used to force rebuilds in certain desired
-circumstances.  For example,
-
-  Salt `uname -s`;
-
-Would force a complete rebuild of every derived file whenever the
-operating system on which the build is performed (as reported by C<uname
--s>) changes.
-
--->
-
   <para>
 
   So far we've seen how &SCons; handles one-time builds.
@@ -230,7 +209,7 @@ operating system on which the build is performed (as reported by C<uname
     <para>
 
     As you've just seen,
-    &SCons; uses signatures to decide whether a 
+    &SCons; uses signatures to decide whether a
     target file is up to date or must be rebuilt.
     When a target file depends on another target file,
     &SCons; allows you to configure separately
@@ -422,7 +401,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
-    The &cv-CPPPATH; value
+    The &cv-link-CPPPATH; value
     tells &SCons; to look in the current directory
     (<literal>'.'</literal>)
     for any files included by C source files
@@ -475,7 +454,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
-    Like the &cv-LIBPATH; variable,
+    Like the &cv-link-LIBPATH; variable,
     the &cv-CPPPATH; variable
     may be a list of directories,
     or a string separated by
@@ -587,22 +566,46 @@ operating system on which the build is performed (as reported by C<uname
        SetOption('implicit_cache', 1)
     </programlisting>
 
-    <!--
-
     <para>
-    
-    XXX
 
-    </para>
+    &SCons; does not cache implicit dependencies like this by default
+    because the &implicit-cache; causes &SCons; to simply use the implicit
+    dependencies stored during the last run, without any checking
+    for whether or not those dependencies are still correct.
+    Specifically, this means &implicit-cache; instructs &SCons;
+    to <emphasis>not</emphasis> rebuild "correctly" in the
+    following cases:
 
-    <para>
 
-    &SCons; does not cache implicit dependencies like this by default
-    because XXX
-    
     </para>
 
-    -->
+    <itemizedlist>
+
+      <listitem>
+        <para>
+
+        When &implicit-cache; is used, &SCons; will ignore any changes that
+        may have been made to search paths
+        (like &cv-CPPPATH; or &cv-LIBPATH;,).
+        This can lead to &SCons; not rebuilding a file if a change to
+        &cv-CPPPATH; would normally cause a different, same-named file from
+        a different directory to be used.
+
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+
+        When &implicit-cache; is used, &SCons; will not detect if a
+        same-named file has been added to a directory that is earlier in
+        the search path than the directory in which the file was found
+        last time.
+
+        </para>
+      </listitem>
+
+    </itemizedlist>
 
     <section>
     <title>The &implicit-deps-changed; Option</title>
@@ -651,7 +654,7 @@ operating system on which the build is performed (as reported by C<uname
       and re-scans the file for any updated
       implicit dependency information.
       Sometimes, however, you may want
-      to force &SCons; to use the cached implicit dependencies, 
+      to force &SCons; to use the cached implicit dependencies,
       even if the source files changed.
       This can speed up a build for example,
       when you have changed your source files
@@ -686,6 +689,17 @@ operating system on which the build is performed (as reported by C<uname
 
     </section>
 
+    <!--
+
+    <section>
+    <title>XXX max drift</title>
+
+      XXX SetOption('max_drift')
+
+    </section>
+
+    -->
+
   </section>
 
   <section>
@@ -693,7 +707,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
-    Sometimes it makes sense 
+    Sometimes it makes sense
     to not rebuild a program,
     even if a dependency file changes.
     In this case,
@@ -797,14 +811,104 @@ operating system on which the build is performed (as reported by C<uname
 
   </section>
 
-  <!-->
+  <section>
+  <title>The &AlwaysBuild; Method</title>
+
+    <para>
+
+    How &SCons; handles dependencies can also be affected
+    by the &AlwaysBuild; method.
+    When a file is passed to the &AlwaysBuild; method,
+    like so:
+
+    </para>
+
+    <programlisting>
+      hello = Program('hello.c')
+      AlwaysBuild(hello)
+    </programlisting>
+
+    <para>
+
+    Then the specified target file (&hello; in our example)
+    will always be considered out-of-date and
+    rebuilt whenever that target file is evaluated
+    while walking the dependency graph:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q</userinput>
+      cc -o hello hello.o
+    </screen>
+
+    <para>
+
+    The &AlwaysBuild; function has a somewhat misleading name,
+    because it does not actually mean the target file will
+    be rebuilt every single time &SCons; is invoked.
+    Instead, it means that the target will, in fact,
+    be rebuilt whenever the target file is encountered
+    while evaluating the targets specified on
+    the command line (and their dependencies).
+    So specifying some other target on the command line,
+    a target that does <emphasis>not</emphasis>
+    itself depend on the &AlwaysBuild; target,
+    will still be rebuilt only if it's out-of-date
+    with respect to its dependencies:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q hello.o</userinput>
+      scons: `hello.o' is up to date.
+    </screen>
+
+    <!--
+
+      XXX AlwaysBuild() and Alias Nodes
+
+      XXX AlwaysBuild() and Dir Nodes
+
+      XXX AlwaysBuild() with no sources
+
+    -->
+
+  </section>
+
+  <!--
 
   <section>
   <title>The &Salt; Method</title>
 
     <para>
 
-    XXX
+    XXX Salt() (are we going to implement this ?)
+
+        original Cons classic POD documentation:
+
+=head2 The C<Salt> method
+
+The C<Salt> method adds a constant value to the signature calculation
+for every derived file.  It is invoked as follows:
+
+  Salt $string;
+
+Changing the Salt value will force a complete rebuild of every derived
+file.  This can be used to force rebuilds in certain desired
+circumstances.  For example,
+
+  Salt `uname -s`;
+
+Would force a complete rebuild of every derived file whenever the
+operating system on which the build is performed (as reported by C<uname
+-s>) changes.
 
     </para>
 
diff --git a/doc/user/environments.in b/doc/user/environments.in
index ae453a0..504ef67 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -305,11 +305,7 @@ by the MD5 signature calculation on the actual file contents.
 
 =back
 
-XXX
-
-DESCRIBE THE Literal() FUNCTION, TOO
-
-XXX
+XXX DESCRIBE THE Literal() FUNCTION, TOO XXX
 
 =head2 Expanding construction variables in file names
 
@@ -459,7 +455,7 @@ environment undisturbed.
   </scons_example>
 
  <para>
-   
+
    The construction environment in this example
    is still initialized with the same default
    construction variable values,
@@ -992,6 +988,21 @@ environment undisturbed.
 
    </section>
 
+   <!--
+
+   <section>
+   <title>Setting Values Only If They're Not Already Defined</title>
+
+     <para>
+
+     XXX SetDefault()
+
+     </para>
+
+   </section>
+
+   -->
+
    <section>
    <title>Appending to the End of Values in a &ConsEnv;</title>
 
@@ -1050,6 +1061,12 @@ environment undisturbed.
         <scons_output_command>scons -Q</scons_output_command>
      </scons_output>
 
+     <!--
+
+     XXX AppendUnique()
+
+     -->
+
    </section>
 
    <section>
@@ -1057,7 +1074,7 @@ environment undisturbed.
 
      <para>
 
-     You can append a value to the beginning
+     You can append a value to the beginning of
      an existing construction variable
      using the &Prepend; method:
 
@@ -1110,6 +1127,29 @@ environment undisturbed.
         <scons_output_command>scons -Q</scons_output_command>
      </scons_output>
 
+     <!--
+
+     XXX PrependUnique()
+
+     -->
+
+   </section>
+
+   <!--
+
+   <section>
+   <title>Adding to Values in the Execution Environment</title>
+
+     <para>
+
+     XXX AppendENVPath()
+
+     XXX PrependENVPath()
+
+     </para>
+
    </section>
 
+   -->
+
  </section>
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index 9404c23..67a5551 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -305,11 +305,7 @@ by the MD5 signature calculation on the actual file contents.
 
 =back
 
-XXX
-
-DESCRIBE THE Literal() FUNCTION, TOO
-
-XXX
+XXX DESCRIBE THE Literal() FUNCTION, TOO XXX
 
 =head2 Expanding construction variables in file names
 
@@ -454,7 +450,7 @@ environment undisturbed.
   </programlisting>
 
  <para>
-   
+
    The construction environment in this example
    is still initialized with the same default
    construction variable values,
@@ -988,6 +984,21 @@ environment undisturbed.
 
    </section>
 
+   <!--
+
+   <section>
+   <title>Setting Values Only If They're Not Already Defined</title>
+
+     <para>
+
+     XXX SetDefault()
+
+     </para>
+
+   </section>
+
+   -->
+
    <section>
    <title>Appending to the End of Values in a &ConsEnv;</title>
 
@@ -1043,6 +1054,12 @@ environment undisturbed.
         scons: `.' is up to date.
      </screen>
 
+     <!--
+
+     XXX AppendUnique()
+
+     -->
+
    </section>
 
    <section>
@@ -1050,7 +1067,7 @@ environment undisturbed.
 
      <para>
 
-     You can append a value to the beginning
+     You can append a value to the beginning of
      an existing construction variable
      using the &Prepend; method:
 
@@ -1100,6 +1117,29 @@ environment undisturbed.
         scons: `.' is up to date.
      </screen>
 
+     <!--
+
+     XXX PrependUnique()
+
+     -->
+
+   </section>
+
+   <!--
+
+   <section>
+   <title>Adding to Values in the Execution Environment</title>
+
+     <para>
+
+     XXX AppendENVPath()
+
+     XXX PrependENVPath()
+
+     </para>
+
    </section>
 
+   -->
+
  </section>
diff --git a/doc/user/factories.in b/doc/user/factories.in
index 95145d8..6ef5249 100644
--- a/doc/user/factories.in
+++ b/doc/user/factories.in
@@ -61,7 +61,7 @@
     <para>
 
     Notice that the action returned by the &Copy; factory
-    will expand the &cv-TARGET; and &cv-SOURCE; strings
+    will expand the &cv-link-TARGET; and &cv-link-SOURCE; strings
     at the time &file_out; is built,
     and that the order of the arguments
     is the same as that of a builder itself--that is,
@@ -201,7 +201,7 @@
 
     Of course, like all of these &Action; factories,
     the &Delete factory also expands
-    &cv-TARGET; and &cv-SOURCE; variables appropriately.
+    &cv-link-TARGET; and &cv-link-SOURCE; variables appropriately.
     For example:
 
     </para>
diff --git a/doc/user/factories.sgml b/doc/user/factories.sgml
index b145ff2..e0567f6 100644
--- a/doc/user/factories.sgml
+++ b/doc/user/factories.sgml
@@ -58,7 +58,7 @@
     <para>
 
     Notice that the action returned by the &Copy; factory
-    will expand the &cv-TARGET; and &cv-SOURCE; strings
+    will expand the &cv-link-TARGET; and &cv-link-SOURCE; strings
     at the time &file_out; is built,
     and that the order of the arguments
     is the same as that of a builder itself--that is,
@@ -180,7 +180,7 @@
 
     Of course, like all of these &Action; factories,
     the &Delete; factory also expands
-    &cv-TARGET; and &cv-SOURCE; variables appropriately.
+    &cv-link-TARGET; and &cv-link-SOURCE; variables appropriately.
     For example:
 
     </para>
diff --git a/doc/user/file-removal.in b/doc/user/file-removal.in
index 1d259bf..adc5b5f 100644
--- a/doc/user/file-removal.in
+++ b/doc/user/file-removal.in
@@ -27,7 +27,7 @@
 
   There are two occasions when &SCons; will,
   by default, remove target files.
-  The first is when &SCons; determines that 
+  The first is when &SCons; determines that
   an target file needs to be rebuilt
   and removes the existing version of the target
   before executing
@@ -44,7 +44,7 @@
   <title>Preventing target removal during build: the &Precious; Function</title>
 
     <para>
-    
+
     By default, &SCons; removes targets before building them.
     Sometimes, however, this is not what you want.
     For example, you may want to update a library incrementally,
@@ -53,9 +53,9 @@
     In such cases, you can use the
     &Precious; method to prevent
     &SCons; from removing the target before it is built:
-    
+
     </para>
-    
+
     <scons_example name="precious-ex1">
       <file name="SConstruct" printme="1">
         env = Environment(RANLIBCOM='')
@@ -72,34 +72,33 @@
       int f3() { }
       </file>
     </scons_example>
-    
+
     <para>
-    
+
     Although the output doesn't look any different,
     &SCons; does not, in fact,
     delete the target library before rebuilding it:
-    
+
     </para>
-    
+
     <scons_output example="precious-ex1">
         <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
-    
+
     <para>
-    
+
     &SCons; will, however, still delete files marked as &Precious;
     when the <literal>-c</literal> option is used.
-    
+
     </para>
 
   </section>
 
-
   <section>
   <title>Preventing target removal during clean: the &NoClean; Function</title>
 
     <para>
-    
+
     By default, &SCons; removes all built targets when invoked
     with the <literal>-c</literal> option to clean a source tree
     of built tragets.
@@ -109,12 +108,12 @@
     but leave the final targets
     (the libraries)
     untouched.
-    
+
     In such cases, you can use the &NoClean; method to prevent &SCons;
     from removing a target during a clean:
-    
+
     </para>
-    
+
     <scons_example name="noclean-ex1">
       <file name="SConstruct" printme="1">
         env = Environment(RANLIBCOM='')
@@ -131,14 +130,14 @@
       int f3() { }
       </file>
     </scons_example>
-    
+
     <para>
-    
+
     Notice that the <filename>libfoo.a</filename>
     is not listed as a removed file:
-    
+
     </para>
-    
+
     <scons_output example="noclean-ex1">
         <scons_output_command>scons -Q</scons_output_command>
         <scons_output_command>scons -c</scons_output_command>
@@ -146,3 +145,79 @@
 
   </section>
 
+  <section>
+  <title>Removing additional files during clean: the &Clean; Function</title>
+
+    <para>
+
+    There may be additional files that you want removed
+    when the <literal>-c</literal> option is used,
+    but which &SCons; doesn't know about
+    because they're not normal target files.
+    For example, perhaps a command you invoke
+    creates a log file as
+    part of building the target file you want.
+    You would like the log file cleaned,
+    but you don't want to have to teach
+    SCons that the command
+    "builds" two files.
+
+    </para>
+
+    <para>
+
+    You can use the &Clean; function to arrange for additional files
+    to be removed when the <literal>-c</literal> option is used.
+    Notice, however, that the &Clean; function takes two arguments,
+    and the <emphasis>second</emphasis> argument
+    is the name of the additional file you want cleaned
+    (<filename>foo.log</filename> in this example):
+
+    </para>
+
+    <scons_example name="clean-ex1">
+      <file name="S" printme="1">
+        t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE')
+        Clean(t, 'foo.log')
+      </file>
+      <file name="SConstruct">
+      env = DefaultEnvironment()
+      import os
+      env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
+      SConscript('S')
+      </file>
+      <file name="foo.in">
+      foo.in
+      </file>
+      <file name="foo.log">
+      foo.log
+      </file>
+      <file name="build" chmod="0755">
+      cat $3 > $2
+      </file>
+    </scons_example>
+
+    <para>
+
+    The first argument is the target with which you want
+    the cleaning of this additional file associated.
+    In the above example,
+    we've used the return value from the
+    &Command; function,
+    which represents the
+    <filename>foo.out</filename>
+    target.
+    Now whenever the
+    <filename>foo.out</filename> target is cleaned
+    by the <literal>-c</literal> option,
+    the <filename>foo.log</filename> file
+    will be removed as well:
+
+    </para>
+
+    <scons_output example="clean-ex1">
+        <scons_output_command>scons -Q</scons_output_command>
+        <scons_output_command>scons -Q -c</scons_output_command>
+    </scons_output>
+
+  </section>
diff --git a/doc/user/file-removal.sgml b/doc/user/file-removal.sgml
index 76a2e01..f64d394 100644
--- a/doc/user/file-removal.sgml
+++ b/doc/user/file-removal.sgml
@@ -27,7 +27,7 @@
 
   There are two occasions when &SCons; will,
   by default, remove target files.
-  The first is when &SCons; determines that 
+  The first is when &SCons; determines that
   an target file needs to be rebuilt
   and removes the existing version of the target
   before executing
@@ -44,7 +44,7 @@
   <title>Preventing target removal during build: the &Precious; Function</title>
 
     <para>
-    
+
     By default, &SCons; removes targets before building them.
     Sometimes, however, this is not what you want.
     For example, you may want to update a library incrementally,
@@ -53,23 +53,23 @@
     In such cases, you can use the
     &Precious; method to prevent
     &SCons; from removing the target before it is built:
-    
+
     </para>
-    
+
     <programlisting>
         env = Environment(RANLIBCOM='')
         lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
         env.Precious(lib)
     </programlisting>
-    
+
     <para>
-    
+
     Although the output doesn't look any different,
     &SCons; does not, in fact,
     delete the target library before rebuilding it:
-    
+
     </para>
-    
+
     <screen>
         % <userinput>scons -Q</userinput>
         cc -o f1.o -c f1.c
@@ -77,22 +77,21 @@
         cc -o f3.o -c f3.c
         ar rc libfoo.a f1.o f2.o f3.o
     </screen>
-    
+
     <para>
-    
+
     &SCons; will, however, still delete files marked as &Precious;
     when the <literal>-c</literal> option is used.
-    
+
     </para>
 
   </section>
 
-
   <section>
   <title>Preventing target removal during clean: the &NoClean; Function</title>
 
     <para>
-    
+
     By default, &SCons; removes all built targets when invoked
     with the <literal>-c</literal> option to clean a source tree
     of built tragets.
@@ -102,25 +101,25 @@
     but leave the final targets
     (the libraries)
     untouched.
-    
+
     In such cases, you can use the &NoClean; method to prevent &SCons;
     from removing a target during a clean:
-    
+
     </para>
-    
+
     <programlisting>
         env = Environment(RANLIBCOM='')
         lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
         env.NoClean(lib)
     </programlisting>
-    
+
     <para>
-    
+
     Notice that the <filename>libfoo.a</filename>
     is not listed as a removed file:
-    
+
     </para>
-    
+
     <screen>
         % <userinput>scons -Q</userinput>
         cc -o f1.o -c f1.c
@@ -139,3 +138,65 @@
 
   </section>
 
+  <section>
+  <title>Removing additional files during clean: the &Clean; Function</title>
+
+    <para>
+
+    There may be additional files that you want removed
+    when the <literal>-c</literal> option is used,
+    but which &SCons; doesn't know about
+    because they're not normal target files.
+    For example, perhaps a command you invoke
+    creates a log file as
+    part of building the target file you want.
+    You would like the log file cleaned,
+    but you don't want to have to teach
+    SCons that the command
+    "builds" two files.
+
+    </para>
+
+    <para>
+
+    You can use the &Clean; function to arrange for additional files
+    to be removed when the <literal>-c</literal> option is used.
+    Notice, however, that the &Clean; function takes two arguments,
+    and the <emphasis>second</emphasis> argument
+    is the name of the additional file you want cleaned
+    (<filename>foo.log</filename> in this example):
+
+    </para>
+
+    <programlisting>
+        t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE')
+        Clean(t, 'foo.log')
+    </programlisting>
+
+    <para>
+
+    The first argument is the target with which you want
+    the cleaning of this additional file associated.
+    In the above example,
+    we've used the return value from the
+    &Command; function,
+    which represents the
+    <filename>foo.out</filename>
+    target.
+    Now whenever the
+    <filename>foo.out</filename> target is cleaned
+    by the <literal>-c</literal> option,
+    the <filename>foo.log</filename> file
+    will be removed as well:
+
+    </para>
+
+    <screen>
+        % <userinput>scons -Q</userinput>
+        build -o foo.out foo.in
+        % <userinput>scons -Q -c</userinput>
+        Removed foo.out
+        Removed foo.log
+    </screen>
+
+  </section>
diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in
index 2ec3fd3..d93e811 100644
--- a/doc/user/hierarchy.in
+++ b/doc/user/hierarchy.in
@@ -419,7 +419,7 @@ make no difference to the build.
     (Notice that the <literal>lib/foo1.o</literal> object file
     is built in the same directory as its source file.
     See <xref linkend="chap-separate">, below,
-    for information about 
+    for information about
     how to build the object file in a different subdirectory.)
 
     </para>
@@ -471,7 +471,7 @@ make no difference to the build.
     notice that the <literal>/usr/joe/lib/foo1.o</literal> object file
     is built in the same directory as its source file.
     See <xref linkend="chap-separate">, below,
-    for information about 
+    for information about
     how to build the object file in a different subdirectory.)
 
     </para>
@@ -773,3 +773,18 @@ make no difference to the build.
     </section>
 
   </section>
+
+  <!--
+
+  <section>
+  <title>Executing From a Subdirectory:  the -D, -u and -U Options</title>
+
+    <para>
+
+    XXX -D, -u and -U
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/hierarchy.sgml b/doc/user/hierarchy.sgml
index 0ce2430..713d605 100644
--- a/doc/user/hierarchy.sgml
+++ b/doc/user/hierarchy.sgml
@@ -393,7 +393,7 @@ make no difference to the build.
     (Notice that the <literal>lib/foo1.o</literal> object file
     is built in the same directory as its source file.
     See <xref linkend="chap-separate">, below,
-    for information about 
+    for information about
     how to build the object file in a different subdirectory.)
 
     </para>
@@ -435,7 +435,7 @@ make no difference to the build.
     notice that the <literal>/usr/joe/lib/foo1.o</literal> object file
     is built in the same directory as its source file.
     See <xref linkend="chap-separate">, below,
-    for information about 
+    for information about
     how to build the object file in a different subdirectory.)
 
     </para>
@@ -725,3 +725,18 @@ make no difference to the build.
     </section>
 
   </section>
+
+  <!--
+
+  <section>
+  <title>Executing From a Subdirectory:  the -D, -u and -U Options</title>
+
+    <para>
+
+    XXX -D, -u and -U
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/main.in b/doc/user/main.in
index be302d7..d864350 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -51,7 +51,6 @@
     <!ENTITY builders-writing SYSTEM "builders-writing.sgml">
     <!ENTITY caching SYSTEM "caching.sgml">
     <!ENTITY command-line SYSTEM "command-line.sgml">
-    <!ENTITY cons SYSTEM "cons.sgml">
     <!ENTITY copyright SYSTEM "copyright.sgml">
     <!ENTITY depends SYSTEM "depends.sgml">
     <!ENTITY ENV_file SYSTEM "ENV.sgml">
@@ -90,6 +89,53 @@
 
 ]>
 
+  <!--
+
+  XXX AllowSubstExceptions()
+  XXX EnsurePythonVersion()
+  XXX EnsureSConsVersion()
+  XXX Exit()
+  XXX FindFile()
+  XXX FindPathDirs()
+  XXX Flatten()
+  XXX GetBuildPath()
+  XXX GetLaunchDir()
+
+  XXX MergeFlags()
+  XXX ParseFlags()
+
+  XXX ParseDepends()
+  XXX Platform()
+  XXX SConsignFile()
+  XXX SideEffect()
+  XXX Tools()
+
+  XXX GetOption('clean')
+  XXX SetOption('clean')
+
+  XXX GetOption('duplicate')
+  XXX SetOption('duplicate')
+  XXX - - duplicate=
+
+  XXX GetOption('num_jobs')
+  XXX SetOption('num_jobs')
+
+  XXX - - diskcheck=
+
+  XXX site_scons
+  XXX - - site-dir
+  XXX - - no-site-dir
+
+  XXX - - warn=
+
+  XXX ARGLIST
+  XXX ARGUMENTS
+  XXX BUILD_TARGETS
+  XXX COMMAND_LINE_TARGETS
+  XXX DEFAULT_TARGETS
+
+  -->
+
 <book>
   <bookinfo>
     <title>SCons User Guide &buildversion;</title>
@@ -231,6 +277,10 @@
 
   <!--
 
+  XXX Action()
+  XXX AddPostAction()
+  XXX AddPreAction()
+
   <chapter id="chap-actions">
     <title>&SCons; Actions</title>
     &actions;
@@ -291,21 +341,6 @@
     &troubleshoot;
   </chapter>
 
-  <!--
-  AddPostAction()
-  AddPreAction()
-  Clean()
-  Dir()
-  File()
-  FindFile()
-  GetJobs()
-  SetJobs()
-  SideEffect()
-  ParseConfig()
-  Platform()
-  Tools()
-  -->
-
   <appendix id="app-variables">
     <title>Construction Variables</title>
     &variables;
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
index be302d7..d864350 100644
--- a/doc/user/main.sgml
+++ b/doc/user/main.sgml
@@ -51,7 +51,6 @@
     <!ENTITY builders-writing SYSTEM "builders-writing.sgml">
     <!ENTITY caching SYSTEM "caching.sgml">
     <!ENTITY command-line SYSTEM "command-line.sgml">
-    <!ENTITY cons SYSTEM "cons.sgml">
     <!ENTITY copyright SYSTEM "copyright.sgml">
     <!ENTITY depends SYSTEM "depends.sgml">
     <!ENTITY ENV_file SYSTEM "ENV.sgml">
@@ -90,6 +89,53 @@
 
 ]>
 
+  <!--
+
+  XXX AllowSubstExceptions()
+  XXX EnsurePythonVersion()
+  XXX EnsureSConsVersion()
+  XXX Exit()
+  XXX FindFile()
+  XXX FindPathDirs()
+  XXX Flatten()
+  XXX GetBuildPath()
+  XXX GetLaunchDir()
+
+  XXX MergeFlags()
+  XXX ParseFlags()
+
+  XXX ParseDepends()
+  XXX Platform()
+  XXX SConsignFile()
+  XXX SideEffect()
+  XXX Tools()
+
+  XXX GetOption('clean')
+  XXX SetOption('clean')
+
+  XXX GetOption('duplicate')
+  XXX SetOption('duplicate')
+  XXX - - duplicate=
+
+  XXX GetOption('num_jobs')
+  XXX SetOption('num_jobs')
+
+  XXX - - diskcheck=
+
+  XXX site_scons
+  XXX - - site-dir
+  XXX - - no-site-dir
+
+  XXX - - warn=
+
+  XXX ARGLIST
+  XXX ARGUMENTS
+  XXX BUILD_TARGETS
+  XXX COMMAND_LINE_TARGETS
+  XXX DEFAULT_TARGETS
+
+  -->
+
 <book>
   <bookinfo>
     <title>SCons User Guide &buildversion;</title>
@@ -231,6 +277,10 @@
 
   <!--
 
+  XXX Action()
+  XXX AddPostAction()
+  XXX AddPreAction()
+
   <chapter id="chap-actions">
     <title>&SCons; Actions</title>
     &actions;
@@ -291,21 +341,6 @@
     &troubleshoot;
   </chapter>
 
-  <!--
-  AddPostAction()
-  AddPreAction()
-  Clean()
-  Dir()
-  File()
-  FindFile()
-  GetJobs()
-  SetJobs()
-  SideEffect()
-  ParseConfig()
-  Platform()
-  Tools()
-  -->
-
   <appendix id="app-variables">
     <title>Construction Variables</title>
     &variables;
diff --git a/doc/user/nodes.in b/doc/user/nodes.in
index 4b8aa0f..6d4b267 100644
--- a/doc/user/nodes.in
+++ b/doc/user/nodes.in
@@ -353,3 +353,18 @@
   </section>
 
   -->
+
+  <!--
+
+  <section>
+  <title>Python Value &Node;</title>
+
+    <para>
+
+    XXX Value()
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/nodes.sgml b/doc/user/nodes.sgml
index c8756c5..4ada5b7 100644
--- a/doc/user/nodes.sgml
+++ b/doc/user/nodes.sgml
@@ -356,3 +356,18 @@
   </section>
 
   -->
+
+  <!--
+
+  <section>
+  <title>Python Value &Node;</title>
+
+    <para>
+
+    XXX Value()
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/preface.in b/doc/user/preface.in
index 2914d40..fb888c4 100644
--- a/doc/user/preface.in
+++ b/doc/user/preface.in
@@ -198,7 +198,7 @@
 
     <para>
 
-    XXX
+    XXX history of SCons
 
     </para>
 
@@ -213,7 +213,7 @@
 
     <para>
 
-    XXX
+    XXX conventions used in this manual
 
     </para>
 
diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml
index ba5d1a3..694f41b 100644
--- a/doc/user/preface.sgml
+++ b/doc/user/preface.sgml
@@ -198,7 +198,7 @@
 
     <para>
 
-    XXX
+    XXX history of SCons
 
     </para>
 
@@ -213,7 +213,7 @@
 
     <para>
 
-    XXX
+    XXX conventions used in this manual
 
     </para>
 
diff --git a/doc/user/repositories.in b/doc/user/repositories.in
index a667a91..9065593 100644
--- a/doc/user/repositories.in
+++ b/doc/user/repositories.in
@@ -114,7 +114,7 @@
     found in the local build tree,
     &SCons; will search first for
     a <filename>/usr/repository1/hello.c</filename> file
-    and then for a <filename>/usr/repository1/hello.c</filename> file
+    and then for a <filename>/usr/repository2/hello.c</filename> file
     to use in its place.
 
     </para>
@@ -195,7 +195,7 @@
     a source file for <literal>#include</literal> file names
     and realize that targets built from that source file
     also depend on the <literal>#include</literal> file(s).
-    For each directory in the &cv-CPPPATH; list,
+    For each directory in the &cv-link-CPPPATH; list,
     &SCons; will actually search the corresponding directories
     in any repository trees and establish the
     correct dependencies on any
@@ -390,8 +390,8 @@ coming into existence.)
 
         Some modern versions of C compilers do have an option
         to disable or control this behavior.
-        If so, add that option to &cv-CFLAGS;
-        (or &cv-CXXFLAGS; or both) in your construction environment(s).
+        If so, add that option to &cv-link-CFLAGS;
+        (or &cv-link-CXXFLAGS; or both) in your construction environment(s).
         Make sure the option is used for all construction
         environments that use C preprocessing!
 
diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml
index c659aa2..f22611b 100644
--- a/doc/user/repositories.sgml
+++ b/doc/user/repositories.sgml
@@ -109,7 +109,7 @@
     found in the local build tree,
     &SCons; will search first for
     a <filename>/usr/repository1/hello.c</filename> file
-    and then for a <filename>/usr/repository1/hello.c</filename> file
+    and then for a <filename>/usr/repository2/hello.c</filename> file
     to use in its place.
 
     </para>
@@ -178,7 +178,7 @@
     a source file for <literal>#include</literal> file names
     and realize that targets built from that source file
     also depend on the <literal>#include</literal> file(s).
-    For each directory in the &cv-CPPPATH; list,
+    For each directory in the &cv-link-CPPPATH; list,
     &SCons; will actually search the corresponding directories
     in any repository trees and establish the
     correct dependencies on any
@@ -360,8 +360,8 @@ coming into existence.)
 
         Some modern versions of C compilers do have an option
         to disable or control this behavior.
-        If so, add that option to &cv-CFLAGS;
-        (or &cv-CXXFLAGS; or both) in your construction environment(s).
+        If so, add that option to &cv-link-CFLAGS;
+        (or &cv-link-CXXFLAGS; or both) in your construction environment(s).
         Make sure the option is used for all construction
         environments that use C preprocessing!
 
diff --git a/doc/user/sconf.in b/doc/user/sconf.in
index 14c10b7..0165ddd 100644
--- a/doc/user/sconf.in
+++ b/doc/user/sconf.in
@@ -469,3 +469,18 @@
     </screen>
 
   </section>
+
+  <!--
+
+  <section>
+  <title>Controlling Configuration:  the &config; Option</title>
+
+    <para>
+
+    XXX -D, -u and -U
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/sconf.sgml b/doc/user/sconf.sgml
index 997c97d..df530fe 100644
--- a/doc/user/sconf.sgml
+++ b/doc/user/sconf.sgml
@@ -469,3 +469,18 @@
     </screen>
 
   </section>
+
+  <!--
+
+  <section>
+  <title>Controlling Configuration:  the &config; Option</title>
+
+    <para>
+
+    XXX -D, -u and -U
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/separate.in b/doc/user/separate.in
index 6d497a2..08bb986 100644
--- a/doc/user/separate.in
+++ b/doc/user/separate.in
@@ -268,7 +268,7 @@ program using the F<build/foo.c> path name.
 
     </para>
 
-  </section> 
+  </section>
 
   <section>
   <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title>
@@ -460,8 +460,8 @@ program using the F<build/foo.c> path name.
   <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title>
 
     <para>
-    
-    XXX
+
+    XXX why call BuildDir() instead of SConscript(build_dir=)
 
     </para>
 
diff --git a/doc/user/separate.sgml b/doc/user/separate.sgml
index 5f0341d..57acd48 100644
--- a/doc/user/separate.sgml
+++ b/doc/user/separate.sgml
@@ -263,7 +263,7 @@ program using the F<build/foo.c> path name.
 
     </para>
 
-  </section> 
+  </section>
 
   <section>
   <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title>
@@ -451,8 +451,8 @@ program using the F<build/foo.c> path name.
   <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title>
 
     <para>
-    
-    XXX
+
+    XXX why call BuildDir() instead of SConscript(build_dir=)
 
     </para>
 
diff --git a/doc/user/tools.in b/doc/user/tools.in
index 8eaa35e..512bf97 100644
--- a/doc/user/tools.in
+++ b/doc/user/tools.in
@@ -26,7 +26,7 @@
 <para>
 
 This appendix contains descriptions of all of the
-Tools that are
+Tools modules that are
 available "out of the box" in this version of SCons.
 
 </para>
diff --git a/doc/user/tools.sgml b/doc/user/tools.sgml
index 8eaa35e..512bf97 100644
--- a/doc/user/tools.sgml
+++ b/doc/user/tools.sgml
@@ -26,7 +26,7 @@
 <para>
 
 This appendix contains descriptions of all of the
-Tools that are
+Tools modules that are
 available "out of the box" in this version of SCons.
 
 </para>
diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in
index 206e50e..11f44dd 100644
--- a/doc/user/troubleshoot.in
+++ b/doc/user/troubleshoot.in
@@ -32,6 +32,28 @@
   the tool is behaving a certain way,
   and how to get it to behave the way you want.
   &SCons; is no different.
+  This appendix contains a number of
+  different ways in which you can
+  get some additional insight into &SCons' behavior.
+
+  </para>
+
+  <para>
+
+  Note that we're always interested in trying to
+  improve how you can troubleshoot configuration problems.
+  If you run into a problem that has
+  you scratching your head,
+  and which there just doesn't seem to be a good way to debug,
+  odds are pretty good that someone else will run into
+  the same problem, too.
+  If so, please let the SCons development team know
+  (preferably by filing a bug report
+  or feature request at our project pages at tigris.org)
+  so that we can use your feedback
+  to try to come up with a better way to help you,
+  and others, get the necessary insight into &SCons; behavior
+  to help identify and fix configuration issues.
 
   </para>
 
@@ -40,7 +62,7 @@
 
     <para>
 
-    Let's take a simple example of
+    Let's look at a simple example of
     a misconfigured build
     that causes a target to be rebuilt
     every time &SCons; is run:
@@ -70,7 +92,7 @@
 
     <para>
 
-    Now if we run &SCons; multiple on this example,
+    Now if we run &SCons; multiple times on this example,
     we see that it re-runs the &cp;
     command every time:
 
@@ -193,6 +215,17 @@
       <scons_output_command>scons -Q --debug=explain</scons_output_command>
     </scons_output>
 
+    <para>
+
+    (Note that the &debug-explain; option will only tell you
+    why &SCons; decided to rebuild necessary targets.
+    It does not tell you what files it examined
+    when deciding <emphasis>not</emphasis>
+    to rebuild a target file,
+    which is often a more valuable question to answer.)
+
+    </para>
+
   </section>
 
   <section>
@@ -223,7 +256,7 @@
     </para>
 
     <scons_example name="Dump">
-      <file name="SConstruct" print="1">
+      <file name="SConstruct" printme="1">
          env = Environment()
          print env.Dump()
       </file>
@@ -279,7 +312,7 @@
     </para>
 
     <scons_example name="Dump_ENV">
-      <file name="SConstruct" print="1">
+      <file name="SConstruct" printme="1">
          env = Environment()
          print env.Dump('ENV')
       </file>
@@ -306,3 +339,533 @@
     </scons_output>
 
   </section>
+
+  <section>
+
+  <title>What Dependencies Does &SCons; Know About?  the &tree; Option</title>
+
+    <para>
+
+    Sometimes the best way to try to figure out what
+    &SCons; is doing is simply to take a look at the
+    dependency graph that it constructs
+    based on your &SConscript; files.
+    The <literal>--tree</literal> option
+    will display all or part of the
+    &SCons; dependency graph in an
+    "ASCII art" graphical format
+    that shows the dependency hierarchy.
+
+    </para>
+
+    <para>
+
+    For example, given the following input &SConstruct; file:
+
+    </para>
+
+    <scons_example name="tree1">
+      <file name="SConstruct" printme="1">
+         env = Environment(CPPPATH = ['.'])
+         env.Program('prog', ['f1.c', 'f2.c', 'f3.c'])
+      </file>
+      <file name="f1.c">
+      #include "inc.h"
+      </file>
+      <file name="f2.c">
+      #include "inc.h"
+      </file>
+      <file name="f3.c">
+      #include "inc.h"
+      </file>
+      <file name="inc.h">
+      inc.h
+      </file>
+    </scons_example>
+
+    <para>
+
+    Running &SCons; with the <literal>--tree=all</literal>
+    option yields:
+
+    </para>
+
+    <scons_output example="tree1">
+      <scons_output_command>scons -Q --tree=all</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    The tree will also be printed when the
+    <literal>-n</literal> (no execute) option is used,
+    which allows you to examine the dependency graph
+    for a configuration without actually
+    rebuilding anything in the tree.
+
+    </para>
+
+    <para>
+
+    The <literaL>--tree</literal> option only prints
+    the dependency graph for the specified targets
+    (or the default target(s) if none are specified on the command line).
+    So if you specify a target like <filename>f2.o</filename>
+    on the command line,
+    the <literaL>--tree</literal> option will only
+    print the dependency graph for that file:
+
+    </para>
+
+    <scons_output example="tree1">
+      <scons_output_command>scons -Q --tree=all f2.o</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    This is, of course, useful for
+    restricting the output from a very large
+    build configuration to just a
+    portion in which you're interested.
+    Multiple targets are fine,
+    in which case a tree will be printed
+    for each specified target:
+
+    </para>
+
+    <scons_output example="tree1">
+      <scons_output_command>scons -Q --tree=all f1.o f3.o</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    The <literal>status</literal> argument may be used
+    to tell &SCons; to print status information about
+    each file in the dependency graph:
+
+    </para>
+
+    <scons_output example="tree1">
+      <scons_output_command>scons -Q --tree=status</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    Note that <literal>--tree=all,status</literal> is equivalent;
+    the <literal>all</literal>
+    is assumed if only <literal>status</literal> is present.
+    As an alternative to <literal>all</literal>,
+    you can specify <literal>--tree=derived</literal>
+    to have &SCons; only print derived targets
+    in the tree output,
+    skipping source files
+    (like <filename>.c</filename> and <filename>.h</filename> files):
+
+    </para>
+
+    <scons_output example="tree1">
+      <scons_output_command>scons -Q --tree=derived</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    You can use the <literal>status</literal>
+    modifier with <literal>derived</literal> as well:
+
+    </para>
+
+    <scons_output example="tree1">
+      <scons_output_command>scons -Q --tree=derived,status</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    Note that the order of the <literal>--tree=</literal>
+    arguments doesn't matter;
+    <literal>--tree=status,derived</literal> is
+    completely equivalent.
+
+    </para>
+
+    <para>
+
+    The default behavior of the <literal>--tree</literal> option
+    is to repeat all of the dependencies each time the library dependency
+    (or any other dependency file) is encountered in the tree.
+    If certain target files share other target files,
+    such as two programs that use the same library:
+
+    </para>
+
+    <scons_example name="tree2">
+      <file name="SConstruct" printme="1">
+         env = Environment(CPPPATH = ['.'],
+                           LIBS = ['foo'],
+                           LIBPATH = ['.'])
+         env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+         env.Program('prog1.c')
+         env.Program('prog2.c')
+      </file>
+      <file name="prog1.c">
+      #include "inc.h"
+      </file>
+      <file name="prog2.c">
+      #include "inc.h"
+      </file>
+      <file name="f1.c">
+      #include "inc.h"
+      </file>
+      <file name="f2.c">
+      #include "inc.h"
+      </file>
+      <file name="f3.c">
+      #include "inc.h"
+      </file>
+      <file name="inc.h">
+      inc.h
+      </file>
+    </scons_example>
+
+    <para>
+
+    Then there can be a <emphasis>lot</emphasis> of repetition in the
+    <literal>--tree=</literal> output:
+
+    </para>
+
+    <scons_output example="tree2">
+      <scons_output_command>scons -Q --tree=all</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    In a large configuration with many internal libraries
+    and include files,
+    this can very quickly lead to huge output trees.
+    To help make this more manageable,
+    a <literal>prune</literal> modifier may
+    be added to the option list,
+    in which case &SCons;
+    will print the name of a target that has
+    already been visited during the tree-printing
+    in <literal>[square brackets]</literal>
+    as an indication that the dependencies
+    of the target file may be found
+    by looking farther up the tree:
+
+    </para>
+
+    <scons_output example="tree2">
+      <scons_output_command>scons -Q --tree=prune</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    Like the <literal>status</literal> keyword,
+    the <literal>prune</literal> argument by itself
+    is equivalent to <literal>--tree=all,prune</literal>.
+
+    </para>
+
+  </section>
+
+  <section>
+
+  <title>How is &SCons; Constructing the Command Lines It Executes?  the &debug-presub; Option</title>
+
+    <para>
+
+    Sometimes it's useful to look at the
+    pre-substitution string
+    that &SCons; uses to generate
+    the command lines it executes.
+    This can be done with the &debug-presub; option:
+
+    </para>
+
+    <scons_example name="presub">
+      <file name="SConstruct">
+         env = Environment(CPPPATH = ['.'])
+         env.Program('prog', 'prog.c')
+      </file>
+      <file name="prog.c">
+      prog.c
+      </file>
+    </scons_example>
+
+    <!--
+
+    Have to capture output here, otherwise the - -debug=presub output
+    shows the Python functions from the sconsdoc.py execution wrapper
+    used to generate this manual, not the underlying command-line strings.
+
+    <scons_output example="presub">
+      <scons_output_command>scons -Q - -debug=presub</scons_output_command>
+    </scons_output>
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q --debug=presub</userinput>
+      Building prog.o with action:
+        $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES
+      cc -o prog.o -c -I. prog.c
+      Building prog with action:
+        $SMART_LINKCOM
+      cc -o prog prog.o
+    </screen>
+
+  </section>
+
+  <section>
+
+  <title>Where is &SCons; Searching for Libraries?  the &debug-findlibs; Option</title>
+
+    <para>
+
+    To get some insight into what library names
+    &SCons; is searching for,
+    and in which directories it is searching,
+    Use the <literal>--debug=findlibs</literal> option.
+    Given the following input &SConstruct; file:
+
+    </para>
+
+    <scons_example name="findlibs">
+      <file name="SConstruct" printme="1">
+        env = Environment(LIBPATH = ['libs1', 'libs2'])
+        env.Program('prog.c', LIBS=['foo', 'bar'])
+      </file>
+      <file name="prog.c">
+      prog.c
+      </file>
+      <file name="libs1/libfoo.a">
+      libs1/libfoo.a
+      </file>
+      <file name="libs2/libbar.a">
+      libs2/libbar.a
+      </file>
+    </scons_example>
+
+    <para>
+
+    And the libraries <filename>libfoo.a</filename>
+    and <filename>libbar.a</filename>
+    in <filename>libs1</filename> and <filename>libs2</filename>,
+    respectively,
+    use of the <literal>--debug=findlibs</literal> option yields:
+
+    </para>
+
+    <scons_output example="findlibs">
+      <scons_output_command>scons -Q --debug=findlibs</scons_output_command>
+    </scons_output>
+
+  </section>
+
+  <!--
+
+  <section>
+
+  <title>What Implicit Dependencies Did the &SCons; Scanner find?  the &debug-includes; Option</title>
+
+    <para>
+
+    XXX explain the - - debug=includes option
+
+    </para>
+
+    <scons_example name="includes">
+      <file name="SConstruct" printme="1">
+        env = Environment(CPPPATH = ['inc1', 'inc2'])
+        env.Program('prog.c')
+      </file>
+      <file name="prog.c">
+      #include "file1.h"
+      #include "file2.h"
+      prog.c
+      </file>
+      <file name="inc1/file1.h">
+      inc1/file1.h
+      </file>
+      <file name="inc2/file2.h">
+      inc2/file2.h
+      </file>
+    </scons_example>
+
+    <scons_output example="includes">
+      <scons_output_command>scons -Q - - debug=includes prog</scons_output_command>
+    </scons_output>
+
+  </section>
+
+  -->
+
+  <section>
+
+  <title>Where is &SCons; Blowing Up?  the &debug-stacktrace; Option</title>
+
+    <para>
+
+    In general, &SCons; tries to keep its error
+    messages short and informative.
+    That means we usually try to avoid showing
+    the stack traces that are familiar
+    to experienced Python programmers,
+    since they usually contain much more
+    information than is useful to most people.
+
+    </para>
+
+    <para>
+
+    For example, the following &SConstruct file:
+
+    </para>
+
+    <scons_example name="stacktrace">
+      <file name="SConstruct" printme="1">
+         Program('prog.c')
+      </file>
+    </scons_example>
+
+    <para>
+
+    Generates the following error if the
+    <filename>prog.c</filename> file
+    does not exist:
+
+    </para>
+
+    <scons_output example="stacktrace">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    In this case,
+    the error is pretty obvious.
+    But if it weren't,
+    and you wanted to try to get more information
+    about the error,
+    the &debug-stacktrace; option
+    would show you exactly where in the &SCons; source code
+    the problem occurs:
+
+    </para>
+
+    <scons_output example="stacktrace">
+      <scons_output_command>scons -Q --debug=stacktrace</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    Of course, if you do need to dive into the &SCons; source code,
+    we'd like to know if, or how,
+    the error messages or troubleshooting options
+    could have been improved to avoid that.
+    Not everyone has the necessary time or
+    Python skill to dive into the source code,
+    and we'd like to improve &SCons;
+    for those people as well...
+
+    </para>
+
+  </section>
+
+  <section>
+
+  <title>How is &SCons; Making Its Decisions?  the &taskmastertrace; Option</title>
+
+    <para>
+
+    The internal &SCons; subsystem that handles walking
+    the dependency graph
+    and controls the decision-making about what to rebuild
+    is the <literal>Taskmaster</literal>.
+    &SCons; supports a <literal>--taskmastertrace</literal>
+    option that tells the Taskmaster to print
+    information about the children (dependencies)
+    of the various Nodes on its walk down the graph,
+    which specific dependent Nodes are being evaluated,
+    and in what order.
+
+    </para>
+
+    <para>
+
+    The <literal>--taskmastertrace</literal> option
+    takes as an argument the name of a file in
+    which to put the trace output,
+    with <filename>-</filename> (a single hyphen)
+    indicating that the trace messages
+    should be printed to the standard output:
+
+    </para>
+
+    <scons_example name="taskmastertrace">
+      <file name="SConstruct" printme="1">
+      env = Environment(CPPPATH = ['.'])
+      env.Program('prog.c')
+      </file>
+      <file name="prog.c">
+      #include "inc.h"
+      prog.c
+      </file>
+      <file name="inc.h">
+      #define   STRING  "one"
+      </file>
+    </scons_example>
+
+    <scons_output example="taskmastertrace" os="posix">
+      <scons_output_command>scons -Q --taskmastertrace=- prog</scons_output_command>
+    </scons_output>
+
+    <para>
+
+    The <literal>--taskmastertrace</literal> option
+    doesn't provide information about the actual
+    calculations involved in deciding if a file is up-to-date,
+    but it does show all of the dependencies
+    it knows about for each Node,
+    and the order in which those dependencies are evaluated.
+    This can be useful as an alternate way to determine
+    whether or not your &SCons; configuration,
+    or the implicit dependency scan,
+    has actually identified all the correct dependencies
+    you want it to.
+
+    </para>
+
+  </section>
+
+  <!--
+
+  <section>
+
+  <title>Where Are My Build Bottlenecks?  the &profile; Option</title>
+
+    <para>
+
+    XXX explain the - - profile= option
+
+    </para>
+
+  </section>
+
+  -->
+
+  <!--
+
+  <section>
+  <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
+
+    <para>
+
+    XXX describe the - - cache-debug option
+    XXX maybe point to the caching.in chapter?
+
+    </para>
+
+  </section>
+
+  -->
diff --git a/doc/user/troubleshoot.sgml b/doc/user/troubleshoot.sgml
index f019baa..3df9c67 100644
--- a/doc/user/troubleshoot.sgml
+++ b/doc/user/troubleshoot.sgml
@@ -32,6 +32,28 @@
   the tool is behaving a certain way,
   and how to get it to behave the way you want.
   &SCons; is no different.
+  This appendix contains a number of
+  different ways in which you can
+  get some additional insight into &SCons;' behavior.
+
+  </para>
+
+  <para>
+
+  Note that we're always interested in trying to
+  improve how you can troubleshoot configuration problems.
+  If you run into a problem that has
+  you scratching your head,
+  and which there just doesn't seem to be a good way to debug,
+  odds are pretty good that someone else will run into
+  the same problem, too.
+  If so, please let the SCons development team know
+  (preferably by filing a bug report
+  or feature request at our project pages at tigris.org)
+  so that we can use your feedback
+  to try to come up with a better way to help you,
+  and others, get the necessary insight into &SCons; behavior
+  to help identify and fix configuration issues.
 
   </para>
 
@@ -40,7 +62,7 @@
 
     <para>
 
-    Let's take a simple example of
+    Let's look at a simple example of
     a misconfigured build
     that causes a target to be rebuilt
     every time &SCons; is run:
@@ -65,7 +87,7 @@
 
     <para>
 
-    Now if we run &SCons; multiple on this example,
+    Now if we run &SCons; multiple times on this example,
     we see that it re-runs the &cp;
     command every time:
 
@@ -184,6 +206,17 @@
       cc -o prog file1.o file2.o file3.o
     </screen>
 
+    <para>
+
+    (Note that the &debug-explain; option will only tell you
+    why &SCons; decided to rebuild necessary targets.
+    It does not tell you what files it examined
+    when deciding <emphasis>not</emphasis>
+    to rebuild a target file,
+    which is often a more valuable question to answer.)
+
+    </para>
+
   </section>
 
   <section>
@@ -213,7 +246,10 @@
 
     </para>
 
-    
+    <programlisting>
+         env = Environment()
+         print env.Dump()
+    </programlisting>
 
     <para>
 
@@ -248,14 +284,14 @@
                          '.spp',
                          '.SPP'],
         'DSUFFIXES': ['.d'],
-        'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43bec&gt;,
-        'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c0c&gt;,
+        'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c3fdac&gt;,
+        'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c3fdcc&gt;,
         'ENV': {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'},
-        'ESCAPE': &lt;function escape at 0xb7b66c34&gt;,
-        'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c2c&gt;,
+        'ESCAPE': &lt;function escape at 0xb7ba1f0c&gt;,
+        'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c3fdec&gt;,
         'IDLSUFFIXES': ['.idl', '.IDL'],
-        'INSTALL': &lt;function installFunc at 0xb7c41f0c&gt;,
-        'INSTALLSTR': &lt;function installStr at 0xb7c41f44&gt;,
+        'INSTALL': &lt;function installFunc at 0xb7c4317c&gt;,
+        'INSTALLSTR': &lt;function installStr at 0xb7c431b4&gt;,
         'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
         'LIBPREFIX': 'lib',
         'LIBPREFIXES': '$LIBPREFIX',
@@ -267,16 +303,16 @@
         'PLATFORM': 'posix',
         'PROGPREFIX': '',
         'PROGSUFFIX': '',
-        'PSPAWN': &lt;function piped_env_spawn at 0xb7b66fb4&gt;,
-        'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c4c&gt;,
+        'PSPAWN': &lt;function piped_env_spawn at 0xb7bb12cc&gt;,
+        'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c3fe0c&gt;,
         'SCANNERS': [],
         'SHELL': 'sh',
         'SHLIBPREFIX': '$LIBPREFIX',
         'SHLIBSUFFIX': '.so',
         'SHOBJPREFIX': '$OBJPREFIX',
         'SHOBJSUFFIX': '$OBJSUFFIX',
-        'SPAWN': &lt;function spawnvpe_spawn at 0xb7b66a74&gt;,
-        'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7bd37ac&gt;,
+        'SPAWN': &lt;function spawnvpe_spawn at 0xb7ba1d4c&gt;,
+        'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7bce89c&gt;,
         'TEMPFILEPREFIX': '@',
         'TOOLS': [],
         '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
@@ -284,10 +320,10 @@
         '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
         '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
         '__RPATH': '$_RPATH',
-        '_concat': &lt;function _concat at 0xb7c41fb4&gt;,
-        '_defines': &lt;function _defines at 0xb7c47064&gt;,
-        '_installStr': &lt;function installStr at 0xb7c41f44&gt;,
-        '_stripixes': &lt;function _stripixes at 0xb7c4702c&gt;}
+        '_concat': &lt;function _concat at 0xb7c43224&gt;,
+        '_defines': &lt;function _defines at 0xb7c432cc&gt;,
+        '_installStr': &lt;function installStr at 0xb7c431b4&gt;,
+        '_stripixes': &lt;function _stripixes at 0xb7c43294&gt;}
       scons: done reading SConscript files.
       scons: Building targets ...
       scons: `.' is up to date.
@@ -304,9 +340,9 @@
     <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      { 'BUILDERS': {'Object': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6024c&gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b603cc&gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6024c&gt;, 'PCH': &lt;SCons.Builder.BuilderBase instance at 0xb7bd2eac&gt;, 'RES': &lt;SCons.Builder.BuilderBase instance at 0xb7b596ec&gt;},
+      { 'BUILDERS': {'Object': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6354c&gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b636cc&gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6354c&gt;, 'PCH': &lt;SCons.Builder.BuilderBase instance at 0xb7bd6e8c&gt;, 'RES': &lt;SCons.Builder.BuilderBase instance at 0xb7b5b9ec&gt;},
         'CC': 'cl',
-        'CCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b6086c&gt;,
+        'CCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b63b6c&gt;,
         'CCCOMFLAGS': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo$TARGET $CCPCHFLAGS $CCPDBFLAGS',
         'CCFLAGS': ['/nologo'],
         'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'],
@@ -341,20 +377,20 @@
         'CXXFILESUFFIX': '.cc',
         'CXXFLAGS': ['$CCFLAGS', '$(', '/TP', '$)'],
         'DSUFFIXES': ['.d'],
-        'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58bec&gt;,
-        'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c0c&gt;,
+        'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c5adac&gt;,
+        'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c5adcc&gt;,
         'ENV': { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include',
                  'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib',
                  'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin',
                  'PATHEXT': '.COM;.EXE;.BAT;.CMD',
                  'SystemRoot': 'C:/WINDOWS'},
-        'ESCAPE': &lt;function escape at 0xb7bc917c&gt;,
-        'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c2c&gt;,
+        'ESCAPE': &lt;function escape at 0xb7bcf454&gt;,
+        'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c5adec&gt;,
         'IDLSUFFIXES': ['.idl', '.IDL'],
         'INCPREFIX': '/I',
         'INCSUFFIX': '',
-        'INSTALL': &lt;function installFunc at 0xb7c56f0c&gt;,
-        'INSTALLSTR': &lt;function installStr at 0xb7c56f44&gt;,
+        'INSTALL': &lt;function installFunc at 0xb7c5e17c&gt;,
+        'INSTALLSTR': &lt;function installStr at 0xb7c5e1b4&gt;,
         'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
         'LIBPREFIX': '',
         'LIBPREFIXES': ['$LIBPREFIX'],
@@ -370,14 +406,14 @@
         'PLATFORM': 'win32',
         'PROGPREFIX': '',
         'PROGSUFFIX': '.exe',
-        'PSPAWN': &lt;function piped_spawn at 0xb7bc90d4&gt;,
+        'PSPAWN': &lt;function piped_spawn at 0xb7bcf3ac&gt;,
         'RC': 'rc',
         'RCCOM': '$RC $_CPPDEFFLAGS $_CPPINCFLAGS $RCFLAGS /fo$TARGET $SOURCES',
         'RCFLAGS': [],
-        'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c4c&gt;,
+        'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c5ae0c&gt;,
         'SCANNERS': [],
         'SHCC': '$CC',
-        'SHCCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b608cc&gt;,
+        'SHCCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b63bcc&gt;,
         'SHCCFLAGS': ['$CCFLAGS'],
         'SHCFLAGS': ['$CFLAGS'],
         'SHCXX': '$CXX',
@@ -388,19 +424,19 @@
         'SHLIBSUFFIX': '.dll',
         'SHOBJPREFIX': '$OBJPREFIX',
         'SHOBJSUFFIX': '$OBJSUFFIX',
-        'SPAWN': &lt;function spawn at 0xb7bc9144&gt;,
+        'SPAWN': &lt;function spawn at 0xb7bcf41c&gt;,
         'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1,
-        'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7be87ac&gt;,
+        'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7be989c&gt;,
         'TEMPFILEPREFIX': '@',
         'TOOLS': ['msvc'],
         '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
         '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
         '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
         '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
-        '_concat': &lt;function _concat at 0xb7c56fb4&gt;,
-        '_defines': &lt;function _defines at 0xb7c5c064&gt;,
-        '_installStr': &lt;function installStr at 0xb7c56f44&gt;,
-        '_stripixes': &lt;function _stripixes at 0xb7c5c02c&gt;}
+        '_concat': &lt;function _concat at 0xb7c5e224&gt;,
+        '_defines': &lt;function _defines at 0xb7c5e2cc&gt;,
+        '_installStr': &lt;function installStr at 0xb7c5e1b4&gt;,
+        '_stripixes': &lt;function _stripixes at 0xb7c5e294&gt;}
       scons: done reading SConscript files.
       scons: Building targets ...
       scons: `.' is up to date.
@@ -434,7 +470,10 @@
 
     </para>
 
-    
+    <programlisting>
+         env = Environment()
+         print env.Dump('ENV')
+    </programlisting>
 
     <para>
 
@@ -473,3 +512,729 @@
     </screen>
 
   </section>
+
+  <section>
+
+  <title>What Dependencies Does &SCons; Know About?  the &tree; Option</title>
+
+    <para>
+
+    Sometimes the best way to try to figure out what
+    &SCons; is doing is simply to take a look at the
+    dependency graph that it constructs
+    based on your &SConscript; files.
+    The <literal>--tree</literal> option
+    will display all or part of the
+    &SCons; dependency graph in an
+    "ASCII art" graphical format
+    that shows the dependency hierarchy.
+
+    </para>
+
+    <para>
+
+    For example, given the following input &SConstruct; file:
+
+    </para>
+
+    <programlisting>
+         env = Environment(CPPPATH = ['.'])
+         env.Program('prog', ['f1.c', 'f2.c', 'f3.c'])
+    </programlisting>
+
+    <para>
+
+    Running &SCons; with the <literal>--tree=all</literal>
+    option yields:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --tree=all</userinput>
+      cc -o f1.o -c -I. f1.c
+      cc -o f2.o -c -I. f2.c
+      cc -o f3.o -c -I. f3.c
+      cc -o prog f1.o f2.o f3.o
+      +-.
+        +--
+        +-SConstruct
+        +-f1.c
+        +-f1.o
+        | +-f1.c
+        | +-inc.h
+        +-f2.c
+        +-f2.o
+        | +-f2.c
+        | +-inc.h
+        +-f3.c
+        +-f3.o
+        | +-f3.c
+        | +-inc.h
+        +-inc.h
+        +-prog
+          +-f1.o
+          | +-f1.c
+          | +-inc.h
+          +-f2.o
+          | +-f2.c
+          | +-inc.h
+          +-f3.o
+            +-f3.c
+            +-inc.h
+    </screen>
+
+    <para>
+
+    The tree will also be printed when the
+    <literal>-n</literal> (no execute) option is used,
+    which allows you to examine the dependency graph
+    for a configuration without actually
+    rebuilding anything in the tree.
+
+    </para>
+
+    <para>
+
+    The <literal>--tree</literal> option only prints
+    the dependency graph for the specified targets
+    (or the default target(s) if none are specified on the command line).
+    So if you specify a target like <filename>f2.o</filename>
+    on the command line,
+    the <literal>--tree</literal> option will only
+    print the dependency graph for that file:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --tree=all f2.o</userinput>
+      cc -o f2.o -c -I. f2.c
+      +-f2.o
+        +-f2.c
+        +-inc.h
+    </screen>
+
+    <para>
+
+    This is, of course, useful for
+    restricting the output from a very large
+    build configuration to just a
+    portion in which you're interested.
+    Multiple targets are fine,
+    in which case a tree will be printed
+    for each specified target:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --tree=all f1.o f3.o</userinput>
+      cc -o f1.o -c -I. f1.c
+      +-f1.o
+        +-f1.c
+        +-inc.h
+      cc -o f3.o -c -I. f3.c
+      +-f3.o
+        +-f3.c
+        +-inc.h
+    </screen>
+
+    <para>
+
+    The <literal>status</literal> argument may be used
+    to tell &SCons; to print status information about
+    each file in the dependency graph:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --tree=status</userinput>
+      cc -o f1.o -c -I. f1.c
+      cc -o f2.o -c -I. f2.c
+      cc -o f3.o -c -I. f3.c
+      cc -o prog f1.o f2.o f3.o
+       E         = exists
+        R        = exists in repository only
+         b       = implicit builder
+         B       = explicit builder
+          S      = side effect
+           P     = precious
+            A    = always build
+             C   = current
+              N  = no clean
+               H = no cache
+      
+      [E b      ]+-.
+      [         ]  +--
+      [E        ]  +-SConstruct
+      [E        ]  +-f1.c
+      [E B   C  ]  +-f1.o
+      [E        ]  | +-f1.c
+      [E        ]  | +-inc.h
+      [E        ]  +-f2.c
+      [E B   C  ]  +-f2.o
+      [E        ]  | +-f2.c
+      [E        ]  | +-inc.h
+      [E        ]  +-f3.c
+      [E B   C  ]  +-f3.o
+      [E        ]  | +-f3.c
+      [E        ]  | +-inc.h
+      [E        ]  +-inc.h
+      [E B   C  ]  +-prog
+      [E B   C  ]    +-f1.o
+      [E        ]    | +-f1.c
+      [E        ]    | +-inc.h
+      [E B   C  ]    +-f2.o
+      [E        ]    | +-f2.c
+      [E        ]    | +-inc.h
+      [E B   C  ]    +-f3.o
+      [E        ]      +-f3.c
+      [E        ]      +-inc.h
+    </screen>
+
+    <para>
+
+    Note that <literal>--tree=all,status</literal> is equivalent;
+    the <literal>all</literal>
+    is assumed if only <literal>status</literal> is present.
+    As an alternative to <literal>all</literal>,
+    you can specify <literal>--tree=derived</literal>
+    to have &SCons; only print derived targets
+    in the tree output,
+    skipping source files
+    (like <filename>.c</filename> and <filename>.h</filename> files):
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --tree=derived</userinput>
+      cc -o f1.o -c -I. f1.c
+      cc -o f2.o -c -I. f2.c
+      cc -o f3.o -c -I. f3.c
+      cc -o prog f1.o f2.o f3.o
+      +-.
+    </screen>
+
+    <para>
+
+    You can use the <literal>status</literal>
+    modifier with <literal>derived</literal> as well:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --tree=derived,status</userinput>
+      cc -o f1.o -c -I. f1.c
+      cc -o f2.o -c -I. f2.c
+      cc -o f3.o -c -I. f3.c
+      cc -o prog f1.o f2.o f3.o
+       E         = exists
+        R        = exists in repository only
+         b       = implicit builder
+         B       = explicit builder
+          S      = side effect
+           P     = precious
+            A    = always build
+             C   = current
+              N  = no clean
+               H = no cache
+      
+      [E b      ]+-.
+      [E B   C  ]  +-f1.o
+      [E B   C  ]  +-f2.o
+      [E B   C  ]  +-f3.o
+      [E B   C  ]  +-prog
+      [E B   C  ]    +-f1.o
+      [E B   C  ]    +-f2.o
+      [E B   C  ]    +-f3.o
+    </screen>
+
+    <para>
+
+    Note that the order of the <literal>--tree=</literal>
+    arguments doesn't matter;
+    <literal>--tree=status,derived</literal> is
+    completely equivalent.
+
+    </para>
+
+    <para>
+
+    The default behavior of the <literal>--tree</literal> option
+    is to repeat all of the dependencies each time the library dependency
+    (or any other dependency file) is encountered in the tree.
+    If certain target files share other target files,
+    such as two programs that use the same library:
+
+    </para>
+
+    <programlisting>
+         env = Environment(CPPPATH = ['.'],
+                           LIBS = ['foo'],
+                           LIBPATH = ['.'])
+         env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+         env.Program('prog1.c')
+         env.Program('prog2.c')
+    </programlisting>
+
+    <para>
+
+    Then there can be a <emphasis>lot</emphasis> of repetition in the
+    <literal>--tree=</literal> output:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --tree=all</userinput>
+      cc -o f1.o -c -I. f1.c
+      cc -o f2.o -c -I. f2.c
+      cc -o f3.o -c -I. f3.c
+      ar rc libfoo.a f1.o f2.o f3.o
+      ranlib libfoo.a
+      cc -o prog1.o -c -I. prog1.c
+      cc -o prog1 prog1.o -L. -lfoo
+      cc -o prog2.o -c -I. prog2.c
+      cc -o prog2 prog2.o -L. -lfoo
+      +-.
+        +--
+        +-SConstruct
+        +-f1.c
+        +-f1.o
+        | +-f1.c
+        | +-inc.h
+        +-f2.c
+        +-f2.o
+        | +-f2.c
+        | +-inc.h
+        +-f3.c
+        +-f3.o
+        | +-f3.c
+        | +-inc.h
+        +-inc.h
+        +-libfoo.a
+        | +-f1.o
+        | | +-f1.c
+        | | +-inc.h
+        | +-f2.o
+        | | +-f2.c
+        | | +-inc.h
+        | +-f3.o
+        |   +-f3.c
+        |   +-inc.h
+        +-prog1
+        | +-prog1.o
+        | | +-prog1.c
+        | | +-inc.h
+        | +-libfoo.a
+        |   +-f1.o
+        |   | +-f1.c
+        |   | +-inc.h
+        |   +-f2.o
+        |   | +-f2.c
+        |   | +-inc.h
+        |   +-f3.o
+        |     +-f3.c
+        |     +-inc.h
+        +-prog1.c
+        +-prog1.o
+        | +-prog1.c
+        | +-inc.h
+        +-prog2
+        | +-prog2.o
+        | | +-prog2.c
+        | | +-inc.h
+        | +-libfoo.a
+        |   +-f1.o
+        |   | +-f1.c
+        |   | +-inc.h
+        |   +-f2.o
+        |   | +-f2.c
+        |   | +-inc.h
+        |   +-f3.o
+        |     +-f3.c
+        |     +-inc.h
+        +-prog2.c
+        +-prog2.o
+          +-prog2.c
+          +-inc.h
+    </screen>
+
+    <para>
+
+    In a large configuration with many internal libraries
+    and include files,
+    this can very quickly lead to huge output trees.
+    To help make this more manageable,
+    a <literal>prune</literal> modifier may
+    be added to the option list,
+    in which case &SCons;
+    will print the name of a target that has
+    already been visited during the tree-printing
+    in <literal>[square brackets]</literal>
+    as an indication that the dependencies
+    of the target file may be found
+    by looking farther up the tree:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --tree=prune</userinput>
+      cc -o f1.o -c -I. f1.c
+      cc -o f2.o -c -I. f2.c
+      cc -o f3.o -c -I. f3.c
+      ar rc libfoo.a f1.o f2.o f3.o
+      ranlib libfoo.a
+      cc -o prog1.o -c -I. prog1.c
+      cc -o prog1 prog1.o -L. -lfoo
+      cc -o prog2.o -c -I. prog2.c
+      cc -o prog2 prog2.o -L. -lfoo
+      +-.
+        +--
+        +-SConstruct
+        +-f1.c
+        +-f1.o
+        | +-[f1.c]
+        | +-inc.h
+        +-f2.c
+        +-f2.o
+        | +-[f2.c]
+        | +-[inc.h]
+        +-f3.c
+        +-f3.o
+        | +-[f3.c]
+        | +-[inc.h]
+        +-[inc.h]
+        +-libfoo.a
+        | +-[f1.o]
+        | +-[f2.o]
+        | +-[f3.o]
+        +-prog1
+        | +-prog1.o
+        | | +-prog1.c
+        | | +-[inc.h]
+        | +-[libfoo.a]
+        +-[prog1.c]
+        +-[prog1.o]
+        +-prog2
+        | +-prog2.o
+        | | +-prog2.c
+        | | +-[inc.h]
+        | +-[libfoo.a]
+        +-[prog2.c]
+        +-[prog2.o]
+    </screen>
+
+    <para>
+
+    Like the <literal>status</literal> keyword,
+    the <literal>prune</literal> argument by itself
+    is equivalent to <literal>--tree=all,prune</literal>.
+
+    </para>
+
+  </section>
+
+  <section>
+
+  <title>How is &SCons; Constructing the Command Lines It Executes?  the &debug-presub; Option</title>
+
+    <para>
+
+    Sometimes it's useful to look at the
+    pre-substitution string
+    that &SCons; uses to generate
+    the command lines it executes.
+    This can be done with the &debug-presub; option:
+
+    </para>
+
+    
+
+    <!--
+
+    Have to capture output here, otherwise the - -debug=presub output
+    shows the Python functions from the sconsdoc.py execution wrapper
+    used to generate this manual, not the underlying command-line strings.
+
+    <scons_output example="presub">
+      <scons_output_command>scons -Q - -debug=presub</scons_output_command>
+    </scons_output>
+
+    -->
+
+    <screen>
+      % <userinput>scons -Q --debug=presub</userinput>
+      Building prog.o with action:
+        $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES
+      cc -o prog.o -c -I. prog.c
+      Building prog with action:
+        $SMART_LINKCOM
+      cc -o prog prog.o
+    </screen>
+
+  </section>
+
+  <section>
+
+  <title>Where is &SCons; Searching for Libraries?  the &debug-findlibs; Option</title>
+
+    <para>
+
+    To get some insight into what library names
+    &SCons; is searching for,
+    and in which directories it is searching,
+    Use the <literal>--debug=findlibs</literal> option.
+    Given the following input &SConstruct; file:
+
+    </para>
+
+    <programlisting>
+        env = Environment(LIBPATH = ['libs1', 'libs2'])
+        env.Program('prog.c', LIBS=['foo', 'bar'])
+    </programlisting>
+
+    <para>
+
+    And the libraries <filename>libfoo.a</filename>
+    and <filename>libbar.a</filename>
+    in <filename>libs1</filename> and <filename>libs2</filename>,
+    respectively,
+    use of the <literal>--debug=findlibs</literal> option yields:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --debug=findlibs</userinput>
+        findlibs: looking for 'libfoo.a' in 'libs1' ...
+        findlibs: ... FOUND 'libfoo.a' in 'libs1'
+        findlibs: looking for 'libfoo.so' in 'libs1' ...
+        findlibs: looking for 'libfoo.so' in 'libs2' ...
+        findlibs: looking for 'libbar.a' in 'libs1' ...
+        findlibs: looking for 'libbar.a' in 'libs2' ...
+        findlibs: ... FOUND 'libbar.a' in 'libs2'
+        findlibs: looking for 'libbar.so' in 'libs1' ...
+        findlibs: looking for 'libbar.so' in 'libs2' ...
+      cc -o prog.o -c prog.c
+      cc -o prog prog.o -Llibs1 -Llibs2 -lfoo -lbar
+    </screen>
+
+  </section>
+
+  <!--
+
+  <section>
+
+  <title>What Implicit Dependencies Did the &SCons; Scanner find?  the &debug-includes; Option</title>
+
+    <para>
+
+    XXX explain the - - debug=includes option
+
+    </para>
+
+    <scons_example name="includes">
+      <file name="SConstruct" printme="1">
+        env = Environment(CPPPATH = ['inc1', 'inc2'])
+        env.Program('prog.c')
+      </file>
+      <file name="prog.c">
+      #include "file1.h"
+      #include "file2.h"
+      prog.c
+      </file>
+      <file name="inc1/file1.h">
+      inc1/file1.h
+      </file>
+      <file name="inc2/file2.h">
+      inc2/file2.h
+      </file>
+    </scons_example>
+
+    <scons_output example="includes">
+      <scons_output_command>scons -Q - - debug=includes prog</scons_output_command>
+    </scons_output>
+
+  </section>
+
+  -->
+
+  <section>
+
+  <title>Where is &SCons; Blowing Up?  the &debug-stacktrace; Option</title>
+
+    <para>
+
+    In general, &SCons; tries to keep its error
+    messages short and informative.
+    That means we usually try to avoid showing
+    the stack traces that are familiar
+    to experienced Python programmers,
+    since they usually contain much more
+    information than is useful to most people.
+
+    </para>
+
+    <para>
+
+    For example, the following &SConstruct; file:
+
+    </para>
+
+    <programlisting>
+         Program('prog.c')
+    </programlisting>
+
+    <para>
+
+    Generates the following error if the
+    <filename>prog.c</filename> file
+    does not exist:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      scons: *** Source `prog.c' not found, needed by target `prog.o'.  Stop.
+    </screen>
+
+    <para>
+
+    In this case,
+    the error is pretty obvious.
+    But if it weren't,
+    and you wanted to try to get more information
+    about the error,
+    the &debug-stacktrace; option
+    would show you exactly where in the &SCons; source code
+    the problem occurs:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --debug=stacktrace</userinput>
+      scons: *** Source `prog.c' not found, needed by target `prog.o'.  Stop.
+      scons: internal stack trace:
+        File "/home/knight/SCons/scons.0.96.C763/bootstrap/src/engine/SCons/Job.py", line 111, in start
+          task.prepare()
+        File "/home/knight/SCons/scons.0.96.C763/bootstrap/src/engine/SCons/Taskmaster.py", line 166, in prepare
+          t.prepare()
+        File "/home/knight/SCons/scons.0.96.C763/bootstrap/src/engine/SCons/Node/FS.py", line 2137, in prepare
+          SCons.Node.Node.prepare(self)
+        File "/home/knight/SCons/scons.0.96.C763/bootstrap/src/engine/SCons/Node/__init__.py", line 806, in prepare
+          raise SCons.Errors.StopError, desc
+    </screen>
+
+    <para>
+
+    Of course, if you do need to dive into the &SCons; source code,
+    we'd like to know if, or how,
+    the error messages or troubleshooting options
+    could have been improved to avoid that.
+    Not everyone has the necessary time or
+    Python skill to dive into the source code,
+    and we'd like to improve &SCons;
+    for those people as well...
+
+    </para>
+
+  </section>
+
+  <section>
+
+  <title>How is &SCons; Making Its Decisions?  the &taskmastertrace; Option</title>
+
+    <para>
+
+    The internal &SCons; subsystem that handles walking
+    the dependency graph
+    and controls the decision-making about what to rebuild
+    is the <literal>Taskmaster</literal>.
+    &SCons; supports a <literal>--taskmastertrace</literal>
+    option that tells the Taskmaster to print
+    information about the children (dependencies)
+    of the various Nodes on its walk down the graph,
+    which specific dependent Nodes are being evaluated,
+    and in what order.
+
+    </para>
+
+    <para>
+
+    The <literal>--taskmastertrace</literal> option
+    takes as an argument the name of a file in
+    which to put the trace output,
+    with <filename>-</filename> (a single hyphen)
+    indicating that the trace messages
+    should be printed to the standard output:
+
+    </para>
+
+    <programlisting>
+      env = Environment(CPPPATH = ['.'])
+      env.Program('prog.c')
+    </programlisting>
+
+    <screen>
+      % <userinput>scons -Q --taskmastertrace=- prog</userinput>
+      Taskmaster: 'prog': children:
+          ['prog.o']
+          waiting on unstarted children:
+          ['prog.o']
+      Taskmaster: 'prog.o': children:
+          ['inc.h', 'prog.c']
+          evaluating prog.o
+      cc -o prog.o -c -I. prog.c
+      Taskmaster: 'prog': children:
+          ['prog.o']
+          evaluating prog
+      cc -o prog prog.o
+      Taskmaster: 'prog': already handled (executed)
+    </screen>
+
+    <para>
+
+    The <literal>--taskmastertrace</literal> option
+    doesn't provide information about the actual
+    calculations involved in deciding if a file is up-to-date,
+    but it does show all of the dependencies
+    it knows about for each Node,
+    and the order in which those dependencies are evaluated.
+    This can be useful as an alternate way to determine
+    whether or not your &SCons; configuration,
+    or the implicit dependency scan,
+    has actually identified all the correct dependencies
+    you want it to.
+
+    </para>
+
+  </section>
+
+  <!--
+
+  <section>
+
+  <title>Where Are My Build Bottlenecks?  the &profile; Option</title>
+
+    <para>
+
+    XXX explain the - - profile= option
+
+    </para>
+
+  </section>
+
+  -->
+
+  <!--
+
+  <section>
+  <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
+
+    <para>
+
+    XXX describe the - - cache-debug option
+    XXX maybe point to the caching.in chapter?
+
+    </para>
+
+  </section>
+
+  -->
author	Steven Knight <knight@baldmt.com>	2007-04-13 23:36:39 (GMT)
committer	Steven Knight <knight@baldmt.com>	2007-04-13 23:36:39 (GMT)
commit	43e86764943c659f53bf0d1d101708bbdf7d07e6 (patch)
tree	7b0e2eadcaf969c35e8bab578471b404a5a7d380 /doc
parent	2174f491d8e103b7af77aa089070503a7b0863c1 (diff)
download	SCons-43e86764943c659f53bf0d1d101708bbdf7d07e6.zip SCons-43e86764943c659f53bf0d1d101708bbdf7d07e6.tar.gz SCons-43e86764943c659f53bf0d1d101708bbdf7d07e6.tar.bz2