Sync CVS log from master Aegis repository.

24 files changed, 1400 insertions, 479 deletions

diff --git a/doc/user/alias.in b/doc/user/alias.in
index 22fc128..6cc68b0 100644
--- a/doc/user/alias.in
+++ b/doc/user/alias.in
@@ -50,7 +50,7 @@
   </para>
 
   <scons_output example="ex1" os="posix">
-     <command>scons install</command>
+     <command>scons -Q install</command>
   </scons_output>
 
   <para>
@@ -95,8 +95,8 @@
   </para>
 
   <scons_output example="ex2" os="posix">
-     <command>scons install-bin</command>
-     <command>scons install-lib</command>
-     <command>scons -c __ROOT__/</command>
-     <command>scons install</command>
+     <command>scons -Q install-bin</command>
+     <command>scons -Q install-lib</command>
+     <command>scons -Q -c __ROOT__/</command>
+     <command>scons -Q install</command>
   </scons_output>
diff --git a/doc/user/alias.sgml b/doc/user/alias.sgml
index 3f48ee0..a4b65da 100644
--- a/doc/user/alias.sgml
+++ b/doc/user/alias.sgml
@@ -45,7 +45,9 @@
   </para>
 
   <literallayout>
-     % <userinput>scons install</userinput>
+     % <userinput>scons -Q install</userinput>
+     cc -c -o hello.o hello.c
+     cc -o hello hello.o
      Install file: "hello" as "/usr/bin/hello"
   </literallayout>
 
@@ -64,8 +66,8 @@
 
   <programlisting>
      env = Environment()
-     p = env.Program('hello.c')
-     l = env.Library('hello.c')
+     p = env.Program('foo.c')
+     l = env.Library('bar.c')
      env.Install('/usr/bin', p)
      env.Install('/usr/lib', l)
      ib = env.Alias('install-bin', '/usr/bin')
@@ -83,12 +85,28 @@
   </para>
 
   <literallayout>
-     % <userinput>scons install-bin</userinput>
-     Install file: "hello" as "/usr/bin/hello"
-     % <userinput>scons install-lib</userinput>
-     Install file: "libhello.a" as "/usr/lib/libhello.a"
-     % <userinput>scons -c /</userinput>
-     % <userinput>scons install</userinput>
-     Install file: "hello" as "/usr/bin/hello"
-     Install file: "libhello.a" as "/usr/lib/libhello.a"
+     % <userinput>scons -Q install-bin</userinput>
+     cc -c -o foo.o foo.c
+     cc -o foo foo.o
+     Install file: "foo" as "/usr/bin/foo"
+     % <userinput>scons -Q install-lib</userinput>
+     cc -c -o bar.o bar.c
+     ar r libbar.a bar.o
+     ranlib libbar.a
+     Install file: "libbar.a" as "/usr/lib/libbar.a"
+     % <userinput>scons -Q -c /</userinput>
+     Removed foo.o
+     Removed foo
+     Removed /usr/bin/foo
+     Removed bar.o
+     Removed libbar.a
+     Removed /usr/lib/libbar.a
+     % <userinput>scons -Q install</userinput>
+     cc -c -o foo.o foo.c
+     cc -o foo foo.o
+     Install file: "foo" as "/usr/bin/foo"
+     cc -c -o bar.o bar.c
+     ar r libbar.a bar.o
+     ranlib libbar.a
+     Install file: "libbar.a" as "/usr/lib/libbar.a"
   </literallayout>
diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in
index 89f0af3..1d00a10 100644
--- a/doc/user/builders-built-in.in
+++ b/doc/user/builders-built-in.in
@@ -33,6 +33,9 @@
   This section will describe all of the different
   types of files that you can build with &SCons;,
   and the built-in &Builder; objects used to build them.
+  By default, all of the  &Builder; objects in this section
+  can be built either with or without an explicit
+  construction environment.
 
   </para>
 
@@ -52,8 +55,7 @@
     </para>
 
     <programlisting>
-      env = Environment()
-      env.Program('prog', 'file1.o')
+      Program('prog', 'file1.o')
     </programlisting>
 
     <para>
@@ -95,15 +97,14 @@
     If you omit the &target;,
     the base of the first input
     file name specified
-    because the base of the target
+    becomes the base of the target
     program created.
     For example:
 
     </para>
 
     <programlisting>
-      env = Environment()
-      env.Program(['hello.c', 'goodbye.c'])
+      Program(['hello.c', 'goodbye.c'])
     </programlisting>
 
     <para>
@@ -114,6 +115,96 @@
 
     </para>
 
+    <para>
+
+    Two construction variables control what libraries
+    will be linked with the resulting program.
+    The &LIBS; variable is a list of the names of
+    libraries that will be linked into any programs,
+    and the &LIBPATH; variables is a list of
+    directories that will be searched for
+    the specified libraries.
+    &SCons; will construct the right command-line
+    options for the running system.
+    For example:
+
+    </para>
+
+    <scons_example name="libs">
+      <file name="SConstruct" printme="1">
+      env = Environment(LIBS = ['foo1', 'foo2'],
+                        LIBPATH = ['/usr/dir1', 'dir2'])
+      env.Program(['hello.c', 'goodbye.c'])
+      </file>
+      <file name="hello.c">
+      int hello() { printf("Hello, world!\n"); }
+      </file>
+      <file name="goodbye.c">
+      int goodbye() { printf("Goodbye, world!\n"); }
+      </file>
+    </scons_example>
+
+    <para>
+
+    Will execute as follows on a POSIX system:
+
+    </para>
+
+    <scons_output example="libs" os="posix">
+      <command>scons -Q</command>
+    </scons_output>
+
+    <para>
+
+    And execute as follows on a Windows system:
+
+    </para>
+
+    <scons_output example="libs" os="win32">
+      <command>scons -Q</command>
+    </scons_output>
+
+    <para>
+
+    The &LIBS; construction variable
+    is turned into command line options
+    by appending the &LIBLINKPREFIX; and &LIBLINKSUFFIX;
+    construction variables to the beginning and end,
+    respectively, of each specified library.
+
+    </para>
+
+    <para>
+
+    The &LIBPATH; construction variable
+    is turned into command line options
+    by appending the &LIBDIRPREFIX; and &LIBDIRSUFFIX;
+    construction variables to the beginning and end,
+    respectively, of each specified library.
+
+    </para>
+
+    <para>
+
+    Other relevant construction variables
+    include those used by the &Object;
+    builders to affect how the
+    source files specified as input to the &Program;
+    builders are turned into object files;
+    see the next section.
+
+    </para>
+
+    <para>
+
+    The command line used to control how a program is linked
+    is specified by the &LINKCOM; construction variable.
+    By default, it uses the
+    &LINK; construction variable
+    and the &LINKFLAGS; construction variable.
+
+    </para>
+
   </section>
 
   <section>
@@ -122,7 +213,9 @@
     <para>
 
     &SCons; provides separate Builder objects
-    to create both static and shared object files.
+    to create static and shared object files.
+    The distinction becomes especially important when 
+    archiving object files into different types of libraries.
 
     </para>
 
@@ -131,18 +224,78 @@
 
       <para>
 
-      XXX
+      The &StaticObject; Builder
+      is used to build an object file
+      suitable for static linking into a program,
+      or for inclusion in a static library.
+      The &source; argument is a single source-code file,
+      and the &target; argument is the
+      name of the static object file to be created.
+      For example:
 
       </para>
 
       <programlisting>
-        XXX
+        StaticObject('file', 'file.c')
       </programlisting>
 
+      <para>
+
+      Will create the &file_o;
+      object file on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      $OBJPREFIX
+      and
+      $OBJSUFFIX
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx')
+        env.StaticObject('file', 'file.c')
+      </programlisting>
+
+      <para>
+
+      Will create an object file named
+      <filename>myfile.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      beomces the base of the name
+      of the static object file to be created.
+      For example:
+
+      </para>
+
       <literallayout>
-        XXX
+        StaticObject('file.c')
       </literallayout>
 
+      <para>
+
+      Will create the &file_o;
+      executable on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
     </section>
 
     <section>
@@ -150,36 +303,87 @@
 
       <para>
 
-      XXX
+      The &SharedObject; Builder
+      is used to build an object file
+      suitable for shared linking into a program,
+      or for inclusion in a shared library.
+      The &source; argument is a single source-code file,
+      and the &target; argument is the
+      name of the shared object file to be created.
+      For example:
 
       </para>
 
       <programlisting>
-        XXX
+        SharedObject('file', 'file.c')
       </programlisting>
 
-      <literallayout>
-        XXX
-      </literallayout>
+      <para>
 
-    </section>
+      Will create the &file_o;
+      object file on a POSIX system,
+      the &file_obj; executable on a Windows system.
 
-    <section>
-    <title>The &Object; Builder</title>
+      </para>
 
       <para>
 
-      XXX
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      $SHOBJPREFIX
+      and
+      $SHOBJSUFFIX
+      construction variables
+      will be appended appropriately.
+      For example:
 
       </para>
 
       <programlisting>
-        XXX
+        env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx')
+        env.SharedObject('file', 'file.c')
       </programlisting>
 
       <para>
 
-      Creates a static object file.
+      Will create an object file named
+      <filename>myfile.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name
+      of the shared object file to be created.
+      For example:
+
+      </para>
+
+      <literallayout>
+        SharedObject('file.c')
+      </literallayout>
+
+      <para>
+
+      Will create the &file_o;
+      executable on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &Object; Builder</title>
+
+      <para>
+
+      The &Object; Builder is a synonym for &StaticObject;
+      and is completely equivalent.
 
       </para>
 
@@ -193,7 +397,7 @@
     <para>
 
     &SCons; provides separate Builder objects
-    to create both static and shared libraries.
+    to create static and shared libraries.
 
     </para>
 
@@ -202,18 +406,73 @@
 
       <para>
 
-      XXX
+      The &StaticLibrary; Builder
+      is used to create a library
+      suitable for static linking into a program.
+      The &source; argument is one or more
+      source-code files or object files,
+      and the &target; argument is the
+      name of the static library to be created.
+      For example:
 
       </para>
 
       <programlisting>
-        XXX
+        StaticLibrary('foo', ['file1.c', 'file2.c'])
       </programlisting>
 
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      $LIBPREFIX
+      and
+      $LIBSUFFIX
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx')
+        env.StaticLibrary('lib', ['file1.o', 'file2.o'])
+      </programlisting>
+
+      <para>
+
+      Will create an object file named
+      <filename>mylib.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <programlisting>
+        StaticLibrary('foo', ['file1.c', 'file2.c'])
+      </programlisting>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name of the static object file to be created.
+      For example:
+
+      </para>
+
       <literallayout>
-        XXX
+        StaticLibrary(['file.c', 'another.c'])
       </literallayout>
 
