Merge pull request #3581 from mwichmann/more-uguide

Some user guide tweaks

3 files changed, 97 insertions, 65 deletions

diff --git a/doc/scons.mod b/doc/scons.mod
index 024afab..fe35657 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -97,20 +97,21 @@
 
 -->
 
-<!ENTITY config "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--config</literal>">
-<!ENTITY debug-explain "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=explain</literal>">
-<!ENTITY debug-findlibs "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=findlibs</literal>">
-<!ENTITY debug-includes "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=includes</literal>">
-<!ENTITY debug-prepare "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=prepare</literal>">
-<!ENTITY debug-presub "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=presub</literal>">
-<!ENTITY debug-stacktrace "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=stacktrace</literal>">
-<!ENTITY implicit-cache "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--implicit-cache</literal>">
-<!ENTITY implicit-deps-changed "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--implicit-deps-changed</literal>">
-<!ENTITY implicit-deps-unchanged "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--implicit-deps-unchanged</literal>">
-<!ENTITY profile "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--profile</literal>">
-<!ENTITY taskmastertrace "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--taskmastertrace</literal>">
-<!ENTITY tree "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>--tree</literal>">
-<!ENTITY Q "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>-Q</literal>">
+<!ENTITY config "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--config</option>">
+<!ENTITY debug-duplicate "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=duplicate</option>">
+<!ENTITY debug-explain "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=explain</option>">
+<!ENTITY debug-findlibs "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=findlibs</option>">
+<!ENTITY debug-includes "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=includes</option>">
+<!ENTITY debug-prepare "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=prepare</option>">
+<!ENTITY debug-presub "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=presub</option>">
+<!ENTITY debug-stacktrace "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--debug=stacktrace</option>">
+<!ENTITY implicit-cache "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--implicit-cache</option>">
+<!ENTITY implicit-deps-changed "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--implicit-deps-changed</option>">
+<!ENTITY implicit-deps-unchanged "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--implicit-deps-unchanged</option>">
+<!ENTITY profile "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--profile</option>">
+<!ENTITY taskmastertrace "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--taskmastertrace</option>">
+<!ENTITY tree "<option xmlns='http://www.scons.org/dbxsd/v1.0'>--tree</option>">
+<!ENTITY Q "<option xmlns='http://www.scons.org/dbxsd/v1.0'>-Q</option>">
 
 <!--
 
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index 19ade49..412b50a 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -160,7 +160,7 @@ CacheDir('/usr/local/build_cache')
 
     <para>
 
-    If, however, you use the <literal>--cache-show</literal> option,
+    If, however, you use the <option>--cache-show</option> option,
     &SCons; will print the command line that it
     <emphasis>would</emphasis> have executed
     to build the file,
@@ -277,7 +277,7 @@ Retrieved `hello' from cache
     <para>
 
     In these cases, you can specify
-    the <literal>--cache-disable</literal>
+    the <option>--cache-disable</option>
     command-line option to tell &SCons;
     to not retrieve already-built files from the
     shared cache directory:
@@ -318,7 +318,7 @@ Retrieved `hello' from cache
     <para>
 
     In this case, you can use the
-    the <literal>--cache-force</literal> option
+    the <option>--cache-force</option> option
     to tell &SCons; to put all derived files in the cache,
     even if the files already exist in your local tree
     from having been built by a previous invocation:
@@ -336,12 +336,12 @@ Retrieved `hello' from cache
     <para>
 
     Notice how the above sample run
-    demonstrates that the <literal>--cache-disable</literal>
+    demonstrates that the <option>--cache-disable</option>
     option avoids putting the built
     <filename>hello.o</filename>
     and
     <filename>hello</filename> files in the cache,
-    but after using the <literal>--cache-force</literal> option,
+    but after using the <option>--cache-force</option> option,
     the files have been put in the cache
     for the next invocation to retrieve.
 
@@ -350,7 +350,7 @@ Retrieved `hello' from cache
   </section>
 
   <section>
-  <title>Minimizing Cache Contention:  the <literal>--random</literal> Option</title>
+  <title>Minimizing Cache Contention:  the <option>--random</option> Option</title>
 
     <para>
 
