Initialize the new branch.

21 files changed, 1628 insertions, 778 deletions

diff --git a/doc/scons.mod b/doc/scons.mod
index 19190b2..958444d 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -73,6 +73,7 @@
 <!ENTITY implicit-cache "<literal>--implicit-cache</literal>">
 <!ENTITY implicit-deps-changed "<literal>--implicit-deps-changed</literal>">
 <!ENTITY implicit-deps-unchanged "<literal>--implicit-deps-unchanged</literal>">
+<!ENTITY Q "<literal>-Q</literal>">
 
 <!--
 
@@ -127,6 +128,7 @@
 <!ENTITY Export "<function>Export</function>">
 <!ENTITY Help "<function>Help</function>">
 <!ENTITY Ignore "<function>Ignore</function>">
+<!ENTITY Import "<function>Import</function>">
 <!ENTITY Install "<function>Install</function>">
 <!ENTITY InstallAs "<function>InstallAs</function>">
 <!ENTITY Link "<function>Link</function>">
@@ -137,6 +139,7 @@
 <!ENTITY Prepend "<function>Prepend</function>">
 <!ENTITY Replace "<function>Replace</function>">
 <!ENTITY Repository "<function>Repository</function>">
+<!ENTITY Return "<function>Return</function>">
 <!ENTITY RuleSet "<function>RuleSet</function>">
 <!ENTITY Salt "<function>Salt</function>">
 <!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>">
@@ -163,6 +166,13 @@
 
 <!ENTITY BUILDERMAP "<varname>BUILDERMAP</varname>">
 <!ENTITY BUILDERS "<varname>BUILDERS</varname>">
+<!ENTITY LIBDIRPREFIX "<varname>LIBDIRPREFIX</varname>">
+<!ENTITY LIBDIRSUFFIX "<varname>LIBDIRSUFFIX</varname>">
+<!ENTITY LIBLINKPREFIX "<varname>LIBLINKPREFIX</varname>">
+<!ENTITY LIBLINKSUFFIX "<varname>LIBLINKSUFFIX</varname>">
+<!ENTITY LINK "<varname>LINK</varname>">
+<!ENTITY LINKCOM "<varname>LINKCOM</varname>">
+<!ENTITY LINKFLAGS "<varname>LINKFLAGS</varname>">
 <!ENTITY SCANNERMAP "<varname>SCANNERMAP</varname>">
 <!ENTITY SCANNERS "<varname>SCANNERS</varname>">
 <!ENTITY TARFLAGS "<varname>TARFLAGS</varname>">
@@ -272,14 +282,22 @@
 
 -->
 
+<!ENTITY bar "<application>bar</application>">
 <!ENTITY common1_c "<application>common1.c</application>">
 <!ENTITY common2_c "<application>common2.c</application>">
 <!ENTITY goodbye "<application>goodbye</application>">
+<!ENTITY file_dll "<application>file.dll</application>">
+<!ENTITY file_lib "<application>file.lib</application>">
+<!ENTITY file_o "<application>file.o</application>">
+<!ENTITY file_obj "<application>file.obj</application>">
+<!ENTITY foo "<application>foo</application>">
 <!ENTITY hello "<application>hello</application>">
 <!ENTITY hello_c "<filename>hello.c</filename>">
 <!ENTITY hello_exe "<filename>hello.exe</filename>">
 <!ENTITY hello_h "<filename>hello.h</filename>">
 <!ENTITY hello_o "<filename>hello.o</filename>">
+<!ENTITY libfile_a "<filename>libfile_a</filename>">
+<!ENTITY libfile_so "<filename>libfile_so</filename>">
 <!ENTITY prog "<filename>prog</filename>">
 <!ENTITY prog1 "<filename>prog1</filename>">
 <!ENTITY prog2 "<filename>prog2</filename>">
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index d911f6c..50c9114 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -167,17 +167,22 @@ This functionality could be invoked as in the following example:
        <file name="SConstruct">
        bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
        env.Foo('file.foo', 'file.input')
        </file>
        <file name="file.input">
        file.input
        </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
     </scons_example>
 
-    <programlisting>
+    <sconstruct>
        bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
-    </programlisting>
+    </sconstruct>
 
     <para>
 
@@ -197,7 +202,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_output example="ex1">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -229,23 +234,8 @@ This functionality could be invoked as in the following example:
        </file>
     </scons_example>
 
-    <!--
-      scons: Reading SConscript files ...
-      other errors
-      Traceback (most recent call last):
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 901, in main
-          _main()
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 762, in _main
-          SCons.Script.SConscript.SConscript(script)
-        File "/usr/lib/scons/SCons/Script/SConscript.py", line 207, in SConscript
-          exec _file_ in stack[-1].globals
-        File "SConstruct", line 4, in ?
-          env.Program('hello.c')
-      scons: Environment instance has no attribute 'Program'
-    -->
-
     <scons_output example="ex2">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -260,6 +250,8 @@ This functionality could be invoked as in the following example:
     <scons_example name="ex3">
        <file name="SConstruct">
        env = Environment()
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
        bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env.Append(BUILDERS = {'Foo' : bld})
        env.Foo('file.foo', 'file.input')
@@ -271,8 +263,19 @@ This functionality could be invoked as in the following example:
        <file name="hello.c">
        hello.c
        </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
     </scons_example>
 
+    <sconstruct>
+       env = Environment()
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+       env.Append(BUILDERS = {'Foo' : bld})
+       env.Foo('file.foo', 'file.input')
+       env.Program('hello.c')
+    </sconstruct>
+
     <para>
 
     Or you can explicitly set the appropriately-named
@@ -280,13 +283,13 @@ This functionality could be invoked as in the following example:
 
     </para>
 
-    <programlisting>
+    <sconstruct>
        env = Environment()
        bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env['BUILDERS']['Foo'] = bld
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
-    </programlisting>
+    </sconstruct>
 
     <para>
 
@@ -298,7 +301,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_output example="ex3">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
   </section>
@@ -324,11 +327,13 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_example name="ex4">
-       <file name="SConstruct" printme="1">
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE',
+       <file name="SConstruct">
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
                      suffix = '.foo',
                      src_suffix = '.input')
        env = Environment(BUILDERS = {'Foo' : bld})
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
        env.Foo('file1')
        env.Foo('file2')
        </file>
@@ -338,10 +343,22 @@ This functionality could be invoked as in the following example:
        <file name="file2.input">
        file2.input
        </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
     </scons_example>
 
+    <sconstruct>
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
+                     suffix = '.foo',
+                     src_suffix = '.input')
+       env = Environment(BUILDERS = {'Foo' : bld})
+       env.Foo('file1')
+       env.Foo('file2')
+    </sconstruct>
+
     <scons_output example="ex4">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -370,7 +387,7 @@ This functionality could be invoked as in the following example:
 
     <programlisting>
        def build_function(target, source, env):
-           # XXX
+           # Code to build "target" from "source"
            return None
     </programlisting>
 
@@ -459,7 +476,7 @@ This functionality could be invoked as in the following example:
     <scons_example name="ex5">
        <file name="SConstruct" printme="1">
        def build_function(target, source, env):
-           # XXX
+           # Code to build "target" from "source"
            return None
        bld = Builder(action = build_function,
                      suffix = '.foo',
@@ -482,7 +499,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_output example="ex5">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
   </section>
@@ -494,14 +511,16 @@ This functionality could be invoked as in the following example:
 
     &SCons; Builder objects can create an action "on the fly"
     by using a function called a &generator;.
-    This provides a great deal of flexibility XXX
+    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 XXX
+           return 'foobuild < %s > %s' % (target[0], source[0])
     </programlisting>
 
     <para>
@@ -575,7 +594,7 @@ This functionality could be invoked as in the following example:
       generator is being called to contribute to a build signature,
       as opposed to actually executing the command.
 
-      XXX
+      <!-- XXX NEED MORE HERE -->
 
       </para>
       </listitem>
@@ -602,20 +621,37 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_example name="ex6">
-       <file name="SConstruct" printme="1">
+       <file name="SConstruct">
+       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})
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
        env.Foo('file')
        </file>
        <file name="file.input">
        file.input
        </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
     </scons_example>
 
+    <sconstruct>
+       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')
+    </sconstruct>
+
     <scons_output example="ex6">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -641,23 +677,46 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_example name="ex7">
-       <file name="SConstruct" printme="1">
-       def modify_targets(XXX):
-           return XXX
-       bld = Builder(action = 'XXX',
+       <file name="SConstruct">
+       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})
+       import os
+       env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
        env.Foo('file')
        </file>
        <file name="file.input">
        file.input
        </file>
-    </programlisting>
+       <file name="new_source">
+       new_source
+       </file>
+       <file name="foobuild" chmod="0755">
+       cat
+       </file>
+    </scons_example>
+
+    <sconstruct>
+       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')
+    </sconstruct>
 
     <scons_output example="ex7">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <programlisting>