+      <para>
+
+      Will create the &libfile_a;
+      library on a POSIX system,
+      the &file_lib; library on a Windows system.
+
+      </para>
+
     </section>
 
     <section>
@@ -221,32 +480,82 @@
 
       <para>
 
-      XXX
+      The &SharedLibrary; Builder
+      is used to create a shared library
+      suitable for linking with a program.
+      The &source; argument is one or more
+      source-code files or object files,
+      and the &target; argument is the
+      name of the shared library to be created.
+      For example:
 
       </para>
 
-    </section>
+      <programlisting>
+        SharedLibrary('foo', ['file1.c', 'file2.c'])
+      </programlisting>
 
-    <section>
-    <title>The &Library; Builder</title>
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      $SHLIBPREFIX
+      and
+      $SHLIBSUFFIX
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx')
+        env.SharedLibrary('shared', ['file1.o', 'file2.o'])
+      </programlisting>
 
       <para>
 
-      XXX
+      Will create an object file named
+      <filename>myshared.xxx</filename>
+      regardless of the system on which it is run.
 
       </para>
 
       <programlisting>
-        XXX
+        SharedLibrary('foo', ['file1.c', 'file2.c'])
       </programlisting>
 
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name of the shared library to be created.
+      For example:
+
+      </para>
+
       <literallayout>
-        XXX
+        SharedLibrary(['file.c', 'another.c'])
       </literallayout>
 
       <para>
 
-      Creates a static library file.
+      Will create the &libfile_so;
+      library on a POSIX system,
+      the &file_dll; library on a Windows system.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &Library; Builder</title>
+
+      <para>
+
+      The &Library; Builder is a synonym for &StaticLibrary;
+      and is completely equivalent.
 
       </para>
 
@@ -285,6 +594,8 @@
     &SCons; supports two Builder objects
     that know how to build source files
     from other input files.
+    These are typically invoked "internally"
+    to turn files that need preprocessing into other source files.
 
     </para>
 
@@ -428,7 +739,7 @@
       </scons_example>
 
       <scons_output example="ex1" os="posix">
-        <command>scons .</command>
+        <command>scons -Q .</command>
       </scons_output>
 
       <para>
@@ -457,7 +768,7 @@
       </scons_example>
 
       <scons_output example="ex2" os="posix">
-        <command>scons .</command>
+        <command>scons -Q .</command>
       </scons_output>
 
       <para>
@@ -482,7 +793,7 @@
       </scons_example>
 
       <scons_output example="ex3" os="posix">
-        <command>scons .</command>
+        <command>scons -Q .</command>
       </scons_output>
 
     </section>
@@ -524,7 +835,7 @@
       </para>
 
       <scons_output example="ex4" os="posix">
-        <command>scons .</command>
+        <command>scons -Q .</command>
       </scons_output>
 
       <para>
@@ -536,7 +847,7 @@
       </para>
 
       <literallayout>
-        % <userinput>scons .</userinput>
+        % <userinput>scons -Q .</userinput>
         zip /home/my/project/zip.out file1 file2
       </literallayout>
 
diff --git a/doc/user/builders-built-in.sgml b/doc/user/builders-built-in.sgml
index bb29cc4..3afbf19 100644
--- a/doc/user/builders-built-in.sgml
+++ b/doc/user/builders-built-in.sgml
@@ -33,6 +33,9 @@
   This section will describe all of the different
   types of files that you can build with &SCons;,
   and the built-in &Builder; objects used to build them.
+  By default, all of the  &Builder; objects in this section
+  can be built either with or without an explicit
+  construction environment.
 
   </para>
 
@@ -52,8 +55,7 @@
     </para>
 
     <programlisting>
-      env = Environment()
-      env.Program('prog', 'file1.o')
+      Program('prog', 'file1.o')
     </programlisting>
 
     <para>
@@ -95,15 +97,14 @@
     If you omit the &target;,
     the base of the first input
     file name specified
-    because the base of the target
+    becomes the base of the target
     program created.
     For example:
 
     </para>
 
     <programlisting>
-      env = Environment()
-      env.Program(['hello.c', 'goodbye.c'])
+      Program(['hello.c', 'goodbye.c'])
     </programlisting>
 
     <para>
@@ -114,6 +115,94 @@
 
     </para>
 
+    <para>
+
+    Two construction variables control what libraries
+    will be linked with the resulting program.
+    The &LIBS; variable is a list of the names of
+    libraries that will be linked into any programs,
+    and the &LIBPATH; variables is a list of
+    directories that will be searched for
+    the specified libraries.
+    &SCons; will construct the right command-line
+    options for the running system.
+    For example:
+
+    </para>
+
+    <programlisting>
+      env = Environment(LIBS = ['foo1', 'foo2'],
+                        LIBPATH = ['/usr/dir1', 'dir2'])
+      env.Program(['hello.c', 'goodbye.c'])
+    </programlisting>
+
+    <para>
+
+    Will execute as follows on a POSIX system:
+
+    </para>
+
+    <literallayout>
+      % <userinput>scons -Q</userinput>
+      cc -c -o goodbye.o goodbye.c
+      cc -c -o hello.o hello.c
+      cc -o hello hello.o goodbye.o -L/usr/dir1 -Ldir2 -lfoo1 -lfoo2
+    </literallayout>
+
+    <para>
+
+    And execute as follows on a Windows system:
+
+    </para>
+
+    <literallayout>
+      C:\><userinput>scons -Q</userinput>
+      cl /nologo /c goodbye.c /Fogoodbye.obj
+      cl /nologo /c hello.c /Fohello.obj
+      link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj
+    </literallayout>
+
+    <para>
+
+    The &LIBS; construction variable
+    is turned into command line options
+    by appending the &LIBLINKPREFIX; and &LIBLINKSUFFIX;
+    construction variables to the beginning and end,
+    respectively, of each specified library.
+
+    </para>
+
+    <para>
+
+    The &LIBPATH; construction variable
+    is turned into command line options
+    by appending the &LIBDIRPREFIX; and &LIBDIRSUFFIX;
+    construction variables to the beginning and end,
+    respectively, of each specified library.
+
+    </para>
+
+    <para>
+
+    Other relevant construction variables
+    include those used by the &Object;
+    builders to affect how the
+    source files specified as input to the &Program;
+    builders are turned into object files;
+    see the next section.
+
+    </para>
+
+    <para>
+
+    The command line used to control how a program is linked
+    is specified by the &LINKCOM; construction variable.
+    By default, it uses the
+    &LINK; construction variable
+    and the &LINKFLAGS; construction variable.
+
+    </para>
+
   </section>
 
   <section>
@@ -122,7 +211,9 @@
     <para>
 
     &SCons; provides separate Builder objects
-    to create both static and shared object files.
+    to create static and shared object files.
+    The distinction becomes especially important when 
+    archiving object files into different types of libraries.
 
     </para>
 
@@ -131,18 +222,78 @@
 
       <para>
 
-      XXX
+      The &StaticObject; Builder
+      is used to build an object file
+      suitable for static linking into a program,
+      or for inclusion in a static library.
+      The &source; argument is a single source-code file,
+      and the &target; argument is the
+      name of the static object file to be created.
+      For example:
 
       </para>
 
       <programlisting>
-        XXX
+        StaticObject('file', 'file.c')
       </programlisting>
 
+      <para>
+
+      Will create the &file_o;
+      object file on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      $OBJPREFIX
+      and
+      $OBJSUFFIX
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx')
+        env.StaticObject('file', 'file.c')
+      </programlisting>
+
+      <para>
+
+      Will create an object file named
+      <filename>myfile.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      beomces the base of the name
+      of the static object file to be created.
+      For example:
+
+      </para>
+
       <literallayout>
-        XXX
+        StaticObject('file.c')
       </literallayout>
 
+      <para>
+
+      Will create the &file_o;
+      executable on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
     </section>
 
     <section>
@@ -150,36 +301,87 @@
 
       <para>
 
-      XXX
+      The &SharedObject; Builder
+      is used to build an object file
+      suitable for shared linking into a program,
+      or for inclusion in a shared library.
+      The &source; argument is a single source-code file,
+      and the &target; argument is the
+      name of the shared object file to be created.
+      For example:
 
       </para>
 
       <programlisting>
-        XXX
+        SharedObject('file', 'file.c')
       </programlisting>
 
-      <literallayout>
-        XXX
-      </literallayout>
+      <para>
 
-    </section>
+      Will create the &file_o;
+      object file on a POSIX system,
+      the &file_obj; executable on a Windows system.
 
-    <section>
-    <title>The &Object; Builder</title>
+      </para>
 
       <para>
 
-      XXX
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      $SHOBJPREFIX
+      and
+      $SHOBJSUFFIX
+      construction variables
+      will be appended appropriately.
+      For example:
 
       </para>
 
       <programlisting>
-        XXX
+        env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx')
+        env.SharedObject('file', 'file.c')
       </programlisting>
 
       <para>
 
-      Creates a static object file.
+      Will create an object file named
+      <filename>myfile.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name
+      of the shared object file to be created.
+      For example:
+
+      </para>
+
+      <literallayout>
+        SharedObject('file.c')
+      </literallayout>
+
+      <para>
+
+      Will create the &file_o;
+      executable on a POSIX system,
+      the &file_obj; executable on a Windows system.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &Object; Builder</title>
+
+      <para>
+
+      The &Object; Builder is a synonym for &StaticObject;
+      and is completely equivalent.
 
       </para>
 
@@ -193,7 +395,7 @@
     <para>
 
     &SCons; provides separate Builder objects
-    to create both static and shared libraries.
+    to create static and shared libraries.
 
     </para>
 
@@ -202,18 +404,73 @@
 
       <para>
 
-      XXX
+      The &StaticLibrary; Builder
+      is used to create a library
+      suitable for static linking into a program.
+      The &source; argument is one or more
+      source-code files or object files,
+      and the &target; argument is the
+      name of the static library to be created.
+      For example:
 
       </para>
 
       <programlisting>
-        XXX
+        StaticLibrary('foo', ['file1.c', 'file2.c'])
+      </programlisting>
+
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      $LIBPREFIX
+      and
+      $LIBSUFFIX
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx')
+        env.StaticLibrary('lib', ['file1.o', 'file2.o'])
+      </programlisting>
+
+      <para>
+
+      Will create an object file named
+      <filename>mylib.xxx</filename>
+      regardless of the system on which it is run.
+
+      </para>
+
+      <programlisting>
+        StaticLibrary('foo', ['file1.c', 'file2.c'])
       </programlisting>
 
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name of the static object file to be created.
+      For example:
+
+      </para>
+
       <literallayout>
-        XXX
+        StaticLibrary(['file.c', 'another.c'])
       </literallayout>
 
