User's Guide updates: fix typos, clarify various things. (Robert P. J. Day)

10 files changed, 121 insertions, 53 deletions

diff --git a/doc/scons.mod b/doc/scons.mod
index a2927cf..7f1b54a 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -46,7 +46,6 @@
 <!ENTITY ranlib         "<application>ranlib</application>">
 <!ENTITY rmic           "<application>rmic</application>">
 <!ENTITY SCons          "<application>SCons</application>">
-<!ENTITY scons          "<application>scons</application>">
 <!ENTITY ScCons         "<application>ScCons</application>">
 <!ENTITY swig           "<application>swig</application>">
 <!ENTITY tar            "<application>tar</application>">
@@ -128,6 +127,7 @@
 <!ENTITY build "<filename>build</filename>">
 <!ENTITY Makefile "<filename>Makefile</filename>">
 <!ENTITY Makefiles "<filename>Makefiles</filename>">
+<!ENTITY scons "<filename>scons</filename>">
 <!ENTITY SConscript "<filename>SConscript</filename>">
 <!ENTITY SConstruct "<filename>SConstruct</filename>">
 <!ENTITY Sconstruct "<filename>Sconstruct</filename>">
@@ -463,11 +463,11 @@
 
 -->
 
-<!ENTITY bar "<application>bar</application>">
+<!ENTITY bar "<filename>bar</filename>">
 <!ENTITY common1_c "<filename>common1.c</filename>">
 <!ENTITY common2_c "<filename>common2.c</filename>">
 <!ENTITY custom_py "<filename>custom.py</filename>">
-<!ENTITY goodbye "<application>goodbye</application>">
+<!ENTITY goodbye "<filename>goodbye</filename>">
 <!ENTITY goodbye_o "<filename>goodbye.o</filename>">
 <!ENTITY goodbye_obj "<filename>goodbye.obj</filename>">
 <!ENTITY file_dll "<filename>file.dll</filename>">
@@ -476,10 +476,10 @@
 <!ENTITY file_o "<filename>file.o</filename>">
 <!ENTITY file_obj "<filename>file.obj</filename>">
 <!ENTITY file_out "<filename>file.out</filename>">
-<!ENTITY foo "<application>foo</application>">
+<!ENTITY foo "<filename>foo</filename>">
 <!ENTITY foo_o "<filename>foo.o</filename>">
 <!ENTITY foo_obj "<filename>foo.obj</filename>">
-<!ENTITY hello "<application>hello</application>">
+<!ENTITY hello "<filename>hello</filename>">
 <!ENTITY hello_c "<filename>hello.c</filename>">
 <!ENTITY hello_exe "<filename>hello.exe</filename>">
 <!ENTITY hello_h "<filename>hello.h</filename>">
@@ -487,8 +487,8 @@
 <!ENTITY hello_obj "<filename>hello.obj</filename>">
 <!ENTITY libfile_a "<filename>libfile_a</filename>">
 <!ENTITY libfile_so "<filename>libfile_so</filename>">
-<!ENTITY new_hello "<application>new_hello</application>">
-<!ENTITY new_hello_exe "<application>new_hello.exe</application>">
+<!ENTITY new_hello "<filename>new_hello</filename>">
+<!ENTITY new_hello_exe "<filename>new_hello.exe</filename>">
 <!ENTITY prog "<filename>prog</filename>">
 <!ENTITY prog1 "<filename>prog1</filename>">
 <!ENTITY prog2 "<filename>prog2</filename>">
diff --git a/doc/user/build-install.in b/doc/user/build-install.in
index e473e37..8616361 100644
--- a/doc/user/build-install.in
+++ b/doc/user/build-install.in
@@ -136,7 +136,7 @@
     If you need to install Python and have a choice,
     we recommend using the most recent Python 2.5 version available.
     Python 2.5 has significant improvements
-    the help speed up the performance of &SCons;.
+    that help speed up the performance of &SCons;.
 
     </para>
 
@@ -214,8 +214,7 @@
 
       <para>
 
-      Or, you can use a graphical RPM package manager
-      like <application>gnorpm</application>.
+      Or, you can use a graphical RPM package manager.
       See your package manager application's documention
       for specific instructions about
       how to use it to install a downloaded RPM.
@@ -411,7 +410,7 @@
     <para>
 
     This will build &SCons;,
-    install the <application>scons</application> script
+    install the &scons; script
     in the default system scripts directory
     (<filename>/usr/local/bin</filename> or
     <filename>C:\Python25\Scripts</filename>),