@@ -665,10 +724,10 @@ This functionality could be invoked as in the following example:
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = 'MY_EMITTER')
-       def modify1(XXX):
-           return XXX
-       def modify2(XXX):
-           return XXX
+       def modify1(target, source, env):
+           return target, source
+       def modify2(target, source, env):
+           return target, source
        env1 = Environment(BUILDERS = {'Foo' : bld},
                           MY_EMITTER = modify1)
        env2 = Environment(BUILDERS = {'Foo' : bld},
@@ -679,6 +738,8 @@ This functionality could be invoked as in the following example:
 
   </section>
 
+  <!--
+
   <section>
   <title>Builders That Use Other Builders</title>
 
@@ -691,13 +752,18 @@ This functionality could be invoked as in the following example:
     <scons_example name="ex8">
        <file name="SConstruct" printme="1">
        env = Environment()
-       env.SourceCode('.', env.BitKeeper('XXX'))
+       #env.SourceCode('.', env.BitKeeper('XXX'))
        env.Program('hello.c')
        </file>
-    </programlisting>
+       <file name="hello.c">
+       hello.c
+       </file>
+    </scons_example>
 
     <scons_output example="ex8">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
   </section>
+
+  -->
diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml
index 27a48b9..796e199 100644
--- a/doc/user/builders-writing.sgml
+++ b/doc/user/builders-writing.sgml
@@ -129,7 +129,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
     </programlisting>
 
     <para>
@@ -163,8 +163,10 @@ This functionality could be invoked as in the following example:
 
     </para>
 
+    
+
     <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
     </programlisting>
 
@@ -186,7 +188,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       foobuild < file.input > file.foo
     </literallayout>
 
@@ -205,26 +207,15 @@ This functionality could be invoked as in the following example:
     </para>
 
     <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env = Environment(BUILDERS = {'Foo' : bld})
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
     </programlisting>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      scons: Reading SConscript files ...
-      other errors
-      Traceback (most recent call last):
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 901, in main
-          _main()
-        File "/usr/lib/scons/SCons/Script/__init__.py", line 762, in _main
-          SCons.Script.SConscript.SConscript(script)
-        File "/usr/lib/scons/SCons/Script/SConscript.py", line 207, in SConscript
-          exec _file_ in stack[-1].globals
-        File "SConstruct", line 4, in ?
-          env.Program('hello.c')
-      scons: Environment instance has no attribute 'Program'
+      % <userinput>scons -Q</userinput>
+      AttributeError: SConsEnvironment instance has no attribute 'Program':
     </literallayout>
 
     <para>
@@ -236,9 +227,11 @@ This functionality could be invoked as in the following example:
 
     </para>
 
+    
+
     <programlisting>
        env = Environment()
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env.Append(BUILDERS = {'Foo' : bld})
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
@@ -253,7 +246,7 @@ This functionality could be invoked as in the following example:
 
     <programlisting>
        env = Environment()
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE')
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
        env['BUILDERS']['Foo'] = bld
        env.Foo('file.foo', 'file.input')
        env.Program('hello.c')
@@ -269,9 +262,9 @@ This functionality could be invoked as in the following example:
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       foobuild < file.input > file.foo
-      cc -c hello.c -o hello.o
+      cc -c -o hello.o hello.c
       cc -o hello hello.o
     </literallayout>
 
@@ -297,8 +290,10 @@ This functionality could be invoked as in the following example:
 
     </para>
 
+    
+
     <programlisting>
-       bld = Builder(action = 'foobuild < $TARGET > $SOURCE',
+       bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
                      suffix = '.foo',
                      src_suffix = '.input')
        env = Environment(BUILDERS = {'Foo' : bld})
@@ -307,7 +302,7 @@ This functionality could be invoked as in the following example:
     </programlisting>
 
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       foobuild < file1.input > file1.foo
       foobuild < file2.input > file2.foo
     </literallayout>
@@ -338,7 +333,7 @@ This functionality could be invoked as in the following example:
 
     <programlisting>
        def build_function(target, source, env):
-           # XXX
+           # Code to build "target" from "source"
            return None
     </programlisting>
 
@@ -426,7 +421,7 @@ This functionality could be invoked as in the following example:
 
     <programlisting>
        def build_function(target, source, env):
-           # XXX
+           # Code to build "target" from "source"
            return None
        bld = Builder(action = build_function,
                      suffix = '.foo',
@@ -445,7 +440,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       build_function("file.foo", "file.input")
     </literallayout>
 
@@ -458,14 +453,16 @@ This functionality could be invoked as in the following example:
 
     &SCons; Builder objects can create an action "on the fly"
     by using a function called a &generator;.
-    This provides a great deal of flexibility XXX
+    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 XXX
+           return 'foobuild < %s > %s' % (target[0], source[0])
     </programlisting>
 
     <para>
@@ -539,7 +536,7 @@ This functionality could be invoked as in the following example:
       generator is being called to contribute to a build signature,
       as opposed to actually executing the command.
 
-      XXX
+      <!-- XXX NEED MORE HERE -->
 
       </para>
       </listitem>
@@ -565,7 +562,11 @@ This functionality could be invoked as in the following example:
 
     </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')
@@ -574,8 +575,8 @@ This functionality could be invoked as in the following example:
     </programlisting>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      XXX
+      % <userinput>scons -Q</userinput>
+      foobuild < file.input > file.foo
     </literallayout>
 
     <para>
@@ -600,10 +601,14 @@ This functionality could be invoked as in the following example:
 
     </para>
 
+    
+
     <programlisting>
-       def modify_targets(XXX):
-           return XXX
-       bld = Builder(action = 'XXX',
+       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)
@@ -612,8 +617,8 @@ This functionality could be invoked as in the following example:
     </programlisting>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      XXX
+      % <userinput>scons -Q</userinput>
+      foobuild file.foo new_target - file.input new_source
     </literallayout>
 
     <programlisting>
@@ -621,10 +626,10 @@ This functionality could be invoked as in the following example:
                      suffix = '.foo',
                      src_suffix = '.input',
                      emitter = 'MY_EMITTER')
-       def modify1(XXX):
-           return XXX
-       def modify2(XXX):
-           return XXX
+       def modify1(target, source, env):
+           return target, source
+       def modify2(target, source, env):
+           return target, source
        env1 = Environment(BUILDERS = {'Foo' : bld},
                           MY_EMITTER = modify1)
        env2 = Environment(BUILDERS = {'Foo' : bld},
@@ -635,6 +640,8 @@ This functionality could be invoked as in the following example:
 
   </section>
 
+  <!--
+
   <section>
   <title>Builders That Use Other Builders</title>
 
@@ -644,15 +651,21 @@ This functionality could be invoked as in the following example:
 
     </para>
 
-    <programlisting>
+    <scons_example name="ex8">
+       <file name="SConstruct" printme="1">
        env = Environment()
-       env.SourceCode('.', env.BitKeeper('XXX')
+       #env.SourceCode('.', env.BitKeeper('XXX'))
        env.Program('hello.c')
-    </programlisting>
+       </file>
+       <file name="hello.c">
+       hello.c
+       </file>
+    </scons_example>
 
-    <literallayout>
-      % <userinput>scons</userinput>
-      XXX
-    </literallayout>
+    <scons_output example="ex8">
+      <command>scons -Q</command>
+    </scons_output>
 
   </section>
+
+  -->
diff --git a/doc/user/depends.in b/doc/user/depends.in
index aa69dc7..bedc91d 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -59,8 +59,7 @@ operating system on which the build is performed (as reported by C<uname
 
   <scons_example name="ex1">
     <file name="SConstruct">
-    env = Environment()
-    env.Program('hello.c')
+    Program('hello.c')
     </file>
     <file name="hello.c">
     int main() { printf("Hello, world!\n"); }
@@ -68,8 +67,8 @@ operating system on which the build is performed (as reported by C<uname
   </scons_example>
 
   <scons_output example="ex1" os="posix">
-     <command>scons</command>
-     <command>scons</command>
+     <command>scons -Q</command>
+     <command>scons -Q</command>
   </scons_output>
 
   <para>
@@ -84,8 +83,8 @@ operating system on which the build is performed (as reported by C<uname
   </para>
 
   <scons_output example="ex1" os="posix">
-     <command>scons hello</command>
-     <command>scons hello</command>
+     <command>scons -Q hello</command>
+     <command>scons -Q hello</command>
   </scons_output>
 
   <para>
@@ -133,9 +132,9 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <scons_output example="ex1" os="posix">
-         <command>scons hello</command>
+         <command>scons -Q hello</command>
          <command>touch hello.c</command>
-         <command>scons hello</command>
+         <command>scons -Q hello</command>
       </scons_output>
 
       <para>
@@ -155,26 +154,10 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <scons_output example="ex1" os="posix">
-         <command>scons hello</command>
-         <command output="[CHANGE THE CONTENTS OF hello.c]">edit hello.c</command>
-         <command>scons hello</command>
-      </scons>
-
-      <!--
-
-      <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         cc -o hello hello.o
-         % <userinput>edit hello.c</userinput>
-             [CHANGE THE CONTENTS OF hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         cc -o hello hello.o
-         %
-      </literallayout>
-
-      -->
+         <command>scons -Q hello</command>
+         <command output="    [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command>
+         <command>scons -Q hello</command>
+      </scons_output>
 
       <para>
 
@@ -186,8 +169,7 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <sconstruct>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         SourceSignatures('MD5')
       </sconstruct>
 
@@ -210,8 +192,7 @@ operating system on which the build is performed (as reported by C<uname
 
       <scons_example name="ex2">
         <file name="SConstruct" printme="1">
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         SourceSignatures('timestamp')
         </file>
         <file name="hello.c">
@@ -227,11 +208,11 @@ operating system on which the build is performed (as reported by C<uname
 
       </para>
 
-      <scons_output example="ex1" os="posix">
-         <command>scons hello</command>
+      <scons_output example="ex2" os="posix">
+         <command>scons -Q hello</command>
          <command>touch hello.c</command>
-         <command>scons hello</command>
-      </scons>
+         <command>scons -Q hello</command>
+      </scons_output>
 
     </section>
 
@@ -247,8 +228,8 @@ operating system on which the build is performed (as reported by C<uname
     target file is up to date or must be rebuilt.
     When a target file depends on another target file,
     &SCons; allows you to separately configure
-    how the signatures of an "intermediate" target file
-    is used when deciding if a dependent target file
+    how the signatures of "intermediate" target files
+    are used when deciding if a dependent target file
     must be rebuilt.
 
     </para>
@@ -271,26 +252,10 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <scons_output example="ex1" os="posix">
-         <command>scons hello</command>
-         <command output="[CHANGE THE CONTENTS OF hello.c]">edit hello.c</command>
-         <command>scons hello</command>
-      </scons>
-
-      <!--
-
-      <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         cc -o hello hello.o
-         % <userinput>edit hello.c</userinput>
-           [CHANGE THE CONTENTS OF hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         cc -o hello hello.o
-         %
-      </literallayout>
-
-      -->
+         <command>scons -Q hello</command>
+         <command output="    [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command>
+         <command>scons -Q hello</command>
+      </scons_output>
 
       <para>
 
@@ -324,8 +289,7 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <sconstruct>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         TargetSignatures('build')
       </sconstruct>
 
@@ -344,17 +308,16 @@ operating system on which the build is performed (as reported by C<uname
       If so, then any other target files
       that depend on such a built-but-not-changed target
       file actually need not be rebuilt.
-      You can have &SCons;
-      realize that a dependent target file
-      need not be rebuilt in this situation
+      You can make &SCons;
+      realize that it does not need to rebuild
+      a dependent target file in this situation
       using the &TargetSignatures; function as follows:
 
       </para>
 
       <scons_example name="ex3">
         <file name="SConstruct" printme="1">
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         TargetSignatures('content')
         </file>
         <file name="hello.c">
@@ -376,10 +339,10 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <scons_output example="ex3" os="posix">
-         <command>scons hello</command>
-         <command output="[CHANGE A COMMENT IN hello.c]">edit hello.c</command>
-         <command>scons hello</command>
-      </scons>
+         <command>scons -Q hello</command>
+         <command output="  [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</command>
+         <command>scons -Q hello</command>
+      </scons_output>
 
       <para>
 
@@ -413,19 +376,18 @@ operating system on which the build is performed (as reported by C<uname
 
     <scons_example name="ex4">
       <file name="SConstruct">
-      env = Environment(CPPPATH = '.')
-      hello = env.Program('hello.c')
+       Program('hello.c', CPPPATH = '.')
       </file>
       <file name="hello.c" printme="1">
-      #include "hello.h" 
-      int
-      main()
-      {
-          printf("Hello, %s!\n", string);
-      }
+       #include "hello.h" 
+       int
+       main()
+       {
+           printf("Hello, %s!\n", string);
+       }
       </file>
       <file name="hello.h">
-      #define string    "world"
+       #define string    "world"
       </file>
     </scons_example>
 
@@ -453,7 +415,7 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
-    The &CPPPATH; assignment in the &Environment; call
+    The &CPPPATH; value
     tells &SCons; to look in the current directory
     (<literal>'.'</literal>)
     for any files included by C source files
@@ -463,11 +425,11 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <scons_output example="ex4" os="posix">
-       <command>scons hello</command>
-       <command>scons hello</command>
-       <command output="[CHANGE THE CONTENTS IN hello.h]">edit hello.h</command>
-       <command>scons hello</command>
-    </scons>
+       <command>scons -Q hello</command>
+       <command>scons -Q hello</command>
+       <command output="    [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command>
+       <command>scons -Q hello</command>
+    </scons_output>
 
     <para>
 
@@ -512,13 +474,9 @@ operating system on which the build is performed (as reported by C<uname
 
     </para>
 
-    <programlisting>
-    </programlisting>
-
     <scons_example name="ex5">
-      <file name="SConstruct">
-      env = Environment(CPPPATH = ['include', '/home/project/inc'])
-      hello = env.Program('hello.c')
+      <file name="SConstruct" printme="1">
+       Program('hello.c', CPPPATH = ['include', '/home/project/inc'])
       </file>
       <file name="hello.c">
       int main() { printf("Hello, world!\n"); }
@@ -531,8 +489,8 @@ operating system on which the build is performed (as reported by C<uname
 
     </para>
 
-    <scons_output example="ex4" os="posix">
-       <command>scons hello</command>
+    <scons_output example="ex5" os="posix">
+       <command>scons -Q hello</command>
     </scons_output>
 
     <para>
@@ -541,8 +499,8 @@ operating system on which the build is performed (as reported by C<uname
 
     </para>
 
-    <scons_output example="ex4" os="win32">
-       <command>scons hello</command>
+    <scons_output example="ex5" os="win32">
+       <command>scons -Q hello.exe</command>
     </scons_output>
 
   </section>
@@ -590,19 +548,22 @@ operating system on which the build is performed (as reported by C<uname
     the implicit dependencies
     that its scanners find,
     for use by later builds.
-    You do this either by specifying the
+    You can do this by specifying the
     &implicit-cache; option on the command line:
 
     </para>
 
-    <scons_output example="ex1" os="win32">
-       <command>scons --implicit-cache hello</command>
-       <command>scons hello</command>
+    <scons_output example="ex1">
+       <command>scons -Q --implicit-cache hello</command>
+       <command>scons -Q hello</command>
     </scons_output>
 
     <para>
 
-    Or by setting the &implicit_cache; option
+    If you don't want to specify &implicit-cache;
+    on the command line each time,
+    you can make it the default behavior for your build
+    by setting the &implicit_cache; option
     in an &SConscript; file:
 
     </para>
@@ -611,25 +572,52 @@ operating system on which the build is performed (as reported by C<uname
        SetOption('implicit_cache', 1)
     </sconstruct>
 
-    <para>
+    <!--
 
-    &SCons; does not cache implicit dependencies like this by default
-    because XXX
+    <para>
     
+    XXX
+
     </para>
 
     <para>
-    
-    XXX
 
+    &SCons; does not cache implicit dependencies like this by default
+    because XXX
+    
     </para>
 
+    -->
+
     <section>
     <title>The &implicit-deps-changed; Option</title>
 
       <para>
 
-      XXX
+      When using cached implicit dependencies,
+      sometimes you want to "start fresh"
+      and have &SCons; re-scan the files
+      for which it previously cached the dependencies.
+      For example,
+      if you have recently installed a new version of
+      external code that you use for compilation,
+      the external header files will have changed
+      and the previously-cached implicit dependencies
+      will be out of date.
+      You can update them by
+      running &SCons; with the &implicit-deps-changed; option:
+
+      </para>
+
+      <scons_output example="ex1">
+         <command>scons -Q --implicit-deps-changed hello</command>
+         <command>scons -Q hello</command>
+      </scons_output>
+
+      <para>
+
+      In this case, &SCons; will re-scan all of the implicit dependencies
+      and cache updated copies of the information.
 
       </para>
 
@@ -640,7 +628,38 @@ operating system on which the build is performed (as reported by C<uname
 
       <para>
 
-      XXX
+      By default when caching dependencies,
+      &SCons; notices when a file has been modified
+      and re-scans the file for any updated
+      implicit dependency information.
+      Sometimes, however, you may want
+      to force &SCons; to use the cached implicit dependencies, 
+      even if the source files changed.
+      This can speed up a build for example,
+      when you have changed your source files
+      but know that you haven't changed
+      any <literal>#include</literal> lines.
+      In this case,
+      you can use the &implicit-deps-unchanged; option:
+
+      </para>
+
+      <scons_output example="ex1">
+         <command>scons -Q --implicit-deps-unchanged hello</command>
+         <command>scons -Q hello</command>
+      </scons_output>
+
+      <para>
+
+      In this case,
+      &SCons; will assume that the cached implicit
+      dependencies are correct and
+      will not bother to re-scan changed files.
+      For typical builds after small,
+      incremental changes to source files,
+      the savings may not be very big,
+      but sometimes every bit of
+      improved performance counts.
 
       </para>
 
@@ -662,24 +681,42 @@ operating system on which the build is performed (as reported by C<uname
 
     </para>
 
-    <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       env.Ignore(hello, 'hello.h')
-    </programlisting>
+    <scons_example name="ignore">
+      <file name="SConstruct" printme="1">
+      hello = Program('hello.c')
+      Ignore(hello, 'hello.h')
+      </file>
+      <file name="hello.c">
+      #include "hello.h" 
+      int main() { printf("Hello, %s!\n", string); }
+      </file>
+      <file name="hello.h">
+      #define string    "world"
+      </file>
+    </scons_example>
 
     <!-- XXX mention that you can use arrays for target and source? -->
 
+    <!--
+    <scons_output example="ignore">
+      <command>scons -Q hello</command>
+      <command>scons -Q hello</command>
+      <command output="    [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command>
+      <command>scons -Q hello</command>
+      XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX
+    </scons_output>
+    -->
+
     <literallayout>
-       % <userinput>scons hello</userinput>
-       cc -c hello.c -o hello.o
-       cc -o hello hello.o
-       % <userinput>scons hello</userinput>
-       scons: `hello' is up to date.
-       % <userinput>edit hello.h</userinput>
-           [CHANGE THE CONTENTS OF hello.h]
-       % <userinput>scons hello</userinput>
-       scons: `hello' is up to date.
+      % <userinput>scons -Q hello</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
+      % <userinput>edit hello.h</userinput>
+        [CHANGE THE CONTENTS OF hello.h]
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
     </literallayout>
 
     <para>
@@ -718,7 +755,7 @@ operating system on which the build is performed (as reported by C<uname
 
     On the other hand,
     sometimes a file depends on another file
-    that has no &SCons; scanner will detect.
+    that is not detected by an &SCons; scanner.
     For this situation,
     &SCons; allows you to specific explicitly that one file
     depends on another file,
@@ -736,14 +773,14 @@ operating system on which the build is performed (as reported by C<uname
     <!-- XXX mention that you can use arrays for target and source? -->
 
     <literallayout>
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        cc -c hello.c -o hello.o
        cc -o hello hello.o
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
        % <userinput>edit other_file</userinput>
            [CHANGE THE CONTENTS OF other_file]
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        cc -c hello.c -o hello.o
        cc -o hello hello.o
     </literallayout>
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index 2049caf..f595e08 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -57,12 +57,14 @@ operating system on which the build is performed (as reported by C<uname
 
   </para>
 
+  
+
   <literallayout>
-     % <userinput>scons</userinput>
-     cc -c hello.c -o hello.o
+     % <userinput>scons -Q</userinput>
+     cc -c -o hello.o hello.c
      cc -o hello hello.o
-     % <userinput>scons</userinput>
-     %
+     % <userinput>scons -Q</userinput>
+     scons: `.' is up to date.
   </literallayout>
 
   <para>
@@ -77,12 +79,11 @@ operating system on which the build is performed (as reported by C<uname
   </para>
 
   <literallayout>
-     % <userinput>scons hello</userinput>
-     cc -c hello.c -o hello.o
+     % <userinput>scons -Q hello</userinput>
+     cc -c -o hello.o hello.c
      cc -o hello hello.o
-     % <userinput>scons hello</userinput>
+     % <userinput>scons -Q hello</userinput>
      scons: `hello' is up to date.
-     %
   </literallayout>
 
   <para>
@@ -130,13 +131,12 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>touch hello.c</userinput>
-         % <userinput>scons hello</userinput>
+         % <userinput>scons -Q hello</userinput>
          scons: `hello' is up to date.
-         %
       </literallayout>
 
       <para>
@@ -156,15 +156,14 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
              [CHANGE THE CONTENTS OF hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
-         %
       </literallayout>
 
       <para>
@@ -177,8 +176,7 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         SourceSignatures('MD5')
       </programlisting>
 
@@ -200,8 +198,7 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         SourceSignatures('timestamp')
       </programlisting>
 
@@ -214,14 +211,13 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>touch hello.c</userinput>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
-         %
       </literallayout>
 
     </section>
@@ -238,8 +234,8 @@ operating system on which the build is performed (as reported by C<uname
     target file is up to date or must be rebuilt.
     When a target file depends on another target file,
     &SCons; allows you to separately configure
-    how the signatures of an "intermediate" target file
-    is used when deciding if a dependent target file
+    how the signatures of "intermediate" target files
+    are used when deciding if a dependent target file
     must be rebuilt.
 
     </para>
@@ -262,15 +258,14 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
-           [CHANGE THE CONTENTS OF hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+             [CHANGE THE CONTENTS OF hello.c]
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
-         %
       </literallayout>
 
       <para>
@@ -305,8 +300,7 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         TargetSignatures('build')
       </programlisting>
 
@@ -325,16 +319,15 @@ operating system on which the build is performed (as reported by C<uname
       If so, then any other target files
       that depend on such a built-but-not-changed target
       file actually need not be rebuilt.
-      You can have &SCons;
-      realize that a dependent target file
-      need not be rebuilt in this situation
+      You can make &SCons;
+      realize that it does not need to rebuild
+      a dependent target file in this situation
       using the &TargetSignatures; function as follows:
 
       </para>
 
       <programlisting>
-        env = Environment()
-        env.Program('hello.c')
+        Program('hello.c')
         TargetSignatures('content')
       </programlisting>
 
@@ -352,14 +345,14 @@ operating system on which the build is performed (as reported by C<uname
       </para>
 
       <literallayout>
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
          cc -o hello hello.o
          % <userinput>edit hello.c</userinput>
            [CHANGE A COMMENT IN hello.c]
-         % <userinput>scons hello</userinput>
-         cc -c hello.c -o hello.o
-         %
+         % <userinput>scons -Q hello</userinput>
+         cc -c -o hello.o hello.c
+         scons: `hello' is up to date.
       </literallayout>
 
       <para>
@@ -407,9 +400,10 @@ operating system on which the build is performed (as reported by C<uname
 
     </para>
 
+    
     <programlisting>
        #define string    "world"
-    </programlisting>
+      </programlisting>
 
     <para>
 
@@ -421,14 +415,14 @@ operating system on which the build is performed (as reported by C<uname
 
     </para>
 
+    
     <programlisting>
-       env = Environment(CPPPATH = '.')
-       hello = env.Program('hello.c')
-    </programlisting>
+       Program('hello.c', CPPPATH = '.')
+      </programlisting>
 
     <para>
 
-    The &CPPPATH; assignment in the &Environment; call
+    The &CPPPATH; value
     tells &SCons; to look in the current directory
     (<literal>'.'</literal>)
     for any files included by C source files
@@ -438,17 +432,16 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <literallayout>
-       % <userinput>scons hello</userinput>
-       cc -I. -c hello.c -o hello.o
+       % <userinput>scons -Q hello</userinput>
+       cc -I. -c -o hello.o hello.c
        cc -o hello hello.o
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
        % <userinput>edit hello.h</userinput>
            [CHANGE THE CONTENTS OF hello.h]
-       % <userinput>scons hello</userinput>
-       cc -I. -c hello.c -o hello.o
+       % <userinput>scons -Q hello</userinput>
+       cc -I. -c -o hello.o hello.c
        cc -o hello hello.o
-       %
     </literallayout>
 
     <para>
@@ -490,13 +483,12 @@ operating system on which the build is performed (as reported by C<uname
     (':' on POSIX/Linux, ';' on Windows).
     Either way, &SCons; creates the
     right command-line options
-    so that the followin example:
+    so that the following example:
 
     </para>
 
     <programlisting>
-       env = Environment(CPPPATH = ['include', '/home/project/inc'])
-       hello = env.Program('hello.c')
+       Program('hello.c', CPPPATH = ['include', '/home/project/inc'])
     </programlisting>
 
     <para>
@@ -506,8 +498,8 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <literallayout>
-       % <userinput>scons hello</userinput>
-       cc -Iinclude -I/home/project/inc -c hello.c -o hello.o
+       % <userinput>scons -Q hello</userinput>
+       cc -Iinclude -I/home/project/inc -c -o hello.o hello.c
        cc -o hello hello.o
     </literallayout>
 
@@ -518,9 +510,9 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <literallayout>
-      % <userinput>scons hello</userinput>
-      cl /Iinclude /I\home\project\inc /Fohello.obj hello.c
-      link /OUT:hello.exe hello.obj
+       C:\><userinput>scons -Q hello.exe</userinput>
+       cl /nologo /Iinclude /I\home\project\inc /c hello.c /Fohello.obj
+       link /nologo /OUT:hello.exe hello.obj
     </literallayout>
 
   </section>
@@ -568,49 +560,82 @@ operating system on which the build is performed (as reported by C<uname
     the implicit dependencies
     that its scanners find,
     for use by later builds.
-    You do this either by specifying the
+    You can do this by specifying the
     &implicit-cache; option on the command line:
 
     </para>
 
     <literallayout>
-       % <userinput>scons --implicit-cache hello</userinput>
-       cc -c hello.c -o hello.o
+       % <userinput>scons -Q --implicit-cache hello</userinput>
+       cc -c -o hello.o hello.c
        cc -o hello hello.o
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
     </literallayout>
 
     <para>
 
-    Or by setting the &implicit_cache; option
+    If you don't want to specify &implicit-cache;
+    on the command line each time,
+    you can make it the default behavior for your build
+    by setting the &implicit_cache; option
     in an &SConscript; file:
 
     </para>
 
-    <literallayout>
+    <programlisting>
        SetOption('implicit_cache', 1)
-    </literallayout>
+    </programlisting>
 
-    <para>
+    <!--
 
-    &SCons; does not cache implicit dependencies like this by default
-    because XXX
+    <para>
     
+    XXX
+
     </para>
 
     <para>
-    
-    XXX
 
+    &SCons; does not cache implicit dependencies like this by default
+    because XXX
+    
     </para>
 
+    -->
+
     <section>
     <title>The &implicit-deps-changed; Option</title>
 
       <para>
 
-      XXX
+      When using cached implicit dependencies,
+      sometimes you want to "start fresh"
+      and have &SCons; re-scan the files
+      for which it previously cached the dependencies.
+      For example,
+      if you have recently installed a new version of
+      external code that you use for compilation,
+      the external header files will have changed
+      and the previously-cached implicit dependencies
+      will be out of date.
+      You can update them by
+      running &SCons; with the &implicit-deps-changed; option:
+
+      </para>
+
+      <literallayout>
+         % <userinput>scons -Q --implicit-deps-changed hello</userinput>
+         cc -c -o hello.o hello.c
+         cc -o hello hello.o
+         % <userinput>scons -Q hello</userinput>
+         scons: `hello' is up to date.
+      </literallayout>
+
+      <para>
+
+      In this case, &SCons; will re-scan all of the implicit dependencies
+      and cache updated copies of the information.
 
       </para>
 
@@ -621,7 +646,41 @@ operating system on which the build is performed (as reported by C<uname
 
       <para>
 
-      XXX
+      By default when caching dependencies,
+      &SCons; notices when a file has been modified
+      and re-scans the file for any updated
+      implicit dependency information.
+      Sometimes, however, you may want
+      to force &SCons; to use the cached implicit dependencies, 
+      even if the source files changed.
+      This can speed up a build for example,
+      when you have changed your source files
+      but know that you haven't changed
+      any <literal>#include</literal> lines.
+      In this case,
+      you can use the &implicit-deps-unchanged; option:
+
+      </para>
+
+      <literallayout>
+         % <userinput>scons -Q --implicit-deps-unchanged hello</userinput>
+         cc -c -o hello.o hello.c
+         cc -o hello hello.o
+         % <userinput>scons -Q hello</userinput>
+         scons: `hello' is up to date.
+      </literallayout>
+
+      <para>
+
+      In this case,
+      &SCons; will assume that the cached implicit
+      dependencies are correct and
+      will not bother to re-scan changed files.
+      For typical builds after small,
+      incremental changes to source files,
+      the savings may not be very big,
+      but sometimes every bit of
+      improved performance counts.
 
       </para>
 
@@ -644,23 +703,32 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <programlisting>
-       env = Environment()
-       hello = env.Program('hello.c')
-       env.Ignore(hello, 'hello.h')
+      hello = Program('hello.c')
+      Ignore(hello, 'hello.h')
     </programlisting>
 
     <!-- XXX mention that you can use arrays for target and source? -->
 
+    <!--
+    <scons_output example="ignore">
+      <command>scons -Q hello</command>
+      <command>scons -Q hello</command>
+      <command output="    [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command>
+      <command>scons -Q hello</command>
+      XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX
+    </scons_output>
+    -->
+
     <literallayout>
-       % <userinput>scons hello</userinput>
-       cc -c hello.c -o hello.o
-       cc -o hello hello.o
-       % <userinput>scons hello</userinput>
-       scons: `hello' is up to date.
-       % <userinput>edit hello.h</userinput>
-           [CHANGE THE CONTENTS OF hello.h]
-       % <userinput>scons hello</userinput>
-       scons: `hello' is up to date.
+      % <userinput>scons -Q hello</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
+      % <userinput>edit hello.h</userinput>
+        [CHANGE THE CONTENTS OF hello.h]
+      % <userinput>scons -Q hello</userinput>
+      scons: `hello' is up to date.
     </literallayout>
 
     <para>
@@ -699,7 +767,7 @@ operating system on which the build is performed (as reported by C<uname
 
     On the other hand,
     sometimes a file depends on another file
-    that has no &SCons; scanner will detect.
+    that is not detected by an &SCons; scanner.
     For this situation,
     &SCons; allows you to specific explicitly that one file
     depends on another file,
@@ -717,14 +785,14 @@ operating system on which the build is performed (as reported by C<uname
     <!-- XXX mention that you can use arrays for target and source? -->
 
     <literallayout>
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        cc -c hello.c -o hello.o
        cc -o hello hello.o
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        scons: `hello' is up to date.
        % <userinput>edit other_file</userinput>
            [CHANGE THE CONTENTS OF other_file]
-       % <userinput>scons hello</userinput>
+       % <userinput>scons -Q hello</userinput>
        cc -c hello.c -o hello.o
        cc -o hello hello.o
     </literallayout>
diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in
index 5a34be2..cc059ed 100644
--- a/doc/user/hierarchy.in
+++ b/doc/user/hierarchy.in
@@ -340,7 +340,7 @@ make no difference to the build.
     </para>
 
     <scons_output example="ex1">
-       <command>scons</command>
+       <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -351,8 +351,11 @@ make no difference to the build.
     in multiple directories, like main.c in the above example.
 
     Second, unlike standard recursive use of &Make;,
-    &SCons; stays in the top-level directory and
-    issues commands
+    &SCons; stays in the top-level directory
+    (where the &SConstruct; file lives)
+    and issues commands that use the path names
+    from the top-level directory to the
+    target and source files within the hierarchy.
 
     </para>
 
@@ -375,7 +378,6 @@ make no difference to the build.
     by appending a &hash; (hash mark)
     to the beginning of the path name:
 
-
     </para>
 
     <scons_example name="ex2">
@@ -409,7 +411,7 @@ make no difference to the build.
     </para>
 
     <scons_output example="ex2">
-       <command>scons</command>
+       <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -460,7 +462,7 @@ make no difference to the build.
     </para>
 
     <scons_output example="ex3">
-       <command>scons</command>
+       <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -512,7 +514,7 @@ make no difference to the build.
 
       There are two ways to export a variable,
       such as a construction environment,
-      from one &SConscript; file,
+      from an &SConscript; file,
       so that it may be used by other &SConscript; files.
       First, you can call the &Export;
       function with a list of variables,
@@ -531,7 +533,7 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      You may export more than one variable name at a time:
 
       </para>
 
@@ -543,7 +545,9 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      Because white space is not legal in Python variable names,
+      the &Export; function will even automatically split
+      a string into separate names for you:
 
       </para>
 
@@ -603,7 +607,10 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      Once a variable has been exported from a calling
+      &SConscript; file,
+      it may be used in other &SConscript; files
+      by calling the &Import; function:
 
       </para>
 
@@ -614,7 +621,18 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      The &Import; call makes the <literal>env</literal> construction
+      environment available to the &SConscript; file,
+      after which the variable can be used to build
+      programs, libraries, etc.
+
+      </para>
+
+      <para>
+
+      Like the &Export; function,
+      the &Import; function can be used
+      with multiple variable names:
 
       </para>
 
@@ -626,7 +644,9 @@ make no difference to the build.
 
       <para>
 
-      Which is exactly equivalent to:
+      And the &Import; function will similarly
+      split a string along white-space
+      into separate variable names:
 
       </para>
 
@@ -638,7 +658,24 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      Lastly, as a special case,
+      you may import all of the variables that
+      have been exported by supplying an asterisk
+      to the &Import; function:
+
+      </para>
+
+      <sconstruct>
+        Import('*')
+        env = env.Copy(DEBUG = debug)
+        env.Program('prog', ['prog.c'])
+      </sconstruct>
+
+      <para>
+
+      If you're dealing with a lot of &SConscript; files,
+      this can be a lot simpler than keeping
+      arbitrary lists of imported variables in each file.
 
       </para>
 
@@ -649,35 +686,90 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      Sometimes, you would like to be able to
+      use information from a subsidiary
+      &SConscript file in some way.
+      For example,
+      suppose that you want to create one
+      library from source files
+      scattered throughout a number
+      of subsidiary &SConscript; files.
+      You can do this by using the &Return;
+      function to return values
+      from the subsidiary &SConscript; files
+      to the calling file.
 
       </para>
 
-      <sconstruct>
-        obj = env.Object('foo.c')
-        Return('obj')
-      </sconstruct>
+      <para>
+
+      If, for example, we have two subdirectories
+      &foo; and &bar;
+      that should each contribute a source
+      file to a Library,
+      what we'd like to be able to do is
+      collect the object files
+      from the subsidiary &SConscript; calls
+      like this:
+
+      </para>
+
+      <scons_example name="Return">
+        <file name="SConstruct" printme="1">
+          env = Environment()
+          Export('env')
+          objs = []
+          for subdir in ['foo', 'bar']:
+              o = SConscript('%s/SConscript' % subdir)
+              objs.append(o)
+          env.Library('prog', objs)
+        </file>
+        <directory name="foo"></directory>
+        <directory name="bar"></directory>
+        <file name="foo/SConscript">
+          Import('env')
+          obj = env.Object('foo.c')
+          Return('obj')
+        </file>
+        <file name="bar/SConscript">
+          Import('env')
+          obj = env.Object('bar.c')
+          Return('obj')
+        </file>
+        <file name="foo/foo.c">
+          void foo(void) { printf("foo/foo.c\n"); }
+        </file>
+        <file name="bar/bar.c">
+          void bar(void) { printf("bar/bar.c\n"); }
+        </file>
+      </scons_example>
 
       <para>
 
-      XXX
+      We can do this by using the &Return;
+      function in the
+      <literal>foo/SConscript</literal> file like this:
 
       </para>
 
-      <sconstruct>
-        objs = []
-        for subdir in ['foo', 'bar']:
-            o = SConscript('%s/SConscript' % subdir)
-            objs.append(o)
-        env.Library('prog', objs)
-      </sconstruct>
+      <scons_example_file example="Return" name="foo/SConscript">
+      </scons_example_file>
 
       <para>
 
-      XXX
+      (The corresponding
+      <literal>bar/SConscript</literal>
+      file should be pretty obvious.)
+      Then when we run &SCons;,
+      the object files from the subsidiary subdirectories
+      are all correctly archived in the desired library:
 
       </para>
 
+      <scons_output example="Return">
+        <command>scons -Q</command>
+      </scons_output>
+
     </section>
 
   </section>
diff --git a/doc/user/hierarchy.sgml b/doc/user/hierarchy.sgml
index 24adb56..5db49a8 100644
--- a/doc/user/hierarchy.sgml
+++ b/doc/user/hierarchy.sgml
@@ -290,10 +290,11 @@ make no difference to the build.
 
     </para>
 
+    
     <programlisting>
       env = Environment()
       env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c'])
-    </programlisting>
+      </programlisting>
 
     <para>
 
@@ -301,10 +302,11 @@ make no difference to the build.
 
     </para>
 
+    
     <programlisting>
       env = Environment()
       env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c'])
-    </programlisting>
+      </programlisting>
 
     <para>
 
@@ -314,14 +316,14 @@ make no difference to the build.
     </para>
 
     <literallayout>
-       % <userinput>scons</userinput>
-       cc -c prog1/foo1.c -o prog1/foo1.o
-       cc -c prog1/foo2.c -o prog1/foo2.o
-       cc -c prog1/main.c -o prog1/main.o
+       % <userinput>scons -Q</userinput>
+       cc -c -o prog1/foo1.o prog1/foo1.c
+       cc -c -o prog1/foo2.o prog1/foo2.c
+       cc -c -o prog1/main.o prog1/main.c
        cc -o prog1/prog1 prog1/main.o prog1/foo1.o prog1/foo2.o
-       cc -c prog2/bar1.c -o prog2/bar1.o
-       cc -c prog2/bar2.c -o prog2/bar2.o
-       cc -c prog2/main.c -o prog2/main.o
+       cc -c -o prog2/bar1.o prog2/bar1.c
+       cc -c -o prog2/bar2.o prog2/bar2.c
+       cc -c -o prog2/main.o prog2/main.c
        cc -o prog2/prog2 prog2/main.o prog2/bar1.o prog2/bar2.o
     </literallayout>
 
@@ -333,8 +335,11 @@ make no difference to the build.
     in multiple directories, like main.c in the above example.
 
     Second, unlike standard recursive use of &Make;,
-    &SCons; stays in the top-level directory and
-    issues commands
+    &SCons; stays in the top-level directory
+    (where the &SConstruct; file lives)
+    and issues commands that use the path names
+    from the top-level directory to the
+    target and source files within the hierarchy.
 
     </para>
 
@@ -357,13 +362,12 @@ make no difference to the build.
     by appending a &hash; (hash mark)
     to the beginning of the path name:
 
-
     </para>
 
-    <literallayout>
+    <programlisting>
        env = Environment()
        env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c'])
-    </literallayout>
+    </programlisting>
 
     <para>
 
@@ -377,11 +381,11 @@ make no difference to the build.
     </para>
 
     <literallayout>
-       % <userinput>scons</userinput>
-       cc -c lib/foo1.c -o lib/foo1.o
-       cc -c src/prog/foo2.c -o src/prog/foo2.o
-       cc -c src/prog/main.c -o src/prog/main.o
-       cc -o src/prog/prog prog/main.o lib/foo1.o prog/foo2.o
+       % <userinput>scons -Q</userinput>
+       cc -c -o lib/foo1.o lib/foo1.c
+       cc -c -o src/prog/foo2.o src/prog/foo2.c
+       cc -c -o src/prog/main.o src/prog/main.c
+       cc -o src/prog/prog src/prog/main.o lib/foo1.o src/prog/foo2.o
     </literallayout>
 
     <para>
@@ -406,10 +410,10 @@ make no difference to the build.
 
     </para>
 
-    <literallayout>
+    <programlisting>
        env = Environment()
        env.Program('prog', ['main.c', '/usr/joe/lib/foo1.c', 'foo2.c'])
-    </literallayout>
+    </programlisting>
 
     <para>
 
@@ -418,11 +422,11 @@ make no difference to the build.
     </para>
 
     <literallayout>
-       % <userinput>scons</userinput>
-       cc -c /usr/joe/lib/foo1.c -o /usr/joe/lib/foo1.o
-       cc -c src/prog/foo2.c -o src/prog/foo2.o
-       cc -c src/prog/main.c -o src/prog/main.o
-       cc -o src/prog/prog prog/main.o /usr/joe/lib/foo1.o prog/foo2.o
+       % <userinput>scons -Q</userinput>
+       cc -c -o src/prog/foo2.o src/prog/foo2.c
+       cc -c -o src/prog/main.o src/prog/main.c
+       cc -c -o /usr/joe/lib/foo1.o /usr/joe/lib/foo1.c
+       cc -o src/prog/prog src/prog/main.o /usr/joe/lib/foo1.o src/prog/foo2.o
     </literallayout>
 
     <para>
@@ -474,7 +478,7 @@ make no difference to the build.
 
       There are two ways to export a variable,
       such as a construction environment,
-      from one &SConscript; file,
+      from an &SConscript; file,
       so that it may be used by other &SConscript; files.
       First, you can call the &Export;
       function with a list of variables,
@@ -493,7 +497,7 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      You may export more than one variable name at a time:
 
       </para>
 
@@ -505,7 +509,9 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      Because white space is not legal in Python variable names,
+      the &Export; function will even automatically split
+      a string into separate names for you:
 
       </para>
 
@@ -516,7 +522,7 @@ make no difference to the build.
       <para>
 
       Second, you can specify a list of
-      variables to exported as a second argument
+      variables to export as a second argument
       to the &SConscript; function call:
 
       </para>
@@ -565,7 +571,10 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      Once a variable has been exported from a calling
+      &SConscript; file,
+      it may be used in other &SConscript; files
+      by calling the &Import; function:
 
       </para>
 
@@ -576,7 +585,18 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      The &Import; call makes the <literal>env</literal> construction
+      environment available to the &SConscript; file,
+      after which the variable can be used to build
+      programs, libraries, etc.
+
+      </para>
+
+      <para>
+
+      Like the &Export; function,
+      the &Import; function can be used
+      with multiple variable names:
 
       </para>
 
@@ -588,7 +608,9 @@ make no difference to the build.
 
       <para>
 
-      Which is exactly equivalent to:
+      And the &Import; function will similarly
+      split a string along white-space
+      into separate variable names:
 
       </para>
 
@@ -600,7 +622,24 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      Lastly, as a special case,
+      you may import all of the variables that
+      have been exported by supplying an asterisk
+      to the &Import; function:
+
+      </para>
+
+      <programlisting>
+        Import('*')
+        env = env.Copy(DEBUG = debug)
+        env.Program('prog', ['prog.c'])
+      </programlisting>
+
+      <para>
+
+      If you're dealing with a lot of &SConscript; files,
+      this can be a lot simpler than keeping
+      arbitrary lists of imported variables in each file.
 
       </para>
 
@@ -611,35 +650,78 @@ make no difference to the build.
 
       <para>
 
-      XXX
+      Sometimes, you would like to be able to
+      use information from a subsidiary
+      &SConscript; file in some way.
+      For example,
+      suppose that you want to create one
+      library from source files
+      scattered throughout a number
+      of subsidiary &SConscript; files.
+      You can do this by using the &Return;
+      function to return values
+      from the subsidiary &SConscript; files
+      to the calling file.
+
+      </para>
+
+      <para>
+
+      If, for example, we have two subdirectories
+      &foo; and &bar;
+      that should each contribute a source
+      file to a Library,
+      what we'd like to be able to do is
+      collect the object files
+      from the subsidiary &SConscript; calls
+      like this:
 
       </para>
 
       <programlisting>
-        obj = env.Object('foo.c')
-        Return('obj')
+          env = Environment()
+          Export('env')
+          objs = []
+          for subdir in ['foo', 'bar']:
+              o = SConscript('%s/SConscript' % subdir)
+              objs.append(o)
+          env.Library('prog', objs)
       </programlisting>
 
       <para>
 
-      XXX
+      We can do this by using the &Return;
+      function in the
+      <literal>foo/SConscript</literal> file like this:
 
       </para>
 
+      
       <programlisting>
-        objs = []
-        for subdir in ['foo', 'bar']:
-            o = SConscript('%s/SConscript' % subdir)
-            objs.append(o)
-        env.Library('prog', objs)
-      </programlisting>
+          Import('env')
+          obj = env.Object('foo.c')
+          Return('obj')
+        </programlisting>
 
       <para>
 
-      XXX
+      (The corresponding
+      <literal>bar/SConscript</literal>
+      file should be pretty obvious.)
+      Then when we run &SCons;,
+      the object files from the subsidiary subdirectories
+      are all correctly archived in the desired library:
 
       </para>
 
+      <literallayout>
+        % <userinput>scons -Q</userinput>
+        cc -c -o bar/bar.o bar/bar.c
+        cc -c -o foo/foo.o foo/foo.c
+        ar r libprog.a foo/foo.o bar/bar.o
+        ranlib libprog.a
+      </literallayout>
+
     </section>
 
   </section>
diff --git a/doc/user/main.in b/doc/user/main.in
index 12b0480..e0ae71d 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -100,11 +100,6 @@
     &simple;
   </chapter>
 
-  <chapter id="chap-environments">
-    <title>Construction Environments</title>
-    &environments;
-  </chapter>
-
   <chapter id="chap-libraries">
     <title>Building and Linking with Libraries</title>
     &libraries;
@@ -115,6 +110,11 @@
     &depends;
   </chapter>
 
+  <chapter id="chap-environments">
+    <title>Construction Environments</title>
+    &environments;
+  </chapter>
+
   <chapter id="chap-default">
     <title>Default Targets</title>
     &default;
@@ -150,11 +150,15 @@
     &variants;
   </chapter>
 
+  <!--
+
   <chapter id="chap-builders-built-in">
     <title>Built-In Builders</title>
     &builders-built-in;
   </chapter>
 
+  -->
+
   <chapter id="chap-builders-writing">
     <title>Writing Your Own Builders</title>
     &builders-writing;
@@ -165,11 +169,15 @@
     &builders-commands;
   </chapter>
 
+  <!--
+
   <chapter id="chap-actions">
     <title>SCons Actions</title>
     &actions;
   </chapter>
 
+  -->
+
   <chapter id="chap-scanners">
     <title>Writing Scanners</title>
     &scanners;
@@ -180,11 +188,15 @@
     &repositories;
   </chapter>
 
+  <!--
+
   <chapter id="chap-sourcecode">
     <title>Fetching Files From Source Code Management Systems</title>
     &sourcecode;
   </chapter>
 
+  -->
+
   <chapter id="chap-caching">
     <title>Caching Built Files</title>
     &caching;
@@ -195,6 +207,8 @@
     &alias;
   </chapter>
 
+  <!--
+
   <chapter id="chap-run">
     <title>How to Run &SCons;</title>
     &run;
@@ -205,6 +219,8 @@
     &troubleshoot;
   </chapter>
 
+  -->
+
   <!--
   AddPostAction()
   AddPreAction()
@@ -220,6 +236,8 @@
   Tools()
   -->
 
+  <!--
+
   <appendix id="app-example">
     <title>Complex &SCons; Example</title>
     &example;
@@ -240,4 +258,6 @@
     &ant;
   </appendix>
 
+  -->
+
 </book>
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
index 12b0480..e0ae71d 100644
--- a/doc/user/main.sgml
+++ b/doc/user/main.sgml
@@ -100,11 +100,6 @@
     &simple;
   </chapter>
 
-  <chapter id="chap-environments">
-    <title>Construction Environments</title>
-    &environments;
-  </chapter>
-
   <chapter id="chap-libraries">
     <title>Building and Linking with Libraries</title>
     &libraries;
@@ -115,6 +110,11 @@
     &depends;
   </chapter>
 
+  <chapter id="chap-environments">
+    <title>Construction Environments</title>
+    &environments;
+  </chapter>
+
   <chapter id="chap-default">
     <title>Default Targets</title>
     &default;
@@ -150,11 +150,15 @@
     &variants;
   </chapter>
 
+  <!--
+
   <chapter id="chap-builders-built-in">
     <title>Built-In Builders</title>
     &builders-built-in;
   </chapter>
 
+  -->
+
   <chapter id="chap-builders-writing">
     <title>Writing Your Own Builders</title>
     &builders-writing;
@@ -165,11 +169,15 @@
     &builders-commands;
   </chapter>
 
+  <!--
+
   <chapter id="chap-actions">
     <title>SCons Actions</title>
     &actions;
   </chapter>
 
+  -->
+
   <chapter id="chap-scanners">
     <title>Writing Scanners</title>
     &scanners;
@@ -180,11 +188,15 @@
     &repositories;
   </chapter>
 
+  <!--
+
   <chapter id="chap-sourcecode">
     <title>Fetching Files From Source Code Management Systems</title>
     &sourcecode;
   </chapter>
 
+  -->
+
   <chapter id="chap-caching">
     <title>Caching Built Files</title>
     &caching;
@@ -195,6 +207,8 @@
     &alias;
   </chapter>
 
+  <!--
+
   <chapter id="chap-run">
     <title>How to Run &SCons;</title>
     &run;
@@ -205,6 +219,8 @@
     &troubleshoot;
   </chapter>
 
+  -->
+
   <!--
   AddPostAction()
   AddPreAction()
@@ -220,6 +236,8 @@
   Tools()
   -->
 
+  <!--
+
   <appendix id="app-example">
     <title>Complex &SCons; Example</title>
     &example;
@@ -240,4 +258,6 @@
     &ant;
   </appendix>
 
+  -->
+
 </book>
diff --git a/doc/user/preface.in b/doc/user/preface.in
index 589399d..5e46f0a 100644
--- a/doc/user/preface.in
+++ b/doc/user/preface.in
@@ -60,8 +60,8 @@
   <emphasis>easier</emphasis>
   for non-programmers to learn
   than the cryptic languages of other build tools,
-  which are usally invented by programmers for other programmers.
-  This is in no small part to the
+  which are usually invented by programmers for other programmers.
+  This is in no small part due to the
   consistency and readability that are built in to Python.
   It just so happens that making a real, live
   scripting language the basis for the
@@ -72,6 +72,8 @@
 
   </para>
 
+  <!--
+
   <section>
   <title>Why &SCons;?</title>
 
@@ -94,6 +96,8 @@
 
   </section>
 
+  -->
+
   <section>
   <title>&SCons; Principles</title>
 
@@ -137,7 +141,8 @@
       down the default &SCons; behavior to guarantee a correct build,
       we also try to make it easy to speed up &SCons;
       through optimization options that let you trade off
-      guaranteed correctness for speed.
+      guaranteed correctness in all end cases for
+      a speedier build in the usual cases.
 
       </para>
       </listitem>
@@ -169,6 +174,8 @@
 
   </section>
 
+  <!--
+
   <section>
   <title>History</title>
 
@@ -197,6 +204,8 @@
 
   </section>
 
+  -->
+
   <!--
 
   <section>
@@ -265,7 +274,7 @@
     and time people have contributed over the past few years.
     The "core team"
     of Chad Austin, Anthony Roach, Charles Crain,
-    Steve Leblanc, Greg Spencer and Christoph Wiedemann
+    Steve Leblanc, Gary Oerbrunner, Greg Spencer and Christoph Wiedemann
     have been great about reviewing my (and other) changes
     and catching problems before they get in the code base.
     Of particular technical note:
@@ -282,7 +291,7 @@
     <para>
 
     Special thanks to David Snopek for contributing
-    his underlying "Autocons" code that formed
+    his underlying "Autoscons" code that formed
     the basis of Christoph's work with the Configure functionality.
     David was extremely generous in making
     this code available to &SCons;,
@@ -291,6 +300,8 @@
 
     </para>
 
+    <!--
+
     <para>
 
     &SCons; has received contributions
@@ -308,12 +319,14 @@
     Jeff Petkau (significant fixes for CacheDir and other areas),
     Stefan Reichor (Ghostscript support),
     Zed Shaw (Append() and Replace() environment methods),
-    Terrel Shumway (build and test fixes, as well as the SCons Wiki),
-    sam th (dynamic checks for utilities)
-    and Moshe Zadke (Debian packaging).
+    Terrel Shumway (build and test fixes, as well as the SCons Wiki)
+    and
+    sam th (dynamic checks for utilities).
 
     </para>
 
+    -->
+
     <para>
 
     Thanks to Peter Miller
diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml
index 589399d..390d6a8 100644
--- a/doc/user/preface.sgml
+++ b/doc/user/preface.sgml
@@ -60,8 +60,8 @@
   <emphasis>easier</emphasis>
   for non-programmers to learn
   than the cryptic languages of other build tools,
-  which are usally invented by programmers for other programmers.
-  This is in no small part to the
+  which are usually invented by programmers for other programmers.
+  This is in no small part due to the
   consistency and readability that are built in to Python.
   It just so happens that making a real, live
   scripting language the basis for the
@@ -72,6 +72,8 @@
 
   </para>
 
+  <!--
+
   <section>
   <title>Why &SCons;?</title>
 
@@ -94,13 +96,15 @@
 
   </section>
 
+  -->
+
   <section>
   <title>&SCons; Principles</title>
 
     <para>
 
     There are a few overriding principles
-    we try to live up to in designing and implementing &SCons:
+    we try to live up to in designing and implementing &SCons;:
 
     </para>
 
@@ -137,7 +141,8 @@
       down the default &SCons; behavior to guarantee a correct build,
       we also try to make it easy to speed up &SCons;
       through optimization options that let you trade off
-      guaranteed correctness for speed.
+      guaranteed correctness in all end cases for
+      a speedier build in the usual cases.
 
       </para>
       </listitem>
@@ -169,6 +174,8 @@
 
   </section>
 
+  <!--
+
   <section>
   <title>History</title>
 
@@ -197,6 +204,8 @@
 
   </section>
 
+  -->
+
   <!--
 
   <section>
@@ -265,7 +274,7 @@
     and time people have contributed over the past few years.
     The "core team"
     of Chad Austin, Anthony Roach, Charles Crain,
-    Steve Leblanc, Greg Spencer and Christoph Wiedemann
+    Steve Leblanc, Gary Oerbrunner, Greg Spencer and Christoph Wiedemann
     have been great about reviewing my (and other) changes
     and catching problems before they get in the code base.
     Of particular technical note:
@@ -282,7 +291,7 @@
     <para>
 
     Special thanks to David Snopek for contributing
-    his underlying "Autocons" code that formed
+    his underlying "Autoscons" code that formed
     the basis of Christoph's work with the Configure functionality.
     David was extremely generous in making
     this code available to &SCons;,
@@ -291,6 +300,8 @@
 
     </para>
 
+    <!--
+
     <para>
 
     &SCons; has received contributions
@@ -308,12 +319,14 @@
     Jeff Petkau (significant fixes for CacheDir and other areas),
     Stefan Reichor (Ghostscript support),
     Zed Shaw (Append() and Replace() environment methods),
-    Terrel Shumway (build and test fixes, as well as the SCons Wiki),
-    sam th (dynamic checks for utilities)
-    and Moshe Zadke (Debian packaging).
+    Terrel Shumway (build and test fixes, as well as the SCons Wiki)
+    and
+    sam th (dynamic checks for utilities).
 
     </para>
 
+    -->
+
     <para>
 
     Thanks to Peter Miller
@@ -365,7 +378,7 @@
 
     <para>
 
-    If you want to receive announcements about &SCons,
+    If you want to receive announcements about &SCons;,
     join the low-volume &scons-announce; mailing list.
 
     </para>
diff --git a/doc/user/repositories.in b/doc/user/repositories.in
index c155617..480ea3f 100644
--- a/doc/user/repositories.in
+++ b/doc/user/repositories.in
@@ -219,7 +219,7 @@ subdirectories under the repository tree.
     and next under the <filename>/usr/repository2</filename> tree.
     &SCons; expects that any files it searches
     for will be found in the same position
-    relative to the top-level directory XXX
+    relative to the top-level directory.
     In the above example, if the &hello_c; file is not
     found in the local build tree,
     &SCons; will search first for
@@ -240,7 +240,7 @@ subdirectories under the repository tree.
     </para>
 
     <scons_output example="ex1">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -264,7 +264,7 @@ subdirectories under the repository tree.
     </scons_example>
 
     <scons_output example="ex2">
-      <command>scons</command>
+      <command>scons -Q</command>
       gcc -c /usr/repository1/hello.c -o hello.o
       gcc -o hello hello.o
     </scons_output>
@@ -289,7 +289,7 @@ subdirectories under the repository tree.
     </scons_example>
 
     <scons_output example="ex3">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -316,7 +316,7 @@ subdirectories under the repository tree.
     </para>
 
     <literallayout>
-      % <userinput>scons -Y /usr/repository1 -Y /usr/repository2</userinput>
+      % <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput>
     </literallayout>
 
     <para>
@@ -361,20 +361,24 @@ subdirectories under the repository tree.
     <scons_example name="ex4">
       <file name="SConstruct">
        env = Environment()
-       env.Program('hello.c')
+       env.Program(['hello.c', 'file1.c', 'file2.c'])
        Repository('/usr/repository1', '/usr/repository2')
       </file>
       <file name="hello.c">
       int main() { printf("Hello, world!\n"); }
       </file>
+      <file name="file1.c">
+      int f1() { printf("file1\n"); }
+      </file>
+      <file name="file2.c">
+      int f2() { printf("file2.c\n"); }
+      </file>
     </scons_example>
 
-    <literallayout>
-      % <userinput>cd /usr/repository1</userinput>
-      % <userinput>scons</userinput>
-      gcc -c hello.c -o hello.o
-      gcc -o hello hello.o
-    </literallayout>
+    <scons_output example="ex4">
+      <command>cd /usr/repository1</command>
+      <command>scons -Q</command>
+    </scons_output>
 
     <para>
     
@@ -396,20 +400,26 @@ subdirectories under the repository tree.
 
     </para>
 
+    <!--
+    <scons_output example="ex4">
+      <command>cd $HOME/build</command>
+      <command>edit hello.c</command>
+      <command>scons -Q -Y __ROOT__/usr/repository1</command>
+    </scons_output>
+    -->
     <literallayout>
       % <userinput>cd $HOME/build</userinput>
       % <userinput>edit hello.c</userinput>
-      % <userinput>scons -Y /usr/repository1</userinput>
-      gcc -c hello.c -o hello.o
-      gcc -o hello hello.o
-      XXXXXXX
+      % <userinput>scons -Q -Y /usr/repository1</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o
     </literallayout>
 
     <para>
 
     Notice that &SCons; realizes that it does not need to
-    rebuild a local XXX.o file,
-    but instead uses the already-compiled XXX.o file
+    rebuild local copies file1.o and file2.o files,
+    but instead uses the already-compiled files
     from the repository.
 
     </para>
@@ -431,7 +441,7 @@ subdirectories under the repository tree.
     <literallayout>
       % <userinput>mkdir $HOME/build2</userinput>
       % <userinput>cd $HOME/build2</userinput>
-      % <userinput>scons -Y /usr/all/repository hello</userinput>
+      % <userinput>scons -Q -Y /usr/all/repository hello</userinput>
       scons: `hello' is up-to-date.
     </literallayout>
 
@@ -460,7 +470,7 @@ subdirectories under the repository tree.
 
     </para>
 
-    <scons_example name="ex1">
+    <scons_example name="ex5">
       <file name="SConstruct" printme="1">
        env = Environment()
        hello = env.Program('hello.c')
@@ -484,7 +494,6 @@ subdirectories under the repository tree.
       % scons -Y /usr/all/repository hello
       Local copy of hello from /usr/all/repository/hello
       scons: `hello' is up-to-date.
-      XXXXXX DO WE REALLY REPORT up-to-date, TOO?
     </literallayout>
 
     <para>
@@ -492,7 +501,6 @@ subdirectories under the repository tree.
     (Notice that, because the act of making the local copy
     is not considered a "build" of the &hello; file,
     &SCons; still reports that it is up-to-date.)
-    XXXXXX DO WE REALLY REPORT up-to-date, TOO?
 
     </para>
 
diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml
index 07af115..fdb8b5b 100644
--- a/doc/user/repositories.sgml
+++ b/doc/user/repositories.sgml
@@ -214,7 +214,7 @@ subdirectories under the repository tree.
     and next under the <filename>/usr/repository2</filename> tree.
     &SCons; expects that any files it searches
     for will be found in the same position
-    relative to the top-level directory XXX
+    relative to the top-level directory.
     In the above example, if the &hello_c; file is not
     found in the local build tree,
     &SCons; will search first for
@@ -235,9 +235,9 @@ subdirectories under the repository tree.
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      gcc -c hello.c -o hello.o
-      gcc -o hello hello.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o
     </literallayout>
 
     <para>
@@ -249,8 +249,12 @@ subdirectories under the repository tree.
 
     </para>
 
+    
+
     <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o
       gcc -c /usr/repository1/hello.c -o hello.o
       gcc -o hello hello.o
     </literallayout>
@@ -263,10 +267,12 @@ subdirectories under the repository tree.
 
     </para>
 
+    
+
     <literallayout>
-      % <userinput>scons</userinput>
-      gcc -c /usr/repository2/hello.c -o hello.o
-      gcc -o hello hello.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o
     </literallayout>
 
     <para>
@@ -293,7 +299,7 @@ subdirectories under the repository tree.
     </para>
 
     <literallayout>
-      % <userinput>scons -Y /usr/repository1 -Y /usr/repository2</userinput>
+      % <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput>
     </literallayout>
 
     <para>
@@ -335,11 +341,15 @@ subdirectories under the repository tree.
 
     </para>
 
+    
+
     <literallayout>
       % <userinput>cd /usr/repository1</userinput>
-      % <userinput>scons</userinput>
-      gcc -c hello.c -o hello.o
-      gcc -o hello hello.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o file1.o file1.c
+      cc -c -o file2.o file2.c
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o file1.o file2.o
     </literallayout>
 
     <para>
@@ -362,20 +372,26 @@ subdirectories under the repository tree.
 
     </para>
 
+    <!--
+    <scons_output example="ex4">
+      <command>cd $HOME/build</command>
+      <command>edit hello.c</command>
+      <command>scons -Q -Y __ROOT__/usr/repository1</command>
+    </scons_output>
+    -->
     <literallayout>
       % <userinput>cd $HOME/build</userinput>
       % <userinput>edit hello.c</userinput>
-      % <userinput>scons -Y /usr/repository1</userinput>
-      gcc -c hello.c -o hello.o
-      gcc -o hello hello.o
-      XXXXXXX
+      % <userinput>scons -Q -Y /usr/repository1</userinput>
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o
     </literallayout>
 
     <para>
 
     Notice that &SCons; realizes that it does not need to
-    rebuild a local XXX.o file,
-    but instead uses the already-compiled XXX.o file
+    rebuild local copies file1.o and file2.o files,
+    but instead uses the already-compiled files
     from the repository.
 
     </para>
@@ -397,7 +413,7 @@ subdirectories under the repository tree.
     <literallayout>
       % <userinput>mkdir $HOME/build2</userinput>
       % <userinput>cd $HOME/build2</userinput>
-      % <userinput>scons -Y /usr/all/repository hello</userinput>
+      % <userinput>scons -Q -Y /usr/all/repository hello</userinput>
       scons: `hello' is up-to-date.
     </literallayout>
 
@@ -445,7 +461,6 @@ subdirectories under the repository tree.
       % scons -Y /usr/all/repository hello
       Local copy of hello from /usr/all/repository/hello
       scons: `hello' is up-to-date.
-      XXXXXX DO WE REALLY REPORT up-to-date, TOO?
     </literallayout>
 
     <para>
@@ -453,7 +468,6 @@ subdirectories under the repository tree.
     (Notice that, because the act of making the local copy
     is not considered a "build" of the &hello; file,
     &SCons; still reports that it is up-to-date.)
-    XXXXXX DO WE REALLY REPORT up-to-date, TOO?
 
     </para>
 
diff --git a/doc/user/scanners.in b/doc/user/scanners.in
index 76b2a1a..fe409ad 100644
--- a/doc/user/scanners.in
+++ b/doc/user/scanners.in
@@ -121,19 +121,211 @@ over the file scanning rather than being called for each input line:
 
 -->
 
- <para>
+  <para>
 
-   XXX
+    &SCons; has built-in scanners that know how to look in
+    C, Fortran and IDL source files for information about
+    other files that targets built from those files depend on--for example,
+    in the case of files that use the C preprocessor,
+    the <filename>.h</filename> files that are specified
+    using <literal>#include</literal> lines in the source.
+    You can use the same mechanisms that &SCons; uses to create
+    its built-in scanners to write scanners of your own for file types
+    that &SCons; does not know how to scan "out of the box."
+
+  </para>
 
- </para>
+  <section>
+  <title>A Simple Scanner Example</title>
 
- <section>
- <title>XXX</title>
+    <para>
 
-   <para>
+      Suppose, for example, that we want to create a simple scanner
+      for <filename>.foo</filename> files.
+      A <filename>.foo</filename> file contains some text that
+      will be processed,
+      and can include other files on lines that begin
+      with <literal>include</literal>
+      followed by a file name:
 
-   XXX
+    </para>
 
-   </para>
+    <programlisting>
+      include filename.foo
+    </programlisting>
 
- </section>
+    <para>
+
+      Scanning a file will be handled by a Python function
+      that you must supply.
+      Here is a function that will use the Python
+      <filename>re</filename> module
+      to scan for the <literal>include</literal> lines in our example:
+
+    </para>
+
+    <programlisting>
+      import re
+      
+      include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
+      
+      def kfile_scan(node, env, path, arg):
+          contents = node.get_contents()
+          return include_re.findall(contents)
+    </programlisting>
+
+    <para>
+
+      The scanner function must
+      accept the four specified arguments
+      and return a list of implicit dependencies.
+      Presumably, these would be dependencies found
+      from examining the contents of the file,
+      although the function can perform any
+      manipulation at all to generate the list of
+      dependencies.
+
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+      <term>node</term>
+
+      <listitem>
+      <para>
+
+      An &SCons; node object representing the file being scanned.
+      The path name to the file can be
+      used by converting the node to a string
+      using the <literal>str()</literal> function,
+      or an internal &SCons; <literal>get_contents()</literal>
+      object method can be used to fetch the contents.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>env</term>
+
+      <listitem>
+      <para>
+
+      The construction environment in effect for this scan.
+      The scanner function may choose to use construction
+      variables from this environment to affect its behavior.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>path</term>
+
+      <listitem>
+      <para>
+
+      A list of directories that form the search path for included files
+      for this scanner.
+      This is how &SCons; handles the &CPPPATH; and &LIBPATH;
+      variables.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>arg</term>
+
+      <listitem>
+      <para>
+
+      An optional argument that you can choose to
+      have passed to this scanner function by
+      various scanner instances.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+
+    A Scanner object is created using the &Scanner; function,
+    which typically takes an <literal>skeys</literal> argument
+    to associate the type of file suffix with this scanner.
+    The Scanner object must then be associated with the
+    &SCANNERS; construction variable of a construction environment,
+    typically by using the &Append; method:
+
+    </para>
+
+    <programlisting>
+       kscan = Scanner(function = kfile_scan,
+                       skeys = ['.k'])
+       env.Append(SCANNERS = kscan)
+    </programlisting>
+
+    <para>
+
+    When we put it all together, it looks like:
+
+    </para>
+
+    <scons_example name="scan">
+      <file name="SConstruct" printme="1">
+        import re
+
+        include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
+
+        def kfile_scan(node, env, path):
+            contents = node.get_contents()
+            includes = include_re.findall(contents)
+            return includes
+
+        kscan = Scanner(function = kfile_scan,
+                        skeys = ['.k'])
+
+        env = Environment(ENV = {'PATH' : '__ROOT__/usr/local/bin'})
+        env.Append(SCANNERS = kscan)
+
+        env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
+      </file>
+      <file name="foo.k">
+      include other_file
+      </file>
+      <file name="other_file">
+      other_file
+      </file>
+      <directory name="__ROOT__/usr"></directory>
+      <directory name="__ROOT__/usr/local"></directory>
+      <directory name="__ROOT__/usr/local/bin"></directory>
+      <file name="__ROOT_/usr/local/bin/kprocess" chmod="755">
+      cat
+      </file>
+    </scons_example>
+
+    <!--
+
+    <para>
+
+      Now if we run &scons;
+      and then re-run it after changing the contents of
+      <filename>other_file</filename>,
+      the <filename>foo</filename>
+      target file will be automatically rebuilt:
+
+    </para>
+
+    <scons_output example="scan">
+      <command>scons -Q</command>
+      <command output="    [CHANGE THE CONTENTS OF other_file]">edit other_file</command>
+      <command>scons -Q</command>
+      <command>scons -Q</command>
+    </scons_output>
+
+    -->
+
+  </section>
diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml
index 76b2a1a..23cd044 100644
--- a/doc/user/scanners.sgml
+++ b/doc/user/scanners.sgml
@@ -121,19 +121,197 @@ over the file scanning rather than being called for each input line:
 
 -->
 
- <para>
+  <para>
 
-   XXX
+    &SCons; has built-in scanners that know how to look in
+    C, Fortran and IDL source files for information about
+    other files that targets built from those files depend on--for example,
+    in the case of files that use the C preprocessor,
+    the <filename>.h</filename> files that are specified
+    using <literal>#include</literal> lines in the source.
+    You can use the same mechanisms that &SCons; uses to create
+    its built-in scanners to write scanners of your own for file types
+    that &SCons; does not know how to scan "out of the box."
+
+  </para>
 
- </para>
+  <section>
+  <title>A Simple Scanner Example</title>
 
- <section>
- <title>XXX</title>
+    <para>
 
-   <para>
+      Suppose, for example, that we want to create a simple scanner
+      for <filename>.foo</filename> files.
+      A <filename>.foo</filename> file contains some text that
+      will be processed,
+      and can include other files on lines that begin
+      with <literal>include</literal>
+      followed by a file name:
 
-   XXX
+    </para>
 
-   </para>
+    <programlisting>
+      include filename.foo
+    </programlisting>
 
- </section>
+    <para>
+
+      Scanning a file will be handled by a Python function
+      that you must supply.
+      Here is a function that will use the Python
+      <filename>re</filename> module
+      to scan for the <literal>include</literal> lines in our example:
+
+    </para>
+
+    <programlisting>
+      import re
+      
+      include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
+      
+      def kfile_scan(node, env, path, arg):
+          contents = node.get_contents()
+          return include_re.findall(contents)
+    </programlisting>
+
+    <para>
+
+      The scanner function must
+      accept the four specified arguments
+      and return a list of implicit dependencies.
+      Presumably, these would be dependencies found
+      from examining the contents of the file,
+      although the function can perform any
+      manipulation at all to generate the list of
+      dependencies.
+
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+      <term>node</term>
+
+      <listitem>
+      <para>
+
+      An &SCons; node object representing the file being scanned.
+      The path name to the file can be
+      used by converting the node to a string
+      using the <literal>str()</literal> function,
+      or an internal &SCons; <literal>get_contents()</literal>
+      object method can be used to fetch the contents.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>env</term>
+
+      <listitem>
+      <para>
+
+      The construction environment in effect for this scan.
+      The scanner function may choose to use construction
+      variables from this environment to affect its behavior.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>path</term>
+
+      <listitem>
+      <para>
+
+      A list of directories that form the search path for included files
+      for this scanner.
+      This is how &SCons; handles the &CPPPATH; and &LIBPATH;
+      variables.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>arg</term>
+
+      <listitem>
+      <para>
+
+      An optional argument that you can choose to
+      have passed to this scanner function by
+      various scanner instances.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+
+    A Scanner object is created using the &Scanner; function,
+    which typically takes an <literal>skeys</literal> argument
+    to associate the type of file suffix with this scanner.
+    The Scanner object must then be associated with the
+    &SCANNERS; construction variable of a construction environment,
+    typically by using the &Append; method:
+
+    </para>
+
+    <programlisting>
+       kscan = Scanner(function = kfile_scan,
+                       skeys = ['.k'])
+       env.Append(SCANNERS = kscan)
+    </programlisting>
+
+    <para>
+
+    When we put it all together, it looks like:
+
+    </para>
+
+    <programlisting>
+        import re
+
+        include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
+
+        def kfile_scan(node, env, path):
+            contents = node.get_contents()
+            includes = include_re.findall(contents)
+            return includes
+
+        kscan = Scanner(function = kfile_scan,
+                        skeys = ['.k'])
+
+        env = Environment(ENV = {'PATH' : '/usr/local/bin'})
+        env.Append(SCANNERS = kscan)
+
+        env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
+    </programlisting>
+
+    <!--
+
+    <para>
+
+      Now if we run &scons;
+      and then re-run it after changing the contents of
+      <filename>other_file</filename>,
+      the <filename>foo</filename>
+      target file will be automatically rebuilt:
+
+    </para>
+
+    <scons_output example="scan">
+      <command>scons -Q</command>
+      <command output="    [CHANGE THE CONTENTS OF other_file]">edit other_file</command>
+      <command>scons -Q</command>
+      <command>scons -Q</command>
+    </scons_output>
+
+    -->
+
+  </section>
diff --git a/doc/user/separate.in b/doc/user/separate.in
index c1b3c32..1b24edf 100644
--- a/doc/user/separate.in
+++ b/doc/user/separate.in
@@ -132,38 +132,37 @@ program using the F<build/foo.c> path name.
 
     The most straightforward way to establish a build directory
     uses the fact that the usual way to
-    set up a build hierarcy is to have an
+    set up a build hierarchy is to have an
     &SConscript; file in the source subdirectory.
     If you then pass a &build_dir; argument to the
     &SConscript; function call:
 
     </para>
 
-    <sconstruct>
-      SConscript('src/SConscript', build_dir='build')
-    </sconstruct>
-
-    <para>
-
-    &SCons; will then build all of the files in
-    the &build; subdirectory:
-
-    </para>
-
     <scons_example name="ex1">
       <file name="SConstruct" printme="1">
+      SConscript('src/SConscript', build_dir='build')
+      </file>
+      <file name="src/SConscript">
       env = Environment()
       env.Program('hello.c')
       </file>
-      <file name="hello.c">
+      <file name="src/hello.c">
       int main() { printf("Hello, world!\n"); }
       </file>
     </scons_example>
 
+    <para>
+
+    &SCons; will then build all of the files in
+    the &build; subdirectory:
+
+    </para>
+
     <scons_output example="ex1">
-      <command>ls -1 src</command>
-      <command>scons</command>
-      <command>ls -1 build</command>
+      <command>ls src</command>
+      <command>scons -Q</command>
+      <command>ls build</command>
     </scons_output>
 
     <para>
@@ -199,48 +198,88 @@ program using the F<build/foo.c> path name.
 
     &SCons; duplicates source files in build directories
     because it's the most straightforward way to guarantee a correct build
-     <emphasis>regardless of include-file directory paths</emphasis>,
+    <emphasis>regardless of include-file directory paths,
+    relative references between files,
+    or tool support for putting files in different locations</emphasis>,
     and the &SCons; philosophy is to, by default,
     guarantee a correct build in all cases.
-    Here is an example of an end case where duplicating
-    source files in a build directory
-    is necessary for a correct build:
 
     </para>
 
     <para>
 
-    XXX
+    The most direct reason to duplicate source files
+    in build directories
+    is simply that some tools (mostly older vesions)
+    are written to only build their output files
+    in the same directory as the source files.
+    In this case, the choices are either
+    to build the output file in the source directory
+    and move it to the build directory,
+    or to duplicate the source files in the build directory.
+
+    </para>
+
+    <para>
+
+    Additionally,
+    relative references between files
+    can cause problems if we don't
+    just duplicate the hierarchy of source files
+    in the build directory.
+    You can see this at work in
+    use of the C preprocessor <literal>#include</literal>
+    mechanism with double quotes, not angle brackets:
 
     </para>
 
     <sconstruct>
-      env = Environmnet()
+      #include "file.h"
     </sconstruct>
 
     <para>
 
-    XXX
+    The <emphasis>de facto</emphasis> standard behavior
+    for most C compilers in this case
+    is to first look in the same directory
+    as the source file that contains the <literal>#include</literal> line,
+    then to look in the directories in the preprocessor search path.
+    Add to this that the &SCons; implementation of
+    support for code repositories
+    (described below)
+    means not all of the files
+    will be found in the same directory hierarchy,
+    and the simplest way to make sure
+    that the right include file is found
+    is to duplicate the source files into the build directory,
+    which provides a correct build
+    regardless of the original location(s) of the source files.
 
     </para>
 
-    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c build/hello.c -o build/hello.o
-      cc -o build/hello build/hello.o
-    </literallayout>
+    <para>
 
-  </section>
+    Although source-file duplication guarantees a correct build
+    even in these end-cases,
+    it <emphasis>can</emphasis> usually be safely disabled.
+    The next section describes
+    how you can disable the duplication of source files
+    in the build directory.
+
+    </para>
+
+  </section> 
 
   <section>
   <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title>
 
     <para>
 
-    In most cases, however,
-    having &SCons; place its target files in a build subdirectory
+    In most cases and with most tool sets,
+    &SCons; can place its target files in a build subdirectory
     <emphasis>without</emphasis>
-    duplicating the source files works just fine.
+    duplicating the source files
+    and everything will work just fine.
     You can disable the default &SCons; behavior
     by specifying <literal>duplicate=0</literal>
     when you call the &SConscript; function:
@@ -262,13 +301,13 @@ program using the F<build/foo.c> path name.
     </para>
 
     <literallayout>
-      % <userinput>ls -1 src</userinput>
+      % <userinput>ls src</userinput>
       SConscript
       hello.c
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       cc -c src/hello.c -o build/hello.o
       cc -o build/hello build/hello.o
-      % <userinput>ls -1 build</userinput>
+      % <userinput>ls build</userinput>
       hello
       hello.o
     </literallayout>
@@ -311,12 +350,6 @@ program using the F<build/foo.c> path name.
 
     <para>
 
-    XXX
-
-    </para>
-
-    <para>
-
     When using the &BuildDir; function directly,
     &SCons; still duplicates the source files
     in the build directory by default:
@@ -325,8 +358,8 @@ program using the F<build/foo.c> path name.
 
     <scons_output example="ex_builddir">
       <command>ls src</command>
-      <command>scons</command>
-      <command>ls -1 build</command>
+      <command>scons -Q</command>
+      <command>ls build</command>
     </scons_output>
 
     <para>
@@ -356,8 +389,8 @@ program using the F<build/foo.c> path name.
 
     <scons_output example="ex_duplicate_0">
       <command>ls src</command>
-      <command>scons</command>
-      <command>ls -1 build</command>
+      <command>scons -Q</command>
+      <command>ls build</command>
     </scons_output>
 
   </section>
@@ -377,22 +410,26 @@ program using the F<build/foo.c> path name.
     </para>
 
     <scons_example name="example_builddir_sconscript">
-      <file name="SConstruct" printme="1">
+      <file name="SConstruct">
+      BuildDir('build', 'src')
+      SConscript('build/SConscript')
+      </file>
+      <file name="src/SConscript" printme="1">
       env = Environment()
       env.Program('hello.c')
       </file>
-      <file name="SConscript">
-      BuildDir('build', 'src')
-      SConscript('build/SConscript')
+      <file name="src/hello.c">
+      int main() { printf("Hello, world!\n"); }
+      </file>
     </scons_example>
 
     <para>
 
-    Then our &SConscript; file could look like:
+    Then our &SConstruct; file could look like:
 
     </para>
 
-    <scons_example_file example="example_builddir_sconscript" name="SConscript">
+    <scons_example_file example="example_builddir_sconscript" name="SConstruct">
     </scons_example_file>
 
     <para>
@@ -402,9 +439,9 @@ program using the F<build/foo.c> path name.
     </para>
 
     <scons_output example="example_builddir_sconscript">
-      <command>ls -1 src</command>
-      <command>scons</command>
-      <command>ls -1 build</command>
+      <command>ls src</command>
+      <command>scons -Q</command>
+      <command>ls build</command>
     </scons_output>
 
     <para>
@@ -417,6 +454,8 @@ program using the F<build/foo.c> path name.
 
   </section>
 
+  <!--
+
   <section>
   <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title>
 
@@ -427,3 +466,5 @@ program using the F<build/foo.c> path name.
     </para>
 
   </section>
+
+  -->
diff --git a/doc/user/separate.sgml b/doc/user/separate.sgml
index ac3c0f3..b00be1a 100644
--- a/doc/user/separate.sgml
+++ b/doc/user/separate.sgml
@@ -132,7 +132,7 @@ program using the F<build/foo.c> path name.
 
     The most straightforward way to establish a build directory
     uses the fact that the usual way to
-    set up a build hierarcy is to have an
+    set up a build hierarchy is to have an
     &SConscript; file in the source subdirectory.
     If you then pass a &build_dir; argument to the
     &SConscript; function call:
@@ -151,16 +151,13 @@ program using the F<build/foo.c> path name.
     </para>
 
     <literallayout>
-      % <userinput>ls -1 src</userinput>
-      SConscript
-      hello.c
-      % <userinput>scons</userinput>
-      cc -c build/hello.c -o build/hello.o
+      % <userinput>ls src</userinput>
+      SConscript  hello.c
+      % <userinput>scons -Q</userinput>
+      cc -c -o build/hello.o build/hello.c
       cc -o build/hello build/hello.o
-      % <userinput>ls -1 build</userinput>
-      hello
-      hello.c
-      hello.o
+      % <userinput>ls build</userinput>
+      SConscript  hello  hello.c  hello.o
     </literallayout>
 
     <para>
@@ -196,48 +193,88 @@ program using the F<build/foo.c> path name.
 
     &SCons; duplicates source files in build directories
     because it's the most straightforward way to guarantee a correct build
-     <emphasis>regardless of include-file directory paths</emphasis>,
+    <emphasis>regardless of include-file directory paths,
+    relative references between files,
+    or tool support for putting files in different locations</emphasis>,
     and the &SCons; philosophy is to, by default,
     guarantee a correct build in all cases.
-    Here is an example of an end case where duplicating
-    source files in a build directory
-    is necessary for a correct build:
 
     </para>
 
     <para>
 
-    XXX
+    The most direct reason to duplicate source files
+    in build directories
+    is simply that some tools (mostly older vesions)
+    are written to only build their output files
+    in the same directory as the source files.
+    In this case, the choices are either
+    to build the output file in the source directory
+    and move it to the build directory,
+    or to duplicate the source files in the build directory.
+
+    </para>
+
+    <para>
+
+    Additionally,
+    relative references between files
+    can cause problems if we don't
+    just duplicate the hierarchy of source files
+    in the build directory.
+    You can see this at work in
+    use of the C preprocessor <literal>#include</literal>
+    mechanism with double quotes, not angle brackets:
 
     </para>
 
     <programlisting>
-      env = Environmnet()
+      #include "file.h"
     </programlisting>
 
     <para>
 
-    XXX
+    The <emphasis>de facto</emphasis> standard behavior
+    for most C compilers in this case
+    is to first look in the same directory
+    as the source file that contains the <literal>#include</literal> line,
+    then to look in the directories in the preprocessor search path.
+    Add to this that the &SCons; implementation of
+    support for code repositories
+    (described below)
+    means not all of the files
+    will be found in the same directory hierarchy,
+    and the simplest way to make sure
+    that the right include file is found
+    is to duplicate the source files into the build directory,
+    which provides a correct build
+    regardless of the original location(s) of the source files.
 
     </para>
 
-    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c build/hello.c -o build/hello.o
-      cc -o build/hello build/hello.o
-    </literallayout>
+    <para>
 
-  </section>
+    Although source-file duplication guarantees a correct build
+    even in these end-cases,
+    it <emphasis>can</emphasis> usually be safely disabled.
+    The next section describes
+    how you can disable the duplication of source files
+    in the build directory.
+
+    </para>
+
+  </section> 
 
   <section>
   <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title>
 
     <para>
 
-    In most cases, however,
-    having &SCons; place its target files in a build subdirectory
+    In most cases and with most tool sets,
+    &SCons; can place its target files in a build subdirectory
     <emphasis>without</emphasis>
-    duplicating the source files works just fine.
+    duplicating the source files
+    and everything will work just fine.
     You can disable the default &SCons; behavior
     by specifying <literal>duplicate=0</literal>
     when you call the &SConscript; function:
@@ -259,13 +296,13 @@ program using the F<build/foo.c> path name.
     </para>
 
     <literallayout>
-      % <userinput>ls -1 src</userinput>
+      % <userinput>ls src</userinput>
       SConscript
       hello.c
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       cc -c src/hello.c -o build/hello.o
       cc -o build/hello build/hello.o
-      % <userinput>ls -1 build</userinput>
+      % <userinput>ls build</userinput>
       hello
       hello.o
     </literallayout>
@@ -303,12 +340,6 @@ program using the F<build/foo.c> path name.
 
     <para>
 
-    XXX
-
-    </para>
-
-    <para>
-
     When using the &BuildDir; function directly,
     &SCons; still duplicates the source files
     in the build directory by default:
@@ -318,13 +349,11 @@ program using the F<build/foo.c> path name.
     <literallayout>
       % <userinput>ls src</userinput>
       hello.c
-      % <userinput>scons</userinput>
-      cc -c build/hello.c -o build/hello.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o build/hello.o build/hello.c
       cc -o build/hello build/hello.o
-      % <userinput>ls -1 build</userinput>
-      hello
-      hello.c
-      hello.o
+      % <userinput>ls build</userinput>
+      hello  hello.c  hello.o
     </literallayout>
 
     <para>
@@ -350,12 +379,11 @@ program using the F<build/foo.c> path name.
     <literallayout>
       % <userinput>ls src</userinput>
       hello.c
-      % <userinput>scons</userinput>
-      cc -c src/hello.c -o build/hello.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o build/hello.o src/hello.c
       cc -o build/hello build/hello.o
-      % <userinput>ls -1 build</userinput>
-      hello
-      hello.o
+      % <userinput>ls build</userinput>
+      hello  hello.o
     </literallayout>
 
   </section>
@@ -381,14 +409,15 @@ program using the F<build/foo.c> path name.
 
     <para>
 
-    Then our &SConscript; file could look like:
+    Then our &SConstruct; file could look like:
 
     </para>
 
+    
     <programlisting>
       BuildDir('build', 'src')
       SConscript('build/SConscript')
-    </programlisting>
+      </programlisting>
 
     <para>
 
@@ -397,16 +426,13 @@ program using the F<build/foo.c> path name.
     </para>
 
     <literallayout>
-      % <userinput>ls -1 src</userinput>
-      SConscript
-      hello.c
-      % <userinput>scons</userinput>
-      cc -c build/hello.c -o build/hello.o
+      % <userinput>ls src</userinput>
+      SConscript  hello.c
+      % <userinput>scons -Q</userinput>
+      cc -c -o build/hello.o build/hello.c
       cc -o build/hello build/hello.o
-      % <userinput>ls -1 build</userinput>
-      hello
-      hello.c
-      hello.o
+      % <userinput>ls build</userinput>
+      SConscript  hello  hello.c  hello.o
     </literallayout>
 
     <para>
@@ -419,6 +445,8 @@ program using the F<build/foo.c> path name.
 
   </section>
 
+  <!--
+
   <section>
   <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title>
 
@@ -429,3 +457,5 @@ program using the F<build/foo.c> path name.
     </para>
 
   </section>
+
+  -->
diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in
index b794c09..30b6ecb 100644
--- a/doc/user/sourcecode.in
+++ b/doc/user/sourcecode.in
@@ -29,7 +29,7 @@
 
  <para>
 
-   X
+   XXX
 
  </para>
 
@@ -38,20 +38,23 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
    <scons_example name="ex_bitkeeper">
       <file name="SConstruct" printme="1">
       env = Environment()
-      env.SourceCode('.', env.BitKeeper('XXX'))
+      env.SourceCode('.', env.BitKeeper())
       env.Program('hello.c')
       </file>
+      <file name="s.hello.c">
+      s.hello.c
+      </file>
    </scons_example>
 
    <scons_output example="ex_bitkeeper">
-     <userinput>scons</userinput>
+     <command>scons -Q</command>
    </scons_output>
 
  </section>
@@ -61,20 +64,20 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
    <scons_example name="ex_cvs">
       <file name="SConstruct" printme="1">
       env = Environment()
-      env.SourceCode('.', env.CVS('XXX'))
+      env.SourceCode('.', env.CVS('/usr/local/CVS'))
       env.Program('hello.c')
       </file>
    </scons_example>
 
    <scons_output example="ex_cvs">
-     <userinput>scons</userinput>
+     <command>scons -Q</command>
    </scons_output>
 
  </section>
@@ -84,7 +87,7 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
@@ -94,10 +97,13 @@
       env.SourceCode('.', env.RCS())
       env.Program('hello.c')
       </file>
+      <file name="hello.c,v">
+      hello.c,v
+      </file>
    </scons_example>
 
    <scons_output example="ex_rcs">
-     <userinput>scons</userinput>
+     <command>scons -Q</command>
    </scons_output>
 
  </section>
@@ -107,7 +113,7 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
@@ -117,10 +123,13 @@
       env.SourceCode('.', env.SCCS())
       env.Program('hello.c')
       </file>
+      <file name="s.hello.c">
+      s.hello.c
+      </file>
    </scons_example>
 
    <scons_output example="ex_sccs">
-     <userinput>scons</userinput>
+     <command>scons -Q</command>
    </scons_output>
 
  </section>
@@ -132,7 +141,7 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
@@ -145,7 +154,7 @@
    </scons_example>
 
    <scons_output example="ex_subversion">
-     <userinput>scons</userinput>
+     <command>scons -Q</command>
    </scons_output>
 
  </section>
diff --git a/doc/user/sourcecode.sgml b/doc/user/sourcecode.sgml
index 6bbccee..74b7347 100644
--- a/doc/user/sourcecode.sgml
+++ b/doc/user/sourcecode.sgml
@@ -29,7 +29,7 @@
 
  <para>
 
-   X
+   XXX
 
  </para>
 
@@ -38,19 +38,22 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
    <programlisting>
       env = Environment()
-      env.SourceCode('.', env.BitKeeper('XXX'))
+      env.SourceCode('.', env.BitKeeper())
       env.Program('hello.c')
    </programlisting>
 
    <literallayout>
-     % <userinput>scons</userinput>
-     XXX
+     % <userinput>scons -Q</userinput>
+     bk get -
+     bk get hello.c
+     cc -c -o hello.o hello.c
+     cc -o hello hello.o
    </literallayout>
 
  </section>
@@ -60,19 +63,22 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
    <programlisting>
       env = Environment()
-      env.SourceCode('.', env.CVS('XXX'))
+      env.SourceCode('.', env.CVS('/usr/local/CVS'))
       env.Program('hello.c')
    </programlisting>
 
    <literallayout>
-     % <userinput>scons</userinput>
-     XXX
+     % <userinput>scons -Q</userinput>
+     cvs -d /usr/local/CVS co -
+     cvs -d /usr/local/CVS co hello.c
+     cc -c -o hello.o hello.c
+     cc -o hello hello.o
    </literallayout>
 
  </section>
@@ -82,7 +88,7 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
@@ -93,8 +99,11 @@
    </programlisting>
 
    <literallayout>
-     % <userinput>scons</userinput>
-     XXX
+     % <userinput>scons -Q</userinput>
+     co -
+     co hello.c
+     cc -c -o hello.o hello.c
+     cc -o hello hello.o
    </literallayout>
 
  </section>
@@ -104,7 +113,7 @@
 
    <para>
 
-   X
+   XXX
 
    </para>
 
@@ -115,30 +124,38 @@
    </programlisting>
 
    <literallayout>
-     % <userinput>scons</userinput>
-     XXX
+     % <userinput>scons -Q</userinput>
+     sccs get -
+     sccs get hello.c
+     cc -c -o hello.o hello.c
+     cc -o hello hello.o
    </literallayout>
 
  </section>
 
+ <!--
+
  <section>
  <title>Fetching Source Code From Subversion</title>
 
    <para>
 
-   X
+   XXX
 
    </para>
 
-   <programlisting>
+   <scons_example name="ex_subversion">
+      <file name="SConstruct" printme="1">
       env = Environment()
       env.SourceCode('.', env.Subversion('XXX'))
       env.Program('hello.c')
-   </programlisting>
+      </file>
+   </scons_example>
 
-   <literallayout>
-     % <userinput>scons</userinput>
-     XXX
-   </literallayout>
+   <scons_output example="ex_subversion">
+     <command>scons -Q</command>
+   </scons_output>
 
  </section>
+
+ -->
diff --git a/doc/user/variants.in b/doc/user/variants.in
index 1fb461a..ceab8f6 100644
--- a/doc/user/variants.in
+++ b/doc/user/variants.in
@@ -27,66 +27,6 @@
 
 =head1 Variant builds
 
-
-=head2 Hello, World! for baNaNa and peAcH OS's
-
-Variant builds require just another simple extension. Let's take as an
-example a requirement to allow builds for both the baNaNa and peAcH
-operating systems. In this case, we are using a distributed file system,
-such as NFS to access the particular system, and only one or the other of
-the systems has to be compiled for any given invocation of C<cons>. Here's
-one way we could set up the F<Construct> file for our B<Hello, World!>
-application:
-
-  # Construct file for Hello, World!
-
-  die qq(OS must be specified) unless $OS = $ARG{OS};
-  die qq(OS must be "peach" or "banana")
-	if $OS ne "peach" && $OS ne "banana";
-
-  # Where to put all our shared products.
-  $EXPORT = "#export/$OS";
-
-  Export qw( CONS INCLUDE LIB BIN );
-
-  # Standard directories for sharing products.
-  $INCLUDE = "$EXPORT/include";
-  $LIB = "$EXPORT/lib";
-  $BIN = "$EXPORT/bin";
-
-  # A standard construction environment.
-  $CONS = new cons (
-	CPPPATH => $INCLUDE,	# Include path for C Compilations
-	LIBPATH => $LIB,	# Library path for linking programs
-	LIBS => '-lworld',	# List of standard libraries
-  );
-
-  # $BUILD is where we will derive everything.
-  $BUILD = "#build/$OS";
-
-  # Tell cons where the source files for $BUILD are.
-  Link $BUILD => 'src';
-
-  Build (
-	"$BUILD/hello/Conscript",
-	"$BUILD/world/Conscript",
-  );
-
-Now if we login to a peAcH system, we can build our B<Hello, World!>
-application for that platform:
-
-  % cons export OS=peach
-  Install build/peach/world/world.h as export/peach/include/world.h
-  cc -Iexport/peach/include -c build/peach/hello/hello.c -o build/peach/hello/hello.o
-  cc -Iexport/peach/include -c build/peach/world/world.c -o build/peach/world/world.o
-  ar r build/peach/world/libworld.a build/peach/world/world.o
-  ar: creating build/peach/world/libworld.a
-  ranlib build/peach/world/libworld.a
-  Install build/peach/world/libworld.a as export/peach/lib/libworld.a
-  cc -o build/peach/hello/hello build/peach/hello/hello.o -Lexport/peach/lib -lworld
-  Install build/peach/hello/hello as export/peach/bin/hello
-
-
 =head2 Variations on a theme
 
 Other variations of this model are possible. For example, you might decide
@@ -122,26 +62,59 @@ is pretty smart about rebuilding things when you change options.
 
   <scons_example name="ex_variants">
     <file name="SConstruct" printme="1">
-    platform = ARGUMENT.get('OS', Platform())
+    platform = ARGUMENTS.get('OS', Platform())
 
     include = "#export/$PLATFORM/include"
     lib = "#export/$PLATFORM/lib"
     bin = "#export/$PLATFORM/bin"
 
     env = Environment(PLATFORM = platform,
+                      BINDIR = bin,
+                      INCDIR = include,
+                      LIBDIR = lib,
                       CPPPATH = [include],
-                      LIB = lib,
-                      LIBS = '-lworld')
+                      LIBPATH = [lib],
+                      LIBS = 'world')
 
     Export('env')
 
-    SConscript('src/SConscript', build_dir='build/$PLATFORM')
+    env.SConscript('src/SConscript', build_dir='build/$PLATFORM')
 
     #
     #BuildDir("#build/$PLATFORM", 'src')
     #SConscript("build/$PLATFORM/hello/SConscript")
     #SConscript("build/$PLATFORM/world/SConscript")
     </file>
+    <directory name="src"></directory>
+    <directory name="src/hello"></directory>
+    <directory name="src/world"></directory>
+    <file name="src/SConscript">
+    Import('env')
+    SConscript('hello/SConscript')
+    SConscript('world/SConscript')
+    </file>
+    <file name="src/hello/SConscript">
+    Import('env')
+    hello = env.Program('hello.c')
+    env.Install('$BINDIR', hello)
+    </file>
+    <file name="src/hello/hello.c">
+    #include "world.h"
+    int main(int argc, char *argv[]) { printf "hello.c\n"; world(); }
+    </file>
+    <file name="src/world/SConscript">
+    Import('env')
+    world = env.Library('world.c')
+    env.Install('$LIBDIR', world)
+    env.Install('$INCDIR', 'world.h')
+    </file>
+    <file name="src/world/world.h">
+    #define STRING "world.h"
+    extern int world();
+    </file>
+    <file name="src/world/world.c">
+    int world() { printf "world.c\n"; }
+    </file>
   </scons_example>
 
   <para>
@@ -152,7 +125,7 @@ is pretty smart about rebuilding things when you change options.
   </para>
 
   <scons_output example="ex_variants" os="posix">
-    <command>scons OS=linux</command>
+    <command>scons -Q OS=linux</command>
   </scons_output>
 
   <para>
@@ -162,18 +135,21 @@ is pretty smart about rebuilding things when you change options.
   </para>
 
   <scons_output example="ex_variants" os="win32">
-    <command>scons OS=windows</command>
+    <command>scons -Q OS=windows</command>
   </scons_output>
 
+  <!--
+
   <scons_example name="ex_var2">
-  <programlisting>
     <file name="SConstruct" printme="1">
-    env = Environment(OS = )
+    env = Environment(OS = ARGUMENTS.get('OS'))
     for os in ['newell', 'post']:
         SConscript('src/SConscript', build_dir='build/' + os)
     </file>
   </scons_example>
 
   <scons_output example="ex_var2">
-    % <userinput>scons</userinput>
+    <command>scons -Q</command>
   </scons_output>
+
+  -->
diff --git a/doc/user/variants.sgml b/doc/user/variants.sgml
index 09dd16d..4ddb40b 100644
--- a/doc/user/variants.sgml
+++ b/doc/user/variants.sgml
@@ -27,66 +27,6 @@
 
 =head1 Variant builds
 
-
-=head2 Hello, World! for baNaNa and peAcH OS's
-
-Variant builds require just another simple extension. Let's take as an
-example a requirement to allow builds for both the baNaNa and peAcH
-operating systems. In this case, we are using a distributed file system,
-such as NFS to access the particular system, and only one or the other of
-the systems has to be compiled for any given invocation of C<cons>. Here's
-one way we could set up the F<Construct> file for our B<Hello, World!>
-application:
-
-  # Construct file for Hello, World!
-
-  die qq(OS must be specified) unless $OS = $ARG{OS};
-  die qq(OS must be "peach" or "banana")
-	if $OS ne "peach" && $OS ne "banana";
-
-  # Where to put all our shared products.
-  $EXPORT = "#export/$OS";
-
-  Export qw( CONS INCLUDE LIB BIN );
-
-  # Standard directories for sharing products.
-  $INCLUDE = "$EXPORT/include";
-  $LIB = "$EXPORT/lib";
-  $BIN = "$EXPORT/bin";
-
-  # A standard construction environment.
-  $CONS = new cons (
-	CPPPATH => $INCLUDE,	# Include path for C Compilations
-	LIBPATH => $LIB,	# Library path for linking programs
-	LIBS => '-lworld',	# List of standard libraries
-  );
-
-  # $BUILD is where we will derive everything.
-  $BUILD = "#build/$OS";
-
-  # Tell cons where the source files for $BUILD are.
-  Link $BUILD => 'src';
-
-  Build (
-	"$BUILD/hello/Conscript",
-	"$BUILD/world/Conscript",
-  );
-
-Now if we login to a peAcH system, we can build our B<Hello, World!>
-application for that platform:
-
-  % cons export OS=peach
-  Install build/peach/world/world.h as export/peach/include/world.h
-  cc -Iexport/peach/include -c build/peach/hello/hello.c -o build/peach/hello/hello.o
-  cc -Iexport/peach/include -c build/peach/world/world.c -o build/peach/world/world.o
-  ar r build/peach/world/libworld.a build/peach/world/world.o
-  ar: creating build/peach/world/libworld.a
-  ranlib build/peach/world/libworld.a
-  Install build/peach/world/libworld.a as export/peach/lib/libworld.a
-  cc -o build/peach/hello/hello build/peach/hello/hello.o -Lexport/peach/lib -lworld
-  Install build/peach/hello/hello as export/peach/bin/hello
-
-
 =head2 Variations on a theme
 
 Other variations of this model are possible. For example, you might decide
@@ -121,20 +61,23 @@ is pretty smart about rebuilding things when you change options.
   </para>
 
   <programlisting>
-    platform = ARGUMENT.get('OS', Platform())
+    platform = ARGUMENTS.get('OS', Platform())
 
     include = "#export/$PLATFORM/include"
     lib = "#export/$PLATFORM/lib"
     bin = "#export/$PLATFORM/bin"
 
     env = Environment(PLATFORM = platform,
+                      BINDIR = bin,
+                      INCDIR = include,
+                      LIBDIR = lib,
                       CPPPATH = [include],
-                      LIB = lib,
-                      LIBS = '-lworld')
+                      LIBPATH = [lib],
+                      LIBS = 'world')
 
     Export('env')
 
-    SConscript('src/SConscript', build_dir='build/$PLATFORM')
+    env.SConscript('src/SConscript', build_dir='build/$PLATFORM')
 
     #
     #BuildDir("#build/$PLATFORM", 'src')
@@ -150,16 +93,15 @@ is pretty smart about rebuilding things when you change options.
   </para>
 
   <literallayout>
-    $ <userinput>scons OS=linux</userinput>
-    Install build/linux/world/world.h as export/linux/include/world.h
-    cc -Iexport/linux/include -c build/linux/hello/hello.c -o build/linux/hello/hello.o
-    cc -Iexport/linux/include -c build/linux/world/world.c -o build/linux/world/world.o
+    % <userinput>scons -Q OS=linux</userinput>
+    Install file: "build/linux/world/world.h" as "export/linux/include/world.h"
+    cc -Iexport/linux/include -c -o build/linux/hello/hello.o build/linux/hello/hello.c
+    cc -Iexport/linux/include -c -o build/linux/world/world.o build/linux/world/world.c
     ar r build/linux/world/libworld.a build/linux/world/world.o
-    ar: creating build/linux/world/libworld.a
     ranlib build/linux/world/libworld.a
-    Install build/linux/world/libworld.a as export/linux/lib/libworld.a
+    Install file: "build/linux/world/libworld.a" as "export/linux/lib/libworld.a"
     cc -o build/linux/hello/hello build/linux/hello/hello.o -Lexport/linux/lib -lworld
-    Install build/linux/hello/hello as export/linux/bin/hello
+    Install file: "build/linux/hello/hello" as "export/linux/bin/hello"
   </literallayout>
 
   <para>
@@ -168,28 +110,29 @@ is pretty smart about rebuilding things when you change options.
 
   </para>
 
-    <!--
-    cl /Fohello.obj hello.c
-    link /Fohello.exe hello.obj
-    -->
   <literallayout>
-    C:\test\><userinput>scons OS=linux</userinput>
-    Install build\linux\world\world.h as export\linux\include\world.h
-    cl /Iexport\linux\include /Fobuild\linux\hello\hello.obj build\linux\hello\hello.c
-    cl /Iexport\linux\include /Fobuild\linux\world\world.obj build\linux\world\world.c
-    XXX
-    ar r build\linux\world\world.lib build\linux\world\world.obj
-    Install build\linux\world\world.lib as export\linux\lib\libworld.a
-    link /Fobuild\linux\hello\hello.exe build\linux\hello\hello.obj -Lexport\linux\lib world.lib
-    Install build\linux\hello\hello.exe as export\linux\bin\hello.exe
+    C:\><userinput>scons -Q OS=windows</userinput>
+    Install file: "build/windows/world/world.h" as "export/windows/include/world.h"
+    cl /nologo /Iexport\windows\include /c build\windows\hello\hello.c /Fobuild\windows\hello\hello.obj
+    cl /nologo /Iexport\windows\include /c build\windows\world\world.c /Fobuild\windows\world\world.obj
+    lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj
+    Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib"
+    link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj
+    Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe"
   </literallayout>
 
-  <programlisting>
-    env = Environment(OS = )
+  <!--
+
+  <scons_example name="ex_var2">
+    <file name="SConstruct" printme="1">
+    env = Environment(OS = ARGUMENTS.get('OS'))
     for os in ['newell', 'post']:
         SConscript('src/SConscript', build_dir='build/' + os)
-  </programlisting>
+    </file>
+  </scons_example>
 
-  <literallayout>
-    % <userinput>scons</userinput>
-  </literallayout>
+  <scons_output example="ex_var2">
+    <command>scons -Q</command>
+  </scons_output>
+
+  -->