+      <para>
+
+      Will create the &libfile_a;
+      library on a POSIX system,
+      the &file_lib; library on a Windows system.
+
+      </para>
+
     </section>
 
     <section>
@@ -221,32 +478,82 @@
 
       <para>
 
-      XXX
+      The &SharedLibrary; Builder
+      is used to create a shared library
+      suitable for linking with a program.
+      The &source; argument is one or more
+      source-code files or object files,
+      and the &target; argument is the
+      name of the shared library to be created.
+      For example:
 
       </para>
 
-    </section>
+      <programlisting>
+        SharedLibrary('foo', ['file1.c', 'file2.c'])
+      </programlisting>
 
-    <section>
-    <title>The &Library; Builder</title>
+      <para>
+
+      The target file's prefix and suffix may be omitted,
+      and the values from the
+      $SHLIBPREFIX
+      and
+      $SHLIBSUFFIX
+      construction variables
+      will be appended appropriately.
+      For example:
+
+      </para>
+
+      <programlisting>
+        env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx')
+        env.SharedLibrary('shared', ['file1.o', 'file2.o'])
+      </programlisting>
 
       <para>
 
-      XXX
+      Will create an object file named
+      <filename>myshared.xxx</filename>
+      regardless of the system on which it is run.
 
       </para>
 
       <programlisting>
-        XXX
+        SharedLibrary('foo', ['file1.c', 'file2.c'])
       </programlisting>
 
+      <para>
+
+      If you omit the &target;,
+      the base of the first input
+      file name specified
+      becomes the base of the name of the shared library to be created.
+      For example:
+
+      </para>
+
       <literallayout>
-        XXX
+        SharedLibrary(['file.c', 'another.c'])
       </literallayout>
 
       <para>
 
-      Creates a static library file.
+      Will create the &libfile_so;
+      library on a POSIX system,
+      the &file_dll; library on a Windows system.
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &Library; Builder</title>
+
+      <para>
+
+      The &Library; Builder is a synonym for &StaticLibrary;
+      and is completely equivalent.
 
       </para>
 
@@ -285,6 +592,8 @@
     &SCons; supports two Builder objects
     that know how to build source files
     from other input files.
+    These are typically invoked "internally"
+    to turn files that need preprocessing into other source files.
 
     </para>
 
@@ -417,7 +726,7 @@
       </programlisting>
 
       <literallayout>
-        % <userinput>scons .</userinput>
+        % <userinput>scons -Q .</userinput>
         tar -c -f out1.tar file1 file2
         tar -c -f out2.tar directory
       </literallayout>
@@ -443,7 +752,7 @@
       </programlisting>
 
       <literallayout>
-        % <userinput>scons .</userinput>
+        % <userinput>scons -Q .</userinput>
         tar -c -z -f out.tar.gz directory
       </literallayout>
 
@@ -464,7 +773,7 @@
       </programlisting>
 
       <literallayout>
-        % <userinput>scons .</userinput>
+        % <userinput>scons -Q .</userinput>
         tar -c -z -f out.tgz directory
       </literallayout>
 
@@ -499,7 +808,7 @@
       </para>
 
       <literallayout>
-        % <userinput>scons .</userinput>
+        % <userinput>scons -Q .</userinput>
         zip("out.zip", ["file1", "file2"])
       </literallayout>
 
@@ -512,7 +821,7 @@
       </para>
 
       <literallayout>
-        % <userinput>scons .</userinput>
+        % <userinput>scons -Q .</userinput>
         zip /home/my/project/zip.out file1 file2
       </literallayout>
 
diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in
index 5fc2c73..2c72bbd 100644
--- a/doc/user/builders-commands.in
+++ b/doc/user/builders-commands.in
@@ -80,7 +80,7 @@
   </scons_example>
 
   <scons_output example="ex1">
-    <command>scons .</command>
+    <command>scons -Q</command>
   </scons_output>
 
   <para>
@@ -112,5 +112,5 @@
   </scons_example>
 
   <scons_output example="ex2">
-    <command>scons .</command>
+    <command>scons -Q</command>
   </scons_output>
diff --git a/doc/user/builders-commands.sgml b/doc/user/builders-commands.sgml
index e21f6d0..64c81e5 100644
--- a/doc/user/builders-commands.sgml
+++ b/doc/user/builders-commands.sgml
@@ -71,12 +71,12 @@
 
   <programlisting>
      env = Environment()
-     env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $TARGET > $SOURCE")
+     env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET")
   </programlisting>
 
   <literallayout>
-    % <userinput>scons .</userinput>
-    sed 's/x/y' < foo.in > foo.out
+    % <userinput>scons -Q</userinput>
+    sed 's/x/y/' < foo.in > foo.out
   </literallayout>
 
   <para>
@@ -96,13 +96,13 @@
 
   <programlisting>
      env = Environment()
-     def build(target, source, env)
-         XXX
+     def build(target, source, env):
+         # Whatever it takes to build
          return None
      env.Command('foo.out', 'foo.in', build)
   </programlisting>
 
   <literallayout>
-    % <userinput>scons .</userinput>
+    % <userinput>scons -Q</userinput>
     build("foo.out", "foo.in")
   </literallayout>
diff --git a/doc/user/caching.in b/doc/user/caching.in
index 2301784..3c87761 100644
--- a/doc/user/caching.in
+++ b/doc/user/caching.in
@@ -93,9 +93,9 @@
     </para>
 
     <scons_output example="ex1">
-      <command>scons</command>
-      <command>scons -c</command>
-      <command>scons</command>
+      <command>scons -Q</command>
+      <command>scons -Q -c</command>
+      <command>scons -Q</command>
     </scons_output>
 
   </section>
@@ -129,9 +129,9 @@
     </para>
 
     <scons_output example="ex1">
-      <command>scons</command>
-      <command>scons -c</command>
-      <command>scons --cache-show</command>
+      <command>scons -Q</command>
+      <command>scons -Q -c</command>
+      <command>scons -Q --cache-show</command>
     </scons_output>
 
     <para>
@@ -176,11 +176,11 @@
     </para>
 
     <scons_output example="ex1">
-      <command>scons</command>
-      <command>scons -c</command>
-      <command>scons</command>
-      <command>scons -c</command>
-      <command>scons --cache-disable</command>
+      <command>scons -Q</command>
+      <command>scons -Q -c</command>
+      <command>scons -Q</command>
+      <command>scons -Q -c</command>
+      <command>scons -Q --cache-disable</command>
     </scons_output>
 
   </section>
@@ -217,12 +217,12 @@
     </para>
 
     <scons_output example="ex1">
-      <command>scons --cache-disable</command>
-      <command>scons -c</command>
-      <command>scons --cache-disable</command>
-      <command>scons --cache-force</command>
-      <command>scons -c</command>
-      <command>scons</command>
+      <command>scons -Q --cache-disable</command>
+      <command>scons -Q -c</command>
+      <command>scons -Q --cache-disable</command>
+      <command>scons -Q --cache-force</command>
+      <command>scons -Q -c</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
diff --git a/doc/user/caching.sgml b/doc/user/caching.sgml
index 3d9158e..223592e 100644
--- a/doc/user/caching.sgml
+++ b/doc/user/caching.sgml
@@ -81,16 +81,15 @@
     </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 -c</userinput>
+      % <userinput>scons -Q -c</userinput>
       Removed hello.o
       Removed hello
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       Retrieved `hello.o' from cache
       Retrieved `hello' from cache
-      %
     </literallayout>
 
   </section>
@@ -124,16 +123,15 @@
     </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 -c</userinput>
+      % <userinput>scons -Q -c</userinput>
       Removed hello.o
       Removed hello
-      % <userinput>scons --cache-show</userinput>
-      cc -c hello.c -o hello.o
+      % <userinput>scons -Q --cache-show</userinput>
+      cc -c -o hello.o hello.c
       cc -o hello hello.o
-      %
     </literallayout>
 
     <para>
@@ -178,22 +176,21 @@
     </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 -c</userinput>
+      % <userinput>scons -Q -c</userinput>
       Removed hello.o
       Removed hello
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       Retrieved `hello.o' from cache
       Retrieved `hello' from cache
-      % <userinput>scons -c</userinput>
+      % <userinput>scons -Q -c</userinput>
       Removed hello.o
       Removed hello
-      % <userinput>scons --cache-disable</userinput>
-      cc -c hello.c -o hello.o
+      % <userinput>scons -Q --cache-disable</userinput>
+      cc -c -o hello.o hello.c
       cc -o hello hello.o
-      %
     </literallayout>
 
   </section>
@@ -230,23 +227,23 @@
     </para>
 
     <literallayout>
-      % <userinput>scons --cache-disable</userinput>
-      cc -c hello.c -o hello.o
+      % <userinput>scons -Q --cache-disable</userinput>
+      cc -c -o hello.o hello.c
       cc -o hello hello.o
-      % <userinput>scons -c</userinput>
+      % <userinput>scons -Q -c</userinput>
       Removed hello.o
       Removed hello
-      % <userinput>scons --cache-disable</userinput>
-      cc -c hello.c -o hello.o
+      % <userinput>scons -Q --cache-disable</userinput>
+      cc -c -o hello.o hello.c
       cc -o hello hello.o
-      % <userinput>scons --cache-force</userinput>
-      % <userinput>scons -c</userinput>
+      % <userinput>scons -Q --cache-force</userinput>
+      scons: `.' is up to date.
+      % <userinput>scons -Q -c</userinput>
       Removed hello.o
       Removed hello
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       Retrieved `hello.o' from cache
       Retrieved `hello' from cache
-      %
     </literallayout>
 
     <para>
diff --git a/doc/user/default.in b/doc/user/default.in
index dbe6ecd..2410da6 100644
--- a/doc/user/default.in
+++ b/doc/user/default.in
@@ -100,9 +100,9 @@ default list.
    </para>
 
    <scons_output example="ex1">
-      <command>scons</command>
-      <command>scons</command>
-      <command>scons goodbye</command>
+      <command>scons -Q</command>
+      <command>scons -Q</command>
+      <command>scons -Q goodbye</command>
    </scons_output>
 
    <para>
@@ -117,7 +117,7 @@ default list.
    </para>
 
    <scons_output example="ex1">
-      <command>scons .</command>
+      <command>scons -Q .</command>
    </scons_output>
 
    <para>
@@ -176,8 +176,8 @@ default list.
    </para>
 
    <scons_output example="ex2">
-      <command>scons</command>
-      <command>scons .</command>
+      <command>scons -Q</command>
+      <command>scons -Q .</command>
    </scons_output>
 
    <para>
@@ -211,6 +211,6 @@ default list.
    </para>
 
    <scons_output example="ex3">
-      <command>scons</command>
-      <command>scons .</command>
+      <command>scons -Q</command>
+      <command>scons -Q .</command>
    </scons_output>
diff --git a/doc/user/default.sgml b/doc/user/default.sgml
index f44719f..fa21bae 100644
--- a/doc/user/default.sgml
+++ b/doc/user/default.sgml
@@ -92,14 +92,14 @@ default list.
    </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 goodbye</userinput>
-      cc -c goodbye.c -o goodbye.o
+      % <userinput>scons -Q</userinput>
+      scons: `hello' is up to date.
+      % <userinput>scons -Q goodbye</userinput>
+      cc -c -o goodbye.o goodbye.c
       cc -o goodbye goodbye.o