@@ -549,7 +548,7 @@
       For example,
       to install &SCons; in appropriate locations
       relative to the user's <literal>$HOME</literal> directory,
-      the <application>scons</application> script in
+      the &scons; script in
       <filename>$HOME/bin</filename>
       and the build engine in 
       <filename>$HOME/lib/scons</filename>,
@@ -570,6 +569,21 @@
 
       </para>
 
+      <para>
+
+      This can also be used to experiment with a newer
+      version of &SCons; than the one installed
+      in your system locations.
+      Of course, the location in which you install the
+      newer version of the &scons; script
+      (<filename>$HOME/bin</filename> in the above example)
+      must be configured in your &PATH; variable
+      before the directory containing
+      the system-installed version
+      of the &scons; script.
+
+      </para>
+
     </section>
 
   </section>
diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml
index e473e37..8616361 100644
--- a/doc/user/build-install.xml
+++ b/doc/user/build-install.xml
@@ -136,7 +136,7 @@
     If you need to install Python and have a choice,
     we recommend using the most recent Python 2.5 version available.
     Python 2.5 has significant improvements
-    the help speed up the performance of &SCons;.
+    that help speed up the performance of &SCons;.
 
     </para>
 
@@ -214,8 +214,7 @@
 
       <para>
 
-      Or, you can use a graphical RPM package manager
-      like <application>gnorpm</application>.
+      Or, you can use a graphical RPM package manager.
       See your package manager application's documention
       for specific instructions about
       how to use it to install a downloaded RPM.
@@ -411,7 +410,7 @@
     <para>
 
     This will build &SCons;,
-    install the <application>scons</application> script
+    install the &scons; script
     in the default system scripts directory
     (<filename>/usr/local/bin</filename> or
     <filename>C:\Python25\Scripts</filename>),
@@ -549,7 +548,7 @@
       For example,
       to install &SCons; in appropriate locations
       relative to the user's <literal>$HOME</literal> directory,
-      the <application>scons</application> script in
+      the &scons; script in
       <filename>$HOME/bin</filename>
       and the build engine in 
       <filename>$HOME/lib/scons</filename>,
@@ -570,6 +569,21 @@
 
       </para>
 
+      <para>
+
+      This can also be used to experiment with a newer
+      version of &SCons; than the one installed
+      in your system locations.
+      Of course, the location in which you install the
+      newer version of the &scons; script
+      (<filename>$HOME/bin</filename> in the above example)
+      must be configured in your &PATH; variable
+      before the directory containing
+      the system-installed version
+      of the &scons; script.
+
+      </para>
+
     </section>
 
   </section>
diff --git a/doc/user/depends.in b/doc/user/depends.in
index 8cd9970..f0fa853 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -27,10 +27,10 @@
 
   So far we've seen how &SCons; handles one-time builds.
   But one of the main functions of a build tool like &SCons;
-  is to rebuild only the necessary things
+  is to rebuild only what is necessary
   when source files change--or, put another way,
   &SCons; should <emphasis>not</emphasis>
-  waste time rebuilding things that have already been built.
+  waste time rebuilding things that don't need to be rebuilt.
   You can see this at work simply by re-invoking &SCons;
   after building our simple &hello; example:
 
@@ -168,7 +168,7 @@
 
         <para>
 
-        Using MD5 Signatures to decide if an input file has changed
+        Using MD5 signatures to decide if an input file has changed
         has one surprising benefit:
         if a source file has been changed
         in such a way that the contents of the
@@ -237,7 +237,7 @@
       The most familiar way to use time stamps
       is the way &Make; does:
       that is, have &SCons; decide
-      and target must be rebuilt if
+      that a target must be rebuilt
       if a source file's modification time is
       <emphasis>newer</emphasis>
       than the target file.
@@ -366,8 +366,8 @@
       As a performance enhancement,
       &SCons; provides a way to use
       MD5 checksums of file contents
-      but to only read the contents
-      whenever the file's timestamp has changed.
+      but to read those contents
+      only when the file's timestamp has changed.
       To do this, call the &Decider;
       function with <literal>'MD5-timestamp'</literal>
       argument as follows:
@@ -444,11 +444,11 @@
       While most developers are programming,
       this isn't a problem in practice,
       since it's unlikely that someone will have built
-      and then thought quickly enought to make a substantive
+      and then thought quickly enough to make a substantive
       change to a source file within one second.
       Certain build scripts or
       continuous integration tools may, however,
-      rely on the ability to applying changes to files
+      rely on the ability to apply changes to files
       automatically and then rebuild as quickly as possible,
       in which case use of
       <literal>Decider('MD5-timestamp')</literal>
