Tweak docs a bit [ci skip]

* Some clarification on Aliases.
* Markup improvements.
* Custom decider manpage entry didn't mention fourth arg.
  While fixing that, noticed an ordering problem in matching
  User Guide section, and converted example there to use
  hasttr instead of depending on mainly-for-REPL dir() function.
* Call it "empty string" instead of "null string" (more common
  Python terminology)
* Fix the table of installers (again, seems old fixes got lost)
* Added a note on installation to try to forestall common confusion.

Signed-off-by: Mats Wichmann <mats@linux.com>

8 files changed, 163 insertions, 120 deletions

diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 703855d..24bede6 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -561,13 +561,6 @@ int main() { printf("Hello, world!\n"); }
 
       </para>
 
-        <para>
-            The fourth argument <varname>repo_node</varname>,
-            is the &Node; to use if it is not None when comparing &BuildInfo;.
-            This is typically only set when the target node only exists in a
-            &Repository;
-        </para>
-
       <variablelist>
 
         <varlistentry>
@@ -612,22 +605,33 @@ int main() { printf("Hello, world!\n"); }
 
       <para>
 
-      Note that ignoring some of the arguments
-      in your custom &Decider; function
-      is a perfectly normal thing to do,
-      if they don't impact the way you want to
-      decide if the dependency file has changed.
+      These attributes may not be present at the time of the
+      first run.  Without any prior build, no targets have been
+      created and no <filename>.sconsign</filename> DB file exists yet.
+      So you should always check whether the
+      <varname>prev_ni</varname> attribute in question is available
+      (use the Python <function>hasattr</function> method or a
+      <literal>try</literal>-<literal>except</literal> block).
+
+      </para>
+
+
+      <para>
+
+      The fourth argument <varname>repo_node</varname>
+      is the &Node; to use if it is not None when comparing &BuildInfo;.
+      This is typically only set when the target node only exists in a
+      &Repository;
 
       </para>
 
       <para>
 
-      Another thing to look out for is the fact that the three
-      attributes above may not be present at the time of the first run.
-      Without any prior build, no targets have been created and no
-      <filename>.sconsign</filename> DB file exists yet.
-      So, you should always check whether the
-      <varname>prev_ni</varname> attribute in question is available.
+      Note that ignoring some of the arguments
+      in your custom &Decider; function
+      is a perfectly normal thing to do,
+      if they don't impact the way you want to
+      decide if the dependency file has changed.
 
       </para>
 
@@ -644,13 +648,14 @@ int main() { printf("Hello, world!\n"); }
       <sconstruct>
 env = Environment()
 
+
 def config_file_decider(dependency, target, prev_ni, repo_node=None):
     import os.path
 
     # We always have to init the .csig value...
     dep_csig = dependency.get_csig()
     # .csig may not exist, because no target was built yet...
-    if 'csig' not in dir(prev_ni):
+    if not prev_ni.hasattr("csig"):
         return True
     # Target file may not exist yet
     if not os.path.exists(str(target.abspath)):
@@ -660,17 +665,18 @@ def config_file_decider(dependency, target, prev_ni, repo_node=None):
         return True
     return False
 
+
 def update_file():
-    f = open("test.txt","a")
-    f.write("some line\n")
-    f.close()
+    with open("test.txt", "a") as f:
+        f.write("some line\n")
+
 
 update_file()
 
 # Activate our own decider function
 env.Decider(config_file_decider)
 
-env.Install("install","test.txt")
+env.Install("install", "test.txt")
       </sconstruct>
 
     </section>
diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml
index 286e882..502e434 100644
--- a/src/engine/SCons/Environment.xml
+++ b/src/engine/SCons/Environment.xml
@@ -442,6 +442,8 @@ including another alias.
 can be called multiple times for the same
 alias to add additional targets to the alias,
 or additional actions to the list for this alias.
+Aliases are global even if set through
+the construction environment method.
 </para>
 
 <para>
@@ -1145,17 +1147,16 @@ env.Decider('content')
 </example_commands>
 
 <para>
-In addition to the above already-available functions,
-the
+In addition to the above already-available functions, the
 <varname>function</varname>
-argument may be an actual Python function
-that takes the following three arguments:
+argument may be a Python function you supply.
+Such a function must accept the following four arguments:
 </para>
 
 <para>
 <variablelist>
 <varlistentry>
