More User's Guide edits.

6 files changed, 418 insertions, 87 deletions

diff --git a/doc/user/default.sgml b/doc/user/default.sgml
index bb81a3a..eb2bdc1 100644
--- a/doc/user/default.sgml
+++ b/doc/user/default.sgml
@@ -60,19 +60,153 @@ default list.
 
 -->
 
- <para>
+   <para>
+
+   As mentioned previously,
+   &SCons; will build every target
+   in or below the current directory
+   by default--that is, when you don't
+   explicitly specify one or more targets
+   on the command line.
+   Sometimes, however, you may want
+   to explicitly specify that only
+   certain programs should be built by default,
+   which you do using the &Default; function:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      hello = env.Program('hello.c')
+      env.Program('goodbye.c')
+      Default(hello)
+   </programlisting>
+
+   <para>
+
+   This &SConstruct; file builds two programs,
+   &hello; and &goodbye;,
+   but only builds the
+   &hello program by default:
+
+   </para>
+
+   <literallayout>
+      % <userinput>scons</userinput>
+      cc -c hello.c -o hello.o
+      cc -o hello hello.o
+      % <userinput>scons</userinput>
+      % <userinput>scons goodbye</userinput>
+      cc -c goodbye.c -o goodbye.o
+      cc -o goodbye goodbye.o
+      %
+   </literallayout>
+
+   <para>
+
+   Note that, even when you use the &Default;
+   function in your &SConstruct; file,
+   you can still explicitly specify the current directory
+   (<literal>.</literal>) on the command line
+   to tell &SCons; to build
+   everything in (or below) the current directory:
+
+   </para>
+
+   <literallayout>
+      % <userinput>scons .</userinput>
+      cc -c goodbye.c -o goodbye.o
+      cc -o goodbye goodbye.o
+      cc -c hello.c -o hello.o
+      cc -o hello hello.o
+      %
+   </literallayout>
+
+   <para>
 
-   X
+   You can also call the &Default;
+   function more than once,
+   in which case each call
+   adds to the list of targets to be built by default:
 
- </para>
+   </para>
+
+   <programlisting>
+      env = Environment()
+      prog1 = env.Program('prog1.c')
+      Default(prog1)
+      prog2 = env.Program('prog2.c')
+      prog3 = env.Program('prog3.c')
+      Default(prog3)
+   </programlisting>
+
+   <para>
+
+   Or you can specify more than one target
+   in a single call to the &Default; function:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      prog1 = env.Program('prog1.c')
+      prog2 = env.Program('prog2.c')
+      prog3 = env.Program('prog3.c')
+      Default(prog1, prog3)
+   </programlisting>
+
+   <para>
+
+   Either of these last two examples
+   will build only the
+   <application>prog1</application>
+   and
+   <application>prog3</application>
+   programs:
+
+   </para>
+
+   <literallayout>
+      % <userinput>scons</userinput>
+      cc -c prog1.c -o prog1.o
+      cc -o prog1 prog1.o
+      cc -c prog3.c -o prog3.o
+      cc -o prog3 prog3.o
+      % <userinput>scons .</userinput>
+      cc -c prog2.c -o prog2.o
+      cc -o prog2 prog2.o
+      %
+   </literallayout>
+
+   <para>
+
+   Lastly, if for some reason you don't want
+   any targets built by default,
+   you can use the Python <literal>None</literal>
+   variable:
+
+   </para>
 
- <section>
- <title>The &Default; Method</title>
+   <programlisting>
+      env = Environment()
+      prog1 = env.Program('prog1.c')
+      prog2 = env.Program('prog2.c')
+      Default(None)
+   </programlisting>
 
    <para>
 
-   X
+   Which would produce build output like:
 
    </para>
 