@@ -486,7 +486,7 @@
       We'd like to have each target file depend on
       only its section of the input file.
       However, since the input file may contain a lot of data,
-      we only want to open the input file if its timestamp has changed.
+      we want to open the input file only if its timestamp has changed.
       This could done with a custom
       &Decider; function that might look something like this:
 
@@ -615,7 +615,7 @@
 
       For example, if we arbitrarily want to build
       one program using MD5 checkums
-      and another use file modification times
+      and another using file modification times
       from the same source
       we might configure it this way:
 
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 512ac68..0e9740f 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -27,10 +27,10 @@
 
   So far we've seen how &SCons; handles one-time builds.
   But one of the main functions of a build tool like &SCons;
-  is to rebuild only the necessary things
+  is to rebuild only what is necessary
   when source files change--or, put another way,
   &SCons; should <emphasis>not</emphasis>
-  waste time rebuilding things that have already been built.
+  waste time rebuilding things that don't need to be rebuilt.
   You can see this at work simply by re-invoking &SCons;
   after building our simple &hello; example:
 
@@ -175,7 +175,7 @@
 
         <para>
 
-        Using MD5 Signatures to decide if an input file has changed
+        Using MD5 signatures to decide if an input file has changed
         has one surprising benefit:
         if a source file has been changed
         in such a way that the contents of the
@@ -249,7 +249,7 @@
       The most familiar way to use time stamps
       is the way &Make; does:
       that is, have &SCons; decide
-      and target must be rebuilt if
+      that a target must be rebuilt
       if a source file's modification time is
       <emphasis>newer</emphasis>
       than the target file.
@@ -350,7 +350,7 @@
          % <userinput>touch -t 198901010000 hello.c</userinput>
          % <userinput>scons -Q hello</userinput>
          cc -o hello.o -c hello.c