-<term><parameter>dependency</parameter></term>
+<term><parameter class="function">dependency</parameter></term>
 <listitem>
 <para>
 The Node (file) which
@@ -1169,7 +1170,7 @@ was built.
 </listitem>
 </varlistentry>
 <varlistentry>
-<term><parameter>target</parameter></term>
+<term><parameter class="function">target</parameter></term>
 <listitem>
 <para>
 The Node (file) being built.
@@ -1182,7 +1183,7 @@ has "changed."
 </listitem>
 </varlistentry>
 <varlistentry>
-<term><parameter>prev_ni</parameter></term>
+<term><parameter class="function">prev_ni</parameter></term>
 <listitem>
 <para>
 Stored information about the state of the
@@ -1198,12 +1199,17 @@ size, or content signature.
 </listitem>
 </varlistentry>
     <varlistentry>
-<term><parameter>repo_node</parameter></term>
+<term><parameter class="function">repo_node</parameter></term>
 <listitem>
 <para>
-Use this node instead of the one specified by
+If set, use this Node instead of the one specified by
 <varname>dependency</varname>
-    to determine if the dependency has changed.
+to determine if the dependency has changed.
+This argument is optional so should be written
+as a default argument (typically it would be
+written as <literal>repo_node=None</literal>).
+A caller will normally only set this if the
+target only exists in a Repository.
 </para>
 </listitem>
 </varlistentry>
diff --git a/src/engine/SCons/Script/Main.xml b/src/engine/SCons/Script/Main.xml
index 5c68dee..b54df0e 100644
--- a/src/engine/SCons/Script/Main.xml
+++ b/src/engine/SCons/Script/Main.xml
@@ -312,7 +312,7 @@ The options supported are:
 <term><literal>cache_debug</literal></term>
 <listitem>
 <para>
-which corresponds to --cache-debug;
+which corresponds to <option>--cache-debug</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -320,7 +320,7 @@ which corresponds to --cache-debug;
 <term><literal>cache_disable</literal></term>
 <listitem>
 <para>
-which corresponds to --cache-disable;
+which corresponds to <option>--cache-disable</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -328,7 +328,7 @@ which corresponds to --cache-disable;
 <term><literal>cache_force</literal></term>
 <listitem>
 <para>
-which corresponds to --cache-force;
+which corresponds to <option>--cache-force</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -336,7 +336,7 @@ which corresponds to --cache-force;
 <term><literal>cache_show</literal></term>
 <listitem>
 <para>
-which corresponds to --cache-show;
+which corresponds to <option>--cache-show</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -344,7 +344,8 @@ which corresponds to --cache-show;
 <term><literal>clean</literal></term>
 <listitem>
 <para>
-which corresponds to -c, --clean and --remove;
+which corresponds to <option>-c</option>, <option>--clean</option>
+and <option>--remove</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -352,7 +353,7 @@ which corresponds to -c, --clean and --remove;
 <term><literal>config</literal></term>
 <listitem>
 <para>
-which corresponds to --config;
+which corresponds to <option>--config</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -360,7 +361,7 @@ which corresponds to --config;
 <term><literal>directory</literal></term>
 <listitem>
 <para>
-which corresponds to -C and --directory;
+which corresponds to <option>-C</option> and <option>--directory</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -368,7 +369,7 @@ which corresponds to -C and --directory;
 <term><literal>diskcheck</literal></term>
 <listitem>
 <para>
-which corresponds to --diskcheck
+which corresponds to <option>--diskcheck</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -376,7 +377,7 @@ which corresponds to --diskcheck
 <term><literal>duplicate</literal></term>
 <listitem>
 <para>
-which corresponds to --duplicate;
+which corresponds to <option>--duplicate</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -384,7 +385,7 @@ which corresponds to --duplicate;
 <term><literal>file</literal></term>
 <listitem>
 <para>
-which corresponds to -f, --file, --makefile and --sconstruct;
+which corresponds to <option>-f</option>, <option>--file</option>, <option>--makefile</option> and <option>--sconstruct</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -392,7 +393,7 @@ which corresponds to -f, --file, --makefile and --sconstruct;
 <term><literal>help</literal></term>
 <listitem>
 <para>
