Branch for User's Guide changes.

10 files changed, 734 insertions, 134 deletions

diff --git a/doc/scons.mod b/doc/scons.mod
index f9deaa1..19190b2 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -15,12 +15,15 @@
 -->
 
 <!ENTITY Aegis "<application>Aegis</application>">
+<!ENTITY Ant "<application>Ant</application>">
 <!ENTITY Autoconf "<application>Autoconf</application>">
+<!ENTITY Automake "<application>Automake</application>">
 <!ENTITY Cons "<application>Cons</application>">
 <!ENTITY gcc "<application>gcc</application>">
 <!ENTITY Jam "<application>Jam</application>">
 <!ENTITY Make "<application>Make</application>">
 <!ENTITY Makepp "<application>Make++</application>">
+<!ENTITY Python "<application>Python</application>">
 <!ENTITY ranlib "<application>ranlib</application>">
 <!ENTITY SCons "<application>SCons</application>">
 <!ENTITY scons "<application>scons</application>">
@@ -63,6 +66,28 @@
 
 <!--
 
+  Options, command-line.
+
+-->
+
+<!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>">
+
+<!--
+
+  Options, SConscript-settable.
+
+-->
+
+<!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>">
+
+
+
+<!--
+
   File and directory names.
 
 -->
@@ -167,6 +192,7 @@
 -->
 
 <!ENTITY build_dir "<varname>build_dir</varname>">
+<!ENTITY exports "<varname>exports</varname>">
 <!ENTITY source "<varname>source</varname>">
 <!ENTITY target "<varname>target</varname>">
 
@@ -255,6 +281,27 @@
 <!ENTITY hello_h "<filename>hello.h</filename>">
 <!ENTITY hello_o "<filename>hello.o</filename>">
 <!ENTITY prog "<filename>prog</filename>">
+<!ENTITY prog1 "<filename>prog1</filename>">
+<!ENTITY prog2 "<filename>prog2</filename>">
 <!ENTITY prog_c "<filename>prog.c</filename>">
 <!ENTITY prog_exe "<filename>prog.exe</filename>">
 <!ENTITY stdio_h "<filename>stdio.h</filename>">
+
+<!--
+
+  Punctuation.
+
+-->
+
+<!ENTITY plus "<literal>+</literal>">
+<!ENTITY hash "<literal>#</literal>">
+
+<!--
+
+  Mailing lists
+
+-->
+
+<!ENTITY scons-announce "<literal>scons-announce@lists.sourceforge.net</literal>">
+<!ENTITY scons-devel "<literal>scons-devel@lists.sourceforge.net</literal>">
+<!ENTITY scons-users "<literal>scons-users@lists.sourceforge.net</literal>">
diff --git a/doc/user/ant.sgml b/doc/user/ant.sgml
index f83ab63..4eb5007 100644
--- a/doc/user/ant.sgml
+++ b/doc/user/ant.sgml
@@ -30,7 +30,18 @@
  </para>
 
  <section>
- <title>XXX</title>
+ <title>Differences Between &Ant; and &SCons;</title>
+
+   <para>
+
+   XXX
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Advantages of &SCons; Over &Ant;</title>
 
    <para>
 
diff --git a/doc/user/cons.sgml b/doc/user/cons.sgml
index f83ab63..be02a51 100644
--- a/doc/user/cons.sgml
+++ b/doc/user/cons.sgml
@@ -30,7 +30,18 @@
  </para>
 
  <section>
