Issue 5062: XML fixes in the User's Guide. (Dirk Baechle)

23 files changed, 54 insertions, 51 deletions

diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in
index d824052..d0aae61 100644
--- a/doc/user/builders-commands.in
+++ b/doc/user/builders-commands.in
@@ -72,7 +72,7 @@
   <scons_example name="ex1">
      <file name="SConstruct" printme="1">
      env = Environment()
-     env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET")
+     env.Command('foo.out', 'foo.in', "sed 's/x/y/' &lt; $SOURCE > $TARGET")
      </file>
      <file name="foo.in">
      foo.in
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 2410831..1da45a5 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -823,7 +823,6 @@ This functionality could be invoked as in the following example:
         <file name="my_command" chmod="0755">
         cat
         </file>
-      </file>
 
     </scons_example>
 
@@ -842,7 +841,6 @@ This functionality could be invoked as in the following example:
                          MY_EMITTER = modify2)
       env1.Foo('file1')
       env2.Foo('file2')
-      </file>
     </sconstruct>
 
     <para>
@@ -931,7 +929,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_example name="site1">
-      <file name="site_scons/site_init.py" printme=1>
+      <file name="site_scons/site_init.py" printme="1">
         def TOOL_ADD_HEADER(env):
            """A Tool to add a header from $HEADER to the source file"""
            add_header = Builder(action=['echo "$HEADER" &gt; $TARGET',
@@ -998,7 +996,7 @@ This functionality could be invoked as in the following example:
     </para>
       
     <scons_example name="site2">
-      <file name="site_scons/my_utils.py" printme=1>
+      <file name="site_scons/my_utils.py" printme="1">
         from SCons.Script import *   # for Execute and Mkdir
         def build_id():
            """Return a build ID (stub version)"""
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 99dfc94..21aa656 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -703,7 +703,6 @@ This functionality could be invoked as in the following example:
         import os
         env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
         env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
-      
 
     </programlisting>
 
@@ -722,7 +721,6 @@ This functionality could be invoked as in the following example:
                          MY_EMITTER = modify2)
       env1.Foo('file1')
       env2.Foo('file2')
-      
     </programlisting>
 
     <para>
diff --git a/doc/user/command-line.in b/doc/user/command-line.in
index 6fb8299..abf8953 100644
--- a/doc/user/command-line.in
+++ b/doc/user/command-line.in
@@ -221,7 +221,7 @@
 
       </para>
 
-      <sconstruct)
+      <sconstruct>
         if not GetOption('help'):
             SConscript('src/SConscript', export='env')
       </sconstruct>
@@ -2195,7 +2195,7 @@
 
         Second,
         the contents of the &DEFAULT_TARGETS; list change
-        in response to calls to the &Default: function,
+        in response to calls to the &Default; function,
         as you can see from the following &SConstruct; file:
 
         </para>
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml
index 4b75eba..5ed8ed8 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.xml
@@ -214,7 +214,10 @@
 
       </para>
 
-      <programlisting></programlisting>
+      <programlisting>
+        if not GetOption('help'):
+            SConscript('src/SConscript', export='env')
+      </programlisting>
 
       <para>
 
@@ -2107,7 +2110,7 @@
 
         Second,
         the contents of the &DEFAULT_TARGETS; list change
-        in response to calls to the &Default;: function,
+        in response to calls to the &Default; function,
         as you can see from the following &SConstruct; file:
 
         </para>
diff --git a/doc/user/depends.in b/doc/user/depends.in
index 7191fa2..4428a63 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -386,7 +386,7 @@
 
       <para>
 
-      So configured, &SCons will still behave like
+      So configured, &SCons; will still behave like
       it does when using <literal>Decider('MD5')</literal>:
 
       </para>
diff --git a/doc/user/environments.in b/doc/user/environments.in
index 6672ea7..f767676 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -347,7 +347,7 @@ environment, of directory names, suffixes, etc.
 
     The <literal>external environment</literal>
     is the set of variables in the user's environment
-    at the time the user runs &SCons.
+    at the time the user runs &SCons;.
     These variables are available within the &SConscript; files
     through the Python <literal>os.environ</literal> dictionary.
     See <xref linkend="sect-external-environments"></xref>, below.