-which corresponds to -h and --help;
+which corresponds to <option>-h</option> and <option>--help</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -400,7 +401,7 @@ which corresponds to -h and --help;
 <term><literal>ignore_errors</literal></term>
 <listitem>
 <para>
-which corresponds to --ignore-errors;
+which corresponds to <option>--ignore-errors</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -408,7 +409,7 @@ which corresponds to --ignore-errors;
 <term><literal>implicit_cache</literal></term>
 <listitem>
 <para>
-which corresponds to --implicit-cache;
+which corresponds to <option>--implicit-cache</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -416,7 +417,7 @@ which corresponds to --implicit-cache;
 <term><literal>implicit_deps_changed</literal></term>
 <listitem>
 <para>
-which corresponds to --implicit-deps-changed;
+which corresponds to <option>--implicit-deps-changed</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -424,7 +425,7 @@ which corresponds to --implicit-deps-changed;
 <term><literal>implicit_deps_unchanged</literal></term>
 <listitem>
 <para>
-which corresponds to --implicit-deps-unchanged;
+which corresponds to <option>--implicit-deps-unchanged</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -432,7 +433,7 @@ which corresponds to --implicit-deps-unchanged;
 <term><literal>interactive</literal></term>
 <listitem>
 <para>
-which corresponds to --interact and --interactive;
+which corresponds to <option>--interact</option> and <option>--interactive</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -440,7 +441,7 @@ which corresponds to --interact and --interactive;
 <term><literal>keep_going</literal></term>
 <listitem>
 <para>
-which corresponds to -k and --keep-going;
+which corresponds to <option>-k</option> and <option>--keep-going</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -448,7 +449,7 @@ which corresponds to -k and --keep-going;
 <term><literal>max_drift</literal></term>
 <listitem>
 <para>
-which corresponds to --max-drift;
+which corresponds to <option>--max-drift</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -456,7 +457,9 @@ which corresponds to --max-drift;
 <term><literal>no_exec</literal></term>
 <listitem>
 <para>
-which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+which corresponds to <option>-n</option>,
+<option>--no-exec</option>, <option>--just-print</option>,
+<option>--dry-run</option> and <option>--recon</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -464,7 +467,7 @@ which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
 <term><literal>no_site_dir</literal></term>
 <listitem>
 <para>
-which corresponds to --no-site-dir;
+which corresponds to <option>--no-site-dir</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -472,7 +475,7 @@ which corresponds to --no-site-dir;
 <term><literal>num_jobs</literal></term>
 <listitem>
 <para>
-which corresponds to -j and --jobs;
+which corresponds to <option>-j</option> and <option>--jobs</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -480,7 +483,7 @@ which corresponds to -j and --jobs;
 <term><literal>profile_file</literal></term>
 <listitem>
 <para>
-which corresponds to --profile;
+which corresponds to <option>--profile</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -488,7 +491,7 @@ which corresponds to --profile;
 <term><literal>question</literal></term>
 <listitem>
 <para>
-which corresponds to -q and --question;
+which corresponds to <option>-q</option> and <option>--question</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -496,7 +499,7 @@ which corresponds to -q and --question;
 <term><literal>random</literal></term>
 <listitem>
 <para>
-which corresponds to --random;
+which corresponds to <option>--random</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -504,7 +507,7 @@ which corresponds to --random;
 <term><literal>repository</literal></term>
 <listitem>
 <para>
-which corresponds to -Y, --repository and --srcdir;
+which corresponds to <option>-Y</option>, <option>--repository</option> and <option>--srcdir</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -512,7 +515,7 @@ which corresponds to -Y, --repository and --srcdir;
 <term><literal>silent</literal></term>
 <listitem>
 <para>
-which corresponds to -s, --silent and --quiet;
+which corresponds to <option>-s</option>, <option>--silent</option> and <option>--quiet</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -520,7 +523,7 @@ which corresponds to -s, --silent and --quiet;
 <term><literal>site_dir</literal></term>
 <listitem>
 <para>
-which corresponds to --site-dir;
+which corresponds to <option>--site-dir</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -528,7 +531,7 @@ which corresponds to --site-dir;
 <term><literal>stack_size</literal></term>
 <listitem>
 <para>