- </section>
+   <literallayout>
+      % <userinput>scons</userinput>
+      scons: *** No targets specified and no Default() targets found.  Stop.
+      % <userinput>scons .</userinput>
+      cc -c prog1.c -o prog1.o
+      cc -o prog1 prog1.o
+      cc -c prog2.c -o prog2.o
+      cc -o prog2 prog2.o
+      %
+   </literallayout>
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index c94ac0d..e8491e4 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -61,10 +61,10 @@ operating system on which the build is performed (as reported by C<uname
  </para>
 
  <literallayout>
-    % <userinput>scons .</userinput>
+    % <userinput>scons</userinput>
     cc -c hello.c -o hello.o
     cc -o hello hello.o
-    % <userinput>scons .</userinput>
+    % <userinput>scons</userinput>
     %
  </literallayout>
 
@@ -89,9 +89,9 @@ operating system on which the build is performed (as reported by C<uname
 
  <para>
 
- (&SCons; only reports "...is up to date"
+ Note that &SCons; only reports "...is up to date"
  for target files named explicitly on the command line,
- to avoid cluttering the output.)
+ to avoid cluttering the output.
 
  </para>
 
@@ -172,15 +172,12 @@ included by included files will also be scanned.
 
    <para>
 
-   X
+   Now suppose that our "Hello, World!" program
+   actually looks like this:
 
    </para>
 
    <programlisting>
-      #define string    "world"
-   </programlisting>
-
-   <programlisting>
       #include "hello.h" 
       int
       main()
@@ -189,11 +186,44 @@ included by included files will also be scanned.
       }
    </programlisting>
 
+   <para>
+
+   That is, the first line
+   includes a &hello_h;
+   that looks like this:
+
+   </para>
+
+   <programlisting>
+      #define string    "world"
+   </programlisting>
+
+   <para>
+
+   In this case, we want &SCons; to recognize that,
+   if the contents of the &hello_h; file change,
+   the &hello; program must be recompiled.
+   To do this, we need to modify the
+   &SConstruct; file like so:
+
+   </para>
+
    <programlisting>
       env = Environment(CPPPATH = '.')  XXX IS CPPPATH NECESSARY?
       hello = env.Program('hello.c')
    </programlisting>
 
+   <para>
+
+   The &CPPPATH; assignment in the &Environment; call
+   tells &SCons; to look in the current directory
+   (<literal>'.'</literal>)
+   for any files included by C source files
+   (<filename>.c</filename> or <filename>.h</filename> files).
+   With this assignment in the &SConstruct file:
+
+   </para>
+
    <literallayout>
       % <userinput>scons hello</userinput>
       cc -c hello.c -o hello.o
@@ -210,20 +240,20 @@ included by included files will also be scanned.
 
    <para>
 
-      &SCons; knows that the &hello;
-      program must be rebuilt
-      because it scans the contents of
-      the &hello_c;
-      for the #include lines that indicate
-      another file is being included in the compilation.
-      &SCons; records these as
-      <emphasis>implicit dependencies</emphasis>
-      of the target file,
-      Consequently,
-      when the &hello_h; file changes,
-      &SCons; realizes that the &hello_c; file includes it,
-      and rebuilds the resulting &hello; program
-      that depends on both the &hello_c; and &hello_h; files.
+   &SCons; knows that the &hello;
+   program must be rebuilt
+   because it scans the contents of
+   the &hello_c; file
+   for the <literal>#include</literal> lines that indicate
+   another file is being included in the compilation.
+   &SCons; records these as
+   <emphasis>implicit dependencies</emphasis>
+   of the target file,
+   Consequently,
+   when the &hello_h; file changes,
+   &SCons; realizes that the &hello_c; file includes it,
+   and rebuilds the resulting &hello; program
+   that depends on both the &hello_c; and &hello_h; files.
 
    </para>
 
diff --git a/doc/user/help.sgml b/doc/user/help.sgml
index 7c1732e..5e2ced3 100644
--- a/doc/user/help.sgml
+++ b/doc/user/help.sgml
@@ -23,15 +23,6 @@
 
 -->
 
- <para>
-
-   X
-
- </para>
-
- <section>
- <title>Providing build-specific help instructions</title>
-
    <para>
 
    It's often very useful to be able to give
@@ -84,5 +75,3 @@
    the <literal>-H</literal> option is used.
 
    </para>
-
- </section>
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
index bb64b72..b285696 100644
--- a/doc/user/main.sgml
+++ b/doc/user/main.sgml
@@ -76,10 +76,10 @@
 
     <edition>Revision &buildrevision; (&builddate;)</edition>
 
-    <pubdate>2001</pubdate>
+    <pubdate>2003</pubdate>
 
     <copyright>
-      <year>2001</year>
+      <year>2003</year>
       <holder>Steven Knight</holder>
     </copyright>
 
diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml
index 4acc943..2193a8f 100644
--- a/doc/user/repositories.sgml
+++ b/doc/user/repositories.sgml
@@ -142,7 +142,7 @@ subdirectories under the repository tree.
  directory trees that contain
  source code, or derived files, or both.
  You can eliminate additional unnecessary
- rebuilds of files by having &SCons;,
+ rebuilds of files by having &SCons;
  use files from one or more code repositories
  to build files in your local build tree.
 
@@ -163,8 +163,8 @@ used to build any local derived files.
 
    <para>
 
-   You use the &Repository; method
-   to tell &SCons; to search one or more
+   The &Repository; method
+   tells &SCons; to search one or more
    central code repositories (in order)
    for any source files and derived files
    that are not present in the local build tree:
@@ -223,7 +223,7 @@ used to build any local derived files.
    </para>
 
    <literallayout>
-     % <userinput>scons .</userinput>
+     % <userinput>scons</userinput>
      gcc -c hello.c -o hello.o
      gcc -o hello hello.o
    </literallayout>
@@ -238,7 +238,7 @@ used to build any local derived files.
    </para>
 
    <literallayout>
-     % <userinput>scons .</userinput>
+     % <userinput>scons</userinput>
      gcc -c /usr/repository1/hello.c -o hello.o
      gcc -o hello hello.o
    </literallayout>
@@ -252,7 +252,7 @@ used to build any local derived files.
    </para>
 
    <literallayout>
-     % <userinput>scons .</userinput>
+     % <userinput>scons</userinput>
      gcc -c /usr/repository2/hello.c -o hello.o
      gcc -o hello hello.o
    </literallayout>
@@ -281,7 +281,7 @@ used to build any local derived files.
    </para>
 
    <literallayout>
-     % <userinput>scons -Y /usr/repository1 -Y /usr/repository2 .</userinput>
+     % <userinput>scons -Y /usr/repository1 -Y /usr/repository2</userinput>
    </literallayout>
 
    <para>
@@ -303,7 +303,7 @@ used to build any local derived files.
 
    If a repository contains not only source files,
    but also derived files (such as object files,
-   libraries, or exectuables), &SCons; will perform
+   libraries, or executables), &SCons; will perform
    its normal MD5 signature calculation to
    decide if a derived file in a repository is up-to-date,
    or the derived file must be rebuilt in the local build directory.