@@ -406,7 +406,7 @@ environment, of directory names, suffixes, etc.
 
   Unlike &Make;,  &SCons; does not automatically
   copy or import values between different environments
-  (with the exception of explicit clones of &consenvs,
+  (with the exception of explicit clones of &consenvs;,
   which inherit values from their parent).
   This is a deliberate design choice
   to make sure that builds are,
@@ -638,7 +638,7 @@ environment, of directory names, suffixes, etc.
          for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
              print "key = %s, value = %s" % (key, dict[key])
          </file>
-      </scons_Example>
+      </scons_example>
 
       <para>
 
@@ -779,18 +779,20 @@ environment, of directory names, suffixes, etc.
       If a problem occurs when expanding a construction variable,
       by default it is expanded to <literal>''</literal>
       (a null string), and will not cause scons to fail. 
-      
+      </para>
+
        <scons_example name="missing1">
          <file name="SConstruct" printme="1">
           env = Environment()
-          print "value is:", env.subst( '->$MISSING<-' )
+          print "value is:", env.subst( '->$MISSING&lt;-' )
         </file>
       </scons_example>
 
        <scons_output example="missing1">
           <scons_output_command>scons -Q</scons_output_command>
        </scons_output>
-      
+
+      <para>
       This default behaviour can be changed using the &AllowSubstExceptions;
       function.
       When a problem occurs with a variable expansion it generates
@@ -810,7 +812,7 @@ environment, of directory names, suffixes, etc.
          <file name="SConstruct" printme="1">
           AllowSubstExceptions()
           env = Environment()
-          print "value is:", env.subst( '->$MISSING<-' )
+          print "value is:", env.subst( '->$MISSING&lt;-' )
         </file>
       </scons_example>
 
@@ -830,7 +832,7 @@ environment, of directory names, suffixes, etc.
          <file name="SConstruct" printme="1">
           AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
           env = Environment()
-          print "value is:", env.subst( '->${1 / 0}<-' )
+          print "value is:", env.subst( '->${1 / 0}&lt;-' )
         </file>
       </scons_example>
 
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 6970a92..b2a8505 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -779,7 +779,8 @@ environment, of directory names, suffixes, etc.
       If a problem occurs when expanding a construction variable,
       by default it is expanded to <literal>''</literal>
       (a null string), and will not cause scons to fail. 
-      
+      </para>
+
        <programlisting>
           env = Environment()
           print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
@@ -790,7 +791,8 @@ environment, of directory names, suffixes, etc.
           value is: -&gt;&lt;-
           scons: `.' is up to date.
        </screen>
-      
+
+      <para>
       This default behaviour can be changed using the &AllowSubstExceptions;
       function.
       When a problem occurs with a variable expansion it generates
diff --git a/doc/user/factories.in b/doc/user/factories.in
index 4451807..cbe313a 100644
--- a/doc/user/factories.in
+++ b/doc/user/factories.in
@@ -209,7 +209,7 @@
     <para>
 
     Of course, like all of these &Action; factories,
-    the &Delete factory also expands
+    the &Delete; factory also expands
     &cv-link-TARGET; and &cv-link-SOURCE; variables appropriately.
     For example:
 
diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in
index 4286556..d70633d 100644
--- a/doc/user/hierarchy.in
+++ b/doc/user/hierarchy.in
@@ -688,7 +688,7 @@ make no difference to the build.
 
       Sometimes, you would like to be able to
       use information from a subsidiary
-      &SConscript file in some way.
+      &SConscript; file in some way.
       For example,
       suppose that you want to create one
       library from source files
diff --git a/doc/user/java.in b/doc/user/java.in
index e1675c1..4561a4c 100644
--- a/doc/user/java.in
+++ b/doc/user/java.in
@@ -390,7 +390,7 @@
     You can generate C header and source files
     for implementing native methods,
     by using the &b-link-JavaH; Builder.
-    There are several ways of using the &JavaH Builder.
+    There are several ways of using the &JavaH; Builder.
     One typical invocation might look like:
 
     </para>
@@ -636,7 +636,7 @@
     As it did with the &b-link-JavaH; Builder,
     &SCons; remembers the class directory
     and passes it as the <option>-classpath</option> option
-    to &rmic:
+    to &rmic;:
 
     </para>
 
diff --git a/doc/user/main.xml b/doc/user/main.xml
index df287a7..5bf274a 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -122,10 +122,10 @@
 
     <edition>Revision &buildrevision; (&builddate;)</edition>
 
-    <pubdate>2004, 2005, 2006, 2007, 2008</pubdate>
+    <pubdate>2004, 2005, 2006, 2007, 2008, 2009, 2010</pubdate>
 
     <copyright>
-      <year>2004, 2005, 2006, 2007, 2008</year>
+      <year>2004, 2005, 2006, 2007, 2008, 2009, 2010</year>
       <holder>Steven Knight</holder>
     </copyright>
 
diff --git a/doc/user/misc.in b/doc/user/misc.in
index 437d4fe..e7ab480 100644
--- a/doc/user/misc.in
+++ b/doc/user/misc.in
@@ -82,7 +82,7 @@
 
     <para>
 
-    And then &SCons will exit with the following error
+    And then &SCons; will exit with the following error
     message when a user runs it with an unsupported
     earlier version of Python:
 
@@ -151,7 +151,7 @@
 
     <para>
 
-    And then &SCons will exit with the following error
+    And then &SCons; will exit with the following error
     message when a user runs it with an unsupported
     earlier version of &SCons;:
 
@@ -274,13 +274,13 @@
       </file>
       <directory name="src"></directory>
       <directory name="src/include"></directory>
-      </file>
       <file name="src/include/private.h">
         exists
-      <directory name="include"></directory>
       </file>
+      <directory name="include"></directory>
       <file name="include/dist.h">
         exists
+      </file>
     </scons_example>
 
     <scons_output example="FindFile1b" os="posix">
diff --git a/doc/user/misc.xml b/doc/user/misc.xml
index 3cd3de7..05fe62e 100644
--- a/doc/user/misc.xml
+++ b/doc/user/misc.xml
@@ -263,7 +263,7 @@
        headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h']
        for hdr in headers:
            print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes)
-</programlisting>
+    </programlisting>
 
     <screen>
        % <userinput>scons -Q</userinput>
diff --git a/doc/user/output.in b/doc/user/output.in
index ca2034a..1383fc0 100644
--- a/doc/user/output.in
+++ b/doc/user/output.in
@@ -490,7 +490,7 @@
     over how to print each evaluated node
     by passing a Python function
     (or other Python callable)
-    to the &Progress function.
+    to the &Progress; function.
     Your function will be called
     for each evaluated node,
     allowing you to
diff --git a/doc/user/preface.in b/doc/user/preface.in
index a76fa1c..6f3140b 100644
--- a/doc/user/preface.in
+++ b/doc/user/preface.in
@@ -104,7 +104,7 @@
     <para>
 
     There are a few overriding principles
-    we try to live up to in designing and implementing &SCons:
+    we try to live up to in designing and implementing &SCons;:
 
     </para>
 
@@ -418,7 +418,7 @@
 
     <para>
 
-    If you want to receive announcements about &SCons,
+    If you want to receive announcements about &SCons;,
     join the low-volume &scons-announce; mailing list.
 
     </para>
diff --git a/doc/user/repositories.in b/doc/user/repositories.in
index d4ed418..33de530 100644
--- a/doc/user/repositories.in
+++ b/doc/user/repositories.in
@@ -210,9 +210,9 @@
     in the repository trees, though,
     it will be unable to find the <literal>#include</literal> files.
     If, for example, the &hello_c; file in
-    our previous example includes the &hello.h;
+    our previous example includes the &hello_h;
     in its current directory,
-    and the &hello.h; only exists in the repository:
+    and the &hello_h; only exists in the repository:
 
     </para>
 
diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml
index 766d8bc..2600381 100644
--- a/doc/user/repositories.xml
+++ b/doc/user/repositories.xml
@@ -193,9 +193,9 @@
     in the repository trees, though,
     it will be unable to find the <literal>#include</literal> files.
     If, for example, the &hello_c; file in
-    our previous example includes the &hello;.h;
+    our previous example includes the &hello_h;
     in its current directory,
-    and the &hello;.h; only exists in the repository:
+    and the &hello_h; only exists in the repository:
 
     </para>
 
diff --git a/doc/user/sconf.in b/doc/user/sconf.in
index 8ac4530..584a82e 100644
--- a/doc/user/sconf.in
+++ b/doc/user/sconf.in
@@ -31,7 +31,7 @@
   figuring out what libraries or header files
   are available on the local system.
   This section describes how to use
-  this &SCons feature.
+  this &SCons; feature.
 
   </para>
 
@@ -446,7 +446,7 @@
     when removing targets doesn't hurt anything,
     it's usually unnecessary.
     You can avoid this by using the
-    &GetOption(); method to
+    &GetOption; method to
     check whether the <option>-c</option> (clean)
     option has been invoked on the command line:
 
diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml
index b6e02eb..f5db744 100644
--- a/doc/user/sconf.xml
+++ b/doc/user/sconf.xml
@@ -446,7 +446,7 @@
     when removing targets doesn't hurt anything,
     it's usually unnecessary.
     You can avoid this by using the
-    &GetOption;(); method to
+    &GetOption; method to
     check whether the <option>-c</option> (clean)
     option has been invoked on the command line:
 
diff --git a/doc/user/simple.in b/doc/user/simple.in
index 9594501..8a25be5 100644
--- a/doc/user/simple.in
+++ b/doc/user/simple.in
@@ -360,7 +360,7 @@
 
      One important way in which the &SConstruct;
      file is not exactly like a normal Python script,
-     and is more like a &Makefile,
+     and is more like a &Makefile;,
      is that the order in which
      the &SCons; functions are called in
      the &SConstruct; file
@@ -453,7 +453,7 @@
      <para>
 
      Notice also that &SCons; built the &goodbye; program first,
-     even though the "reading &SConscript" output
+     even though the "reading &SConscript;" output
      shows that we called <literal>Program('hello.c')</literal>
      first in the &SConstruct; file.
 
diff --git a/doc/user/tasks.in b/doc/user/tasks.in
index de42cd1..79787a6 100644
--- a/doc/user/tasks.in
+++ b/doc/user/tasks.in
@@ -99,14 +99,14 @@ env.Append(CPPPATH = "#")
 
 ## Header example
 env.Append(BUILDERS =
-   {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET',
+   {'Copy1' : Builder(action = 'cat &lt; $SOURCE > $TARGET',
                       suffix='.h', src_suffix='.bar')})
 env.Copy1('test.bar') # produces test.h from test.bar. 
 env.Program('app','main.cpp') # indirectly depends on test.bar
 
 ## Source file example
 env.Append(BUILDERS =
-  {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET',
+  {'Copy2' : Builder(action = 'cat &lt; $SOURCE > $TARGET',
                      suffix='.cpp', src_suffix='.bar2')})
 foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2. 
 env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2.
diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in
index 3e0bfdb..392caf6 100644
--- a/doc/user/troubleshoot.in
+++ b/doc/user/troubleshoot.in
@@ -34,7 +34,7 @@
   &SCons; is no different.
   This appendix contains a number of
   different ways in which you can
-  get some additional insight into &SCons' behavior.
+  get some additional insight into &SCons;' behavior.
 
   </para>
 
@@ -410,12 +410,12 @@
 
     <para>
 
-    The <literaL>--tree</literal> option only prints
+    The <literal>--tree</literal> option only prints
     the dependency graph for the specified targets
     (or the default target(s) if none are specified on the command line).
     So if you specify a target like <filename>f2.o</filename>
     on the command line,
-    the <literaL>--tree</literal> option will only
+    the <literal>--tree</literal> option will only
     print the dependency graph for that file:
 
     </para>
@@ -722,7 +722,7 @@
 
     <para>
 
-    For example, the following &SConstruct file:
+    For example, the following &SConstruct; file:
 
     </para>