-which corresponds to --stack-size;
+which corresponds to <option>--stack-size</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -536,7 +539,7 @@ which corresponds to --stack-size;
 <term><literal>taskmastertrace_file</literal></term>
 <listitem>
 <para>
-which corresponds to --taskmastertrace; and
+which corresponds to <option>--taskmastertrace</option>; and
 </para>
 </listitem>
 </varlistentry>
@@ -544,7 +547,7 @@ which corresponds to --taskmastertrace; and
 <term><literal>warn</literal></term>
 <listitem>
 <para>
-which corresponds to --warn and --warning.
+which corresponds to <option>--warn</option> and <option>--warning</option>.
 </para>
 </listitem>
 </varlistentry>
@@ -553,7 +556,7 @@ which corresponds to --warn and --warning.
 
 <para>
 See the documentation for the
-corresponding command line object for information about each specific
+corresponding command line option for information about each specific
 option.
 </para>
 </summary>
@@ -749,7 +752,8 @@ line options from a SConscript file. The options supported are:
 <term><literal>clean</literal></term>
 <listitem>
 <para>
-which corresponds to -c, --clean and --remove;
+which corresponds to <option>-c</option>, <option>--clean</option>
+and <option>--remove</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -757,7 +761,7 @@ which corresponds to -c, --clean and --remove;
 <term><literal>duplicate</literal></term>
 <listitem>
 <para>
-which corresponds to --duplicate;
+which corresponds to <option>--duplicate</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -765,7 +769,7 @@ which corresponds to --duplicate;
 <term><literal>help</literal></term>
 <listitem>
 <para>
-which corresponds to -h and --help;
+which corresponds to <option>-h</option> and <option>--help</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -773,7 +777,7 @@ which corresponds to -h and --help;
 <term><literal>implicit_cache</literal></term>
 <listitem>
 <para>
-which corresponds to --implicit-cache;
+which corresponds to <option>--implicit-cache</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -781,7 +785,7 @@ which corresponds to --implicit-cache;
 <term><literal>max_drift</literal></term>
 <listitem>
 <para>
-which corresponds to --max-drift;
+which corresponds to <option>--max-drift</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -789,7 +793,9 @@ which corresponds to --max-drift;
 <term><literal>no_exec</literal></term>
 <listitem>
 <para>
-which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
+which corresponds to <option>-n</option>, <option>--no-exec</option>,
+<option>--just-print</option>, <option>--dry-run</option>
+and <option>--recon</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -797,7 +803,7 @@ which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
 <term><literal>num_jobs</literal></term>
 <listitem>
 <para>
-which corresponds to -j and --jobs;
+which corresponds to <option>-j</option> and <option>--jobs</option>;
 </para>
 </listitem>
 </varlistentry>
@@ -805,7 +811,7 @@ which corresponds to -j and --jobs;
 <term><literal>random</literal></term>
 <listitem>
 <para>
-which corresponds to --random; and
+which corresponds to <option>--random</option>; and
 </para>
 </listitem>
 </varlistentry>
@@ -813,7 +819,7 @@ which corresponds to --random; and
 <term><literal>silent</literal></term>
 <listitem>
 <para>
-which corresponds to --silent.
+which corresponds to <option>--silent</option>.
 </para>
 </listitem>
 </varlistentry>
@@ -830,7 +836,7 @@ which corresponds to --stack-size.
 
 <para>
 See the documentation for the
-corresponding command line object for information about each specific
+corresponding command line option for information about each specific
 option.
 </para>
 
diff --git a/src/engine/SCons/Subst.xml b/src/engine/SCons/Subst.xml
index 980a9ad..77372ce 100644
--- a/src/engine/SCons/Subst.xml
+++ b/src/engine/SCons/Subst.xml
@@ -39,7 +39,7 @@ or
 <literal>IndexError</literal>
 exception will expand to a
 <literal>''</literal>
-(a null string) and not cause scons to fail.
+(an empty string) and not cause scons to fail.
 All exceptions not in the specified list
 will generate an error message
 and terminate processing.
diff --git a/src/engine/SCons/Tool/install.xml b/src/engine/SCons/Tool/install.xml
index 150308b..ce70d91 100644
--- a/src/engine/SCons/Tool/install.xml
+++ b/src/engine/SCons/Tool/install.xml
@@ -50,10 +50,24 @@ a builder.
 </para>
 
 <example_commands>