@@ -325,7 +325,7 @@ used to build any local derived files.
 
    <literallayout>
      % <userinput>cd /usr/repository1</userinput>
-     % <userinput>scons .</userinput>
+     % <userinput>scons</userinput>
      gcc -c hello.c -o hello.o
      gcc -o hello hello.o
    </literallayout>
@@ -353,7 +353,7 @@ used to build any local derived files.
    <literallayout>
      % <userinput>cd $HOME/build</userinput>
      % <userinput>edit hello.c</userinput>
-     % <userinput>scons -Y /usr/repository1 .</userinput>
+     % <userinput>scons -Y /usr/repository1</userinput>
      gcc -c hello.c -o hello.o
      gcc -o hello hello.o
      XXXXXXX
@@ -385,8 +385,8 @@ used to build any local derived files.
    <literallayout>
      % <userinput>mkdir $HOME/build2</userinput>
      % <userinput>cd $HOME/build2</userinput>
-     % <userinput>cons -Y /usr/all/repository hello</userinput>
-     cons: "hello" is up-to-date.
+     % <userinput>scons -Y /usr/all/repository hello</userinput>
+     scons: `hello' is up-to-date.
    </literallayout>
 
    <para>
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
index 9071160..8cafe2d 100644
--- a/doc/user/simple.sgml
+++ b/doc/user/simple.sgml
@@ -44,7 +44,6 @@ requirements of a build.
  <para>
 
  Here's how to build the famous "Hello, World!" example using &SCons;.
- Enter the following into a file name &SConstruct;:
 
  </para>
 
@@ -56,6 +55,12 @@ requirements of a build.
     }
  </programlisting>
 
+ <para>
+
+ Enter the following into a file name &SConstruct;:
+
+ </para>
+
  <programlisting>
     env = Environment()
     env.Program('hello.c')
@@ -70,7 +75,7 @@ requirements of a build.
  </para>
 
  <literallayout>
-    % <userinput>scons .</userinput>
+    % <userinput>scons</userinput>
     cc -c hello.c -o hello.o
     cc -o hello hello.o
  </literallayout>
@@ -83,32 +88,42 @@ requirements of a build.
  </para>
 
  <literallayout>
-    C:\><userinput>scons .</userinput>
+    C:\><userinput>scons</userinput>
     cl /Fohello.obj hello.c
     link /Fohello.exe hello.obj
  </literallayout>
 
  <para>
 
- First, notice that you need to supply a '.' on the command line.
- This tells &SCons; to build everything in the current directory
- or its subdirectories.
- We'll tell you later how to avoid having to use the '.'
+ First, notice that you only need
+ 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.
 
  </para>
 
  <para>
 
- Next, notice that the same input &SConstruct; file
- without any special input,
- generates the right output file names on both systems:
+ Second, notice that the same input &SConstruct; file
+ without any changes,
+ generates the correct output file names on both systems:
  <filename>hello.o</filename> and <filename>hello</filename>
  on POSIX systems,
  <filename>hello.obj</filename> and <filename>hello.exe</filename>
  on Windows systems.
- (We won't provide side-by-side examples of POSIX
- and Windows runs for all future examples;
- just know that XXX.)
+ This is a simple example of how easy it is to
+ use &SCons; 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;
+ just keep in mind that, unless otherwise specified,
+ any of the examples should work equally well on both types of systems.)
 
  </para>
 
@@ -132,19 +147,17 @@ requirements of a build.
    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;
-   you don't really need to know Python to be able to use
-   &SCons; effectively.
-   But you'll see that being able to use the power of a
-   real scripting language
-   can greatly simplify the solutions
-   to complex requirements of real-world builds.
+   Python is extremely easy to learn,
+   and this User's Guide will introduce you step-by-step
+   to the relatively small amount of Python you'll
+   neede to know to be able to use &SCons; effectively.
 
    </para>
 
    <para>
 
-   For now, one ramification of using Python as the
-   scripting language means that you can put comments
+   One aspect of using Python as the
+   scripting language is that you can put comments
    in your &SConstruct; file using Python's commenting convention;
    that is, everything between a '#' and the end of the line
    will be ignored:
@@ -157,6 +170,16 @@ requirements of a build.
       env.Program('hello.c')
    </programlisting>
 
+   <para>
+
+   You'll see throughout the remainder of this Guide
+   that being able to use the power of a
+   real scripting language
+   can greatly simplify the solutions
+   to complex requirements of real-world builds.
+
+   </para>
+
  </section>
 
  <section>
@@ -164,7 +187,15 @@ requirements of a build.
 
    <para>
 
-   If you want
+   It's more common, of course,
+   that you'll need to build a program from
+   not just one, but many input source files.
+   To do this, you need to put the
+   source files in a Python list
+   (enclosed in square brackets),
+   and slide that list over to to the right
+   to make room for the output program file name.
+   For example:
 
    </para>
 
@@ -173,19 +204,156 @@ requirements of a build.
       env.Program('program', ['main.c', 'file1.c', 'file2.'])
    </programlisting>
 
-   <programlisting>
-      env = Environment()
-      env.Program('program', Split('main.c file1.c file2.'))
-   </programlisting>
+   <para>
+
+   (&SCons; puts the output file name to the left
+   of the source file names
+   so that the order mimics that of an
+   assignment statement:  "program = source files".)
+
+   </para>
+
+   <para>
+
+   A build of the above example would look:
+
+   </para>
 
    <literallayout>
-      % <userinput>scons .</userinput>
+      % <userinput>scons</userinput>
       cc -c file1.c -o file1.o
       cc -c file2.c -o file2.o
       cc -c main.c -o main.o
       cc -o program main.o file1.o file2.o
    </literallayout>
 
+   <!--
+
+   XXX DO WE NEED WINDOWS EXAMPLE OUTPUT HERE?
+
+   </para>
+
+   Or on Windows:
+
+   </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
+   </literallayout>
+
+   -->
+
+ </section>
+
+ <section>
+ <title>Keeping &SConstruct; Files Easy to Read</title>
+
+   <para>
+
+   One minor drawback to the use of a Python list
+   for source files is that 
+   each file name must be enclosed in quotes
+   (either single quotes or double quotes).
+   This can get cumbersome and difficult to read
+   when the list of file names is long.
+   Fortunately, there are a number of things
+   we can do to make sure that
+   the &SConstruct; file stays easy to read.
+
+   </para>
+
+   <para>
+
+   To make long lists of file names
+   easier to deal with, &SCons; provides a
+   &Split; function
+   that takes a quoted list of file names,
+   with the names separated by spaces or other white-space characters,
+   and turns it into a list of separate file names.
+   Using the &Split; function turns the
+   previous example into:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      env.Program('program', Split('main.c file1.c file2.'))
+   </programlisting>
+
+   <para>
+
+   Putting the call to the &Split; function
+   inside the <function>env.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:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      list = Split('main.c file1.c file2.')
+      env.Program('program', list)
+   </programlisting>
+
+   <para>
+
+   Lastly, the &Split; function
+   doesn't care how much white space separates
+   the file names in the quoted string.
+   This allows you to create lists of file
+   names that span multiple lines,
+   which often makes for easier editing:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      list = Split('main.c
+                    file1.c
+                    file2.c')
+      env.Program('program', list)
+   </programlisting>
+
+ </section>
+
+ <section>
+ <title>Keyword Arguments</title>
+
+   <para>
+
+   &SCons; also allows you to identify
+   the output file and input source files
+   by Python keyword arguments.
+   The output file is known as the
+   <emphasis>target</emphasis>,
+   and the source file(s) are known (logically enough) as the
+   <emphasis>source</emphasis>.
+   The Python syntax for this is:
+
+   </para>
+
+   <programlisting>
+      env = Environment()
+      list = Split('main.c file1.c file2.')
+      env.Program(target = 'program', source = list)
+   </programlisting>
+
+   <para>
+
+   Whether or not you choose to use keyword arguments
+   to identify the target and source files
+   is purely a personal choice.
+
+   </para>
+
  </section>
 
  <section>
@@ -193,7 +361,11 @@ requirements of a build.
 
    <para>
 
-   If you want
+   In order to compile multiple programs
+   within the same &SConstruct; file,
+   simply call <function>env.Program</function>
+   multiple times,
+   once for each program you need to build:
 
    </para>
 
@@ -203,8 +375,14 @@ requirements of a build.
       env.Program('bar', ['bar1.c', 'bar2.c'])
    </programlisting>
 
+   <para>
+
+   &SCons; would then build the programs as follows:
+
+   </para>
+
    <literallayout>
-      % <userinput>scons .</userinput>
+      % <userinput>scons</userinput>
       cc -c bar1.c -o bar1.o
       cc -c bar2.c -o bar2.o
       cc -o bar bar1.o bar2.o
@@ -215,11 +393,11 @@ requirements of a build.
  </section>
 
  <section>
- <title>Sharing Files Between Multiple Programs</title>
+ <title>Sharing Source Files Between Multiple Programs</title>
 
    <para>
 
-   If you want
+   XXX
 
    </para>
 
@@ -231,7 +409,7 @@ requirements of a build.
    </programlisting>
 
    <literallayout>
-      % <userinput>scons .</userinput>
+      % <userinput>scons</userinput>
       cc -c bar1.c -o bar1.o
       cc -c bar2.c -o bar2.o
       cc -c common1.c -o common1.o