-         scons: `hello' is up to date.
+         cc -o hello hello.o
       </screen>
 
       <para>
@@ -376,8 +376,8 @@
       As a performance enhancement,
       &SCons; provides a way to use
       MD5 checksums of file contents
-      but to only read the contents
-      whenever the file's timestamp has changed.
+      but to read those contents
+      only when the file's timestamp has changed.
       To do this, call the &Decider;
       function with <literal>'MD5-timestamp'</literal>
       argument as follows:
@@ -449,11 +449,11 @@
       While most developers are programming,
       this isn't a problem in practice,
       since it's unlikely that someone will have built
-      and then thought quickly enought to make a substantive
+      and then thought quickly enough to make a substantive
       change to a source file within one second.
       Certain build scripts or
       continuous integration tools may, however,
-      rely on the ability to applying changes to files
+      rely on the ability to apply changes to files
       automatically and then rebuild as quickly as possible,
       in which case use of
       <literal>Decider('MD5-timestamp')</literal>
@@ -491,7 +491,7 @@
       We'd like to have each target file depend on
       only its section of the input file.
       However, since the input file may contain a lot of data,
-      we only want to open the input file if its timestamp has changed.
+      we want to open the input file only if its timestamp has changed.
       This could done with a custom
       &Decider; function that might look something like this:
 
@@ -615,7 +615,7 @@
 
       For example, if we arbitrarily want to build
       one program using MD5 checkums
-      and another use file modification times
+      and another using file modification times
       from the same source
       we might configure it this way:
 
diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in
index 23b585c..f7bd7d5 100644
--- a/doc/user/less-simple.in
+++ b/doc/user/less-simple.in
@@ -231,8 +231,12 @@
 
     <para>
 
-    The SCons man page has more details on using &Glob; with Variant
-    directories and Repositories, and returning strings rather than Nodes.
+    The SCons man page has more details on using &Glob;
+    with variant directories
+    (see <xref linkend="chap-variants"></xref>, below)
+    and repositories
+    (see <xref linkend="chap-repositories"></xref>, below),
+    and returning strings rather than Nodes.
 
     </para>
 
@@ -578,7 +582,7 @@
 
     &SCons; recognizes that the object files for
     the &common1_c; and &common2_c; source files
-    each only need to be built once,
+    each need to be built only once,
     even though the resulting object files are
     each linked in to both of the resulting executable programs:
 
diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml
index 28fc053..0bc382e 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.xml
@@ -220,8 +220,12 @@
 
     <para>
 
-    The SCons man page has more details on using &Glob; with Variant
-    directories and Repositories, and returning strings rather than Nodes.
+    The SCons man page has more details on using &Glob;
+    with variant directories
+    (see <xref linkend="chap-variants"></xref>, below)
+    and repositories
+    (see <xref linkend="chap-repositories"></xref>, below),
+    and returning strings rather than Nodes.
 
     </para>
 
@@ -544,7 +548,7 @@
 
     &SCons; recognizes that the object files for
     the &common1_c; and &common2_c; source files
-    each only need to be built once,
+    each need to be built only once,
     even though the resulting object files are
     each linked in to both of the resulting executable programs:
 
diff --git a/doc/user/libraries.in b/doc/user/libraries.in
index 73ba6c9..e219e21 100644
--- a/doc/user/libraries.in
+++ b/doc/user/libraries.in
@@ -62,7 +62,7 @@
     &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>
 
diff --git a/doc/user/nodes.in b/doc/user/nodes.in
index 6d4b267..d8169df 100644
--- a/doc/user/nodes.in
+++ b/doc/user/nodes.in
@@ -44,7 +44,7 @@
     &Node; objects that identify the
     target file or files that will be built.
     These returned &Nodes; can be passed
-    as source files to other builder methods,
+    as arguments to other builder methods.
 
     </para>
 
@@ -81,7 +81,7 @@
 
     <para>
 
-    The problem with listing the names as strings
+    The problem with specifying the names as strings
     is that our &SConstruct; file is no longer portable
     across operating systems.
     It won't, for example, work on Windows
@@ -155,7 +155,7 @@
     between Nodes that represent files
     and Nodes that represent directories.
     &SCons; supports &File; and &Dir;
-    functions that, repectively,
+    functions that, respectively,
     return a file or directory Node:
 
     </para>
@@ -231,6 +231,11 @@
     One of the most common things you can do
     with a Node is use it to print the
     file name that the node represents.
+    Keep in mind, though, that because the object
+    returned by a builder call
+    is a <emphasis>list</emphasis> of Nodes,
+    you must use Python subscripts
+    to fetch individual Nodes from the list.
     For example, the following &SConstruct; file:
 
     </para>
@@ -267,6 +272,17 @@
       <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
 
+    <para>
+
+    Note that in the above example,
+    the <literal>object_list[0]</literal>
+    extracts an actual Node <emphasis>object</emphasis>
+    from the list,
+    and the Python <literal>print</literal> statement
+    converts the object to a string for printing.
+
+    </para>
+
   </section>
 
   <section>
@@ -276,7 +292,7 @@
 
     Printing a &Node;'s name
     as described in the previous section
-    works because the string representation of a &Node;
+    works because the string representation of a &Node; object
     is the name of the file.
     If you want to do something other than
     print the name of the file,
diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml
index 28af973..8f3436a 100644
--- a/doc/user/nodes.xml
+++ b/doc/user/nodes.xml
@@ -44,7 +44,7 @@
     &Node; objects that identify the
     target file or files that will be built.
     These returned &Nodes; can be passed
-    as source files to other builder methods,
+    as arguments to other builder methods.
 
     </para>
 
@@ -81,7 +81,7 @@
 
     <para>
 
-    The problem with listing the names as strings
+    The problem with specifying the names as strings
     is that our &SConstruct; file is no longer portable
     across operating systems.
     It won't, for example, work on Windows
@@ -153,7 +153,7 @@
     between Nodes that represent files
     and Nodes that represent directories.
     &SCons; supports &File; and &Dir;
-    functions that, repectively,
+    functions that, respectively,
     return a file or directory Node:
 
     </para>
@@ -227,6 +227,11 @@
     One of the most common things you can do
     with a Node is use it to print the
     file name that the node represents.
+    Keep in mind, though, that because the object
+    returned by a builder call
+    is a <emphasis>list</emphasis> of Nodes,
+    you must use Python subscripts
+    to fetch individual Nodes from the list.
     For example, the following &SConstruct; file:
 
     </para>
@@ -272,6 +277,17 @@
       link /nologo /OUT:hello.exe hello.obj
     </screen>
 
+    <para>
+
+    Note that in the above example,
+    the <literal>object_list[0]</literal>
+    extracts an actual Node <emphasis>object</emphasis>
+    from the list,
+    and the Python <literal>print</literal> statement
+    converts the object to a string for printing.
+
+    </para>
+
   </section>
 
   <section>
@@ -281,7 +297,7 @@
 
     Printing a &Node;'s name
     as described in the previous section
-    works because the string representation of a &Node;
+    works because the string representation of a &Node; object
     is the name of the file.
     If you want to do something other than
     print the name of the file,