-env.Install('/usr/local/bin', source = ['foo', 'bar'])
+env.Install(target='/usr/local/bin', source=['foo', 'bar'])
 </example_commands>
 
 <para>
+Note that if target paths chosen for the
+&Install; builder (and the related &InstallAs; and
+&InstallVersionedLib; builders) are outside the
+project tree, such as in the example above,
+they may not be selected for "building" by default,
+since in the absence of other instructions
+&scons; builds targets that are underneath the top directory
+(the directory that contains the &SConstruct; file,
+usually the current directory).
+Use command line targets or the &Default; function
+in this case.
+</para>
+
+<para>
 If the <option>--install-sandbox</option> command line
 option is given, the target directory will be prefixed
 by the directory path specified.
@@ -86,12 +100,16 @@ arguments list different numbers of files or directories.
 </para>
 
 <example_commands>
-env.InstallAs(target = '/usr/local/bin/foo',
-              source = 'foo_debug')
-env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
-              source = ['libFOO.a', 'libBAR.a'])
+env.InstallAs(target='/usr/local/bin/foo',
+              source='foo_debug')
+env.InstallAs(target=['../lib/libfoo.a', '../lib/libbar.a'],
+              source=['libFOO.a', 'libBAR.a'])
 </example_commands>
 
+<para>
+See the note under &Install;.
+</para>
+
 </summary>
 </builder>
 
@@ -103,9 +121,14 @@ architecture will be generated based on symlinks of the source library.
 </para>
 
 <example_commands>
-env.InstallVersionedLib(target = '/usr/local/bin/foo',
-              source = 'libxyz.1.5.2.so')
+env.InstallVersionedLib(target='/usr/local/bin/foo',
+                        source='libxyz.1.5.2.so')
 </example_commands>
+
+<para>
+See the note under &Install;.
+</para>
+
 </summary>
 </builder>
 
diff --git a/src/engine/SCons/Tool/javac.xml b/src/engine/SCons/Tool/javac.xml
index bc89342..893130b 100644
--- a/src/engine/SCons/Tool/javac.xml
+++ b/src/engine/SCons/Tool/javac.xml
@@ -95,9 +95,9 @@ See its __doc__ string for a discussion of the format.
             </para>
 
             <example_commands>
-                env.Java(target = 'classes', source = 'src')
-                env.Java(target = 'classes', source = ['src1', 'src2'])
-                env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
+env.Java(target = 'classes', source = 'src')
+env.Java(target = 'classes', source = ['src1', 'src2'])
+env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
             </example_commands>
 
             <para>
@@ -114,8 +114,8 @@ See its __doc__ string for a discussion of the format.
             </para>
 
             <example_commands>
-                env = Environment()
-                env['ENV']['LANG'] = 'en_GB.UTF-8'
+env = Environment()
+env['ENV']['LANG'] = 'en_GB.UTF-8'
             </example_commands>
         </summary>
     </builder>
@@ -174,7 +174,7 @@ See its __doc__ string for a discussion of the format.
             </para>
 
             <example_commands>
-                env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
+env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
             </example_commands>
         </summary>
     </cvar>
diff --git a/src/engine/SCons/Tool/packaging/__init__.xml b/src/engine/SCons/Tool/packaging/__init__.xml
index 31c6eed..66a7aa0 100644
--- a/src/engine/SCons/Tool/packaging/__init__.xml
+++ b/src/engine/SCons/Tool/packaging/__init__.xml
@@ -62,24 +62,25 @@ option or with the &cv-PACKAGETYPE; construction variable. Currently
 the following packagers available:
 </para>
 
