rebuilt docs

19 files changed, 1862 insertions, 352 deletions

diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml
index 8e078fd..d4a484e 100644
--- a/doc/user/add-method.xml
+++ b/doc/user/add-method.xml
@@ -56,7 +56,7 @@
 
   <screen>
     % <userinput>scons -Q /</userinput>
-    [?1034hcc -o hello.o -c hello.c
+    cc -o hello.o -c hello.c
     cc -o hello hello.o
     Install file: "hello" as "/usr/bin/hello"
     Install file: "hello" as "install/bin/hello"
@@ -100,7 +100,7 @@
 
   <screen>
     % <userinput>scons -Q</userinput>
-    [?1034hcc -o test_stuff.o -c test_stuff.c
+    cc -o test_stuff.o -c test_stuff.c
     cc -o tests/test_stuff test_stuff.o
   </screen>
 
@@ -110,40 +110,9 @@
 
   <screen>
     C:\><userinput>scons -Q</userinput>
-    IndexError: list index out of range:
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 1294:
-        _exec_main(parser, values)
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 1259:
-        _main(parser)
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 929:
-        SCons.Script._SConscript._SConscript(fs, script)
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 179:
-        exec sys.stdin in call_stack[-1].globals
-      File "&lt;stdin&gt;", line 219:
-        None
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 614:
-        env = self.factory()
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 594:
-        default_env = SCons.Defaults.DefaultEnvironment()
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Defaults.py", line 91:
-        _default_env = apply(SCons.Environment.Environment, args, kw)
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 1004:
-        apply_tools(self, tools, toolpath)
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 106:
-        env.Tool(tool)
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 1703:
-        tool(self)
-      File "&lt;stdin&gt;", line 67:
-        None
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\msvc.py", line 239:
-        mssdk.generate(env)
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\mssdk.py", line 41:
-        mssdk_setup_env(env)
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\MSCommon\sdk.py", line 298:
-        mssdk = get_default_sdk()
-      File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\MSCommon\sdk.py", line 262:
-        return InstalledSDKList[0]
-    [?1034h
+    rc /fores.res res.rc
+    cl /Fotest_stuff.obj /c test_stuff.c /nologo
+    link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res
   </screen>
 
   <para>
diff --git a/doc/user/alias.xml b/doc/user/alias.xml
index 9c4a179..f285d70 100644
--- a/doc/user/alias.xml
+++ b/doc/user/alias.xml
@@ -46,7 +46,7 @@
 
   <screen>
      % <userinput>scons -Q install</userinput>
-     [?1034hcc -o hello.o -c hello.c
+     cc -o hello.o -c hello.c
      cc -o hello hello.o
      Install file: "hello" as "/usr/bin/hello"
   </screen>
@@ -86,23 +86,23 @@
 
   <screen>
      % <userinput>scons -Q install-bin</userinput>
-     [?1034hcc -o foo.o -c foo.c
+     cc -o foo.o -c foo.c
      cc -o foo foo.o
      Install file: "foo" as "/usr/bin/foo"
      % <userinput>scons -Q install-lib</userinput>
-     [?1034hcc -o bar.o -c bar.c
+     cc -o bar.o -c bar.c
      ar rc libbar.a bar.o
      ranlib libbar.a
      Install file: "libbar.a" as "/usr/lib/libbar.a"
      % <userinput>scons -Q -c /</userinput>
-     [?1034hRemoved foo.o
+     Removed foo.o
      Removed foo
      Removed /usr/bin/foo
      Removed bar.o
      Removed libbar.a
      Removed /usr/lib/libbar.a
      % <userinput>scons -Q install</userinput>
-     [?1034hcc -o foo.o -c foo.c
+     cc -o foo.o -c foo.c
      cc -o foo foo.o
      Install file: "foo" as "/usr/bin/foo"
      cc -o bar.o -c bar.c
diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml
index cb7fb70..738683b 100644
--- a/doc/user/builders-built-in.xml
+++ b/doc/user/builders-built-in.xml
@@ -144,7 +144,7 @@
 
     <screen>
       % <userinput>scons -Q</userinput>
-      [?1034hcc -o goodbye.o -c goodbye.c
+      cc -o goodbye.o -c goodbye.c
       cc -o hello.o -c hello.c
       cc -o hello hello.o goodbye.o -L/usr/dir1 -Ldir2 -lfoo1 -lfoo2
     </screen>
@@ -157,40 +157,9 @@
 
     <screen>
       C:\><userinput>scons -Q</userinput>
-      IndexError: list index out of range:
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 1294:
-          _exec_main(parser, values)
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 1259:
-          _main(parser)
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 929:
-          SCons.Script._SConscript._SConscript(fs, script)
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 179:
-          exec sys.stdin in call_stack[-1].globals
-        File "&lt;stdin&gt;", line 219:
-          None
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 614:
-          env = self.factory()
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 594:
-          default_env = SCons.Defaults.DefaultEnvironment()
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Defaults.py", line 91:
-          _default_env = apply(SCons.Environment.Environment, args, kw)
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 1004:
-          apply_tools(self, tools, toolpath)
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 106:
-          env.Tool(tool)
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 1703:
-          tool(self)
-        File "&lt;stdin&gt;", line 67:
-          None
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\msvc.py", line 239:
-          mssdk.generate(env)
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\mssdk.py", line 41:
-          mssdk_setup_env(env)
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\MSCommon\sdk.py", line 298:
-          mssdk = get_default_sdk()
-        File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\MSCommon\sdk.py", line 262:
-          return InstalledSDKList[0]
-      [?1034h
+      cl /Fogoodbye.obj /c goodbye.c /nologo
+      cl /Fohello.obj /c hello.c /nologo
+      link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj
     </screen>
 
     <para>
@@ -758,7 +727,7 @@
 
       <screen>
         % <userinput>scons -Q .</userinput>
-        [?1034htar -c -f out1.tar file1 file2
+        tar -c -f out1.tar file1 file2
         tar -c -f out2.tar directory
       </screen>
 
@@ -784,3 +753,185 @@
 
       <screen>
         % <userinput>scons -Q .</userinput>
+        tar -c -z -f out.tar.gz directory
+      </screen>
+
+      <para>
+
+      you may also wish to set the value of the
+      &cv-link-TARSUFFIX; construction variable
+      to your desired suffix for compress &tar; archives,
+      so that &SCons; can append it to the target file name
+      without your having to specify it explicitly:
+
+      </para>
+
+      <programlisting>
+        env = Environment(TARFLAGS = '-c -z',
+                          TARSUFFIX = '.tgz')
+        env.Tar('out', 'directory')
+      </programlisting>
+
+      <screen>
+        % <userinput>scons -Q .</userinput>
+        tar -c -z -f out.tgz directory
+      </screen>
+
+    </section>
+
+    <section>
+    <title>The &Zip; Builder</title>
+
+      <para>
+
+      The &b-link-Zip; Builder object creates archives of files
+      and/or directory trees in the ZIP file format.
+      Python versions 1.6 or later
+      contain an internal &zipfile; module
+      that &SCons; will use.
+      In this case, given the following
+      &SConstruct; file:
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        env.Zip('out', ['file1', 'file2'])
+      </programlisting>
+
+      <para>
+
+      Your output will reflect the fact
+      that an internal Python function
+      is being used to create the output ZIP archive:
+
+      </para>
+
+      <screen>
+        % <userinput>scons -Q .</userinput>
+        zip(["out.zip"], ["file1", "file2"])
+      </screen>
+
+      <para>
+
+      If you're using Python version 1.5.2 to run &SCons;,
+      then &SCons; will try to use an external
+      &zip; program as follows:
+
+      </para>
+
+      <screen>
+        % <userinput>scons -Q .</userinput>
+        zip /home/my/project/zip.out file1 file2
+      </screen>
+
+    </section>
+
+  </section>
+
+  <section>
+  <title>Java</title>
+
+    <para>
+
+    &SCons; provides Builder objects
+    for creating various types of Java output files.
+
+    </para>
+
+    <section>
+    <title>Building Class Files:  the &Java; Builder</title>
+
+      <para>
+
+      The &b-link-Java; builder takes one or more input
+      <filename>.java</filename> files
+      and turns them into one or more
+      <filename>.class</filename> files
+      Unlike most builders, however,
+      the &Java; builder takes
+      target and source <emphasis>directories</emphasis>,
+      not files, as input.
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        env.Java(target = 'classes', source = 'src')
+      </programlisting>
+
+      <para>
+
+      The &Java; builder will then
+      search the specified source directory
+      tree for all <filename>.java</filename> files,
+      and pass any out-of-date
+
+      </para>
+
+      <screen>
+        XXX Java() screen
+      </screen>
+
+    </section>
+
+    <section>
+    <title>The &Jar; Builder</title>
+
+      <para>
+
+      XXX The &Jar; builder object
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        env.Java(target = 'classes', source = 'src')
+        env.Jar(target = '', source = 'classes')
+      </programlisting>
+
+      <screen>
+        XXX Jar() screen
+      </screen>
+
+    </section>
+
+    <section>
+    <title>Building C header and stub files:  the &JavaH; Builder</title>
+
+      <para>
+
+      XXX JavaH() para
+
+      </para>
+
+      <programlisting>
+        XXX JavaH() programlisting
+      </programlisting>
+
+      <screen>
+        XXX JavaH() screen
+      </screen>
+
+    </section>
+
+    <section>
+    <title>Building RMI stub and skeleton class files:  the &RMIC; Builder</title>
+
+      <para>
+
+      XXX RMIC() para
+
+      </para>
+
+      <programlisting>
+        XXX RMIC() programlisting
+      </programlisting>
+
+      <screen>
+        XXX RMIC() screen
+      </screen>
+
+    </section>
+
+  </section>
diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml
index 23fe4ce..fcb2a96 100644
--- a/doc/user/builders-commands.xml
+++ b/doc/user/builders-commands.xml
@@ -85,3 +85,62 @@
 
   <screen>
     % <userinput>scons -Q</userinput>
+    sed 's/x/y/' &lt; foo.in &gt; foo.out
+  </screen>
+
+  <para>
+
+  This is often more convenient than
+  creating a &Builder; object
+  and adding it to the &cv-link-BUILDERS; variable
+  of a &consenv;
+
+  </para>
+
+  <para>
+
+  Note that the action you specify to the
+  &Command; &Builder; can be any legal &SCons; &Action;,
+  such as a Python function:
+
+  </para>
+
+  <programlisting>
+     env = Environment()
+     def build(target, source, env):
+         # Whatever it takes to build
+         return None
+     env.Command('foo.out', 'foo.in', build)
+  </programlisting>
+
+  <para>
+
+  Which executes as follows:
+
+  </para>
+
+  <screen>
+    % <userinput>scons -Q</userinput>
+    build(["foo.out"], ["foo.in"])
+  </screen>
+
+  <para>
+
+  Note that &cv-link-SOURCE; and &cv-link-TARGET; are expanded 
+  in the source and target as well as of SCons 1.1,
+  so you can write:
+
+  </para>
+
+  <programlisting>
+     env.Command('${SOURCE.basename}.out', 'foo.in', build)
+  </programlisting>
+
+
+  <para>
+
+  which does the same thing as the previous example, but allows you
+  to avoid repeating yourself.
+
+  </para>
+
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index e69de29..3932181 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -0,0 +1,957 @@
+<!--
+
+  __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.
+
+-->
+
+<!--
+
+=head2 Adding new methods
+
+For slightly more demanding changes, you may wish to add new methods to the
+C<cons> package. Here's an example of a very simple extension,
+C<InstallScript>, which installs a tcl script in a requested location, but
+edits the script first to reflect a platform-dependent path that needs to be
+installed in the script:
+
+  # cons::InstallScript - Create a platform dependent version of a shell
+  # script by replacing string ``#!your-path-here'' with platform specific
+  # path $BIN_DIR.
+
+  sub cons::InstallScript {
+	my ($env, $dst, $src) = @_;
+	Command $env $dst, $src, qq(
+		sed s+your-path-here+$BIN_DIR+ %< > %>
+		chmod oug+x %>
+	);
+  }
+
+Notice that this method is defined directly in the C<cons> package (by
+prefixing the name with C<cons::>). A change made in this manner will be
+globally visible to all environments, and could be called as in the
+following example:
+
+  InstallScript $env "$BIN/foo", "foo.tcl";
+
+For a small improvement in generality, the C<BINDIR> variable could be
+passed in as an argument or taken from the construction environment-,-as
+C<%BINDIR>.
+
+
+=head2 Overriding methods
+
+Instead of adding the method to the C<cons> name space, you could define a
+new package which inherits existing methods from the C<cons> package and
+overrides or adds others. This can be done using Perl's inheritance
+mechanisms.
+
+The following example defines a new package C<cons::switch> which
+overrides the standard C<Library> method. The overridden method builds
+linked library modules, rather than library archives. A new
+constructor is provided. Environments created with this constructor
+will have the new library method; others won't.
+
+  package cons::switch;
+  BEGIN {@ISA = 'cons'}
+
+  sub new {
+	shift;
+	bless new cons(@_);
+  }
+
+  sub Library {
+	my($env) = shift;
+	my($lib) = shift;
+	my(@objs) = Objects $env @_;
+	Command $env $lib, @objs, q(
+		%LD -r %LDFLAGS %< -o %>
+	);
+  }
+
+This functionality could be invoked as in the following example:
+
+  $env = new cons::switch(@overrides);
+  ...
+  Library $env 'lib.o', 'foo.c', 'bar.c';
+
+-->
+
+  <para>
+
+  Although &SCons; provides many useful methods
+  for building common software products:
+  programs, libraries, documents.
+  you frequently want to be
+  able to build some other type of file
+  not supported directly by &SCons;.
+  Fortunately, &SCons; makes it very easy
+  to define your own &Builder; objects
+  for any custom file types you want to build.
+  (In fact, the &SCons; interfaces for creating
+  &Builder; objects are flexible enough and easy enough to use
+  that all of the the &SCons; built-in &Builder; objects
+  are created the mechanisms described in this section.)
+
+  </para>
+
+  <section>
+  <title>Writing Builders That Execute External Commands</title>
+
+    <para>
+
+    The simplest &Builder; to create is
+    one that executes an external command.
+    For example, if we want to build
+    an output file by running the contents
+    of the input file through a command named
+    <literal>foobuild</literal>,
+    creating that &Builder; might look like:
+
+    </para>
+
+    <programlisting>
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+    </programlisting>
+
+    <para>
+
+    All the above line does is create a free-standing
+    &Builder; object.
+    The next section will show us how to actually use it.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Attaching a Builder to a &ConsEnv;</title>
+
+    <para>
+
+    A &Builder; object isn't useful
+    until it's attached to a &consenv;
+    so that we can call it to arrange
+    for files to be built.
+    This is done through the &cv-link-BUILDERS;
+    &consvar; in an environment.
+    The &cv-BUILDERS; variable is a Python dictionary
+    that maps the names by which you want to call
+    various &Builder; objects to the objects themselves.
+    For example, if we want to call the
+    &Builder; we just defined by the name
+    <function>Foo</function>,
+    our &SConstruct; file might look like:
+
+    </para>
+
+    
+
+    <programlisting>
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+       env = Environment(BUILDERS = {'Foo' : bld})
+    </programlisting>
+
+    <para>
+
+    With the &Builder; attached to our &consenv;
+    with the name <function>Foo</function>,
+    we can now actually call it like so:
+
+    </para>
+
+    <programlisting>
+       env.Foo('file.foo', 'file.input')
+    </programlisting>
+
+    <para>
+
+    Then when we run &SCons; it looks like:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      foobuild &lt; file.input &gt; file.foo
+    </screen>
+
+    <para>
+
+    Note, however, that the default &cv-BUILDERS;
+    variable in a &consenv;
+    comes with a default set of &Builder; objects
+    already defined:
+    &b-link-Program;, &b-link-Library;, etc.
+    And when we explicitly set the &cv-BUILDERS; variable
+    when we create the &consenv;,
+    the default &Builder;s are no longer part of
+    the environment:
+
+    </para>
+
+   <!--
+   The ToolSurrogate stuff that's used to capture output initializes
+   SCons.Defaults.ConstructionEnvironment with its own list of TOOLS.
+   In this next example, we want to show the user that when they
+   set the BUILDERS explicitly, the call to env.Program() generates
+   an AttributeError.  This won't happen with all of the default
+   ToolSurrogates in the default construction environment.  To make the
+   AttributeError show up, we have to overwite the default construction
+   environment's TOOLS variable so Program() builder doesn't show up.
+
+   We do this by executing a slightly different SConstruct file than the
+   one we print in the guide, with two extra statements at the front
+   that overwrite the TOOLS variable as described.  Note that we have
+   to jam those statements on to the first line to keep the line number
+   in the generated error consistent with what the user will see in the
+   User's Guide.
+   -->
+    <programlisting>
+       bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file.foo', 'file.input')
+       env.Program('hello.c')
+    </programlisting>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      AttributeError: SConsEnvironment instance has no attribute 'Program':
+        File "/home/my/project/SConstruct", line 4:
+          env.Program('hello.c')
+    </screen>
+
+    <para>
+
+    To be able to use both our own defined &Builder; objects
+    and the default &Builder; objects in the same &consenv;,
+    you can either add to the &cv-BUILDERS; variable
+    using the &Append; function:
+
+    </para>
+
+    
+
+    <programlisting>
+       env = Environment()
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+       env.Append(BUILDERS = {'Foo' : bld})
+       env.Foo('file.foo', 'file.input')
+       env.Program('hello.c')
+    </programlisting>
+
+    <para>
+
+    Or you can explicitly set the appropriately-named
+    key in the &cv-BUILDERS; dictionary:
+
+    </para>
+
+    <programlisting>
+       env = Environment()
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+       env['BUILDERS']['Foo'] = bld
+       env.Foo('file.foo', 'file.input')
+       env.Program('hello.c')
+    </programlisting>
+
+    <para>
+
+    Either way, the same &consenv;
+    can then use both the newly-defined
+    <function>Foo</function> &Builder;
+    and the default &b-link-Program; &Builder;:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      foobuild &lt; file.input &gt; file.foo
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Letting &SCons; Handle The File Suffixes</title>
+
+    <para>
+
+    By supplying additional information
+    when you create a &Builder;,
+    you can let &SCons; add appropriate file
+    suffixes to the target and/or the source file.
+    For example, rather than having to specify
+    explicitly that you want the <literal>Foo</literal>
+    &Builder; to build the <literal>file.foo</literal>
+    target file from the <literal>file.input</literal> source file,
+    you can give the <literal>.foo</literal>
+    and <literal>.input</literal> suffixes to the &Builder;,
+    making for more compact and readable calls to
+    the <literal>Foo</literal> &Builder;:
+
+    </para>
+
+    
+
+    <programlisting>
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file1')
+       env.Foo('file2')
+    </programlisting>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      foobuild &lt; file1.input &gt; file1.foo
+      foobuild &lt; file2.input &gt; file2.foo
+    </screen>
+
+    <para>
+
+    You can also supply a <literal>prefix</literal> keyword argument
+    if it's appropriate to have &SCons; append a prefix
+    to the beginning of target file names.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Builders That Execute Python Functions</title>
+
+    <para>
+
+    In &SCons;, you don't have to call an external command
+    to build a file.
+    You can, instead, define a Python function
+    that a &Builder; object can invoke
+    to build your target file (or files).
+    Such a &buildfunc; definition looks like:
+
+    </para>
+
+    <programlisting>
+       def build_function(target, source, env):
+           # Code to build "target" from "source"
+           return None
+    </programlisting>
+
+    <para>
+
+    The arguments of a &buildfunc; are:
+
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+      <term>target</term>
+
+      <listitem>
+      <para>
+
+      A list of Node objects representing
+      the target or targets to be
+      built by this builder function.
+      The file names of these target(s)
+      may be extracted using the Python &str; function.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>source</term>
+
+      <listitem>
+      <para>
+
+      A list of Node objects representing
+      the sources to be
+      used by this builder function to build the targets.
+      The file names of these source(s)
+      may be extracted using the Python &str; function.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>env</term>
+
+      <listitem>
+      <para>
+
+      The &consenv; used for building the target(s).
+      The builder function may use any of the
+      environment's construction variables
+      in any way to affect how it builds the targets.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+
+    The builder function must
+    return a <literal>0</literal> or <literal>None</literal> value
+    if the target(s) are built successfully.
+    The builder function
+    may raise an exception
+    or return any non-zero value
+    to indicate that the build is unsuccessful,
+
+    </para>
+
+    <para>
+
+    Once you've defined the Python function
+    that will build your target file,
+    defining a &Builder; object for it is as
+    simple as specifying the name of the function,
+    instead of an external command,
+    as the &Builder;'s
+    <literal>action</literal>
+    argument:
+
+    </para>
+
+    <programlisting>
+       def build_function(target, source, env):
+           # Code to build "target" from "source"
+           return None
+       bld = Builder(action = build_function,
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file')
+    </programlisting>
+
+    <para>
+
+    And notice that the output changes slightly,
+    reflecting the fact that a Python function,
+    not an external command,
+    is now called to build the target file:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      build_function(["file.foo"], ["file.input"])
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Builders That Create Actions Using a &Generator;</title>
+
+    <para>
+
+    &SCons; Builder objects can create an action "on the fly"
+    by using a function called a &generator;.
+    This provides a great deal of flexibility to
+    construct just the right list of commands
+    to build your target.
+    A &generator; looks like:
+
+    </para>
+
+    <programlisting>
+       def generate_actions(source, target, env, for_signature):
+           return 'foobuild < %s > %s' % (target[0], source[0])
+    </programlisting>
+
+    <para>
+
+    The arguments of a &generator; are:
+
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+      <term>source</term>
+
+      <listitem>
+      <para>
+
+      A list of Node objects representing
+      the sources to be built
+      by the command or other action
+      generated by this function.
+      The file names of these source(s)
+      may be extracted using the Python &str; function.
+
+      </para>
+      </listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+      <term>target</term>
+
+      <listitem>
+      <para>
+
+      A list of Node objects representing
+      the target or targets to be built
+      by the command or other action
+      generated by this function.
+      The file names of these target(s)
+      may be extracted using the Python &str; function.
+
+      </para>
+      </listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+      <term>env</term>
+
+      <listitem>
+      <para>
+
+      The &consenv; used for building the target(s).
+      The generator may use any of the
+      environment's construction variables
+      in any way to determine what command
+      or other action to return.
+
+      </para>
+      </listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+      <term>for_signature</term>
+
+      <listitem>
+      <para>
+
+      A flag that specifies whether the
+      generator is being called to contribute to a build signature,
+      as opposed to actually executing the command.
+
+      <!-- XXX NEED MORE HERE, describe generators use in signatures -->
+
+      </para>
+      </listitem>
+
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+
+    The &generator; must return a
+    command string or other action that will be used to
+    build the specified target(s) from the specified source(s).
+
+    </para>
+
+    <para>
+
+    Once you've defined a &generator;,
+    you create a &Builder; to use it
+    by specifying the generator keyword argument
+    instead of <literal>action</literal>.
+
+    </para>
+
+    
+
+    <programlisting>
+       def generate_actions(source, target, env, for_signature):
+           return 'foobuild < %s > %s' % (source[0], target[0])
+       bld = Builder(generator = generate_actions,
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file')
+    </programlisting>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      foobuild &lt; file.input &gt; file.foo
+    </screen>
+
+    <para>
+
+    Note that it's illegal to specify both an
+    <literal>action</literal>
+    and a
+    <literal>generator</literal>
+    for a &Builder;.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Builders That Modify the Target or Source Lists Using an &Emitter;</title>
+
+    <para>
+
+    &SCons; supports the ability for a Builder to modify the
+    lists of target(s) from the specified source(s).
+    You do this by defining an &emitter; function
+    that takes as its arguments
+    the list of the targets passed to the builder,
+    the list of the sources passed to the builder,
+    and the construction environment.
+    The emitter function should return the modified
+    lists of targets that should be built
+    and sources from which the targets will be built.
+
+    </para>
+
+    <para>
+
+    For example, suppose you want to define a Builder
+    that always calls a <filename>foobuild</filename> program,
+    and you want to automatically add
+    a new target file named
+    <filename>new_target</filename>
+    and a new source file named
+    <filename>new_source</filename>
+    whenever it's called.
+    The &SConstruct; file might look like this:
+
+    </para>
+
+    
+
+    <programlisting>
+       def modify_targets(target, source, env):
+           target.append('new_target')
+           source.append('new_source')
+           return target, source
+       bld = Builder(action = 'foobuild $TARGETS - $SOURCES',
+                     suffix = '.foo',
+                     src_suffix = '.input',
+                     emitter = modify_targets)
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file')
+    </programlisting>
+
+    <para>
+    
+    And would yield the following output:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      foobuild file.foo new_target - file.input new_source
+    </screen>
+
+    <para>
+
+    One very flexible thing that you can do is
+    use a construction variable to specify
+    different emitter functions for different
+    construction variable.
+    To do this, specify a string
+    containing a construction variable
+    expansion as the emitter when you call
+    the &Builder; function,
+    and set that construction variable to
+    the desired emitter function
+    in different construction environments:
+
+    </para>
+
+    <programlisting>
+        bld = Builder(action = 'my_command $SOURCES &gt; $TARGET',
+                      suffix = '.foo',
+                      src_suffix = '.input',
+                      emitter = '$MY_EMITTER')
+        def modify1(target, source, env):
+            return target, source + ['modify1.in']
+        def modify2(target, source, env):
+            return target, source + ['modify2.in']
+        env1 = Environment(BUILDERS = {'Foo' : bld},
+                           MY_EMITTER = modify1)
+        env2 = Environment(BUILDERS = {'Foo' : bld},
+                           MY_EMITTER = modify2)
+        env1.Foo('file1')
+        env2.Foo('file2')
+        import os
+        env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
+        env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
+      
+
+    </programlisting>
+
+    <programlisting>
+      bld = Builder(action = 'my_command $SOURCES > $TARGET',
+                    suffix = '.foo',
+                    src_suffix = '.input',
+                    emitter = '$MY_EMITTER')
+      def modify1(target, source, env):
+          return target, source + ['modify1.in']
+      def modify2(target, source, env):
+          return target, source + ['modify2.in']
+      env1 = Environment(BUILDERS = {'Foo' : bld},
+                         MY_EMITTER = modify1)
+      env2 = Environment(BUILDERS = {'Foo' : bld},
+                         MY_EMITTER = modify2)
+      env1.Foo('file1')
+      env2.Foo('file2')
+      
+    </programlisting>
+
+    <para>
+
+    In this example, the <filename>modify1.in</filename>
+    and <filename>modify2.in</filename> files
+    get added to the source lists
+    of the different commands:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      my_command file1.input modify1.in &gt; file1.foo
+      my_command file2.input modify2.in &gt; file2.foo
+    </screen>
+
+  </section>
+
+  <!--
+
+  <section>
+  <title>target_factor=, source_factory=</title>
+
+  </section>
+
+  <section>
+  <title>target_scanner=, source_scanner=</title>
+
+  </section>
+
+  <section>
+  <title>multi=</title>
+
+  </section>
+
+  <section>
+  <title>single_source=</title>
+
+  </section>
+
+  <section>
+  <title>src_builder=</title>
+
+  </section>
+
+  <section>
+  <title>ensure_suffix=</title>
+
+  </section>
+
+  -->
+
+  <section>
+  <title>Where To Put Your Custom Builders and Tools</title>
+
+    <para>
+
+    The <filename>site_scons</filename> directory gives you a place to
+    put Python modules you can import into your &SConscript; files
+    (<filename>site_scons</filename>),
+    add-on tools that can integrate into &SCons;
+    (<filename>site_scons/site_tools</filename>),
+    and a <filename>site_scons/site_init.py</filename> file that
+    gets read before any &SConstruct; or &SConscript; file,
+    allowing you to change &SCons;'s default behavior.
+
+    </para>
+
+    <para>
+
+    If you get a tool from somewhere (the &SCons; wiki or a third party,
+    for instance) and you'd like to use it in your project, the
+    <filename>site_scons</filename> dir is the simplest place to put it.
+    Tools come in two flavors; either a Python function that operates on
+    an &Environment; or a Python file containing two functions,
+    <function>exists()</function> and <function>generate()</function>.
+
+    </para>
+
+    <para>
+
+    A single-function Tool can just be included in your
+    <filename>site_scons/site_init.py</filename> file where it will be
+    parsed and made available for use.  For instance, you could have a
+    <filename>site_scons/site_init.py</filename> file like this:
+
+    </para>
+
+    <programlisting>
+        def TOOL_ADD_HEADER(env):
+           """A Tool to add a header from $HEADER to the source file"""
+           add_header = Builder(action=['echo "$HEADER" &gt; $TARGET',
+                                        'cat $SOURCE &gt;&gt; $TARGET'])
+           env.Append(BUILDERS = {'AddHeader' : add_header})
+           env['HEADER'] = '' # set default value
+    </programlisting>
+
+    <para>
+
+    and a &SConstruct; like this:
+
+    </para>
+
+    <programlisting>
+        # Use TOOL_ADD_HEADER from site_scons/site_init.py
+        env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====")
+        env.AddHeader('tgt', 'src')
+    </programlisting>
+
+    <para>
+
+      The <function>TOOL_ADD_HEADER</function> tool method will be
+      called to add the <function>AddHeader</function> tool to the
+      environment.
+
+    </para>
+
+    <!-- 
+    <scons_output example="site1" os="posix">
+       <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+    -->
+
+    <para>
+      Similarly, a more full-fledged tool with
+      <function>exists()</function> and <function>generate()</function>
+      methods can be installed in
+      <filename>site_scons/site_tools/toolname.py</filename>.  Since
+      <filename>site_scons/site_tools</filename> is automatically added
+      to the head of the tool search path, any tool found there will be
+      available to all environments.  Furthermore, a tool found there
+      will override a built-in tool of the same name, so if you need to
+      change the behavior of a built-in tool, site_scons gives you the
+      hook you need.
+    </para>
+
+    <para>
+      Many people have a library of utility Python functions they'd like
+      to include in &SConscript;s; just put that module in
+      <filename>site_scons/my_utils.py</filename> or any valid Python module name of your
+      choice.  For instance you can do something like this in
+      <filename>site_scons/my_utils.py</filename> to add
+      <function>build_id</function> and <function>MakeWorkDir</function>
+      functions:
+    </para>
+      
+    <programlisting>
+        from SCons.Script import *   # for Execute and Mkdir
+        def build_id():
+           """Return a build ID (stub version)"""
+           return "100"
+        def MakeWorkDir(workdir):
+           """Create the specified dir immediately"""
+           Execute(Mkdir(workdir))
+    </programlisting>
+
+    <para>
+
+    And then in your &SConscript; or any sub-&SConscript; anywhere in
+    your build, you can import <filename>my_utils</filename> and use it:
+
+    </para>
+
+    <programlisting>
+        import my_utils
+        print "build_id=" + my_utils.build_id()
+        my_utils.MakeWorkDir('/tmp/work')
+    </programlisting>
+
+    <para>
+      Note that although you can put this library in
+      <filename>site_scons/site_init.py</filename>,
+      it is no better there than <filename>site_scons/my_utils.py</filename>
+      since you still have to import that module into your &SConscript;.
+      Also note that in order to refer to objects in the SCons namespace
+      such as &Environment; or &Mkdir; or &Execute; in any file other
+      than a &SConstruct; or &SConscript; you always need to do
+    </para>
+    <programlisting>
+        from SCons.Script import *
+    </programlisting>
+
+    <para>
+      This is true in modules in <filename>site_scons</filename> such as
+      <filename>site_scons/site_init.py</filename> as well.
+    </para>
+
+    <para>
+
+      If you have a machine-wide site dir you'd like to use instead of
+      <filename>./site_scons</filename>, use the
+      <literal>--site-dir</literal> option to point to your dir.
+      <filename>site_init.py</filename> and
+      <filename>site_tools</filename> will be located under that dir.
+      To avoid using a <filename>site_scons</filename> dir at all, even
+      if it exists, use the <literal>--no-site-dir</literal> option.
+
+    </para>
+
+  </section>
+
+
+  <!--
+
+  <section>
+  <title>Builders That Use Other Builders</title>
+
+    <para>
+
+    XXX para
+
+    </para>
+
+    <scons_example name="ex8">
+       <file name="SConstruct" printme="1">
+       env = Environment()
+       #env.SourceCode('.', env.BitKeeper('my_command'))
+       env.Program('hello.c')
+       </file>
+       <file name="hello.c">
+       hello.c
+       </file>
+    </scons_example>
+
+    <scons_output example="ex8">
+      <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+
+  </section>
+
+  -->
diff --git a/doc/user/builders.xml b/doc/user/builders.xml
index e69de29..f3989ef 100644
--- a/doc/user/builders.xml
+++ b/doc/user/builders.xml
@@ -0,0 +1,57 @@
+<!--
+
+  __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.
+
+-->
+
+<!--
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<refentry id="Command">
+
+<refmeta>
+<refentrytitle>Command</refentrytitle>
+</refmeta>
+
+<methodsynopsis>
+  <methodname>env.Command</methodname>
+  <methodparam>foo</methodparam>
+  <methodparam>bar</methodparam>
+</methodsynopsis>
+
+</refentry>
+-->
+
+<para>
+
+This appendix contains descriptions of all of the
+Builders that are <emphasis>potentially</emphasis>
+available "out of the box" in this version of SCons.
+
+</para>
+
+<variablelist>
+
+&builders-gen;
+
+</variablelist>
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index e69de29..2348d32 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -0,0 +1,506 @@
+<!--
+
+  __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>
+
+  On multi-developer software projects,
+  you can sometimes speed up every developer's builds a lot by
+  allowing them to share the derived files that they build.
+  &SCons; makes this easy, as well as reliable.
+
+  </para>
+
+  <section>
+  <title>Specifying the Shared Cache Directory</title>
+
+    <para>
+
+    To enable sharing of derived files,
+    use the &CacheDir; function
+    in any &SConscript; file:
+
+    </para>
+
+    <programlisting>
+       CacheDir('/usr/local/build_cache')
+    </programlisting>
+
+    <para>
+
+    Note that the directory you specify must already exist
+    and be readable and writable by all developers
+    who will be sharing derived files.
+    It should also be in some central location
+    that all builds will be able to access.
+    In environments where developers are using separate systems
+    (like individual workstations) for builds,
+    this directory would typically be
+    on a shared or NFS-mounted file system.
+
+    </para>
+
+    <para>
+
+    Here's what happens:
+    When a build has a &CacheDir; specified,
+    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
+    to see if a file with the exact same build
+    signature already exists.
+    If so, the derived file will not be built locally,
+    but will be copied into the local build directory
+    from the shared cache directory,
+    like so:
+
+    </para>
+
+    <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>
+      Retrieved `hello.o' from cache
+      Retrieved `hello' from cache
+    </screen>
+
+    <para>
+
+    Note that the &CacheDir; feature still calculates
+    MD5 build sigantures for the shared cache file names
+    even if you configure &SCons; to use timestamps
+    to decide if files are up to date.
+    (See the <xref linkend="chap-depends"></xref>
+    chapter for information about the &Decider; function.)
+    Consequently, using &CacheDir; may reduce or eliminate any
+    potential performance improvements
+    from using timestamps for up-to-date decisions.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Keeping Build Output Consistent</title>
+
+    <para>
+
+    One potential drawback to using a shared cache
+    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,
+    especially for automated scripts that
+    expect consistent output each time.
+
+    </para>
+
+    <para>
+
+    If, however, you use the <literal>--cache-show</literal> option,
+    &SCons; will print the command line that it
+    <emphasis>would</emphasis> have executed
+    to build the file,
+    even when it is retrieving the file from the shared cache.
+    This makes the build output consistent
+    every time the build is run:
+
+    </para>
+
+    <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 --cache-show</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+    </screen>
+
+    <para>
+
+    The trade-off, of course, is that you no longer
+    know whether or not &SCons;
+    has retrieved a derived file from cache
+    or has rebuilt it locally.
+
+    </para>
+
+  </section>
+
+  <section>
+  <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>
+
+    Retrieving an already-built file
+    from the shared cache
+    is usually a significant time-savings
+    over rebuilding the file,
+    but how much of a savings
+    (or even whether it saves time at all)
+    can depend a great deal on your
+    system or network configuration.
+    For example, retrieving cached files
+    from a busy server over a busy network
+    might end up being slower than
+    rebuilding the files locally.
+
+    </para>
+
+    <para>
+
+    In these cases, you can specify
+    the <literal>--cache-disable</literal>
+    command-line option to tell &SCons;
+    to not retrieve already-built files from the
+    shared cache directory:
+
+    </para>
+
+    <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>
+      Retrieved `hello.o' from cache
+      Retrieved `hello' from cache
+      % <userinput>scons -Q -c</userinput>
+      Removed hello.o
+      Removed hello
+      % <userinput>scons -Q --cache-disable</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Populating a Shared Cache With Already-Built Files</title>
+
+    <para>
+
+    Sometimes, you may have one or more derived files
+    already built in your local build tree
+    that you wish to make available to other people doing builds.
+    For example, you may find it more effective to perform
+    integration builds with the cache disabled
+    (per the previous section)
+    and only populate the shared cache directory
+    with the built files after the integration build
+    has completed successfully.
+    This way, the cache will only get filled up
+    with derived files that are part of a complete, successful build
+    not with files that might be later overwritten
+    while you debug integration problems.
+
+    </para>
+
+    <para>
+
+    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 already exist in your local tree
+    from having been built by a previous invocation:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q --cache-disable</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 --cache-disable</userinput>
+      cc -o hello.o -c hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q --cache-force</userinput>
+      scons: `.' is up to date.
+      % <userinput>scons -Q</userinput>
+      scons: `.' is up to date.
+    </screen>
+
+    <para>
+
+    Notice how the above sample run
+    demonstrates that the <literal>--cache-disable</literal>
+    option avoids putting the built
+    <filename>hello.o</filename>
+    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
+    for the next invocation to retrieve.
+
+    </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>
+
+    <para>
+
+    If you want to make sure dependencies will be built
+    in a random order without having to specify
+    the <literal>--random</literal> on very command line,
+    you can use the &SetOption; function to
+    set the <literal>random</literal> option
+    within any &SConscript; file:
+
+    </para>
+
+    <programlisting>
+       Program('prog',
+               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+
+       SetOption('random', 1)
+       Program('prog',
+               ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+    </programlisting>
+
+  </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.xml b/doc/user/command-line.xml
index 3d48b2a..148922e 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.xml
@@ -150,14 +150,14 @@
 
       <screen>
         % <userinput>scons</userinput>
-        [?1034hscons: Reading SConscript files ...
+        scons: Reading SConscript files ...
         scons: done reading SConscript files.
         scons: Building targets ...
             ... [build output] ...
         scons: done building targets.
         % <userinput>export SCONSFLAGS="-Q"</userinput>
         % <userinput>scons</userinput>
-        [?1034h    ... [build output] ...
+            ... [build output] ...
       </screen>
 
       <para>
@@ -309,7 +309,7 @@
 
       <screen>
         % <userinput>scons -Q</userinput>
-        [?1034hrunning with -j 2
+        running with -j 2
         scons: `.' is up to date.
       </screen>
 
@@ -324,7 +324,7 @@
       <screen>
         % <userinput>export NUM_CPU="4"</userinput>
         % <userinput>scons -Q</userinput>
-        [?1034hrunning with -j 4
+        running with -j 4
         scons: `.' is up to date.
       </screen>
 
@@ -341,11 +341,11 @@
 
       <screen>
         % <userinput>scons -Q -j 7</userinput>
-        [?1034hrunning with -j 7
+        running with -j 7
         scons: `.' is up to date.
         % <userinput>export NUM_CPU="4"</userinput>
         % <userinput>scons -Q -j 3</userinput>
-        [?1034hrunning with -j 3
+        running with -j 3
         scons: `.' is up to date.
       </screen>
 
@@ -630,7 +630,7 @@
 
       <screen>
         % <userinput>scons -Q -n</userinput>
-        [?1034hInstall file: "foo.in" as "/usr/bin/foo.in"
+        Install file: "foo.in" as "/usr/bin/foo.in"
       </screen>
 
       <para>
@@ -643,7 +643,7 @@
 
       <screen>
         % <userinput>scons -Q -n --prefix=/tmp/install</userinput>
-        [?1034hInstall file: "foo.in" as "/tmp/install/usr/bin/foo.in"
+        Install file: "foo.in" as "/tmp/install/usr/bin/foo.in"
       </screen>
 
     </section>
@@ -718,14 +718,15 @@
 
     <screen>
        % <userinput>scons -Q debug=0</userinput>
-       [?1034hcc -o prog.o -c prog.c
+       cc -o prog.o -c prog.c
        cc -o prog prog.o
        % <userinput>scons -Q debug=0</userinput>
-       [?1034hscons: `.' is up to date.
+       scons: `.' is up to date.
        % <userinput>scons -Q debug=1</userinput>
-       [?1034hscons: `.' is up to date.
+       cc -o prog.o -c -g prog.c
+       cc -o prog prog.o
        % <userinput>scons -Q debug=1</userinput>
-       [?1034hscons: `.' is up to date.
+       scons: `.' is up to date.
     </screen>
 
     <para>
@@ -805,9 +806,9 @@
 
     <screen>
        % <userinput>scons -Q define=FOO</userinput>
-       [?1034hcc -o prog.o -c -DFOO prog.c
+       cc -o prog.o -c -DFOO prog.c
        % <userinput>scons -Q define=FOO define=BAR</userinput>
-       [?1034hscons: `.' is up to date.
+       cc -o prog.o -c -DFOO -DBAR prog.c
     </screen>
 
     <para>
@@ -908,7 +909,7 @@
 
       <screen>
         % <userinput>scons -Q RELEASE=1</userinput>
-        [?1034hcc -o bar.o -c -DRELEASE_BUILD=1 bar.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>
@@ -971,7 +972,7 @@
 
       <screen>
         % <userinput>scons -Q -h</userinput>
-        [?1034h
+        
         RELEASE: Set to 1 to build for release
             default: 0
             actual: 0
@@ -1036,7 +1037,7 @@
 
       <screen>
         % <userinput>scons -Q</userinput>
-        [?1034hcc -o bar.o -c -DRELEASE_BUILD=1 bar.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>
@@ -1060,7 +1061,7 @@
 
       <screen>
         % <userinput>scons -Q</userinput>
-        [?1034hcc -o bar.o -c -DRELEASE_BUILD=0 bar.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>
@@ -1126,12 +1127,12 @@
 
         <screen>
           % <userinput>scons -Q RELEASE=yes foo.o</userinput>
-          [?1034hcc -o foo.o -c -DRELEASE_BUILD=True foo.c
+          cc -o foo.o -c -DRELEASE_BUILD=True foo.c
         </screen>
 
         <screen>
           % <userinput>scons -Q RELEASE=t foo.o</userinput>
-          [?1034hcc -o foo.o -c -DRELEASE_BUILD=True foo.c
+          cc -o foo.o -c -DRELEASE_BUILD=True foo.c
         </screen>
 
         <para>
@@ -1157,12 +1158,12 @@
 
         <screen>
           % <userinput>scons -Q RELEASE=no foo.o</userinput>
-          [?1034hcc -o foo.o -c -DRELEASE_BUILD=False foo.c
+          cc -o foo.o -c -DRELEASE_BUILD=False foo.c
         </screen>
 
         <screen>
           % <userinput>scons -Q RELEASE=f foo.o</userinput>
-          [?1034hcc -o foo.o -c -DRELEASE_BUILD=False foo.c
+          cc -o foo.o -c -DRELEASE_BUILD=False foo.c
         </screen>
 
         <para>
@@ -1189,8 +1190,7 @@
           
           scons: *** Error converting option: RELEASE
           Invalid value for boolean option: bad_value
-          File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\__init__.py", line 214, in Update
-          [?1034h
+          File "/home/my/project/SConstruct", line 4, in &lt;module&gt;
         </screen>
 
       </section>
@@ -1233,11 +1233,11 @@
 
         <screen>
           % <userinput>scons -Q COLOR=red foo.o</userinput>
-          [?1034hcc -o foo.o -c -DCOLOR="red" foo.c
+          cc -o foo.o -c -DCOLOR="red" foo.c
           % <userinput>scons -Q COLOR=blue foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLOR="blue" foo.c
           % <userinput>scons -Q COLOR=green foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLOR="green" foo.c
         </screen>
 
         <para>
@@ -1253,8 +1253,7 @@
           % <userinput>scons -Q COLOR=magenta foo.o</userinput>
           
           scons: *** Invalid value for option COLOR: magenta
-          File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\EnumVariable.py", line 51, in _validator
-          [?1034h
+          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
         </screen>
 
         <para>
@@ -1293,7 +1292,7 @@
 
         <screen>
           % <userinput>scons -Q COLOR=navy foo.o</userinput>
-          [?1034hcc -o foo.o -c -DCOLOR="blue" foo.c
+          cc -o foo.o -c -DCOLOR="blue" foo.c
         </screen>
 
         <para>
@@ -1310,18 +1309,15 @@
           % <userinput>scons -Q COLOR=Red foo.o</userinput>
           
           scons: *** Invalid value for option COLOR: Red
-          File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\EnumVariable.py", line 51, in _validator
-          [?1034h
+          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
           % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
           
           scons: *** Invalid value for option COLOR: BLUE
-          File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\EnumVariable.py", line 51, in _validator
-          [?1034h
+          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
           % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
           
           scons: *** Invalid value for option COLOR: nAvY
-          File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\EnumVariable.py", line 51, in _validator
-          [?1034h
+          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
         </screen>
 
         <para>
@@ -1353,13 +1349,13 @@
 
         <screen>
           % <userinput>scons -Q COLOR=Red foo.o</userinput>
-          [?1034hcc -o foo.o -c -DCOLOR="Red" foo.c
+          cc -o foo.o -c -DCOLOR="Red" foo.c
           % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLOR="BLUE" foo.c
           % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLOR="blue" foo.c
           % <userinput>scons -Q COLOR=green foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLOR="green" foo.c
         </screen>
 
         <para>
@@ -1397,11 +1393,11 @@
 
         <screen>
           % <userinput>scons -Q COLOR=Red foo.o</userinput>
-          [?1034hcc -o foo.o -c -DCOLOR="red" foo.c
+          cc -o foo.o -c -DCOLOR="red" foo.c
           % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLOR="blue" foo.c
           % <userinput>scons -Q COLOR=GREEN foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLOR="green" foo.c
         </screen>
 
       </section>
@@ -1440,9 +1436,9 @@
 
         <screen>
           % <userinput>scons -Q COLORS=red,blue foo.o</userinput>
-          [?1034hcc -o foo.o -c -DCOLORS="red blue" foo.c
+          cc -o foo.o -c -DCOLORS="red blue" foo.c
           % <userinput>scons -Q COLORS=blue,green,red foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLORS="blue green red" foo.c
         </screen>
 
         <para>
@@ -1457,9 +1453,9 @@
 
         <screen>
           % <userinput>scons -Q COLORS=all foo.o</userinput>
-          [?1034hcc -o foo.o -c -DCOLORS="red green blue" foo.c
+          cc -o foo.o -c -DCOLORS="red green blue" foo.c
           % <userinput>scons -Q COLORS=none foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DCOLORS="" foo.c
         </screen>
 
         <para>
@@ -1474,8 +1470,7 @@
           
           scons: *** Error converting option: COLORS
           Invalid value(s) for option: magenta
-          File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\__init__.py", line 214, in Update
-          [?1034h
+          File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
         </screen>
 
       </section>
@@ -1515,9 +1510,9 @@
 
         <screen>
           % <userinput>scons -Q foo.o</userinput>
-          [?1034hcc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c
+          cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c
           % <userinput>scons -Q CONFIG=/usr/local/etc/other_config foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          scons: `foo.o' is up to date.
         </screen>
 
         <para>
@@ -1532,8 +1527,7 @@
           % <userinput>scons -Q CONFIG=/does/not/exist foo.o</userinput>
           
           scons: *** Path for option CONFIG does not exist: /does/not/exist
-          File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\PathVariable.py", line 117, in PathExists
-          [?1034h
+          File "/home/my/project/SConstruct", line 6, in &lt;module&gt;
         </screen>
 
         <para>
@@ -1661,13 +1655,13 @@
 
         <screen>
           % <userinput>scons -Q foo.o</userinput>
-          [?1034hcc -o foo.o -c -DPACKAGE="/opt/location" foo.c
+          cc -o foo.o -c -DPACKAGE="/opt/location" foo.c
           % <userinput>scons -Q PACKAGE=/usr/local/location foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c
           % <userinput>scons -Q PACKAGE=yes foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DPACKAGE="True" foo.c
           % <userinput>scons -Q PACKAGE=no foo.o</userinput>
-          [?1034hscons: `foo.o' is up to date.
+          cc -o foo.o -c -DPACKAGE="False" foo.c
         </screen>
 
       </section>
@@ -1787,7 +1781,7 @@
 
       <screen>
         % <userinput>scons -Q NOT_KNOWN=foo</userinput>
-        [?1034hUnknown variables: ['NOT_KNOWN']
+        Unknown variables: ['NOT_KNOWN']
       </screen>
 
       <para>
@@ -1855,10 +1849,10 @@
 
       <screen>
         % <userinput>scons -Q</userinput>
-        [?1034hcc -o foo.o -c foo.c
+        cc -o foo.o -c foo.c
         cc -o foo foo.o
         % <userinput>scons -Q bar</userinput>
-        [?1034hDon't forget to copy `bar' to the archive!
+        Don't forget to copy `bar' to the archive!
         cc -o bar.o -c bar.c
         cc -o bar bar.o
       </screen>
@@ -1914,12 +1908,12 @@
 
       <screen>
          % <userinput>scons -Q</userinput>
-         [?1034hcc -o hello.o -c hello.c
+         cc -o hello.o -c hello.c
          cc -o hello hello.o
          % <userinput>scons -Q</userinput>
-         [?1034hscons: `hello' is up to date.
+         scons: `hello' is up to date.
          % <userinput>scons -Q goodbye</userinput>
-         [?1034hcc -o goodbye.o -c goodbye.c
+         cc -o goodbye.o -c goodbye.c
          cc -o goodbye goodbye.o
       </screen>
 
@@ -1936,7 +1930,7 @@
 
       <screen>
          % <userinput>scons -Q .</userinput>
-         [?1034hcc -o goodbye.o -c goodbye.c
+         cc -o goodbye.o -c goodbye.c
          cc -o goodbye goodbye.o
          cc -o hello.o -c hello.c
          cc -o hello hello.o
@@ -1988,12 +1982,12 @@
 
       <screen>
          % <userinput>scons -Q</userinput>
-         [?1034hcc -o prog1.o -c prog1.c
+         cc -o prog1.o -c prog1.c
          cc -o prog1 prog1.o
          cc -o prog3.o -c prog3.c
          cc -o prog3 prog3.o
          % <userinput>scons -Q .</userinput>
-         [?1034hcc -o prog2.o -c prog2.c
+         cc -o prog2.o -c prog2.c
          cc -o prog2 prog2.o
       </screen>
 
@@ -2020,13 +2014,13 @@
 
       <screen>
          % <userinput>scons -Q</userinput>
-         [?1034hcc -o prog1/foo.o -c prog1/foo.c
+         cc -o prog1/foo.o -c prog1/foo.c
          cc -o prog1/main.o -c prog1/main.c
          cc -o prog1/main prog1/main.o prog1/foo.o
          % <userinput>scons -Q</userinput>
-         [?1034hscons: `prog1' is up to date.
+         scons: `prog1' is up to date.
          % <userinput>scons -Q .</userinput>
-         [?1034hcc -o prog2/bar.o -c prog2/bar.c
+         cc -o prog2/bar.o -c prog2/bar.c
          cc -o prog2/main.o -c prog2/main.c
          cc -o prog2/main prog2/main.o prog2/bar.o
       </screen>
@@ -2056,9 +2050,8 @@
       <screen>
          % <userinput>scons -Q</userinput>
          scons: *** No targets specified and no Default() targets found.  Stop.
-         [?1034h
          % <userinput>scons -Q .</userinput>
-         [?1034hcc -o prog1.o -c prog1.c
+         cc -o prog1.o -c prog1.c
          cc -o prog1 prog1.o
          cc -o prog2.o -c prog2.c
          cc -o prog2 prog2.o
@@ -2101,7 +2094,7 @@
 
         <screen>
            % <userinput>scons</userinput>
-           [?1034hscons: Reading SConscript files ...
+           scons: Reading SConscript files ...
            DEFAULT_TARGETS is ['prog1']
            scons: done reading SConscript files.
            scons: Building targets ...
@@ -2136,7 +2129,7 @@
 
         <screen>
            % <userinput>scons</userinput>
-           [?1034hscons: Reading SConscript files ...
+           scons: Reading SConscript files ...
            DEFAULT_TARGETS is now ['prog1']
            DEFAULT_TARGETS is now ['prog1', 'prog2']
            scons: done reading SConscript files.
@@ -2231,15 +2224,15 @@
 
       <screen>
         % <userinput>scons -Q</userinput>
-        [?1034hBUILD_TARGETS is ['prog1']
+        BUILD_TARGETS is ['prog1']
         cc -o prog1.o -c prog1.c
         cc -o prog1 prog1.o
         % <userinput>scons -Q prog2</userinput>
-        [?1034hBUILD_TARGETS is ['prog2']
+        BUILD_TARGETS is ['prog2']
         cc -o prog2.o -c prog2.c
         cc -o prog2 prog2.o
         % <userinput>scons -Q -c .</userinput>
-        [?1034hBUILD_TARGETS is ['.']
+        BUILD_TARGETS is ['.']
         Removed prog1.o
         Removed prog1
         Removed prog2.o
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 873c5f1..c9207d5 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -347,7 +347,6 @@
          % <userinput>touch -t 198901010000 hello.c</userinput>
          % <userinput>scons -Q hello.o</userinput>
          cc -o hello.o -c hello.c
-         cc -o hello hello.o
       </screen>
 
       <para>
@@ -987,12 +986,6 @@
 
     <screen>
        C:\><userinput>scons -Q hello.exe</userinput>
-       
-       scons: warning: No installed VCs
-       File "&lt;stdin&gt;", line 67, in __call__
-       
-       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-       File "&lt;stdin&gt;", line 67, in __call__
        cl /Fohello.obj /c hello.c /nologo /Iinclude /I\home\project\inc
        link /nologo /OUT:hello.exe hello.obj
     </screen>
@@ -1657,15 +1650,17 @@
     <screen>
       % <userinput>scons -Q hello</userinput>
       cc -o version.o -c version.c
-      cc -o version.o -c version.c
       cc -o hello.o -c hello.c
+      cc -o hello version.o hello.o
+      % <userinput>sleep 1</userinput>
+      % <userinput>scons -Q hello</userinput>
+      cc -o version.o -c version.c
       scons: `hello' is up to date.
       % <userinput>sleep 1</userinput>
       % <userinput>edit hello.c</userinput>
           [CHANGE THE CONTENTS OF hello.c]
       % <userinput>scons -Q hello</userinput>
       cc -o version.o -c version.c
-      cc -o version.o -c version.c
       cc -o hello.o -c hello.c
       cc -o hello version.o hello.o
       % <userinput>sleep 1</userinput>
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index f81dac7..0746793 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -656,18 +656,6 @@ environment, of directory names, suffixes, etc.
 
       <screen>
          C:\><userinput>scons -Q</userinput>
-         
-         scons: warning: No installed VCs
-         File "&lt;stdin&gt;", line 67, in __call__
-         
-         scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-         File "&lt;stdin&gt;", line 67, in __call__
-         
-         scons: warning: No installed VCs
-         File "&lt;stdin&gt;", line 67, in __call__
-         
-         scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-         File "&lt;stdin&gt;", line 67, in __call__
          key = OBJSUFFIX, value = .obj
          key = LIBSUFFIX, value = .lib
          key = PROGSUFFIX, value = .exe
@@ -963,15 +951,8 @@ environment, of directory names, suffixes, etc.
       <screen>
          % <userinput>scons -Q</userinput>
          
-         scons: warning: Two different environments were specified for target foo.o,
-         	but they appear to have the same action: CCCom(target, source, env)
-         File "/home/my/project/SConstruct", line 6, in ?
-         
-         scons: warning: Two different environments were specified for target foo,
-         	but they appear to have the same action: Cat(target, source, env)
-         File "/home/my/project/SConstruct", line 6, in ?
-         cc -o foo.o -c -g foo.c
-         cc -o foo foo.o
+         scons: *** Two environments with different actions were specified for the same target: foo.o
+         File "/home/my/project/SConstruct", line 6, in &lt;module&gt;
       </screen>
 
       <para>
diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml
index e7db86d..0bc382e 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.xml
@@ -100,12 +100,6 @@
 
     <screen>
        C:\><userinput>scons -Q</userinput>
-       
-       scons: warning: No installed VCs
-       File "&lt;stdin&gt;", line 67, in __call__
-       
-       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-       File "&lt;stdin&gt;", line 67, in __call__
        cl /Fohello.obj /c hello.c /nologo
        link /nologo /OUT:new_hello.exe hello.obj
     </screen>
@@ -195,12 +189,6 @@
 
     <screen>
        C:\><userinput>scons -Q</userinput>
-       
-       scons: warning: No installed VCs
-       File "&lt;stdin&gt;", line 67, in __call__
-       
-       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-       File "&lt;stdin&gt;", line 67, in __call__
        cl /Fofile1.obj /c file1.c /nologo
        cl /Fofile2.obj /c file2.c /nologo
        cl /Foprog.obj /c prog.c /nologo
diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml
index 45ad16a..1fa06af 100644
--- a/doc/user/libraries.xml
+++ b/doc/user/libraries.xml
@@ -73,12 +73,6 @@
 
     <screen>
       C:\><userinput>scons -Q</userinput>
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       cl /Fof1.obj /c f1.c /nologo
       cl /Fof2.obj /c f2.c /nologo
       cl /Fof3.obj /c f3.c /nologo
@@ -207,12 +201,6 @@
 
       <screen>
         C:\><userinput>scons -Q</userinput>
-        
-        scons: warning: No installed VCs
-        File "&lt;stdin&gt;", line 67, in __call__
-        
-        scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-        File "&lt;stdin&gt;", line 67, in __call__
         cl /Fof1.obj /c f1.c /nologo
         cl /Fof2.obj /c f2.c /nologo
         cl /Fof3.obj /c f3.c /nologo
@@ -294,12 +282,6 @@
 
     <screen>
       C:\><userinput>scons -Q</userinput>
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       cl /Fof1.obj /c f1.c /nologo
       cl /Fof2.obj /c f2.c /nologo
       cl /Fof3.obj /c f3.c /nologo
@@ -428,12 +410,6 @@
 
     <screen>
       C:\><userinput>scons -Q</userinput>
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       cl /Foprog.obj /c prog.c /nologo
       link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
     </screen>
diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml
index 394ec37..8f3436a 100644
--- a/doc/user/nodes.xml
+++ b/doc/user/nodes.xml
@@ -128,12 +128,6 @@
 
     <screen>
        C:\><userinput>scons -Q</userinput>
-       
-       scons: warning: No installed VCs
-       File "&lt;stdin&gt;", line 67, in __call__
-       
-       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-       File "&lt;stdin&gt;", line 67, in __call__
        cl /Fogoodbye.obj /c goodbye.c -DGOODBYE
        cl /Fohello.obj /c hello.c -DHELLO
        link /nologo /OUT:hello.exe hello.obj goodbye.obj
@@ -277,12 +271,6 @@
 
     <screen>
       C:\><userinput>scons -Q</userinput>
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       The object file is: hello.obj
       The program file is: hello.exe
       cl /Fohello.obj /c hello.c /nologo
diff --git a/doc/user/output.xml b/doc/user/output.xml
index 8a9b67e..ff39fca 100644
--- a/doc/user/output.xml
+++ b/doc/user/output.xml
@@ -132,18 +132,6 @@
     <screen>
        C:\><userinput>scons -h</userinput>
        scons: Reading SConscript files ...
-       
-       scons: warning: No installed VCs
-       File "&lt;stdin&gt;", line 67, in __call__
-       
-       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-       File "&lt;stdin&gt;", line 67, in __call__
-       
-       scons: warning: No installed VCs
-       File "&lt;stdin&gt;", line 67, in __call__
-       
-       scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-       File "&lt;stdin&gt;", line 67, in __call__
        scons: done reading SConscript files.
        
        Type: 'scons program' to build the production program.
diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml
index 4adf97d..3613d77 100644
--- a/doc/user/parseconfig.xml
+++ b/doc/user/parseconfig.xml
@@ -89,17 +89,8 @@
 
  <screen>
     % <userinput>scons -Q</userinput>
-    Package x11 was not found in the pkg-config search path.
-    Perhaps you should add the directory containing `x11.pc'
-    to the PKG_CONFIG_PATH environment variable
-    No package 'x11' found
-    OSError: 'pkg-config x11 --cflags --libs' exited 1:
-      File "/home/my/project/SConstruct", line 3:
-        env.ParseConfig("pkg-config x11 --cflags --libs")
-      File "bootstrap/src/engine/SCons/Environment.py", line 1474:
-        None
-      File "bootstrap/src/engine/SCons/Environment.py", line 593:
-        None
+    ['/lib/compat', '/usr/X11/include']
+    scons: `.' is up to date.
  </screen>
 
  <para>
@@ -140,15 +131,6 @@
 
  <screen>
     % <userinput>scons -Q</userinput>
-    Package x11 was not found in the pkg-config search path.
-    Perhaps you should add the directory containing `x11.pc'
-    to the PKG_CONFIG_PATH environment variable
-    No package 'x11' found
-    OSError: 'pkg-config x11 --cflags --libs' exited 1:
-      File "/home/my/project/SConstruct", line 2:
-        env.ParseConfig("pkg-config x11 --cflags --libs")
-      File "bootstrap/src/engine/SCons/Environment.py", line 1474:
-        None
-      File "bootstrap/src/engine/SCons/Environment.py", line 593:
-        None
+    ['/usr/X11/include']
+    scons: `.' is up to date.
  </screen>
diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml
index 1a169ac..632077e 100644
--- a/doc/user/parseflags.xml
+++ b/doc/user/parseflags.xml
@@ -88,18 +88,6 @@
 
  <screen>
     C:\><userinput>scons -Q</userinput>
-    
-    scons: warning: No installed VCs
-    File "&lt;stdin&gt;", line 67, in __call__
-    
-    scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-    File "&lt;stdin&gt;", line 67, in __call__
-    
-    scons: warning: No installed VCs
-    File "&lt;stdin&gt;", line 67, in __call__
-    
-    scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-    File "&lt;stdin&gt;", line 67, in __call__
     CPPPATH ['/opt/include']
     LIBPATH ['/opt/lib']
     LIBS ['foo']
diff --git a/doc/user/simple.xml b/doc/user/simple.xml
index 3089854..6bd70b0 100644
--- a/doc/user/simple.xml
+++ b/doc/user/simple.xml
@@ -106,12 +106,6 @@
    <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       scons: done reading SConscript files.
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
@@ -199,12 +193,6 @@
    <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       scons: done reading SConscript files.
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
@@ -308,12 +296,6 @@
    <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       scons: done reading SConscript files.
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
@@ -321,12 +303,6 @@
       scons: done building targets.
       C:\><userinput>scons -c</userinput>
       scons: Reading SConscript files ...
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       scons: done reading SConscript files.
       scons: Cleaning targets ...
       Removed hello.obj
@@ -527,12 +503,6 @@
    <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       scons: done reading SConscript files.
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
@@ -564,12 +534,6 @@
 
    <screen>
       C:\><userinput>scons -Q</userinput>
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
    </screen>
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml
index 2ac91ec..a3339e0 100644
--- a/doc/user/troubleshoot.xml
+++ b/doc/user/troubleshoot.xml
@@ -286,7 +286,7 @@
         'DSUFFIXES': ['.d'],
         'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x700000&gt;,
         'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x700000&gt;,
-        'ENV': {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'},
+        'ENV': { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'},
         'ESCAPE': &lt;function escape at 0x700000&gt;,
         'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x700000&gt;,
         'HOST_ARCH': None,
@@ -341,18 +341,6 @@
     <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
       { 'BUILDERS': {'_InternalInstall': &lt;function InstallBuilderWrapper at 0x700000&gt;, 'Object': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;, 'PCH': &lt;SCons.Builder.BuilderBase instance at 0x700000&gt;, 'RES': &lt;SCons.Builder.BuilderBase instance at 0x700000&gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder instance at 0x700000&gt;, '_InternalInstallAs': &lt;function InstallAsBuilderWrapper at 0x700000&gt;},
         'CC': 'cl',
         'CCCOM': &lt;SCons.Action.FunctionAction instance at 0x700000&gt;,
@@ -391,7 +379,7 @@
         'DSUFFIXES': ['.d'],
         'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x700000&gt;,
         'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0x700000&gt;,
-        'ENV': { 'PATH': 'C:/WINDOWS\\System32',
+        'ENV': { 'PATH': 'C:\\WINDOWS\\System32',
                  'PATHEXT': '.COM;.EXE;.BAT;.CMD',
                  'SystemRoot': 'C:\\WINDOWS'},
         'ESCAPE': &lt;function escape at 0x700000&gt;,
@@ -501,7 +489,7 @@
     <screen>
       % <userinput>scons</userinput>
       scons: Reading SConscript files ...
-      {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}
+      { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}
       scons: done reading SConscript files.
       scons: Building targets ...
       scons: `.' is up to date.
@@ -517,18 +505,7 @@
     <screen>
       C:\><userinput>scons</userinput>
       scons: Reading SConscript files ...
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No installed VCs
-      File "&lt;stdin&gt;", line 67, in __call__
-      
-      scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-      File "&lt;stdin&gt;", line 67, in __call__
-      { 'PATH': 'C:/WINDOWS\\System32',
+      { 'PATH': 'C:\\WINDOWS\\System32',
         'PATHEXT': '.COM;.EXE;.BAT;.CMD',
         'SystemRoot': 'C:\\WINDOWS'}
       scons: done reading SConscript files.
@@ -1144,8 +1121,11 @@
         File "bootstrap/src/engine/SCons/Job.py", line 197, in start
           task.prepare()
         File "bootstrap/src/engine/SCons/Script/Main.py", line 167, in prepare
+          return SCons.Taskmaster.OutOfDateTask.prepare(self)
         File "bootstrap/src/engine/SCons/Taskmaster.py", line 190, in prepare
+          executor.prepare()
         File "bootstrap/src/engine/SCons/Executor.py", line 397, in prepare
+          raise SCons.Errors.StopError, msg % (s, self.batches[0].targets[0])
     </screen>
 
     <para>
diff --git a/doc/user/variants.xml b/doc/user/variants.xml
index e60dd8c..3ae3e4a 100644
--- a/doc/user/variants.xml
+++ b/doc/user/variants.xml
@@ -108,18 +108,6 @@ is pretty smart about rebuilding things when you change options.
 
   <screen>
     C:\><userinput>scons -Q OS=windows</userinput>
-    
-    scons: warning: No installed VCs
-    File "&lt;stdin&gt;", line 67, in __call__
-    
-    scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-    File "&lt;stdin&gt;", line 67, in __call__
-    
-    scons: warning: No installed VCs
-    File "&lt;stdin&gt;", line 67, in __call__
-    
-    scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
-    File "&lt;stdin&gt;", line 67, in __call__
     Install file: "build/windows/world/world.h" as "export/windows/include/world.h"
     cl /Fobuild\windows\hello\hello.obj /c build\windows\hello\hello.c /nologo /Iexport\windows\include
     cl /Fobuild\windows\world\world.obj /c build\windows\world\world.c /nologo /Iexport\windows\include