- <title>XXX</title>
+ <title>Differences Between &Cons; and &SCons;</title>
+
+   <para>
+
+   XXX
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Advantages of &SCons; Over &Cons;</title>
 
    <para>
 
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index fbbb54a..2049caf 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -48,9 +48,8 @@ operating system on which the build is performed (as reported by C<uname
 
   So far we've seen how &SCons; handles one-time builds.
   But the real point of a build tool like &SCons;
-  is to rebuild the necessary things,
-  and only the necessary thing, when source files change.
-  Put another way,
+  is to rebuild only the necessary things
+  when source files change--or, put another way,
   &SCons; should <emphasis>not</emphasis>
   waste time rebuilding things that have already been built.
   You can see this at work simply be re-invoking &SCons;
@@ -88,8 +87,8 @@ operating system on which the build is performed (as reported by C<uname
 
   <para>
 
-  Note that &SCons; only reports "...is up to date"
-  for target files named explicitly on the command line,
+  Note that &SCons; reports <literal>"...is up to date"</literal>
+  only for target files named explicitly on the command line,
   to avoid cluttering the output.
 
   </para>
@@ -102,7 +101,8 @@ operating system on which the build is performed (as reported by C<uname
     The other side of avoiding unnecessary rebuilds
     is the fundamental build tool behavior
     of <emphasis>rebuilding</emphasis>
-    things when a source file changes.
+    things when a source file changes,
+    so that the built software is up to date.
     &SCons; keeps track of this through a
     &signature; for each source file,
     and allows you to configure
@@ -113,7 +113,7 @@ operating system on which the build is performed (as reported by C<uname
     </para>
 
     <section>
-    <title>MD5 Signatures</title>
+    <title>MD5 Source File Signatures</title>
 
       <para>
 
@@ -185,7 +185,7 @@ operating system on which the build is performed (as reported by C<uname
     </section>
 
     <section>
-    <title>Time Stamps</title>
+    <title>Source File Time Stamps</title>
 
       <para>
 
@@ -231,17 +231,30 @@ operating system on which the build is performed (as reported by C<uname
   <section>
   <title>Target File Signatures</title>
 
+    <para>
+
+    As you've just seen,
+    &SCons; uses signatures to decide whether a 
+    target file is up to date or must be rebuilt.
+    When a target file depends on another target file,
+    &SCons; allows you to separately configure
+    how the signatures of an "intermediate" target file
+    is used when deciding if a dependent target file
+    must be rebuilt.
+
+    </para>
+
     <section>
     <title>Build Signatures</title>
 
       <para>
 
-      We've already seen how modifying a source file
+      Modifying a source file
       will cause not only its direct target file to be rebuilt,
       but also the target file(s)
       that depend on that direct target file.
       In our example,
-      changing the contents of &hello_c; cause
+      changing the contents of the &hello_c; file causes
       the &hello_o; file to be rebuilt,
       which in turn causes the
       &hello; program to be rebuilt:
@@ -304,14 +317,13 @@ operating system on which the build is performed (as reported by C<uname
 
       <para>
 
-      Sometimes, however,
-      a source file can be changed
-      in such a way that the
-      target file(s) built from it
-      will be rebuilt
-      exactly the same as the last time.
-      If so, then any target files
-      that depend on built-but-not-changed target
+      Sometimes a source file can be changed
+      in such a way that the contents of the
+      rebuilt target file(s)
+      will be exactly the same as the last time
+      the file was built.
+      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
@@ -376,7 +388,7 @@ operating system on which the build is performed (as reported by C<uname
 
     Now suppose that our "Hello, World!" program
     actually has a <literal>#include</literal> line
-    to include &hello_h; file in the compilation:
+    to include the &hello_h; file in the compilation:
 
     </para>
 
@@ -524,11 +536,13 @@ operating system on which the build is performed (as reported by C<uname
     the scanning time is usually a very small percentage
     of the overall time spent on the build.
     You're most likely to notice the scanning time,
-    however, when you rebuild all or part of a large system:
-    &SCons; will take some extra time to "think about"
+    however, when you <emphasis>rebuild</emphasis>
+    all or part of a large system:
+    &SCons; will likely take some extra time to "think about"
     what must be built before it issues the
-    first build command,
-    or decides that nothing must be rebuilt.
+    first build command
+    (or decides that everything is up to date
+    and nothing must be rebuilt).
 
  <!--
  Isn't this expensive? The answer is, it depends. If you do a full build of a
@@ -549,9 +563,13 @@ operating system on which the build is performed (as reported by C<uname
     introduced by incorrect dependencies.
     Nevertheless, the "waiting time"
     while &SCons; scans files can annoy
-    individual developers waiting for their builds.
+    individual developers waiting for their builds to finish.
     Consequently, &SCons; lets you cache
     the implicit dependencies
+    that its scanners find,
+    for use by later builds.
+    You do this either by specifying the
+    &implicit-cache; option on the command line:
 
     </para>
 
@@ -565,11 +583,50 @@ operating system on which the build is performed (as reported by C<uname
 
     <para>
 
+    Or by setting the &implicit_cache; option
+    in an &SConscript; file:
+
+    </para>
+
+    <literallayout>
+       SetOption('implicit_cache', 1)
+    </literallayout>
+
+    <para>
+
     &SCons; does not cache implicit dependencies like this by default
     because XXX
+    
+    </para>
+
+    <para>
+    
+    XXX
 
     </para>
 
+    <section>
+    <title>The &implicit-deps-changed; Option</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+    </section>
+
+    <section>
+    <title>The &implicit-deps-unchanged; Option</title>
+
+      <para>
+
+      XXX
+
+      </para>
+
+    </section>
+
   </section>
 
   <section>
@@ -641,13 +698,13 @@ operating system on which the build is performed (as reported by C<uname
     <para>
 
     On the other hand,
-    sometimes a file depends on another
-    file that the scanner(s) in &SCons; will not detect.
+    sometimes a file depends on another file
+    that has no &SCons; scanner will detect.
     For this situation,
-    &SCons; allows you to specific that one file explicitly
+    &SCons; allows you to specific explicitly that one file
     depends on another file,
-    and must be rebuilt whenever that file changes,
-    using the &Depends; method:
+    and must be rebuilt whenever that file changes.
+    This is specified using the &Depends; method:
 
     </para>
 
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index d3c3b0c..2cba46e 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -391,11 +391,10 @@ environment undisturbed.
 
    It is rare that all of the software in a large,
    complicated system needs to be built the same way.
-   Different source files need different options
-   enabled on the command line;
-   different executable programs need to be linked
-   with different libraries (shared or static);
-   XXX
+   For example, different source files may need different options
+   enabled on the command line,
+   or different executable programs need to be linked
+   with different libraries.
    &SCons; accomodates these different build
    requirements by allowing you to create and
    configure multiple &consenvs;
@@ -651,46 +650,58 @@ environment undisturbed.
    <para>
 
    You can fetch individual construction variables
-   using the normal Python syntax
-   for accessing individual named items in a dictionary:
+   using the normal syntax
+   for accessing individual named items in a Python dictionary:
 
    </para>
 
    <programlisting>
       env = Environment()
-      print "CCCOM is:", env['CCCOM']
+      print "CC is:", env['CC']
    </programlisting>
 
+   <para>
+
+   This example &SConstruct; file doesn't build anything,
+   but because it's actually a Python script,
+   it will print the value of &CC; for us:
+
+   </para>
+
    <literallayout>
       % <userinput>scons</userinput>
-      CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
+      CC is: cc
    </literallayout>
 
    <para>
 
-   Note, however, that a &consenv;
+   A &consenv;, however,
    is actually a Python object with
    associated methods, etc.
    If you want to have direct access to only the
    dictionary of construction variables,
-   you can fetch this using the &Dictionary; method.
-   This provides the
+   you can fetch this using the &Dictionary; method:
 
    </para>
 
    <programlisting>
-      env = Environment()
+      env = Environment(FOO = 'foo', BAR = 'bar')
       dict = env.Dictionary()
-      # XXX SOMETHING WHERE A DICT IS NEEDED
+      for key, value in dict.items():
+          print "key = %s, value = %s % (key, value)
    </programlisting>
 
    <para>
 
+   This &SConstruct; file
+   will print the dictionary items for us as follows:
+
    </para>
 
    <literallayout>
       % <userinput>scons</userinput>
-      # XXX
+      key = FOO, value = foo
+      key = BAR, value = bar
    </literallayout>
 
  </section>
diff --git a/doc/user/hierarchy.sgml b/doc/user/hierarchy.sgml
index e39da8f..24adb56 100644
--- a/doc/user/hierarchy.sgml
+++ b/doc/user/hierarchy.sgml
@@ -25,14 +25,6 @@
 
 <!--
 
-=head2 A hierarchy of build scripts
-
-A larger build, in Cons, is organized by creating a hierarchy of B<build
-scripts>. At the top of the tree is a script called F<Construct>. The rest
-of the scripts, by convention, are each called F<Conscript>. These scripts
-are connected together, very simply, by the C<Build>, C<Export>, and
-C<Import> commands.
-
 
 =head2 The Build command
 
@@ -56,16 +48,6 @@ F<Conscript> file should explicitly disable this feature as follows:
 
 =head2 Relative, top-relative, and absolute file names
 
-You may have noticed that the file names specified to the Build command are
-relative to the location of the script it is invoked from. This is generally
-true for other filename arguments to other commands, too, although we might
-as well mention here that if you begin a file name with a hash mark, ``#'',
-then that file is interpreted relative to the top-level directory (where the
-F<Construct> file resides). And, not surprisingly, if you begin it with ``/'',
-then it is considered to be an absolute pathname. This is true even on
-systems which use a back slash rather than a forward slash to name absolute
-paths.
-
 (There is another file prefix, ``!'', that is interpreted specially by
 Cons.  See discussion of the C<Link> command, below, for details.)
 
@@ -159,7 +141,6 @@ C<$env> is to be exported, then the following will suffice:
 Needless to say, the variables may be modified locally before invoking
 C<Build> on the subsidiary script.
 
-
 =head2 Build script evaluation order
 
 The only constraint on the ordering of build scripts is that superior
@@ -274,15 +255,187 @@ make no difference to the build.
 
     <para>
 
-    XXX
+    Subsidiary &SConscript; files make it easy to create a build
+    hierarchy because all of the file and directory names
+    in a subsidiary &SConscript; files are interpreted
+    relative to the directory in which the &SConscript; file lives.
+    Typically, this allows the &SConscript; file containing the
+    instructions to build a target file
+    to live in the same directory as the source files
+    from which the target will be built,
+    making it easy to update how the software is built
+    whenever files are added or deleted
+    (or other changes are made).
+
+    </para>
+
+    <para>
+
+    For example, suppose we want to build two programs
+    &prog1; and &prog2; in two separate directories
+    with the same names as the programs.
+    One typical way to do this would be
+    with a top-level &SConstruct; file like this:
 
     </para>
 
     <programlisting>
-      SConscript(['display/SConscript',
-                  'mouse/SConscript'])
+      SConscript(['prog1/SConscript',
+                  'prog2/SConscript'])
+    </programlisting>
+
+    <para>
+
+    And subsidiary &SConscript; files that look like this:
+
+    </para>
+
+    <programlisting>
+      env = Environment()
+      env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c'])
+    </programlisting>
+
+    <para>
+
+    And this:
+
+    </para>
+
+    <programlisting>
+      env = Environment()
+      env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c'])
     </programlisting>
 
+    <para>
+
+    Then, when we run &SCons; in the top-level directory,
+    our build looks like:
+
+    </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
+       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 -o prog2/prog2 prog2/main.o prog2/bar1.o prog2/bar2.o
+    </literallayout>
+
+    <para>
+
+    Notice the following:
+
+    First, you can have files with the same names
+    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
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Top-Level Path Names in Subsidiary &SConscript; Files</title>
+
+    <para>
+
+    If you need to use a file from another directory,
+    it's sometimes more convenient to specify
+    the path to a file in another directory
+    from the top-level &SConstruct; directory,
+    even when you're using that file in
+    a subsidiary &SConscript; file in a subdirectory.
+    You can tell &SCons; to interpret a path name
+    as relative to the top-level &SConstruct; directory,
+    not the local directory of the &SConscript; file,
+    by appending a &hash; (hash mark)
+    to the beginning of the path name:
+
+
+    </para>
+
+    <literallayout>
+       env = Environment()
+       env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c'])
+    </literallayout>
+
+    <para>
+
+    In this example,
+    the <literal>lib</literal> directory is
+    directly underneath the top-level &SConstruct; directory.
+    If the above &SConscript; file is in a subdirectory
+    named <literal>src/prog</literal>,
+    the output would look like:
+
+    </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
+    </literallayout>
+
+    <para>
+
+    (Notice that the <literal>lib/foo1.o</literal> object file
+    is built in the same directory as its source file.
+    See section XXX, below,
+    for information about 
+    how to build the object file in a different subdirectory.)
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>Absolute Path Names</title>
+
+    <para>
+
+    Of course, you can always specify
+    an absolute path name for a file--for example:
+
+    </para>
+
+    <literallayout>
+       env = Environment()
+       env.Program('prog', ['main.c', '/usr/joe/lib/foo1.c', 'foo2.c'])
+    </literallayout>
+
+    <para>
+
+    Which, when executed, would yield:
+
+    </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
+    </literallayout>
+
+    <para>
+
+    (As was the case with top-relative path names,
+    notice that the <literal>/usr/joe/lib/foo1.o</literal> object file
+    is built in the same directory as its source file.
+    See section XXX, below,
+    for information about 
+    how to build the object file in a different subdirectory.)
+
+    </para>
+
   </section>
 
   <section>
@@ -290,29 +443,121 @@ make no difference to the build.
 
     <para>
 
-    XXX
+    In the previous example,
+    each of the subsidiary &SConscript; files
+    created its own construction environment
+    by calling &Environment; separately.
+    This obviously works fine,
+    but if each program must be built
+    with the same construction variables,
+    it's cumbersome and error-prone to initialize
+    separate construction environments
+    in the same way over and over in each subsidiary
+    &SConscript; file.
 
     </para>
 
-    <programlisting>
-      SConscript(['display/SConscript',
-                  'mouse/SConscript'])
-    </programlisting>
+    <para>
+
+    &SCons; supports the ability to <emphasis>export</emphasis> variables
+    from a parent &SConscript; file
+    to its subsidiary &SConscript; files,
+    which allows you to share common initialized
+    values throughout your build hierarchy.
+
+    </para>
 
     <section>
     <title>Exporting Variables</title>
 
       <para>
 
+      There are two ways to export a variable,
+      such as a construction environment,
+      from one &SConscript; file,
+      so that it may be used by other &SConscript; files.
+      First, you can call the &Export;
+      function with a list of variables,
+      or a string white-space separated variable names.
+      Each call to &Export; adds one
+      or more variables to a global list
+      of variables that are available for import
+      by other &SConscript; files.
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        Export('env')
+      </programlisting>
+
+      <para>
+
       XXX
 
       </para>
 
       <programlisting>
-        SConscript(['display/SConscript',
-                    'mouse/SConscript'])
+        env = Environment()
+        debug = ARGUMENTS['debug']
+        Export('env', 'debug')
+      </programlisting>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        Export('env debug')
+      </programlisting>
+
+      <para>
+
+      Second, you can specify a list of
+      variables to exported as a second argument
+      to the &SConscript; function call:
+
+      </para>
+
+      <programlisting>
+        SConscript('src/SConscript', 'env')
+      </programlisting>
+
+      <para>
+
+      Or as the &exports; keyword argument:
+
+      </para>
+
+      <programlisting>
+        SConscript('src/SConscript', exports='env')
+      </programlisting>
+
+      <para>
+
+      These calls export the specified variables
+      to only the listed &SConscript; files.
+      You may, however, specify more than one
+      &SConscript; file in a list:
+
+      </para>
+
+      <programlisting>
+        SConscript(['src1/SConscript',
+                    'src2/SConscript'], exports='env')
       </programlisting>
 
+      <para>
+
+      This is functionally equivalent to
+      calling the &SConscript; function
+      multiple times with the same &exports; argument,
+      one per &SConscript; file.
+
+      </para>
+
     </section>
 
     <section>
@@ -325,14 +570,44 @@ make no difference to the build.
       </para>
 
       <programlisting>
-        SConscript(['display/SConscript',
-                   'mouse/SConscript'])
+        Import('env')
+        env.Program('prog', ['prog.c'])
+      </programlisting>
+
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        Import('env', 'debug')
+        env = env.Copy(DEBUG = debug)
+        env.Program('prog', ['prog.c'])
+      </programlisting>
+
+      <para>
+
+      Which is exactly equivalent to:
+
+      </para>
+
+      <programlisting>
+        Import('env debug')
+        env = env.Copy(DEBUG = debug)
+        env.Program('prog', ['prog.c'])
       </programlisting>
 
+      <para>
+
+      XXX
+
+      </para>
+
     </section>
 
     <section>
-    <title>Returning Values</title>
+    <title>Returning Values From an &SConscript; File</title>
 
       <para>
 
@@ -341,10 +616,30 @@ make no difference to the build.
       </para>
 
       <programlisting>
-        SConscript(['display/SConscript',
-                    'mouse/SConscript'])
+        obj = env.Object('foo.c')
+        Return('obj')
       </programlisting>
 
+      <para>
+
+      XXX
+
+      </para>
+
+      <programlisting>
+        objs = []
+        for subdir in ['foo', 'bar']:
+            o = SConscript('%s/SConscript' % subdir)
+            objs.append(o)
+        env.Library('prog', objs)
+      </programlisting>
+
+      <para>
+
+      XXX
+
+      </para>
+
     </section>
 
   </section>
diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml
index ea41f5d..6fc6c5d 100644
--- a/doc/user/libraries.sgml
+++ b/doc/user/libraries.sgml
@@ -98,8 +98,8 @@
 
     <para>
 
-    Usually, the goal of building a library
-    is to link it with one or more programs.
+    Usually, you build a library
+    because you want to link it with one or more programs.
     You link libraries with a program by specifying
     the libraries in the &LIBS; construction variable,
     and by specifying the directory in which
@@ -215,7 +215,11 @@
 
     <para>
 
-    On a POSIX or Linux system,
+    When the linker is executed,
+    &SCons; will create appropriate flags
+    so that the linker will look for
+    libraries in the same directories as &SCons;.
+    So on a POSIX or Linux system,
     a build of the above example would look like:
 
     </para>
diff --git a/doc/user/make.sgml b/doc/user/make.sgml
index c7ecc63..fe697a0 100644
--- a/doc/user/make.sgml
+++ b/doc/user/make.sgml
@@ -99,7 +99,18 @@ the makefiles.
  </para>
 
  <section>
- <title>XXX</title>
+ <title>Differences Between &Make; and &SCons;</title>
+
+   <para>
+
+   XXX
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Advantages of &SCons; Over &Make;</title>
 
    <para>
 
diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml
index bba7f49..589399d 100644
--- a/doc/user/preface.sgml
+++ b/doc/user/preface.sgml
@@ -25,7 +25,50 @@
 
   <para>
 
-  XXX
+  Thank you for taking the time to read about &SCons;.
+  &SCons; is a next-generation
+  software construction tool,
+  or make tool--that is, a software utility
+  for building software (or other files)
+  and keeping built software up-to-date
+  whenever the underlying input files change.
+
+  </para>
+
+  <para>
+
+  The most distinctive thing about &SCons;
+  is that its configuration files are
+  actually <emphasis>scripts</emphasis>,
+  written in the &Python; programming language.
+  This is in contrast to most alternative build tools,
+  which typically invent a new language to
+  configure the build.
+  &SCons; still has a learning curve, of course,
+  because you have to know what functions to call
+  to set up your build properly,
+  but the underlying syntax used should be familiar
+  to anyone who has ever looked at a Python script.
+
+  </para>
+
+  <para>
+
+  Paradoxically,
+  using Python as the configuration file format
+  makes &SCons;
+  <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
+  consistency and readability that are built in to Python.
+  It just so happens that making a real, live
+  scripting language the basis for the
+  configuration files
+  makes it a snap for more accomplished programmers
+  to do more complicated things with builds,
+  as necessary.
 
   </para>
 
@@ -34,7 +77,18 @@
 
     <para>
 
-    XXX
+    &SCons; is a response to a perennial problem:
+    building software is harder than it should be.
+    In a nutshell:  the old, reliable model of the
+    venerable and ubiquitous &Make; program
+    has had a hard time keeping up with
+    how complicated building software has become.
+    The fact that &Make; has kept up as well as it has is impressive,
+    and a testament to how the simplicity.
+    But anyone who has wrestled with &Automake; and &Autoconf;
+    to try to guarantee that a bit of software
+    will build correctly on multiple platforms
+    can tell you that it takes a lot of work to get right.
 
     </para>
 
@@ -45,22 +99,71 @@
 
     <para>
 
-    By default, &SCons; guarantees a correct build
-    regardless of what end case you may have.
+    There are a few overriding principles
+    we try to live up to in designing and implementing &SCons:
 
     </para>
 
-    <para>
+    <variablelist>
 
-    &SCons; makes it easy to speed up the build through
-    optimization options that trade off
-    guaranteed correctness for speed.
+      <varlistentry>
+      <term>Correctness</term>
 
-    </para>
+      <listitem>
+      <para>
+
+      First and foremost,
+      by default, &SCons; guarantees a correct build
+      even if it means sacrificing performance a little.
+      We strive to guarantee the build is correct
+      regardless of how the software being built is structured,
+      how it may have been written,
+      or how unusual the tools are that build it.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>Performance</term>
+
+      <listitem>
+      <para>
+
+      Given that the build is correct,
+      we try to make &SCons; build software
+      as quickly as possible.
+      In particular, wherever we may have needed to slow
+      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.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>Convenience</term>
+
+      <listitem>
+      <para>
+
+      &SCons; tries to do as much for you out of the box as reasonable,
+      including detecting the right tools on your system
+      and using them correctly to build the software.
+
+      </para>
+      </listitem>
+      </varlistentry>
+
+    </variablelist>
 
     <para>
 
-    &SCons; tries to do as much for you out of the box as reasonable.
+    In a nutshell, we try hard to make &SCons; just
+    "do the right thing" and build software correctly,
+    with a minimum of hassles.
 
     </para>
 
@@ -86,8 +189,16 @@
 
     </para>
 
+    <para>
+
+    XXX
+
+    </para>
+
   </section>
 
+  <!--
+
   <section>
   <title>Conventions</title>
 
@@ -99,6 +210,8 @@
 
   </section>
 
+  -->
+
   <section>
   <title>Acknowledgements</title>
 
@@ -151,23 +264,49 @@
     tool without the energy, enthusiasm
     and time people have contributed over the past few years.
     The "core team"
-    of Chad Austin, Anthony Roach, Charles Crain, and Steve Leblanc
+    of Chad Austin, Anthony Roach, Charles Crain,
+    Steve Leblanc, Greg Spencer and Christoph Wiedemann
     have been great about reviewing my (and other) changes
     and catching problems before they get in the code base.
-    Technically,
+    Of particular technical note:
     Anthony's outstanding and innovative work on the tasking engine
-    has given &SCons; a vastly superior parallel build model,
-    and Charles has been the master of the crucial Node infrastructure.
+    has given &SCons; a vastly superior parallel build model;
+    Charles has been the master of the crucial Node infrastructure;
+    Christoph's work on the Configure infrastructure
+    has added crucial Autoconf-like functionality;
+    and Greg has provided excellent support
+    for Microsoft Visual Studio.
+
+    </para>
+
+    <para>
+
+    Special thanks to David Snopek for contributing
+    his underlying "Autocons" code that formed
+    the basis of Christoph's work with the Configure functionality.
+    David was extremely generous in making
+    this code available to &SCons;,
+    given that he initially released it under the GPL
+    and &SCons; is released under a less-restrictive MIT-style license.
+
+    </para>
+
+    <para>
+
     &SCons; has received contributions
     from many other people, of course:
     Matt Balvin (extending long command-line support on Win32),
+    Allen Bierbaum (extensions and fixes to Options),
+    Steve Christensen (help text sorting and function action signature fixes),
     Michael Cook (avoiding losing signal bits from executed commands),
     Derrick 'dman' Hudson (),
     Alex Jacques (work on the Win32 scons.bat file),
     Stephen Kennedy (performance enhancements),
     Lachlan O'Dea (SharedObject() support for masm
     and normalized paths for the WhereIs() function),
-    Jeff Petkau (fixes for CacheDir and other areas),
+    Damyan Pepper (keeping output like Make),
+    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)
@@ -188,6 +327,15 @@
 
     </para>
 
+    <para>
+
+    And last, thanks to Guido van Rossum
+    for his elegant scripting language,
+    which is the basis not only for the &SCons; implementation,
+    but for the interface itself.
+
+    </para>
+
   </section>
 
   <section>
@@ -201,4 +349,25 @@
 
     </para>
 
+    <para>
+
+    If you want to ask general questions about how to use &SCons;
+    send email to &scons-users;.
+
+    </para>
+
+    <para>
+
+    If you want to contact the &SCons; development community directly,
+    send email to &scons-devel;.
+
+    </para>
+
+    <para>
+
+    If you want to receive announcements about &SCons,
+    join the low-volume &scons-announce; mailing list.
+
+    </para>
+
   </section>
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
index 8f76f2a..d97badc 100644
--- a/doc/user/simple.sgml
+++ b/doc/user/simple.sgml
@@ -23,24 +23,6 @@
 
 -->
 
-<!--
-
-=head2 Perl scripts
-
-Cons is Perl-based. That is, Cons scripts F<Conscript> and F<Construct>
-files, the equivalent to F<Makefile> or F<makefile> are all written in
-Perl. This provides an immediate benefit: the language for writing scripts
-is a familiar one. Even if you don't happen to be a Perl programmer, it
-helps to know that Perl is basically just a simple declarative language,
-with a well-defined flow of control, and familiar semantics. It has
-variables that behave basically the way you would expect them to,
-subroutines, flow of control, and so on. There is no special syntax
-introduced for Cons. The use of Perl as a scripting language simplifies
-the task of expressing the appropriate solution to the often complex
-requirements of a build.
-
--->
-
  <para>
 
  Here's the famous "Hello, World!" program in C:
@@ -100,7 +82,7 @@ requirements of a build.
  to specify the name of the source file,
  and that &SCons; deduces the names of
  the object and executable files
- correctly from the source file.
+ correctly from the base of the source file name.
 
  </para>
 
@@ -113,16 +95,16 @@ requirements of a build.
  on POSIX systems,
  <filename>hello.obj</filename> and <filename>hello.exe</filename>
  on Windows systems.
- This is a simple example of how easy it is to
- use &SCons; to write portable software builds.
+ This is a simple example of how &SCons;
+ makes it extremely easy to
+ write portable software builds.
 
  </para>
 
  <para>
 
  (Note that we won't provide duplicate side-by-side
- POSIX and Windows output for the 
- rest of the examples in this guide;
+ POSIX and Windows output for all of the examples in this guide;
  just keep in mind that, unless otherwise specified,
  any of the examples should work equally well on both types of systems.)
 
@@ -143,15 +125,14 @@ requirements of a build.
 
    <para>
 
-   What may not be obvious, though, is that
-   there's an important difference between
+   There is, however, an important difference between
    an &SConstruct; file and a &Makefile;:
    the &SConstruct; file is actually a Python script.
-   If you're not already familiar with Python, don't worry;
-   Python is very easy to learn,
-   and this User's Guide will introduce you step-by-step
+   If you're not already familiar with Python, don't worry.
+   This User's Guide will introduce you step-by-step
    to the relatively small amount of Python you'll
    need to know to be able to use &SCons; effectively.
+   And Python is very easy to learn.
 
    </para>
 
@@ -188,9 +169,11 @@ requirements of a build.
 
    <para>
 
+   You've just seen how to configure &SCons;
+   to compile a program from a single source file.
    It's more common, of course,
    that you'll need to build a program from
-   not just one, but many input source files.
+   many input source files, not just one.
    To do this, you need to put the
    source files in a Python list
    (enclosed in square brackets),
@@ -355,7 +338,7 @@ requirements of a build.
 
    &SCons; also allows you to identify
    the output file and input source files
-   by Python keyword arguments.
+   using Python keyword arguments.
    The output file is known as the
    <emphasis>target</emphasis>,
    and the source file(s) are known (logically enough) as the
@@ -374,7 +357,8 @@ requirements of a build.
 
    Whether or not you choose to use keyword arguments
    to identify the target and source files
-   is purely a personal choice.
+   is purely a personal choice;
+   &SCons; functions the same either way.
 
    </para>
 
@@ -448,8 +432,8 @@ requirements of a build.
 
    A more straightforward, but perhaps less convenient,
    way to share source files between multiple programs
-   is to simply include the common source files
-   when listing the source files for each program:
+   is simply to include the common files
+   in the lists of source files for each program:
 
    </para>
 
@@ -484,12 +468,12 @@ requirements of a build.
    If two or more programs
    share a lot of common source files,
    repeating the common files in the list for each program
-   a maintenance problem if you need to change the
+   can be a maintenance problem when you need to change the
    list of common files.
    You can simplify this by creating a separate Python list
    to hold the common file names,
    and concatenating it with other lists
-   using the Python &+; operator:
+   using the Python &plus; operator:
 
    </para>