-<para>
- * msi - Microsoft Installer
- * rpm - RPM Package Manger
- * ipkg - Itsy Package Management System
- * tarbz2 - bzip2 compressed tar
- * targz - gzip compressed tar
- * tarxz - xz compressed tar
- * zip - zip file
- * src_tarbz2 - bzip2 compressed tar source
- * src_targz - gzip compressed tar source
- * src_tarxz - xz compressed tar source
- * src_zip - zip file source
-</para>
+<para><literal>msi</literal> - Microsoft Installer</para>
+<para><literal>rpm</literal> - RPM Package Manger</para>
+<para><literal>ipkg</literal> - Itsy Package Management System</para>
+<para><literal>tarbz2</literal> - bzip2 compressed tar</para>
+<para><literal>targz</literal> - gzip compressed tar</para>
+<para><literal>tarxz</literal> - xz compressed tar</para>
+<para><literal>zip</literal> - zip file</para>
+<para><literal>src_tarbz2</literal> - bzip2 compressed tar source</para>
+<para><literal>src_targz</literal> - gzip compressed tar source</para>
+<para><literal>src_tarxz</literal> - xz compressed tar source</para>
+<para><literal>src_zip</literal> - zip file source</para>
 
 <para>
-An updated list is always available under the "package_type" option when
-running "scons --help" on a project that has packaging activated.
+An updated list is always available under the
+<replaceable>package_type</replaceable> option when
+running <command>scons --help</command>
+on a project that has packaging activated.
 </para>
+
 <example_commands>
 env = Environment(tools=['default', 'packaging'])
 env.Install('/bin/', 'my_program')
@@ -198,20 +199,21 @@ placed if applicable.  The default value is "$NAME-$VERSION".
 Selects the package type to build.  Currently these are available:
 </para>
 
-<para>
- * msi - Microsoft Installer
- * rpm - Redhat Package Manger
- * ipkg - Itsy Package Management System
- * tarbz2 - compressed tar
- * targz - compressed tar
- * zip - zip file
- * src_tarbz2 - compressed tar source
- * src_targz - compressed tar source
- * src_zip - zip file source
-</para>
+<para><literal>msi</literal> - Microsoft Installer</para>
+<para><literal>rpm</literal> - RPM Package Manger</para>
+<para><literal>ipkg</literal> - Itsy Package Management System</para>
+<para><literal>tarbz2</literal> - bzip2 compressed tar</para>
+<para><literal>targz</literal> - gzip compressed tar</para>
+<para><literal>tarxz</literal> - xz compressed tar</para>
+<para><literal>zip</literal> - zip file</para>
+<para><literal>src_tarbz2</literal> - bzip2 compressed tar source</para>
+<para><literal>src_targz</literal> - gzip compressed tar source</para>
+<para><literal>src_tarxz</literal> - xz compressed tar source</para>
+<para><literal>src_zip</literal> - zip file source</para>
 
 <para>
-This may be overridden with the "package_type" command line option.
+This may be overridden with the <option>package_type</option>
+command line option.
 </para>
 </summary>
 </cvar>
diff --git a/src/engine/SCons/Tool/textfile.xml b/src/engine/SCons/Tool/textfile.xml
index 957e18c..878eb9f 100644
--- a/src/engine/SCons/Tool/textfile.xml
+++ b/src/engine/SCons/Tool/textfile.xml
@@ -59,7 +59,7 @@ see the &b-Substfile; description for details.
 <para>
 The prefix and suffix specified by the &cv-TEXTFILEPREFIX;
 and &cv-TEXTFILESUFFIX; construction variables
-(the null string and <filename>.txt</filename> by default, respectively)
+(an empty string and <filename>.txt</filename> by default, respectively)
 are automatically added to the target if they are not already present.
 Examples:
 </para>
@@ -124,7 +124,7 @@ the suffix is stripped and the remainder is used as the default target name.
 <para>
 The prefix and suffix specified by the &cv-SUBSTFILEPREFIX;
 and &cv-SUBSTFILESUFFIX; construction variables
-(the null string by default in both cases)
+(an empty string by default in both cases)
 are automatically added to the target if they are not already present.
 </para>
 
@@ -218,7 +218,7 @@ lists of tuples are also acceptable.
 <summary>
 <para>
 The prefix used for &b-Substfile; file names,
-the null string by default.
+an empty string by default.
 </para>
 </summary>
 </cvar>
@@ -227,7 +227,7 @@ the null string by default.
 <summary>
 <para>
 The suffix used for &b-Substfile; file names,
-the null string by default.
+an empty string by default.
 </para>
 </summary>
 </cvar>
@@ -236,7 +236,7 @@ the null string by default.
 <summary>
 <para>
 The prefix used for &b-Textfile; file names,
-the null string by default.
+an empty string by default.
 </para>
 </summary>
 </cvar>