-      %
    </literallayout>
 
    <para>
@@ -114,12 +114,11 @@ default list.
    </para>
 
    <literallayout>
-      % <userinput>scons .</userinput>
-      cc -c goodbye.c -o goodbye.o
+      % <userinput>scons -Q .</userinput>
+      cc -c -o goodbye.o goodbye.c
       cc -o goodbye goodbye.o
-      cc -c hello.c -o hello.o
+      cc -c -o hello.o hello.c
       cc -o hello hello.o
-      %
    </literallayout>
 
    <para>
@@ -167,15 +166,14 @@ default list.
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c prog1.c -o prog1.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o prog1.o prog1.c
       cc -o prog1 prog1.o
-      cc -c prog3.c -o prog3.o
+      cc -c -o prog3.o prog3.c
       cc -o prog3 prog3.o
-      % <userinput>scons .</userinput>
-      cc -c prog2.c -o prog2.o
+      % <userinput>scons -Q .</userinput>
+      cc -c -o prog2.o prog2.c
       cc -o prog2 prog2.o
-      %
    </literallayout>
 
    <para>
@@ -201,12 +199,11 @@ default list.
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       scons: *** No targets specified and no Default() targets found.  Stop.
-      % <userinput>scons .</userinput>
-      cc -c prog1.c -o prog1.o
+      % <userinput>scons -Q .</userinput>
+      cc -c -o prog1.o prog1.c
       cc -o prog1 prog1.o
-      cc -c prog2.c -o prog2.o
+      cc -c -o prog2.o prog2.c
       cc -o prog2 prog2.o
-      %
    </literallayout>
diff --git a/doc/user/environments.in b/doc/user/environments.in
index 7f022c1..2083d4f 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -410,10 +410,8 @@ environment undisturbed.
 
  <para>
 
-   A &consenv; is created by the &Environment;
-   method which you have already seen.
-   What you haven't seen, though,
-   is that when you initialize a &consenv;,
+   A &consenv; is created by the &Environment; method.
+   When you initialize a &consenv;,
    you can set the values of the
    environment's &consvars;
    to control how a program is built.
@@ -422,7 +420,7 @@ environment undisturbed.
  </para>
 
   <scons_example name="ex1">
-    <file name="SConstruct">
+    <file name="SConstruct" printme="1">
     env = Environment(CC = 'gcc',
                       CCFLAGS = '-O2')
 
@@ -446,7 +444,7 @@ environment undisturbed.
  </para>
 
  <scons_output example="ex1">
-    <command>scons</command>
+    <command>scons -Q</command>
  </scons_output>
 
  <section>
@@ -454,36 +452,21 @@ environment undisturbed.
 
    <para>
 
-   So far,
-   all of our examples have
-   created a single &consenv; named
-   <literal>env</literal>.
-   <literal>env</literal>, however,
-   is simply a Python variable name,
-   and you can use any other variable name that you like.
-   For example:
-
-   </para>
-
-   <sconstruct>
-      my_env = Environment(CC = 'gcc',
-                           CCFLAGS = '-O2')
-
-      my_env.Program('foo.c')
-   </sconstruct>
-
-   <para>
-
-   This opens up the possibility of
-   using multiple &consenvs;,
-   each with a separate variable name.
-   We can then use these separate &consenvs;
-   to build different programs in different ways:
+   The real advantage of construction environments
+   become apparent when you realize
+   that you can create as many different construction
+   environments as you need,
+   each tailored to a different way to build
+   some piece of software or other file.
+   If, for example, we need to build
+   one program with the <literal>-O2</literal> flag
+   and another with the <literal>-g</literal> (debug) flag,
+   we would do this like so:
 
    </para>
 
    <scons_example name="ex2">
-     <file name="SConstruct">
+     <file name="SConstruct" printme="1">
       opt = Environment(CCFLAGS = '-O2')
       dbg = Environment(CCFLAGS = '-g')
 
@@ -500,7 +483,7 @@ environment undisturbed.
    </scons_example>
 
    <scons_output example="ex2">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
    <para>
@@ -514,7 +497,7 @@ environment undisturbed.
    </para>
 
    <scons_example name="ex3">
-     <file name="SConstruct">
+     <file name="SConstruct" printme="1">
       opt = Environment(CCFLAGS = '-O2')
       dbg = Environment(CCFLAGS = '-g')
 
@@ -534,7 +517,7 @@ environment undisturbed.
    </para>
 
    <scons_output example="ex3">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
    <para>
@@ -546,6 +529,9 @@ environment undisturbed.
    <literal>-O2</literal>
    and one with a &CCFLAGS; value of
    <literal>-g</literal>.
+   &SCons; can't just decide that one of them
+   should take precedence over the other,
+   so it generates the error.
    To avoid this problem,
    we must explicitly specify
    that each environment compile
@@ -559,7 +545,7 @@ environment undisturbed.
    </programlisting>
 
    <scons_example name="ex4">
-     <file name="SConstruct">
+     <file name="SConstruct" printme="1">
       opt = Environment(CCFLAGS = '-O2')
       dbg = Environment(CCFLAGS = '-g')
 
@@ -579,7 +565,7 @@ environment undisturbed.
    Notice that each call to the &Object; builder
    returns a value,
    an internal &SCons; object that
-   represents the file that will be built.
+   represents the object file that will be built.
    We then use that object
    as input to the &Program; builder.
    This avoids having to specify explicitly
@@ -591,7 +577,7 @@ environment undisturbed.
    </para>
 
    <scons_output example="ex4">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
  </section>
@@ -622,7 +608,7 @@ environment undisturbed.
    that sets &CC; to &gcc;,
    and then creating two copies,
    one which sets &CCFLAGS; for optimization
-   and the other with sets &CCFLAGS; for debugging:
+   and the other which sets &CCFLAGS; for debugging:
 
    </para>
 
@@ -632,7 +618,7 @@ environment undisturbed.
       opt = env.Copy(CCFLAGS = '-O2')
       dbg = env.Copy(CCFLAGS = '-g')
 
-      e = opt.Object('foo', 'foo.c')
+      env.Program('foo', 'foo.c')
 
       o = opt.Object('foo-opt', 'foo.c')
       opt.Program(o)
@@ -652,7 +638,7 @@ environment undisturbed.
    </para>
 
    <scons_output example="ex5">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
  </section>
@@ -684,8 +670,7 @@ environment undisturbed.
    </para>
 
    <scons_output example="ex6">
-      <command>scons</command>
-      CC is: cc
+      <command>scons -Q</command>
    </scons_output>
 
    <para>
@@ -703,22 +688,31 @@ environment undisturbed.
       <file name="SConstruct" printme="1">
       env = Environment(FOO = 'foo', BAR = 'bar')
       dict = env.Dictionary()
-      for key, value in dict.items():
-          print "key = %s, value = %s % (key, value)
+      for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
+          print "key = %s, value = %s" % (key, dict[key])
       </file>
    </scons_Example>
 
    <para>
 
    This &SConstruct; file
-   will print the dictionary items for us as follows:
+   will print the specified dictionary items for us on POSIX
+   systems as follows:
+
+   </para>
+
+   <scons_output example="ex6b" os="posix">
+      <command>scons -Q</command>
+   </scons_output>
+
+   <para>
+
+   And on Win32:
 
    </para>
 
-   <scons_output example="ex6b">
-      % <userinput>scons</userinput>
-      key = FOO, value = foo
-      key = BAR, value = bar
+   <scons_output example="ex6b" os="win32">
+      <command>scons -Q</command>
    </scons_output>
 
  </section>
@@ -765,7 +759,7 @@ environment undisturbed.
      </para>
 
      <scons_output example="ex7">
-        <command>scons</command>
+        <command>scons -Q</command>
      </scons_output>
 
    </section>
@@ -793,7 +787,7 @@ environment undisturbed.
      </scons_example>
 
      <scons_output example="ex8">
-        <command>scons</command>
+        <command>scons -Q</command>
      </scons_output>
 
    </section>
@@ -821,7 +815,7 @@ environment undisturbed.
      </scons_example>
 
      <scons_output example="ex9">
-        <command>scons</command>
+        <command>scons -Q</command>
      </scons_output>
 
    </section>
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index 2cba46e..2be8614 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -410,10 +410,8 @@ environment undisturbed.
 
  <para>
 
-   A &consenv; is created by the &Environment;
-   method which you have already seen.
-   What you haven't seen, though,
-   is that when you initialize a &consenv;,
+   A &consenv; is created by the &Environment; method.
+   When you initialize a &consenv;,
    you can set the values of the
    environment's &consvars;
    to control how a program is built.
@@ -421,12 +419,12 @@ environment undisturbed.
 
  </para>
 
- <programlisting>
+  <programlisting>
     env = Environment(CC = 'gcc',
                       CCFLAGS = '-O2')
 
     env.Program('foo.c')
- </programlisting>
+  </programlisting>
 
  <para>
    
@@ -441,8 +439,8 @@ environment undisturbed.
  </para>
 
  <literallayout>
-    % <userinput>scons</userinput>
-    gcc -c -O2 foo.c -o foo.o
+    % <userinput>scons -Q</userinput>
+    gcc -O2 -c -o foo.o foo.c
     gcc -o foo foo.o
  </literallayout>
 
@@ -451,31 +449,16 @@ environment undisturbed.
 
    <para>
 
-   So far,
-   all of our examples have
-   created a single &consenv; named
-   <literal>env</literal>.
-   <literal>env</literal>, however,
-   is simply a Python variable name,
-   and you can use any other variable name that you like.
-   For example:
-
-   </para>
-
-   <programlisting>
-      my_env = Environment(CC = 'gcc',
-                           CCFLAGS = '-O2')
-
-      my_env.Program('foo.c')
-   </programlisting>
-
-   <para>
-
-   This opens up the possibility of
-   using multiple &consenvs;,
-   each with a separate variable name.
-   We can then use these separate &consenvs;
-   to build different programs in different ways:
+   The real advantage of construction environments
+   become apparent when you realize
+   that you can create as many different construction
+   environments as you need,
+   each tailored to a different way to build
+   some piece of software or other file.
+   If, for example, we need to build
+   one program with the <literal>-O2</literal> flag
+   and another with the <literal>-g</literal> (debug) flag,
+   we would do this like so:
 
    </para>
 