@@ -410,7 +410,7 @@ Program('prog',
     <para>
 
     To alleviate such contention for the cache,
-    you can use the <literal>--random</literal> command-line option
+    you can use the <option>--random</option> command-line option
     to tell &SCons; to build dependencies
     in a random order:
 
@@ -442,7 +442,7 @@ to return things in the original sorted order.
 
     <para>
 
-    Multiple builds using the <literal>--random</literal> option
+    Multiple builds using the <option>--random</option> option
     will usually build their dependencies in different,
     random orders,
     which minimizes the chances for a lot of
@@ -458,7 +458,7 @@ to return things in the original sorted order.
     <para>
 
     Note, of course,
-    the <literal>--random</literal> option
+    the <option>--random</option> option
     will cause the output that &SCons; prints
     to be inconsistent from invocation to invocation,
     which may be an issue when
@@ -470,7 +470,7 @@ to return things in the original sorted order.
 
     If you want to make sure dependencies will be built
     in a random order without having to specify
-    the <literal>--random</literal> on very command line,
+    the <option>--random</option> on very command line,
     you can use the &SetOption; function to
     set the <literal>random</literal> option
     within any &SConscript; file:
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml
index 80e0e24..beea8c9 100644
--- a/doc/user/troubleshoot.xml
+++ b/doc/user/troubleshoot.xml
@@ -160,7 +160,8 @@ file.in
     </para>
 
     <para>
-    Note that you can also use --warn=target-not-built which checks
+    Note that you can also use
+    <option>--warn=target-not-built</option> which checks
     whether or not expected targets exist after a build rule is
     executed.
     </para>
@@ -385,7 +386,7 @@ print(env.Dump('ENV'))
     &SCons; is doing is simply to take a look at the
     dependency graph that it constructs
     based on your &SConscript; files.
-    The <literal>--tree</literal> option
+    The <option>--tree</option> option
     will display all or part of the
     &SCons; dependency graph in an
     "ASCII art" graphical format
@@ -420,7 +421,7 @@ inc.h
 
     <para>
 
-    Running &SCons; with the <literal>--tree=all</literal>
+    Running &SCons; with the <option>--tree=all</option>
     option yields:
 
     </para>
@@ -432,7 +433,7 @@ inc.h
     <para>
 
     The tree will also be printed when the
-    <literal>-n</literal> (no execute) option is used,
+    <option>-n</option> (no execute) option is used,
     which allows you to examine the dependency graph
     for a configuration without actually
     rebuilding anything in the tree.
@@ -441,12 +442,12 @@ inc.h
 
     <para>
 
-    The <literal>--tree</literal> option only prints
+    The <option>--tree</option> 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 <option>--tree</option> option will only
     print the dependency graph for that file:
 
     </para>
@@ -473,7 +474,7 @@ inc.h
 
     <para>
 
-    The <literal>status</literal> argument may be used
+    The <parameter class="option">status</parameter> argument may be used
     to tell &SCons; to print status information about
     each file in the dependency graph:
 
@@ -485,11 +486,11 @@ inc.h
 
     <para>
 
-    Note that <literal>--tree=all,status</literal> is equivalent;
-    the <literal>all</literal>
-    is assumed if only <literal>status</literal> is present.
-    As an alternative to <literal>all</literal>,
-    you can specify <literal>--tree=derived</literal>
+    Note that <option>--tree=all,status</option> is equivalent;
+    the <parameter class="option">all</parameter>
+    is assumed if only <parameter class="option">status</parameter> is present.
+    As an alternative to <parameter class="option">all</parameter>,
+    you can specify <option>--tree=derived</option>
     to have &SCons; only print derived targets
     in the tree output,
     skipping source files
@@ -503,8 +504,8 @@ inc.h
 
     <para>
 
-    You can use the <literal>status</literal>
-    modifier with <literal>derived</literal> as well:
+    You can use the <parameter class="option">status</parameter>
+    modifier with <parameter class="option">derived</parameter> as well:
 
     </para>
 
@@ -514,16 +515,16 @@ inc.h
 
     <para>
 
-    Note that the order of the <literal>--tree=</literal>
+    Note that the order of the <option>--tree=</option>
     arguments doesn't matter;
-    <literal>--tree=status,derived</literal> is
+    <option>--tree=status,derived</option> is
     completely equivalent.
 
     </para>
 
     <para>
 
-    The default behavior of the <literal>--tree</literal> option
+    The default behavior of the <option>--tree</option> option
     is to repeat all of the dependencies each time the library dependency
     (or any other dependency file) is encountered in the tree.
     If certain target files share other target files,
@@ -563,7 +564,7 @@ inc.h
     <para>
 
     Then there can be a <emphasis>lot</emphasis> of repetition in the
-    <literal>--tree=</literal> output:
+    <option>--tree=</option> output:
 
     </para>
 
@@ -577,12 +578,12 @@ inc.h
     and include files,
     this can very quickly lead to huge output trees.
     To help make this more manageable,
-    a <literal>prune</literal> modifier may
+    a <parameter class="option">prune</parameter> modifier may
     be added to the option list,
     in which case &SCons;
     will print the name of a target that has
     already been visited during the tree-printing
-    in <literal>[square brackets]</literal>
+    in square brackets (<literal>[]</literal>)
     as an indication that the dependencies
     of the target file may be found
     by looking farther up the tree:
@@ -595,9 +596,9 @@ inc.h
 
     <para>
 
-    Like the <literal>status</literal> keyword,
-    the <literal>prune</literal> argument by itself
-    is equivalent to <literal>--tree=all,prune</literal>.
+    Like the <parameter class="option">status</parameter> keyword,
+    the <parameter class="option">prune</parameter> argument by itself
+    is equivalent to <option>--tree=all,prune</option>.
 
     </para>
 
@@ -609,10 +610,10 @@ inc.h
 
     <para>
 
-    Sometimes it's useful to look at the
-    pre-substitution string
-    that &SCons; uses to generate
-    the command lines it executes.
+    Sometimes the command lines that &SCons; executes don't
+    come out looking as you expect. In this case it may be
+    useful to look at the strings before &SCons; performs
+    substitution on them.
     This can be done with the &debug-presub; option:
 
     </para>
@@ -660,7 +661,7 @@ cc -o prog prog.o
     To get some insight into what library names
     &SCons; is searching for,
     and in which directories it is searching,
-    Use the <literal>--debug=findlibs</literal> option.
+    Use the &debug-findlibs; option.
     Given the following input &SConstruct; file:
 
     </para>
@@ -687,7 +688,7 @@ libs2/libbar.a
     and <filename>libbar.a</filename>
     in <filename>libs1</filename> and <filename>libs2</filename>,
     respectively,
-    use of the <literal>--debug=findlibs</literal> option yields:
+    use of the &debug-findlibs; option yields:
 
     </para>
 
@@ -816,8 +817,8 @@ Program('prog.c')
     The internal &SCons; subsystem that handles walking
     the dependency graph
     and controls the decision-making about what to rebuild
-    is the <literal>Taskmaster</literal>.
-    &SCons; supports a <literal>--taskmastertrace</literal>
+    is the <firstterm>Taskmaster</firstterm>.
+    &SCons; supports a &taskmastertrace;
     option that tells the Taskmaster to print
     information about the children (dependencies)
     of the various Nodes on its walk down the graph,
@@ -828,7 +829,7 @@ Program('prog.c')
 
     <para>
 
-    The <literal>--taskmastertrace</literal> option
+    The &taskmastertrace; option
     takes as an argument the name of a file in
     which to put the trace output,
     with <filename>-</filename> (a single hyphen)
@@ -857,7 +858,7 @@ prog.c
 
     <para>
 
-    The <literal>--taskmastertrace</literal> option
+    The &taskmastertrace; option
     doesn't provide information about the actual
     calculations involved in deciding if a file is up-to-date,
     but it does show all of the dependencies
@@ -881,8 +882,8 @@ prog.c
 
     Sometimes SCons doesn't build the target you want
     and it's difficult to figure out why.  You can use
-    the <literal>--debug=prepare</literal> option
-    to see all the targets &SCons; is considering, whether
+    the &debug-prepare; option
+    to see all the targets &SCons; is considering, and whether
     they are already up-to-date or not. The message is
     printed before &SCons; decides whether to build the target.
     </para>
@@ -891,16 +892,16 @@ prog.c
 
   <section>
 
-  <title>Why is a file disappearing?  the --debug=duplicate Option</title>
+  <title>Why is a file disappearing?  the &debug-duplicate; Option</title>
 
     <para>
 
     When using the &Duplicate; option to create variant dirs,
-    sometimes you may find files not getting copied to where you
-    expect (or not at all), or files mysteriously disappearing.  These
-    are usually because of a misconfiguration of some kind in the
-    SConstruct/SConscript, but they can be tricky to debug.  The
-    --debug=duplicate option shows each time a variant file is
+    sometimes you may find files not getting linked or copied to where you
+    expect (or not at all), or files mysteriously disappearing.
+    These are usually because of a misconfiguration of some kind in the
+    SConscript files, but they can be tricky to debug.  The
+    &debug-duplicate; option shows each time a variant file is
     unlinked and relinked from its source (or copied, depending on
     settings), and also shows a message for removing "stale"
     variant-dir files that no longer have a corresponding source file.
@@ -911,6 +912,36 @@ prog.c
 
   </section>
 
+  <section>
+
+  <title>Keep it simple</title>
+
+  <para>
+  Over the years, many developers have chosen to dive in and make vastly
+  complicated build systems out of &SCons;, which sometimes don't work
+  quite as expected.  As a general rule, make sure you
+  <emphasis>need</emphasis> to reach for a complex solution before you do so.
+  &SCons; is mature software and has evolved over time to meet a lot
+  of feature requests, so there is often an easier way to do something
+  if you can just find it.  The &SCons; community can be helpful here -
+  the discussion lists and chat channels can be a way to find out if
+  something can be done an easier way before embarking on an implementation.
+  </para>
+
+  <para>
+  When something does misbehave, trying to isolate the problem to
+  a simple test case can really help.  The work to create a reproducer
+  often helps you spot the issue yourself, and a simple example is much
+  easier for others to look over and possibly spot logical flaws,
+  misuse of the API, or other ways something could have been done.
+  In addition, if it turns out there's actually a real &SCons; bug
+  (we believe it's a high quality piece of software, but all software
+  has some bugs), it's very likely the bug filing will result in a
+  request for a simple reproducer anyway.
+  </para>
+
+  </section>
+
   <!--