@@ -489,10 +472,10 @@ environment undisturbed.
    </programlisting>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c -O2 bar.c -o bar.o
+      % <userinput>scons -Q</userinput>
+      cc -g -c -o bar.o bar.c
       cc -o bar bar.o
-      cc -c -g foo.c -o foo.o
+      cc -O2 -c -o foo.o foo.c
       cc -o foo foo.o
    </literallayout>
 
@@ -522,8 +505,9 @@ environment undisturbed.
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      scons: *** Two different environments were specified for the same target:  foo.o
+      % <userinput>scons -Q</userinput>
+      
+      scons: *** Two different environments were specified for the same target: foo.o
       File "SConstruct", line 6, in ?
    </literallayout>
 
@@ -536,6 +520,9 @@ environment undisturbed.
    <literal>-O2</literal>
    and one with a &CCFLAGS; value of
    <literal>-g</literal>.
+   &SCons; can't just decide that one of them
+   should take precedence over the other,
+   so it generates the error.
    To avoid this problem,
    we must explicitly specify
    that each environment compile
@@ -546,6 +533,9 @@ environment undisturbed.
    </para>
 
    <programlisting>
+   </programlisting>
+
+   <programlisting>
       opt = Environment(CCFLAGS = '-O2')
       dbg = Environment(CCFLAGS = '-g')
 
@@ -561,7 +551,7 @@ environment undisturbed.
    Notice that each call to the &Object; builder
    returns a value,
    an internal &SCons; object that
-   represents the file that will be built.
+   represents the object file that will be built.
    We then use that object
    as input to the &Program; builder.
    This avoids having to specify explicitly
@@ -573,10 +563,10 @@ environment undisturbed.
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c -g foo.c -o foo-dbg.o
+      % <userinput>scons -Q</userinput>
+      cc -g -c -o foo-dbg.o foo.c
       cc -o foo-dbg foo-dbg.o
-      cc -c -O2 foo.c -o foo-opt.o
+      cc -O2 -c -o foo-opt.o foo.c
       cc -o foo-opt foo-opt.o
    </literallayout>
 
@@ -608,7 +598,7 @@ environment undisturbed.
    that sets &CC; to &gcc;,
    and then creating two copies,
    one which sets &CCFLAGS; for optimization
-   and the other with sets &CCFLAGS; for debugging:
+   and the other which sets &CCFLAGS; for debugging:
 
    </para>
 
@@ -617,7 +607,7 @@ environment undisturbed.
       opt = env.Copy(CCFLAGS = '-O2')
       dbg = env.Copy(CCFLAGS = '-g')
 
-      e = opt.Object('foo', 'foo.c')
+      env.Program('foo', 'foo.c')
 
       o = opt.Object('foo-opt', 'foo.c')
       opt.Program(o)
@@ -633,12 +623,12 @@ environment undisturbed.
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      gcc -c foo.c -o foo.o
+      % <userinput>scons -Q</userinput>
+      gcc -c -o foo.o foo.c
       gcc -o foo foo.o
-      gcc -c -g foo.c -o foo-dbg.o
+      gcc -g -c -o foo-dbg.o foo.c
       gcc -o foo-dbg foo-dbg.o
-      gcc -c -O2 foo.c -o foo-opt.o
+      gcc -O2 -c -o foo-opt.o foo.c
       gcc -o foo-opt foo-opt.o
    </literallayout>
 
@@ -669,8 +659,9 @@ environment undisturbed.
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
+      % <userinput>scons -Q</userinput>
       CC is: cc
+      scons: `.' is up to date.
    </literallayout>
 
    <para>
@@ -687,21 +678,38 @@ environment undisturbed.
    <programlisting>
       env = Environment(FOO = 'foo', BAR = 'bar')
       dict = env.Dictionary()
-      for key, value in dict.items():
-          print "key = %s, value = %s % (key, value)
+      for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
+          print "key = %s, value = %s" % (key, dict[key])
    </programlisting>
 
    <para>
 
    This &SConstruct; file
-   will print the dictionary items for us as follows:
+   will print the specified dictionary items for us on POSIX
+   systems as follows:
+
+   </para>
+
+   <literallayout>
+      % <userinput>scons -Q</userinput>
+      key = OBJSUFFIX, value = .o
+      key = LIBSUFFIX, value = .a
+      key = PROGSUFFIX, value = 
+      scons: `.' is up to date.
+   </literallayout>
+
+   <para>
+
+   And on Win32:
 
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      key = FOO, value = foo
-      key = BAR, value = bar
+      C:\><userinput>scons -Q</userinput>
+      key = OBJSUFFIX, value = .obj
+      key = LIBSUFFIX, value = .lib
+      key = PROGSUFFIX, value = .exe
+      scons: `.' is up to date.
    </literallayout>
 
  </section>
@@ -727,7 +735,7 @@ environment undisturbed.
      </para>
 
      <programlisting>
-        env = Environment(CCFLAGS = '-DDEFINE1)
+        env = Environment(CCFLAGS = '-DDEFINE1')
         env.Program('foo.c')
         env.Replace(CCFLAGS = '-DDEFINE2')
         env.Program('bar.c')
@@ -740,11 +748,11 @@ environment undisturbed.
      </para>
 
      <literallayout>
-        % <userinput>scons</userinput>
-        gcc -DDEFINE2 -c bar.c -o bar.o
-        gcc -o bar bar.o
-        gcc -DDEFINE2 -c foo.c -o foo.o
-        gcc -o foo foo.o
+        % <userinput>scons -Q</userinput>
+        cc -DDEFINE2 -c -o bar.o bar.c
+        cc -o bar bar.o
+        cc -DDEFINE1 -c -o foo.o foo.c
+        cc -o foo foo.o
      </literallayout>
 
    </section>
@@ -767,9 +775,9 @@ environment undisturbed.
      </programlisting>
 
      <literallayout>
-        % <userinput>scons</userinput>
-        gcc -DMY_VALUE -DLAST -c foo.c -o foo.o
-        gcc -o foo foo.o
+        % <userinput>scons -Q</userinput>
+        cc -DMY_VALUE -DLAST -c -o foo.o foo.c
+        cc -o foo foo.o
      </literallayout>
 
    </section>
@@ -792,9 +800,9 @@ environment undisturbed.
      </programlisting>
 
      <literallayout>
-        % <userinput>scons</userinput>
-        gcc -DFIRST -DMY_VALUE -c foo.c -o foo.o
-        gcc -o foo foo.o
+        % <userinput>scons -Q</userinput>
+        cc -DFIRST -DMY_VALUE -c -o foo.o foo.c
+        cc -o foo foo.o
      </literallayout>
 
    </section>
diff --git a/doc/user/help.in b/doc/user/help.in
index 96e775b..087f3bf 100644
--- a/doc/user/help.in
+++ b/doc/user/help.in
@@ -28,14 +28,14 @@
    It's often very useful to be able to give
    users some help that describes the
    specific targets, build options, etc.,
-   that can be used for the build.
+   that can be used for your build.
    &SCons; provides the &Help; function
    to allow you to specify this help text:
 
    </para>
 
    <scons_example name="ex1">
-      <file name="SConstruct">
+      <file name="SConstruct" printme="1">
       Help("""
       Type: 'scons program' to build the production program,
             'scons debug' to build the debug version.
diff --git a/doc/user/help.sgml b/doc/user/help.sgml
index 233809e..72e09aa 100644
--- a/doc/user/help.sgml
+++ b/doc/user/help.sgml
@@ -28,7 +28,7 @@
    It's often very useful to be able to give
    users some help that describes the
    specific targets, build options, etc.,
-   that can be used for the build.
+   that can be used for your build.
    &SCons; provides the &Help; function
    to allow you to specify this help text:
 
@@ -60,8 +60,13 @@
 
    <literallayout>
       % <userinput>scons -h</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      
       Type: 'scons program' to build the production program,
             'scons debug' to build the debug version.
+      
+      Use scons -H for help about command-line options.
    </literallayout>
 
    <para>
diff --git a/doc/user/install.in b/doc/user/install.in
index a263f65..370ca9f 100644
--- a/doc/user/install.in
+++ b/doc/user/install.in
@@ -62,8 +62,8 @@
   </para>
 
   <scons_output example="ex1">
-     <command>scons</command>
-     <command>scons __ROOT__/usr/bin</command>
+     <command>scons -Q</command>
+     <command>scons -Q __ROOT__/usr/bin</command>
   </scons_output>
 
   <para>
@@ -100,9 +100,9 @@
 
   </para>
 
-  <scons_output example="ex1">
-     <command>scons</command>
-     <command>scons install</command>
+  <scons_output example="ex2">
+     <command>scons -Q</command>
+     <command>scons -Q install</command>
   </scons_output>
 
   <section>
@@ -127,6 +127,9 @@
       <file name="hello.c">
       int main() { printf("Hello, world!\n"); }
       </file>
+      <file name="goodbye.c">
+      int main() { printf("Goodbye, world!\n"); }
+      </file>
     </scons_example>
 
     <para>
@@ -152,7 +155,7 @@
     </para>
 
     <scons_output example="ex3">
-       <command>scons install</command>
+       <command>scons -Q install</command>
     </scons_output>
 
   </section>
@@ -191,7 +194,7 @@
     </para>
 
     <scons_output example="ex4">
-       <command>scons install</command>
+       <command>scons -Q install</command>
     </scons_output>
 
   </section>
@@ -218,10 +221,14 @@
        env.InstallAs(['__ROOT__/usr/bin/hello-new',
                       '__ROOT__/usr/bin/goodbye-new'],
                      [hello, goodbye])
+       env.Alias('install', '__ROOT__/usr/bin')
       </file>
       <file name="hello.c">
       int main() { printf("Hello, world!\n"); }
       </file>
+      <file name="goodbye.c">
+      int main() { printf("Goodbye, world!\n"); }
+      </file>
     </scons_example>
 
     <para>
@@ -234,7 +241,7 @@
     </para>
 
     <scons_output example="ex5">
-       <command>scons install</command>
+       <command>scons -Q install</command>
     </scons_output>
 
   </section>
diff --git a/doc/user/install.sgml b/doc/user/install.sgml
index 7f522e5..b7555b7 100644
--- a/doc/user/install.sgml
+++ b/doc/user/install.sgml
@@ -57,10 +57,10 @@
   </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 /usr/bin</userinput>
+     % <userinput>scons -Q /usr/bin</userinput>
      Install file: "hello" as "/usr/bin/hello"
   </literallayout>
 
@@ -94,7 +94,10 @@
   </para>
 
   <literallayout>
-     % <userinput>scons install</userinput>
+     % <userinput>scons -Q</userinput>
+     cc -c -o hello.o hello.c
+     cc -o hello hello.o
+     % <userinput>scons -Q install</userinput>
      Install file: "hello" as "/usr/bin/hello"
   </literallayout>
 
@@ -113,7 +116,7 @@
        hello = env.Program('hello.c')
        goodbye = env.Program('goodbye.c')
        env.Install('/usr/bin', hello)
-       env.Install('/usr/bin', goodbye])
+       env.Install('/usr/bin', goodbye)
        env.Alias('install', '/usr/bin')
     </programlisting>
 
@@ -140,12 +143,12 @@
     </para>
 
     <literallayout>
-       % <userinput>scons install</userinput>
-       cc -c goodbye.c -o goodbye.o
+       % <userinput>scons -Q install</userinput>
+       cc -c -o goodbye.o goodbye.c
        cc -o goodbye goodbye.o
-       cc -c hello.c -o hello.o
-       cc -o hello hello.o
        Install file: "goodbye" as "/usr/bin/goodbye"
+       cc -c -o hello.o hello.c
+       cc -o hello hello.o
        Install file: "hello" as "/usr/bin/hello"
     </literallayout>
 
@@ -180,8 +183,8 @@
     </para>
 
     <literallayout>
-       % <userinput>scons install</userinput>
-       cc -c hello.c -o hello.o
+       % <userinput>scons -Q install</userinput>
+       cc -c -o hello.o hello.c
        cc -o hello hello.o
        Install file: "hello" as "/usr/bin/hello-new"
     </literallayout>
@@ -207,8 +210,9 @@
        hello = env.Program('hello.c')
        goodbye = env.Program('goodbye.c')
        env.InstallAs(['/usr/bin/hello-new',
-                      '/usr/bin/goodbye-new',
+                      '/usr/bin/goodbye-new'],
                      [hello, goodbye])
+       env.Alias('install', '/usr/bin')
     </programlisting>
 
     <para>
@@ -221,12 +225,12 @@
     </para>
 
     <literallayout>
-       % <userinput>scons install</userinput>
-       cc -c goodbye.c -o goodbye.o
+       % <userinput>scons -Q install</userinput>
+       cc -c -o goodbye.o goodbye.c
        cc -o goodbye goodbye.o
-       cc -c hello.c -o hello.o
-       cc -o hello hello.o
        Install file: "goodbye" as "/usr/bin/goodbye-new"
+       cc -c -o hello.o hello.c
+       cc -o hello hello.o
        Install file: "hello" as "/usr/bin/hello-new"
     </literallayout>
 
diff --git a/doc/user/libraries.in b/doc/user/libraries.in
index 337b0da..a69bbee 100644
--- a/doc/user/libraries.in
+++ b/doc/user/libraries.in
@@ -43,8 +43,7 @@
 
     <scons_example name="ex1" printme="1">
       <file name="SConstruct" printme="1">
-      env = Environment()
-      env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
       </file>
       <file name="hello.c">
       int main() { printf("Hello, world!\n"); }
@@ -69,8 +68,8 @@
 
     </para>
 
-    <scons_output example="ex1">
-      <command>scons</command>
+    <scons_output example="ex1" os="posix">
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -80,8 +79,8 @@
 
     </para>
 
-    <scons_output example="ex1">
-      <command>scons</command>
+    <scons_output example="ex1" os="win32">
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -110,14 +109,14 @@
     and by specifying the directory in which
     the library will be found in the 
     &LIBPATH; construction variable:
+      env = Environment(LIBS = 'foo', LIBPATH = '.')
 
     </para>
 
     <scons_example name="ex2">
-      <file name="SConstruct">
-      env = Environment(LIBS = 'foo', LIBPATH = '.')
-      env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
-      env.Program('prog.c')
+      <file name="SConstruct" printme="1">
+      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+      Program('prog.c', LIBS='foo', LIBPATH='.')
       </file>
       <file name="f1.c">
       int main() { printf("Hello, world!\n"); }
@@ -149,8 +148,8 @@
 
     </para>
 
-    <scons_output example="ex2">
-      <command>scons</command>
+    <scons_output example="ex2" os="posix">
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -161,7 +160,7 @@
     </para>
 
     <scons_output example="ex2" os="win32">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -191,9 +190,8 @@
 
     <scons_example name="ex3">
       <file name="SConstruct" printme="1">
-      env = Environment(LIBS = 'm',
+      Program('prog.c', LIBS = 'm',
                         LIBPATH = ['/usr/lib', '/usr/local/lib'])
-      env.Program('prog.c')
       </file>
       <file name="prog.c">
       int main() { printf("prog.c\n"); }
@@ -235,8 +233,8 @@
 
     </para>
 
-    <scons_output example="ex3">
-      <command>scons</command>
+    <scons_output example="ex3" os="posix">
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
@@ -247,7 +245,7 @@
     </para>
 
     <scons_output example="ex3" os="win32">
-      <command>scons</command>
+      <command>scons -Q</command>
     </scons_output>
 
     <para>
diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml
index 6fc6c5d..118a560 100644
--- a/doc/user/libraries.sgml
+++ b/doc/user/libraries.sgml
@@ -42,8 +42,7 @@
     </para>
 
     <programlisting>
-      env = Environment()
-      env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
     </programlisting>
 
     <para>
@@ -51,15 +50,15 @@
     &SCons; uses the appropriate library prefix and suffix for your system.
     So on POSIX or Linux systems,
     the above example would build as follows
-    (although &ranlib may not be called on all systems):
+    (although &ranlib; may not be called on all systems):
 
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      cc -c f1.c -o f1.o
-      cc -c f2.c -o f2.o
-      cc -c f3.c -o f3.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o f1.o f1.c
+      cc -c -o f2.o f2.c
+      cc -c -o f3.o f3.c
       ar r libfoo.a f1.o f2.o f3.o
       ranlib libfoo.a
     </literallayout>
@@ -72,10 +71,10 @@
     </para>
 
     <literallayout>
-      C:\><userinput>scons</userinput>
-      cl /Fof1.obj f1.c
-      cl /Fof2.obj f2.c
-      cl /Fof3.obj f3.c
+      C:\><userinput>scons -Q</userinput>
+      cl /nologo /c f1.c /Fof1.obj
+      cl /nologo /c f2.c /Fof2.obj
+      cl /nologo /c f3.c /Fof3.obj
       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
     </literallayout>
 
@@ -105,13 +104,13 @@
     and by specifying the directory in which
     the library will be found in the 
     &LIBPATH; construction variable:
+      env = Environment(LIBS = 'foo', LIBPATH = '.')
 
     </para>
 
     <programlisting>
-      env = Environment(LIBS = 'foo', LIBPATH = '.')
-      env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
-      env.Program('prog.c')
+      Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+      Program('prog.c', LIBS='foo', LIBPATH='.')
     </programlisting>
 
     <para>
@@ -131,14 +130,14 @@
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      cc -c f1.c -o f1.o
-      cc -c f2.c -o f2.o
-      cc -c f3.c -o f3.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o f1.o f1.c
+      cc -c -o f2.o f2.c
+      cc -c -o f3.o f3.c
       ar r libfoo.a f1.o f2.o f3.o
       ranlib libfoo.a
-      cc -c prog.c -o prog.o
-      cc -o prog -L. -lfoo prog.o
+      cc -c -o prog.o prog.c
+      cc -o prog prog.o -L. -lfoo
     </literallayout>
 
     <para>
@@ -149,13 +148,13 @@
     </para>
 
     <literallayout>
-      C:\><userinput>scons</userinput>
-      cl /Fof1.obj f1.c
-      cl /Fof2.obj f2.c
-      cl /Fof3.obj f3.c
+      C:\><userinput>scons -Q</userinput>
+      cl /nologo /c f1.c /Fof1.obj
+      cl /nologo /c f2.c /Fof2.obj
+      cl /nologo /c f3.c /Fof3.obj
       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
-      cl /Foprog.obj prog.c
-      link /OUT:prog.exe /LIBPATH:. foo.lib prog.obj
+      cl /nologo /c prog.c /Foprog.obj
+      link /nologo /OUT:prog.exe /LIBPATH:. foo.lib prog.obj
     </literallayout>
 
     <para>
@@ -184,9 +183,8 @@
     </para>
 
     <programlisting>
-      env = Environment(LIBS = 'm',
+      Program('prog.c', LIBS = 'm',
                         LIBPATH = ['/usr/lib', '/usr/local/lib'])
-      env.Program('prog.c')
     </programlisting>
 
     <para>
@@ -225,9 +223,9 @@
     </para>
 
     <literallayout>
-      % <userinput>scons</userinput>
-      cc -c prog.c -o prog.o
-      cc -o prog -L/usr/lib -L/usr/local/lib -lm prog.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o prog.o prog.c
+      cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
     </literallayout>
 
     <para>
@@ -238,9 +236,9 @@
     </para>
 
     <literallayout>
-      C:\><userinput>scons</userinput>
-      cl /Foprog.obj prog.c
-      link /nologo /OUT:program.exe /LIBPATH:\usr\lib;\usr\local\lib m.lib prog.obj
+      C:\><userinput>scons -Q</userinput>
+      cl /nologo /c prog.c /Foprog.obj
+      link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
     </literallayout>
 
     <para>
diff --git a/doc/user/precious.in b/doc/user/precious.in
index 2be22ec..95a2c56 100644
--- a/doc/user/precious.in
+++ b/doc/user/precious.in
@@ -55,8 +55,7 @@ which the C<AfterBuild> method is called.
 
  <scons_example name="ex1">
    <file name="SConstruct" printme="1">
-    env = Environment(XXX NEED LIBRARY FLAGS
-                      LIBFLAGS = '-r')
+    env = Environment()
     lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
     env.Precious(lib)
    </file>
@@ -73,17 +72,19 @@ which the C<AfterBuild> method is called.
 
  <para>
 
- XXX:
+ Although the output doesn't look any different,
+ &SCons; does not, in fact,
+ delete the target library before rebuilding it:
 
  </para>
 
  <scons_output example="ex1">
-    <command>scons</command>
+    <command>scons -Q</command>
  </scons_output>
 
  <para>
 
- &SCons; will still delete files marked as &Precious;
+ &SCons; will, however, still delete files marked as &Precious;
  when the <literal>-c</literal> option is used.
 
  </para>
diff --git a/doc/user/precious.sgml b/doc/user/precious.sgml
index 26ad345..4453d4b 100644
--- a/doc/user/precious.sgml
+++ b/doc/user/precious.sgml
@@ -54,26 +54,31 @@ which the C<AfterBuild> method is called.
  </para>
 
  <programlisting>
-    env = Environment(XXX NEED LIBRARY FLAGS
-                      LIBFLAGS = '-r')
+    env = Environment()
     lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
     env.Precious(lib)
  </programlisting>
 
  <para>
 
- XXX:
+ Although the output doesn't look any different,
+ &SCons; does not, in fact,
+ delete the target library before rebuilding it:
 
  </para>
 
  <literallayout>
-    % <userinput>scons</userinput>
-    XXX ANY INPUT HERE?
+    % <userinput>scons -Q</userinput>
+    cc -c -o f1.o f1.c
+    cc -c -o f2.o f2.c
+    cc -c -o f3.o f3.c
+    ar r libfoo.a f1.o f2.o f3.o
+    ranlib libfoo.a
  </literallayout>
 
  <para>
 
- &SCons; will still delete files marked as &Precious;
+ &SCons; will, however, still delete files marked as &Precious;
  when the <literal>-c</literal> option is used.
 
  </para>
diff --git a/doc/user/run.in b/doc/user/run.in
index 83ca3d2..d8e19f8 100644
--- a/doc/user/run.in
+++ b/doc/user/run.in
@@ -316,6 +316,28 @@ do an unconstrained build before committing the integration).
   </para>
 
   <section>
+  <title>Command-Line Options</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Getting at Command-Line Arguments</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+  </section>
+
+  <section>
   <title>Selective Builds</title>
 
     <para>
@@ -357,7 +379,37 @@ do an unconstrained build before committing the integration).
 
     <para>
 
-    XXX
+    Users may find themselves supplying
+    the same command-line options every time
+    they run &SCons;.
+    For example, a user might find that it saves time
+    to always specify a value of <literal>-j 2</literal>
+    to run the builds in parallel.
+
+    </para>
+
+    <scons_example name="SCONSFLAGS">
+      <file name="SConstruct">
+      def b(target, source, env):
+          pass
+      def s(target, source, env):
+          return "    ..."
+      a = Action(b, strfunction = s)
+      env = Environment(BUILDERS = {'A' : a})
+      env.A('foo.out', 'foo.in')
+      </file>
+      <file name="foo.in">
+      foo.in
+      </file>
+    </scons_example>
+
+    <scons_output example="SCONSFLAGS">
+      <command>scons</command>
+      <command>export SCONSFLAGS="-Q"</command>
+      <command>scons</command>
+    </scons_output>
+
+    <para>
 
     </para>
 
diff --git a/doc/user/run.sgml b/doc/user/run.sgml
index 83ca3d2..9cdb07c 100644
--- a/doc/user/run.sgml
+++ b/doc/user/run.sgml
@@ -316,6 +316,28 @@ do an unconstrained build before committing the integration).
   </para>
 
   <section>
+  <title>Command-Line Options</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Getting at Command-Line Arguments</title>
+
+    <para>
+
+    XXX
+
+    </para>
+
+  </section>
+
+  <section>
   <title>Selective Builds</title>
 
     <para>
@@ -357,7 +379,36 @@ do an unconstrained build before committing the integration).
 
     <para>
 
-    XXX
+    Users may find themselves supplying
+    the same command-line options every time
+    they run &SCons;.
+    For example, a user might find that it saves time
+    to always specify a value of <literal>-j 2</literal>
+    to run the builds in parallel.
+
+    </para>
+
+    
+
+    <literallayout>
+      % <userinput>scons</userinput>
+      scons: Reading SConscript files ...
+          ...
+      scons: done reading SConscript files.
+      scons: Building targets ...
+      scons: `.' is up to date.
+      scons: done building targets.
+      % <userinput>export SCONSFLAGS="-Q"</userinput>
+      % <userinput>scons</userinput>
+      scons: Reading SConscript files ...
+          ...
+      scons: done reading SConscript files.
+      scons: Building targets ...
+      scons: `.' is up to date.
+      scons: done building targets.
+    </literallayout>
+
+    <para>
 
     </para>
 
diff --git a/doc/user/simple.in b/doc/user/simple.in
index df82ea2..3940bc3 100644
--- a/doc/user/simple.in
+++ b/doc/user/simple.in
@@ -46,8 +46,7 @@
 
  <scons_example name="ex1">
     <file name="SConstruct" printme="1">
-    env = Environment()
-    env.Program('hello.c')
+    Program('hello.c')
     </file>
     <file name="hello.c">
     int main() { printf("Hello, world!\n"); }
@@ -148,9 +147,8 @@
    </para>
 
    <programlisting>
-      env = Environment()    # Create an environment.
       # Arrange to build the "hello" program.
-      env.Program('hello.c')
+      Program('hello.c')    # "hello.c" is the source file.
    </programlisting>
 
    <para>
@@ -166,6 +164,59 @@
  </section>
 
  <section>
+ <title>Making the Output Less Verbose</title>
+
+   <para>
+
+   You've already seen how &SCons; prints
+   some messages about what it's doing,
+   surrounding the actual commands used to build the software:
+
+   </para>
+
+   <scons_output example="ex1" os="win32">
+      <command>scons</command>
+   </scons_output>
+
+   <para>
+
+   These messages emphasize the
+   order in which &SCons; does its work:
+   the configuration files
+   (generically referred to as &SConscript; files)
+   are read and executed first,
+   and only then are the target files built.
+   Among other benefits, these messages help to distinguish between
+   errors that occur while the configuration files are read,
+   and errors that occur while targets are being built.
+
+   </para>
+
+   <para>
+
+   The drawback, of course, is that these messages clutter the output.
+   Fortunately, they're easily disabled by using
+   the &Q; option when invoking &SCons;:
+
+   </para>
+
+   <scons_output example="ex1" os="win32">
+      <command>scons -Q</command>
+   </scons_output>
+
+   <para>
+
+   Because we want this User's Guide to focus
+   on what &SCons; is actually doing,
+   we're going use the &Q; option
+   to remove these messages from the
+   output of all the remaining examples in this Guide.
+
+   </para>
+
+ </section>
+
+ <section>
  <title>Compiling Multiple Source Files</title>
 
    <para>
@@ -184,8 +235,7 @@
 
    <scons_example name="ex2">
       <file name="SConstruct" printme="1">
-      env = Environment()
-      env.Program(['prog.c', 'file1.c', 'file2.c'])
+      Program(['prog.c', 'file1.c', 'file2.c'])
       </file>
       <file name="prog.c">
       int main() { printf("prog.c\n"); }
@@ -205,7 +255,7 @@
    </para>
 
    <scons_output example="ex2">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
    <para>
@@ -231,8 +281,7 @@
 
    <scons_example name="ex3">
       <file name="SConstruct" printme="1">
-      env = Environment()
-      env.Program('program', ['main.c', 'file1.c', 'file2.c'])
+      Program('program', ['main.c', 'file1.c', 'file2.c'])
       </file>
       <file name="main.c">
       int main() { printf("prog.c\n"); }
@@ -252,7 +301,7 @@
    </para>
 
    <scons_output example="ex3" os="posix">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
    <para>
@@ -262,7 +311,7 @@
    </para>
 
    <scons_output example="ex3" os="win32">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
  </section>
@@ -298,27 +347,42 @@
    </para>
 
    <programlisting>
-      env = Environment()
-      env.Program('program', Split('main.c file1.c file2.'))
+      Program('program', Split('main.c file1.c file2.'))
    </programlisting>
 
    <para>
 
+   (If you're already familiar with Python,
+   you'll have realized that this is similar to the
+   <function>split()</function> method
+   in the Python standard <function>string</function> module.
+   Unlike the <function>string.split()</function> method,
+   however, the &Split; function
+   does not require a string as input
+   and will wrap up a single non-string object in a list,
+   or return its argument untouched if it's already a list.
+   This comes in handy as a way to make sure
+   arbitrary values can be passed to &SCons; functions
+   without having to check the type of the variable by hand.)
+
+   </para>
+
+   <para>
+
    Putting the call to the &Split; function
-   inside the <function>env.Program</function> call
+   inside the <function>Program</function> call
    can also be a little unwieldy.
    A more readable alternative is to
    assign the output from the &Split; call
    to a variable name,
    and then use the variable when calling the
-   <function>env.Program</function> function:
+   <function>Program</function> function:
 
    </para>
 
    <programlisting>
-      env = Environment()
       list = Split('main.c file1.c file2.')
-      env.Program('program', list)
+      Program('program', list)
    </programlisting>
 
    <para>
@@ -333,11 +397,10 @@
    </para>
 
    <programlisting>
-      env = Environment()
       list = Split('main.c
                     file1.c
                     file2.c')
-      env.Program('program', list)
+      Program('program', list)
    </programlisting>
 
  </section>
@@ -359,17 +422,31 @@
    </para>
 
    <programlisting>
-      env = Environment()
       list = Split('main.c file1.c file2.')
-      env.Program(target = 'program', source = list)
+      Program(target = 'program', source = list)
+   </programlisting>
+
+   <para>
+
+   Because the keywords explicitly identify
+   what each argument is,
+   you can actually reverse the order if you prefer:
+
+   </para>
+
+   <programlisting>
+      list = Split('main.c file1.c file2.')
+      Program(source = list, target = 'program')
    </programlisting>
 
    <para>
 
    Whether or not you choose to use keyword arguments
-   to identify the target and source files
-   is purely a personal choice;
-   &SCons; functions the same either way.
+   to identify the target and source files,
+   and the order in which you specify them
+   when using keywords,
+   are purely personal choices;
+   &SCons; functions the same regardless.
 
    </para>
 
@@ -382,7 +459,7 @@
 
    In order to compile multiple programs
    within the same &SConstruct; file,
-   simply call the <function>env.Program</function> method
+   simply call the <function>Program</function> method
    multiple times,
    once for each program you need to build:
 
@@ -390,9 +467,8 @@
 
    <scons_example name="ex4">
       <file name="SConstruct" printme="1">
-      env = Environment()
-      env.Program('foo.c')
-      env.Program('bar', ['bar1.c', 'bar2.c'])
+      Program('foo.c')
+      Program('bar', ['bar1.c', 'bar2.c'])
       </file>
       <file name="foo.c">
       int main() { printf("foo.c\n"); }
@@ -412,7 +488,7 @@
    </para>
 
    <scons_output example="ex4">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
    <para>
@@ -456,9 +532,8 @@
 
    <scons_example name="ex5">
       <file name="SConstruct" printme="1">
-      env = Environment()
-      env.Program(Split('foo.c common1.c common2.c'))
-      env.Program('bar', Split('bar1.c bar2.c common1.c common2.c'))
+      Program(Split('foo.c common1.c common2.c'))
+      Program('bar', Split('bar1.c bar2.c common1.c common2.c'))
       </file>
       <file name="foo.c">
       int main() { printf("foo.c\n"); }
@@ -482,12 +557,13 @@
    &SCons; recognizes that the object files for
    the &common1_c; and &common2_c; source files
    each only need to be built once,
-   even though the files are listed multiple times:
+   even though the resulting object files are
+   each linked in to both of the resulting executable programs:
 
    </para>
 
    <scons_output example="ex5">
-      <command>scons</command>
+      <command>scons -Q</command>
    </scons_output>
 
    <para>
@@ -508,9 +584,8 @@
       common = ['common1.c', 'common2.c']
       foo_files = ['foo.c'] + common
       bar_files = ['bar1.c', 'bar2.c'] + common
-      env = Environment()
-      env.Program('foo', foo_files)
-      env.Program('bar', bar_files)
+      Program('foo', foo_files)
+      Program('bar', bar_files)
    </programlisting>
 
    <para>
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
index d97badc..02a57ef 100644
--- a/doc/user/simple.sgml
+++ b/doc/user/simple.sgml
@@ -45,8 +45,7 @@
  </para>
 
  <programlisting>
-    env = Environment()
-    env.Program('hello.c')
+    Program('hello.c')
  </programlisting>
 
  <para>
@@ -59,8 +58,12 @@
 
  <literallayout>
     % <userinput>scons</userinput>
-    cc -c hello.c -o hello.o
+    scons: Reading SConscript files ...
+    scons: done reading SConscript files.
+    scons: Building targets ...
+    cc -c -o hello.o hello.c
     cc -o hello hello.o
+    scons: done building targets.
  </literallayout>
 
  <para>
@@ -72,8 +75,12 @@
 
  <literallayout>
     C:\><userinput>scons</userinput>
-    cl /Fohello.obj hello.c
-    link /Fohello.exe hello.obj
+    scons: Reading SConscript files ...
+    scons: done reading SConscript files.
+    scons: Building targets ...
+    cl /nologo /c hello.c /Fohello.obj
+    link /nologo /OUT:hello.exe hello.obj
+    scons: done building targets.
  </literallayout>
 
  <para>
@@ -147,9 +154,8 @@
    </para>
 
    <programlisting>
-      env = Environment()    # Create an environment.
       # Arrange to build the "hello" program.
-      env.Program('hello.c')
+      Program('hello.c')    # "hello.c" is the source file.
    </programlisting>
 
    <para>
@@ -165,6 +171,67 @@
  </section>
 
  <section>
+ <title>Making the Output Less Verbose</title>
+
+   <para>
+
+   You've already seen how &SCons; prints
+   some messages about what it's doing,
+   surrounding the actual commands used to build the software:
+
+   </para>
+
+   <literallayout>
+      C:\><userinput>scons</userinput>
+      scons: Reading SConscript files ...
+      scons: done reading SConscript files.
+      scons: Building targets ...
+      cl /nologo /c hello.c /Fohello.obj
+      link /nologo /OUT:hello.exe hello.obj
+      scons: done building targets.
+   </literallayout>
+
+   <para>
+
+   These messages emphasize the
+   order in which &SCons; does its work:
+   the configuration files
+   (generically referred to as &SConscript; files)
+   are read and executed first,
+   and only then are the target files built.
+   Among other benefits, these messages help to distinguish between
+   errors that occur while the configuration files are read,
+   and errors that occur while targets are being built.
+
+   </para>
+
+   <para>
+
+   The drawback, of course, is that these messages clutter the output.
+   Fortunately, they're easily disabled by using
+   the &Q; option when invoking &SCons;:
+
+   </para>
+
+   <literallayout>
+      C:\><userinput>scons -Q</userinput>
+      cl /nologo /c hello.c /Fohello.obj
+      link /nologo /OUT:hello.exe hello.obj
+   </literallayout>
+
+   <para>
+
+   Because we want this User's Guide to focus
+   on what &SCons; is actually doing,
+   we're going use the &Q; option
+   to remove these messages from the
+   output of all the remaining examples in this Guide.
+
+   </para>
+
+ </section>
+
+ <section>
  <title>Compiling Multiple Source Files</title>
 
    <para>
@@ -182,8 +249,7 @@
    </para>
 
    <programlisting>
-      env = Environment()
-      env.Program(['prog.c', 'file1.c', 'file2.'])
+      Program(['prog.c', 'file1.c', 'file2.c'])
    </programlisting>
 
    <para>
@@ -193,10 +259,10 @@
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c file1.c -o file1.o
-      cc -c file2.c -o file2.o
-      cc -c prog.c -o prog.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o file1.o file1.c
+      cc -c -o file2.o file2.c
+      cc -c -o prog.o prog.c
       cc -o prog prog.o file1.o file2.o
    </literallayout>
 
@@ -222,8 +288,7 @@
    </para>
 
    <programlisting>
-      env = Environment()
-      env.Program('program', ['main.c', 'file1.c', 'file2.'])
+      Program('program', ['main.c', 'file1.c', 'file2.c'])
    </programlisting>
 
    <para>
@@ -233,10 +298,10 @@
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c file1.c -o file1.o
-      cc -c file2.c -o file2.o
-      cc -c main.c -o main.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o file1.o file1.c
+      cc -c -o file2.o file2.c
+      cc -c -o main.o main.c
       cc -o program main.o file1.o file2.o
    </literallayout>
 
@@ -247,11 +312,11 @@
    </para>
 
    <literallayout>
-      C:\><userinput>scons</userinput>
-      cl /Fofile1.obj file1.c
-      cl /Fofile2.obj file2.c
-      cl /Fomain.obj main.c
-      link /Foprogram.exe main.obj file1.obj file2.obj
+      C:\><userinput>scons -Q</userinput>
+      cl /nologo /c file1.c /Fofile1.obj
+      cl /nologo /c file2.c /Fofile2.obj
+      cl /nologo /c main.c /Fomain.obj
+      link /nologo /OUT:program.exe main.obj file1.obj file2.obj
    </literallayout>
 
  </section>
@@ -287,27 +352,42 @@
    </para>
 
    <programlisting>
-      env = Environment()
-      env.Program('program', Split('main.c file1.c file2.'))
+      Program('program', Split('main.c file1.c file2.'))
    </programlisting>
 
    <para>
 
+   (If you're already familiar with Python,
+   you'll have realized that this is similar to the
+   <function>split()</function> method
+   in the Python standard <function>string</function> module.
+   Unlike the <function>string.split()</function> method,
+   however, the &Split; function
+   does not require a string as input
+   and will wrap up a single non-string object in a list,
+   or return its argument untouched if it's already a list.
+   This comes in handy as a way to make sure
+   arbitrary values can be passed to &SCons; functions
+   without having to check the type of the variable by hand.)
+
+   </para>
+
+   <para>
+
    Putting the call to the &Split; function
-   inside the <function>env.Program</function> call
+   inside the <function>Program</function> call
    can also be a little unwieldy.
    A more readable alternative is to
    assign the output from the &Split; call
    to a variable name,
    and then use the variable when calling the
-   <function>env.Program</function> function:
+   <function>Program</function> function:
 
    </para>
 
    <programlisting>
-      env = Environment()
       list = Split('main.c file1.c file2.')
-      env.Program('program', list)
+      Program('program', list)
    </programlisting>
 
    <para>
@@ -322,11 +402,10 @@
    </para>
 
    <programlisting>
-      env = Environment()
       list = Split('main.c
                     file1.c
                     file2.c')
-      env.Program('program', list)
+      Program('program', list)
    </programlisting>
 
  </section>
@@ -348,17 +427,31 @@
    </para>
 
    <programlisting>
-      env = Environment()
       list = Split('main.c file1.c file2.')
-      env.Program(target = 'program', source = list)
+      Program(target = 'program', source = list)
+   </programlisting>
+
+   <para>
+
+   Because the keywords explicitly identify
+   what each argument is,
+   you can actually reverse the order if you prefer:
+
+   </para>
+
+   <programlisting>
+      list = Split('main.c file1.c file2.')
+      Program(source = list, target = 'program')
    </programlisting>
 
    <para>
 
    Whether or not you choose to use keyword arguments
-   to identify the target and source files
-   is purely a personal choice;
-   &SCons; functions the same either way.
+   to identify the target and source files,
+   and the order in which you specify them
+   when using keywords,
+   are purely personal choices;
+   &SCons; functions the same regardless.
 
    </para>
 
@@ -371,16 +464,15 @@
 
    In order to compile multiple programs
    within the same &SConstruct; file,
-   simply call the <function>env.Program</function> method
+   simply call the <function>Program</function> method
    multiple times,
    once for each program you need to build:
 
    </para>
 
    <programlisting>
-      env = Environment()
-      env.Program('foo.c')
-      env.Program('bar', ['bar1.c', 'bar2.c'])
+      Program('foo.c')
+      Program('bar', ['bar1.c', 'bar2.c'])
    </programlisting>
 
    <para>
@@ -390,11 +482,11 @@
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c bar1.c -o bar1.o
-      cc -c bar2.c -o bar2.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o bar1.o bar1.c
+      cc -c -o bar2.o bar2.c
       cc -o bar bar1.o bar2.o
-      cc -c foo.c -o foo.o
+      cc -c -o foo.o foo.c
       cc -o foo foo.o
    </literallayout>
 
@@ -438,9 +530,8 @@
    </para>
 
    <programlisting>
-      env = Environment()
-      env.Program(Split('foo.c common1.c common2.c'))
-      env.Program('bar', Split('bar1.c bar2.c common1.c common2.c'))
+      Program(Split('foo.c common1.c common2.c'))
+      Program('bar', Split('bar1.c bar2.c common1.c common2.c'))
    </programlisting>
 
    <para>
@@ -448,18 +539,19 @@
    &SCons; recognizes that the object files for
    the &common1_c; and &common2_c; source files
    each only need to be built once,
-   even though the files are listed multiple times:
+   even though the resulting object files are
+   each linked in to both of the resulting executable programs:
 
    </para>
 
    <literallayout>
-      % <userinput>scons</userinput>
-      cc -c bar1.c -o bar1.o
-      cc -c bar2.c -o bar2.o
-      cc -c common1.c -o common1.o
-      cc -c common2.c -o common2.o
+      % <userinput>scons -Q</userinput>
+      cc -c -o bar1.o bar1.c
+      cc -c -o bar2.o bar2.c
+      cc -c -o common1.o common1.c
+      cc -c -o common2.o common2.c
       cc -o bar bar1.o bar2.o common1.o common2.o
-      cc -c foo.c -o foo.o
+      cc -c -o foo.o foo.c
       cc -o foo foo.o common1.o common2.o
    </literallayout>
 
@@ -481,9 +573,8 @@
       common = ['common1.c', 'common2.c']
       foo_files = ['foo.c'] + common
       bar_files = ['bar1.c', 'bar2.c'] + common
-      env = Environment()
-      env.Program('foo', foo_files)
-      env.Program('bar', bar_files)
+      Program('foo', foo_files)
+      Program('bar', bar_files)
    </programlisting>
 
    <para>