Merge branch 'master' into doc/var-subst-escape

6 files changed, 269 insertions, 207 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 13a06a4..71ae139 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1165,7 +1165,7 @@ the help message not to be displayed.
     <option>--hash-chunksize=<replaceable>KILOBYTES</replaceable></option>
   </term>
   <listitem>
-<para>Set the block size used when computing content signatures to
+<para>Set the block size used when computing &contentsigs; to
 <replaceable>KILOBYTES</replaceable>.
 This value determines the size of the chunks which are read in at once when
 computing signature hashes.  Files below that size are fully stored in memory
@@ -1187,8 +1187,8 @@ be appropriate for most uses.</para>
   <listitem>
 <para>Set the hashing algorithm used by SCons to
 <replaceable>ALGORITHM</replaceable>.
-This value determines the hashing algorithm used in generating content
-signatures or &f-link-CacheDir; keys.</para>
+This value determines the hashing algorithm used in generating
+&contentsigs; or &CacheDir; keys.</para>
 
 <para>The supported list of values are: md5, sha1, and sha256.
 However, the Python interpreter used to run SCons must have the corresponding
@@ -1272,8 +1272,7 @@ but with the following limitations:</para>
 
 <para>&scons;
 will not detect changes to implicit dependency search paths
-(e.g.
-<envar>CPPPATH</envar>, <envar>LIBPATH</envar>)
+(e.g.  &cv-link-CPPPATH;, &cv-link-LIBPATH;)
 that would ordinarily
 cause different versions of same-named files to be used.</para>
 
@@ -1281,8 +1280,7 @@ cause different versions of same-named files to be used.</para>
 will miss changes in the implicit dependencies
 in cases where a new implicit
 dependency is added earlier in the implicit dependency search path
-(e.g.
-<envar>CPPPATH</envar>, <envar>LIBPATH</envar>)
+(e.g.  &cv-link-CPPPATH;, &cv-link-LIBPATH;)
 than a current implicit dependency with the same name.</para>
   </listitem>
   </varlistentry>
@@ -1551,16 +1549,16 @@ targets specified on the command line will still be processed.</para>
 <para>Set the maximum expected drift in the modification time of files to
 <replaceable>SECONDS</replaceable>.
 This value determines how long a file must be unmodified
-before its cached content signature
+before its cached &contentsig;
 will be used instead of
-calculating a new content signature (hash)
+calculating a new &contentsig; (hash)
 of the file's contents.
 The default value is 2 days, which means a file must have a
 modification time of at least two days ago in order to have its
-cached content signature used.
-A negative value means to never cache the content
-signature and to ignore the cached value if there already is one. A value
-of 0 means to always use the cached signature,
+cached &contentsig; used.
+A negative value means to never cache the
+&contentsig; and to ignore the cached value if there already is one.
+A value of 0 means to always use the cached signature,
 no matter how old the file is.</para>
   </listitem>
   </varlistentry>
@@ -2408,11 +2406,11 @@ env = Environment(parse_flags='-Iinclude -DEBUG -lm')
 </programlisting>
 
 <para>This example adds 'include' to
-the <envar>CPPPATH</envar> &consvar;,
+the &cv-link-CPPPATH; &consvar;,
 'EBUG' to
-<envar>CPPDEFINES</envar>,
+&cv-link-CPPDEFINES;,
 and 'm' to
-<envar>LIBS</envar>.
+&cv-link-LIBS;.
 </para>
 
 <para>
@@ -2574,7 +2572,7 @@ or if <parameter>tools</parameter> includes <literal>'default'</literal>,
 then &scons; will auto-detect usable tools,
 using the execution environment value of <varname>PATH</varname>
 (that is, <varname><replaceable>env</replaceable>['ENV']['PATH']</varname> -
-the external evironment <envar>PATH</envar> from <varname>os.environ</varname>
+the external evironment &PATH; from <varname>os.environ</varname>
 is <emphasis>not</emphasis> used)
 for looking up any backing programs, and the platform name in effect
 to determine the default tools for that platform.
@@ -2856,11 +2854,12 @@ env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
 </programlisting>
 
 <para>This example adds 'include' to
-<envar>CPPPATH</envar>,
+the &cv-link-CPPPATH; &consvar;,
 'EBUG' to
-<envar>CPPDEFINES</envar>,
+&cv-link-CPPDEFINES;,
 and 'm' to
-<envar>LIBS</envar>.</para>
+&cv-link-LIBS;.
+</para>
 
 <para>Although the builder methods defined by
 &scons;
@@ -5546,9 +5545,9 @@ must accept four arguments:
 <parameter>env</parameter> is the &consenv; to use for context,
 and <parameter>for_signature</parameter> is
 a Boolean value that tells the function
-if it is being called for the purpose of generating a build signature
+if it is being called for the purpose of generating a &buildsig;
 (as opposed to actually executing the command).
-Since the build signature is used for rebuild determination,
+Since the &buildsig; is used for rebuild determination,
 the function should omit those elements
 that do not affect whether a rebuild should be triggered
 if <parameter>for_signature</parameter> is true.
@@ -5974,6 +5973,7 @@ l = Action(build_it, '$STRINGIT')
 <para>Any additional positional arguments, if present,
 may either be &consvars; or lists of &consvars;
 whose values will be included in the signature of the Action
+(the &buildsig;)
 when deciding whether a target should be rebuilt because the action changed.
 Such variables may also be specified using the
 <parameter>varlist</parameter>
@@ -6644,14 +6644,14 @@ may be used to surround parts of a command line
 that may change
 <emphasis>without</emphasis>
 causing a rebuild--that is,
-which are not included in the signature
+which are not included in the &buildsig;
 of target files built with this command.
 All text between
 <emphasis role="bold">$(</emphasis>
 and
 <emphasis role="bold">$)</emphasis>
 will be removed from the command line
-before it is added to the build action signature,
+before it is added to the &buildsig;
 and the
 <emphasis role="bold">$(</emphasis>
 and
@@ -6669,7 +6669,9 @@ echo Last build occurred $( $TODAY $). &gt; $TARGET
 echo Last build occurred $TODAY. &gt; $TARGET
 </screen>
 
-<para>but the command signature added to any target files would be:</para>
+<para>but the command portion of the
+the &buildsig; computed for any target files built
+by this action would be:</para>
 
 <screen>
 echo Last build occurred  . &gt; $TARGET
@@ -6689,16 +6691,14 @@ The callable must accept four arguments:
 <parameter>target</parameter> is a list of target nodes,
 <parameter>env</parameter> is the &consenv; to use for context,
 and <parameter>for_signature</parameter> is
-a boolean value that tells the callable
-if it is being called for the purpose of generating a build signature.
-Since the build signature is used for rebuild determination,
-variable elements that do not affect whether
-a rebuild should be triggered
-should be omitted from the returned string
-if <parameter>for_signature</parameter> is true.
-See <emphasis role="bold">$(</emphasis>
-and <emphasis role="bold">$)</emphasis> above
-for the syntax.
+a Boolean value that tells the function
+if it is being called for the purpose of generating a &buildsig;.
+Since the &buildsig; is used for rebuild determination,
+the function should omit variable elements
+that do not affect whether a rebuild should be triggered
+(see <emphasis role="bold">$(</emphasis>
+and <emphasis role="bold">$)</emphasis>
+above) if <parameter>for_signature</parameter> is true.
 </para>
 
 <para>
@@ -6931,7 +6931,7 @@ directories when generating the dependency Nodes. To illustrate this,
 a C language source file may contain a line like
 <literal>#include "foo.h"</literal>.  However, there is no guarantee
 that <filename>foo.h</filename> exists in the current directory:
-the contents of &cv-CPPPATH; is passed to the C preprocessor which
+the contents of &cv-link-CPPPATH; is passed to the C preprocessor which
 will look in those places for the header,
 so the scanner function needs to look in those places as well
 in order to build Nodes with correct paths.
@@ -7211,7 +7211,7 @@ to vary its initialization.</para>
 <para>Returns <constant>True</constant> if the tool can
 be called in the context of <parameter>env</parameter>.
 Usually this means looking up one or more
-known programs using the <envar>PATH</envar> from the
+known programs using the <varname>PATH</varname> from the
 supplied <parameter>env</parameter>, but the tool can
 make the "exists" decision in any way it chooses.
 </para>
diff --git a/doc/scons.mod b/doc/scons.mod
index 6a2fd6b..5579d4d 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -450,8 +450,9 @@
 
 <!ENTITY Nodes "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>Nodes</literal>">
 
-<!ENTITY signature "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>signature</literal>">
-<!ENTITY buildsignature "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>build signature</literal>">
+<!ENTITY contentsig "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>content signature</phrase>">
+<!ENTITY contentsigs "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>content signatures</phrase>">
+<!ENTITY buildsig "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>build signature</phrase>">
 
 <!ENTITY true "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>true</literal>">
 <!ENTITY false "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>false</literal>">
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index c7b3842..69368d7 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -22,7 +22,9 @@
 
 <!--
 
-  __COPYRIGHT__
+  MIT License
+
+  Copyright The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -49,19 +51,24 @@
 
   On multi-developer software projects,
   you can sometimes speed up every developer's builds a lot by
-  allowing them to share the derived files that they build.
+  allowing them to share a cache of the derived files that they build.
   After all, it is relatively rare that any in-progress change affects
   more than a few derived files, most will be unchanged.
+  Using a cache can also help an individual developer:
+  for example if you wish to start work on a new feature in a clean tree,
+  those build artifacts which could be reused can be
+  retrieved from the cache to populate the tree and save
+  a lot of initial build time.
   &SCons; makes this easy and reliable.
 
   </para>
 
   <section>
-  <title>Specifying the Shared Cache Directory</title>
+  <title>Specifying the Derived-File Cache Directory</title>
 
     <para>
 
-    To enable sharing of derived files,
+    To enable caching of derived files,
     use the &f-link-CacheDir; function
     in any &SConscript; file:
 
@@ -86,8 +93,10 @@ CacheDir('/usr/local/build_cache')
     <para>
 
     The cache directory you specify must
-    be readable and writable by all developers
-    who will be sharing derived files.
+    have read and write access for all developers
+    who will be accessing the cached files
+    (if <option>--cache-readonly</option> is used,
+    only read access is required).
     It should also be in some central location
     that all builds will be able to access.
     In environments where developers are using separate systems
@@ -107,31 +116,44 @@ CacheDir('/usr/local/build_cache')
     When a build has a &CacheDir; specified,
     every time a file is built,
     it is stored in that cache directory
-    along with its build signature.
+    indexed by its &buildsig;.
     On subsequent builds,
     before an action is invoked to build a file,
-    &SCons; will check the shared cache directory
-    to see if a file with the exact same build
-    signature already exists.
+    the &buildsig; is computed and &SCons; checks
+    the derived-file cache directory
+    to see if a file with the exact same &buildsig;
+    already exists.
+
       <footnote>
       <para>
-      A few inner details: &SCons; tracks two main kinds of cryptographic
-      hashes: <emphasis>content signatures</emphasis>,
-      which are a hash of the contents of a file;
-      and <emphasis>build signatures</emphasis>, which are a hash of the
-      elements needed to build a target, such as the exact command line,
+      A few inside details: &SCons; tracks two main kinds of cryptographic
+      hashes: a <emphasis>&contentsig;</emphasis>,
+      which is a hash of the contents of a file participating in the
+      build (depepdencies as well as targets);
+      and a <emphasis>&buildsig;</emphasis>, which is a hash of the
+      elements needed to build a target, such as the command line,
       the contents of the sources, and possibly information about
       tools used in the build. The hash function produces a unique signature
       from its inputs, no other set of inputs can produce that same
-      signature.  The build signature from building
+      signature.  The &buildsig; from building
       a target is used as the filename of the target file in the
-      shared cache - that way lookups are efficient, just compute
-      a build signature and see if a file exists with that as the name.
+      derived-file cache - that way lookups are efficient, just compute
+      a &buildsig; and see if a file exists with that as the name.
+      </para>
+
+      <para>
+      The use of the &buildsig; provides protection from concflicts:
+      if two developers have different setups, so they would produce
+      built objects that are not identical, then because the difference in
+      tools will show up in the &buildsig;, which is used as the
+      name of the cache entry, they will end up being
+      stored as separate entries.
       </para>
       </footnote>
+
     If so, the derived file will not be built locally,
     but will be copied into the local build directory
-    from the shared cache directory,
+    from the derived-file cache directory,
     like this:
 
     </para>
@@ -144,17 +166,16 @@ CacheDir('/usr/local/build_cache')
 
     <para>
 
-    Note that the &CacheDir; feature requires that build signatures
+    Note that the &CacheDir; feature requires that the &buildsig;
     be calculated,
     even if you configure &SCons; to use timestamps
     to decide if files are up to date
     (see the <xref linkend="chap-depends"></xref>
     chapter for information about the &f-link-Decider; function),
-    since the build signature is used to determine if a target file
+    since the &buildsig; is used to determine if a target file
     exists in the cache.
-    Consequently, using &CacheDir; may reduce or eliminate any
-    potential performance improvements
-    from using timestamps for up-to-date decisions.
+    Consequently, using &CacheDir; may reduce or negate any performance
+    improvements from using timestamps for up-to-date decisions.
 
     </para>
 
@@ -165,11 +186,11 @@ CacheDir('/usr/local/build_cache')
 
     <para>
 
-    One potential drawback to using a shared cache
+    One potential drawback to using a derived-file cache
     is that the output printed by &SCons;
     can be inconsistent from invocation to invocation,
     because any given file may be rebuilt one time
-    and retrieved from the shared cache the next time.
+    and retrieved from the derived-file cache the next time.
     This can make analyzing build output more difficult,
     especially for automated scripts that
     expect consistent output each time.
@@ -182,9 +203,8 @@ CacheDir('/usr/local/build_cache')
     &SCons; will print the command line that it
     <emphasis>would</emphasis> have executed
     to build the file,
-    even when it is retrieving the file from the shared cache.
-    This makes the build output consistent
-    every time the build is run:
+    even when it is retrieving the file from the derived-file cache.
+    This keeps the build output consistent across builds:
 
     </para>
 
@@ -206,7 +226,7 @@ CacheDir('/usr/local/build_cache')
   </section>
 
   <section>
-  <title>Not Using the Shared Cache for Specific Files</title>
+  <title>Not Using the Derived-File Cache for Specific Files</title>
 
     <para>
 
@@ -215,7 +235,7 @@ CacheDir('/usr/local/build_cache')
     For example, if you only want to put
     executable files in a central cache,
     but not the intermediate object files,
-    you can use the &NoCache;
+    you can use the &f-link-NoCache;
     function to specify that the
     object files should not be cached:
 
@@ -241,8 +261,8 @@ hello.c
     Then when you run &scons; after cleaning
     the built targets,
     it will recompile the object file locally
-    (since it doesn't exist in the shared cache directory),
-    but still realize that the shared cache directory
+    (since it doesn't exist in the derived-file cache directory),
+    but still realize that the derived-file cache directory
     contains an up-to-date executable program
     that can be retrieved instead of re-linking:
 
@@ -273,12 +293,12 @@ Retrieved `hello' from cache
   </section>
 
   <section>
-  <title>Disabling the Shared Cache</title>
+  <title>Disabling the Derived-File Cache</title>
 
     <para>
 
     Retrieving an already-built file
-    from the shared cache
+    from the derived-file cache
     is usually a significant time-savings
     over rebuilding the file,
     but how much of a savings
@@ -298,7 +318,7 @@ Retrieved `hello' from cache
     the <option>--cache-disable</option>
     command-line option to tell &SCons;
     to not retrieve already-built files from the
-    shared cache directory:
+    derived-file cache directory:
 
     </para>
 
@@ -313,7 +333,7 @@ Retrieved `hello' from cache
   </section>
 
   <section>
-  <title>Populating a Shared Cache With Already-Built Files</title>
+  <title>Populating a Derived-File Cache With Already-Built Files</title>
 
     <para>
 
@@ -323,7 +343,7 @@ Retrieved `hello' from cache
     For example, you may find it more effective to perform
     integration builds with the cache disabled
     (per the previous section)
-    and only populate the shared cache directory
+    and only populate the derived-file cache directory
     with the built files after the integration build
     has completed successfully.
     This way, the cache will only get filled up
@@ -373,7 +393,7 @@ Retrieved `hello' from cache
     <para>
 
     If you allow multiple builds to update the
-    shared cache directory simultaneously,
+    derived-file cache directory simultaneously,
     two builds that occur at the same time
     can sometimes start "racing"
     with one another to build the same files
@@ -385,8 +405,7 @@ Retrieved `hello' from cache
 
     <scons_example name="caching_ex-random">
        <file name="SConstruct" printme="1">
-Program('prog',
-        ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+Program('prog', ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
        </file>
        <file name="f1.c">f1.c</file>
        <file name="f2.c">f2.c</file>
@@ -412,9 +431,9 @@ Program('prog',
     But if two such builds take place simultaneously,
     they may each look in the cache at nearly the same
     time and both decide that <filename>f1.o</filename>
-    must be rebuilt and pushed into the shared cache directory,
+    must be rebuilt and pushed into the derived-file cache directory,
     then both decide that <filename>f2.o</filename>
-    must be rebuilt (and pushed into the shared cache directory),
+    must be rebuilt (and pushed into the derived-file cache directory),
     then both decide that <filename>f3.o</filename>
     must be rebuilt...
     This won't cause any actual build problems--both
@@ -465,7 +484,7 @@ to return things in the original sorted order.
     random orders,
     which minimizes the chances for a lot of
     contention for same-named files
-    in the shared cache directory.
+    in the derived-file cache directory.
     Multiple simultaneous builds might still race to try to build
     the same target file on occasion,
     but long sequences of inefficient contention
@@ -489,7 +508,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 <option>--random</option> on very command line,
-    you can use the &SetOption; function to
+    you can use the &f-link-SetOption; function to
     set the <literal>random</literal> option
     within any &SConscript; file:
 
@@ -498,8 +517,7 @@ to return things in the original sorted order.
     <scons_example name="caching_ex-random">
        <file name="SConstruct" printme="1">
 SetOption('random', 1)
-Program('prog',
-        ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
+Program('prog', ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
        </file>
        <file name="f1.c">f1.c</file>
        <file name="f2.c">f2.c</file>
@@ -516,7 +534,7 @@ Program('prog',
 
     <para>
 
-    SCons' internal <classname>CacheDir</classname> class can be extended to support customization
+    &SCons;' internal <classname>CacheDir</classname> class can be extended to support customization
     around the details of caching behaviors, for example using compressed cache files,
     encrypted cache files, gathering statistics and data, or many other aspects.
 
@@ -524,33 +542,38 @@ Program('prog',
 
     <para>
 
-    To create your own custom &f-link-CacheDir; class, your custom class must be a subclass
-    of SCons internal <classname>SCons.CacheDir.CacheDir</classname> class.
-    You can then pass your custom &f-link-CacheDir; class to the &f-link-CacheDir;
-    method or set the environment construction variable &cv-link-CACHEDIR_CLASS; to the class before configuring the cache
-    in that environment. SCons will internally invoke and use your custom class when performing
-    cache operations. The below example shows a simple use case of overriding the copy_from_cache
+    To create your own custom cache class,
+    your custom class must be a subclass
+    of the <classname>SCons.CacheDir.CacheDir</classname> class.
+    You can then pass your custom class to the &f-link-CacheDir;
+    method or set the &consvar;
+    &cv-link-CACHEDIR_CLASS; to the class before configuring the cache
+    in that environment.
+    SCons will internally invoke and use your custom class when performing
+    cache operations.
+    The below example shows a simple use case of overriding the
+    <function>copy_from_cache</function>
     method to record the total number of bytes pulled from the cache.
 
     </para>
 
     <scons_example name="custom_caching">
       <file name="SConstruct" printme="1">
-        import SCons
-        import os
+import SCons
+import os
 
-        class CustomCacheDir(SCons.CacheDir.CacheDir):
-            total_retrieved = 0
+class CustomCacheDir(SCons.CacheDir.CacheDir):
+    total_retrieved = 0
 
-            @classmethod
-            def copy_from_cache(cls, env, src, dst):
-                # record total bytes pulled from cache
-                cls.total_retrieved += os.stat(src).st_size
-                super().copy_from_cache(env, src, dst)
+    @classmethod
+    def copy_from_cache(cls, env, src, dst):
+        # record total bytes pulled from cache
+        cls.total_retrieved += os.stat(src).st_size
+        super().copy_from_cache(env, src, dst)
 
-        env = Environment()
-        env.CacheDir('scons-cache', CustomCacheDir)
-        # ...
+env = Environment()
+env.CacheDir('scons-cache', CustomCacheDir)
+# ...
       </file>
     </scons_example>
 
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 90b446c..62b6d91 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -109,26 +109,26 @@ int main() { printf("Hello, world!\n"); }
     things when an input file changes,
     so that the built software is up to date.
     By default,
-    &SCons; keeps track of this through an
-    MD5 &signature;, or checksum, of the contents of each file,
+    &SCons; keeps track of this through a
+    <firstterm>&contentsig;</firstterm>,
+    or hash, of the contents of each file,
     although you can easily configure
     &SCons; to use the
-    modification times (or time stamps)
-    instead.
-    You can even specify your own Python function
-    for deciding if an input file has changed.
+    modification times (or time stamps) instead.
+    You can even write your own Python function
+    for deciding if an input file should trigger a rebuild.
 
     </para>
 
     <section>
-    <title>Using MD5 Signatures to Decide if a File Has Changed</title>
+    <title>Using Content Signatures to Decide if a File Has Changed</title>
 
       <para>
 
-      By default,
-      &SCons; keeps track of whether a file has changed
-      based on an MD5 checksum of the file's contents,
-      not the file's modification time.
+      By default, &SCons; 
+      uses a cryptographic hash of the file's contents,
+      not the file's modification time,
+      to decide whether a file has changed.
       This means that you may be surprised by the
       default &SCons; behavior if you are used to the
       &Make; convention of forcing
@@ -168,31 +168,33 @@ int main() { printf("Hello, world!\n"); }
       <para>
 
       Note that you can, if you wish,
-      specify this default behavior
-      (MD5 signatures) explicitly
-      using the &Decider; function as follows:
+      specify the default behavior of using
+      &contentsigs; explicitly,
+      using the &f-link-Decider; function as follows:
 
       </para>
 
       <sconstruct>
 Program('hello.c')
-Decider('MD5')
+Decider('content')
       </sconstruct>
 
       <para>
 
-      You can also use the string <literal>'content'</literal>
-      as a synonym for <literal>'MD5'</literal>
-      when calling the &Decider; function.
+      You can also use the string <literal>'MD5'</literal>
+      as a synonym for <literal>'content'</literal>
+      when calling the &f-Decider; function - this older
+      name is deprecated since &SCons; now supports a
+      choice of hash functions, not just the MD5 function.
 
       </para>
 
       <section>
-      <title>Ramifications of Using MD5 Signatures</title>
+      <title>Ramifications of Using Content Signatures</title>
 
         <para>
 
-        Using MD5 signatures to decide if an input file has changed
+        Using &contentsigs; 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
@@ -265,7 +267,7 @@ Decider('MD5')
       if a source file's modification time is
       <emphasis>newer</emphasis>
       than the target file.
-      To do this, call the &Decider;
+      To do this, call the &f-link-Decider;
       function as follows:
 
       </para>
@@ -300,7 +302,7 @@ int main() { printf("Hello, world!\n"); }
       as the behavior of &Make;,
       you can also use the string <literal>'make'</literal>
       as a synonym for <literal>'timestamp-newer'</literal>
-      when calling the &Decider; function:
+      when calling the &f-Decider; function:
 
       </para>
 
@@ -335,7 +337,7 @@ Decider('make')
       is newer than the target file.
       To do this, specify the argument
       <literal>'timestamp-match'</literal>
-      when calling the &Decider; function:
+      when calling the &f-Decider; function:
 
       </para>
 
@@ -389,11 +391,11 @@ int main() { printf("Hello, world!\n"); }
 
       As a performance enhancement,
       &SCons; provides a way to use
-      MD5 checksums of file contents
+      a file's &contentsig;,
       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>
+      To do this, call the &f-link-Decider;
+      function with <literal>'content-timestamp'</literal>
       argument as follows:
 
       </para>
@@ -401,7 +403,7 @@ int main() { printf("Hello, world!\n"); }
       <scons_example name="depends_MD5-timestamp">
         <file name="SConstruct" printme="1">
 Program('hello.c')
-Decider('MD5-timestamp')
+Decider('content-timestamp')
         </file>
         <file name="hello.c">
 int main() { printf("Hello, world!\n"); }
@@ -411,7 +413,7 @@ int main() { printf("Hello, world!\n"); }
       <para>
 
       So configured, &SCons; will still behave like
-      it does when using <literal>Decider('MD5')</literal>:
+      it does when using <literal>Decider('content')</literal>:
 
       </para>
 
@@ -453,7 +455,7 @@ cc -o hello hello.o
       will have been performed by simply looking at the
       modification time of the &hello_c; file,
       not by opening it and performing
-      an MD5 checksum calcuation on its contents.
+      a signature calcuation on its contents.
       This can significantly speed up many up-to-date builds.
 
       </para>
@@ -461,7 +463,7 @@ cc -o hello hello.o
       <para>
 
       The only drawback to using
-      <literal>Decider('MD5-timestamp')</literal>
+      <literal>Decider('content-timestamp')</literal>
       is that &SCons; will <emphasis>not</emphasis>
       rebuild a target file if a source file was modified
       within one second of the last time &SCons; built the file.
@@ -475,7 +477,7 @@ cc -o hello hello.o
       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>
+      <literal>Decider('content-timestamp')</literal>
       may not be appropriate.
 
       </para>
@@ -488,7 +490,7 @@ cc -o hello hello.o
       <para>
 
       The different string values that we've passed to
-      the &Decider; function are essentially used by &SCons;
+      the &f-link-Decider; function are essentially used by &SCons;
       to pick one of several specific internal functions
       that implement various ways of deciding if a dependency
       (usually a source file)
@@ -550,7 +552,7 @@ int main() { printf("Hello, world!\n"); }
 
       The third argument, <varname>prev_ni</varname>,
       is an object that holds the
-      signature or timestamp information
+      &contentsig; and/or timestamp information
       that was recorded about the dependency
       the last time the target was built.
       A <varname>prev_ni</varname> object can hold
@@ -566,13 +568,13 @@ int main() { printf("Hello, world!\n"); }
       <variablelist>
 
         <varlistentry>
-        <term>.csig</term>
+        <term><literal>csig</literal></term>
 
         <listitem>
         <para>
-        The <emphasis>content signature</emphasis>,
-        or MD5 checksum, of the contents of the
-        <varname>dependency</varname>
+        The &contentsig;:
+        a cryptgraphic hash, or checksum, of the file contents
+        of the <varname>dependency</varname>
         file the last time the &target; was built.
         </para>
         </listitem>
@@ -580,7 +582,7 @@ int main() { printf("Hello, world!\n"); }
         </varlistentry>
 
         <varlistentry>
-        <term>.size</term>
+        <term><literal>size</literal></term>
 
         <listitem>
         <para>
@@ -592,7 +594,7 @@ int main() { printf("Hello, world!\n"); }
         </varlistentry>
 
         <varlistentry>
-        <term>.timestamp</term>
+        <term><literal>timestamp</literal></term>
 
         <listitem>
         <para>
@@ -689,22 +691,21 @@ env.Install("install", "test.txt")
       <para>
 
       The previous examples have all demonstrated calling
-      the global &Decider; function
+      the global &f-link-Decider; function
       to configure all dependency decisions that &SCons; makes.
       Sometimes, however, you want to be able to configure
       different decision-making for different targets.
-      When that's necessary, you can use the
-      <function>env.Decider</function>
+      When that's necessary, you can use the &f-env-Decider;
       method to affect only the configuration
       decisions for targets built with a
-      specific construction environment.
+      specific &consenv;.
 
       </para>
 
       <para>
 
       For example, if we arbitrarily want to build
-      one program using MD5 checkums
+      one program using &contentsigs;
       and another using file modification times
       from the same source
       we might configure it this way:
@@ -716,7 +717,7 @@ env.Install("install", "test.txt")
 env1 = Environment(CPPPATH = ['.'])
 env2 = env1.Clone()
 env2.Decider('timestamp-match')
-env1.Program('prog-MD5', 'program1.c')
+env1.Program('prog-content', 'program1.c')
 env2.Program('prog-timestamp', 'program2.c')
         </file>
         <file name="program1.c">
@@ -767,7 +768,7 @@ int main() { printf("Hello, world!\n"); }
 
     <scons_example name="depends_include">
       <file name="SConstruct">
-Program('hello.c', CPPPATH = '.')
+Program('hello.c', CPPPATH='.')
       </file>
       <file name="hello.c" printme="1">
 #include &lt;hello.h&gt;
@@ -825,8 +826,8 @@ main()
     <para>
 
     First, notice that &SCons;
-    added the <literal>-I.</literal> argument
-    from the &cv-CPPPATH; variable
+    constructed the <literal>-I.</literal> argument
+    from the <literal>'.'</literal> in the &cv-CPPPATH; variable
     so that the compilation would find the
     &hello_h; file in the local directory.
 
@@ -1104,7 +1105,7 @@ SetOption('implicit_cache', 1)
     &SCons; allows you to specific explicitly that one file
     depends on another file,
     and must be rebuilt whenever that file changes.
-    This is specified using the &Depends; method:
+    This is specified using the &f-link-Depends; method:
 
     </para>
 
@@ -1131,7 +1132,7 @@ cc -o hello hello.o
     <para>
 
     Note that the dependency
-    (the second argument to &Depends;)
+    (the second argument to &f-Depends;)
     may also be a list of Node objects
     (for example, as returned by a call to a Builder):
 
@@ -1206,7 +1207,7 @@ Program('hello', 'hello.c', CPPPATH='.')
     <para>
 
     Apparently, the scanner does not know about the header dependency.
-    Being not a full-fledged C preprocessor, the scanner does not
+    Not being a full-fledged C preprocessor, the scanner does not
     expand the macro.
 
     </para>
@@ -1214,7 +1215,7 @@ Program('hello', 'hello.c', CPPPATH='.')
     <para>
 
     In these cases, you may also use the compiler to extract the
-    implicit dependencies. &ParseDepends; can parse the contents of
+    implicit dependencies. &f-link-ParseDepends; can parse the contents of
     the compiler output in the style of &Make;, and explicitly
     establish all of the listed dependencies.
 
@@ -1222,7 +1223,7 @@ Program('hello', 'hello.c', CPPPATH='.')
 
     <para>
 
-    The following example uses &ParseDepends; to process a compiler
+    The following example uses &f-ParseDepends; to process a compiler
     generated dependency file which is generated as a side effect
     during compilation of the object file:
 
@@ -1320,13 +1321,13 @@ scons: `.' is up to date.
 
     <para>
 
-    &ParseDepends; immediately reads the specified file at invocation
+    &f-ParseDepends; immediately reads the specified file at invocation
     time and just returns if the file does not exist. A dependency
     file generated during the build process is not automatically
     parsed again. Hence, the compiler-extracted dependencies are not
     stored in the signature database during the same build pass. This
-    limitation of &ParseDepends; leads to unnecessary recompilations.
-    Therefore, &ParseDepends; should only be used if scanners are not
+    limitation of &f-ParseDepends; leads to unnecessary recompilations.
+    Therefore, &f-ParseDepends; should only be used if scanners are not
     available for the employed language or not powerful enough for the
     specific task.
 
@@ -1344,7 +1345,8 @@ scons: `.' is up to date.
     even if a dependency file changes.
     In this case,
     you would tell &SCons; specifically
-    to ignore a dependency as follows:
+    to ignore a dependency using the
+    &f-link-Ignore; function as follows:
 
     </para>
 
@@ -1414,7 +1416,7 @@ Ignore(hello, '/usr/include/stdio.h')
     </programlisting>
 
     <para>
-    &Ignore; can also be used to prevent a generated file from being built
+    &f-Ignore; can also be used to prevent a generated file from being built
     by default. This is due to the fact that directories depend on
     their contents.  So to ignore a generated file from the default build,
     you specify that the directory should ignore the generated file.
@@ -1535,7 +1537,7 @@ int main() { printf("Hello, %s!  I was built: %s\n", date); }
 
     <para>
 
-    One solution is to use the &Requires; function
+    One solution is to use the &f-link-Requires; function
     to specify that the <filename>version.o</filename>
     must be rebuilt before it is used by the link step,
     but that changes to <filename>version.o</filename>
@@ -1573,7 +1575,7 @@ int main() { printf("Hello, %s!  I was built: %s\n", date); }
     we have to find some other way to get it into the link command line.
     For this example, we're cheating a bit and stuffing the
     object file name (extracted from <literal>version_obj</literal>
-    list returned by the &b-Object; call)
+    list returned by the &b-Object; builder call)
     into the &cv-link-LINKFLAGS; variable,
     because &cv-LINKFLAGS; is already included
     in the &cv-link-LINKCOM; command line.
@@ -1611,8 +1613,8 @@ int main() { printf("Hello, %s!  I was built: %s\n", date); }
     <para>
 
     How &SCons; handles dependencies can also be affected
-    by the &AlwaysBuild; method.
-    When a file is passed to the &AlwaysBuild; method,
+    by the &f-link-AlwaysBuild; method.
+    When a file is passed to the &f-AlwaysBuild; method,
     like so:
 
     </para>
@@ -1643,7 +1645,7 @@ int main() { printf("Hello, %s!\n", string); }
 
     <para>
 
-    The &AlwaysBuild; function has a somewhat misleading name,
+    The &f-AlwaysBuild; function has a somewhat misleading name,
     because it does not actually mean the target file will
     be rebuilt every single time &SCons; is invoked.
     Instead, it means that the target will, in fact,
@@ -1652,7 +1654,7 @@ int main() { printf("Hello, %s!\n", string); }
     the command line (and their dependencies).
     So specifying some other target on the command line,
     a target that does <emphasis>not</emphasis>
-    itself depend on the &AlwaysBuild; target,
+    itself depend on the &f-AlwaysBuild; target,
     will still be rebuilt only if it's out-of-date
     with respect to its dependencies:
 
diff --git a/doc/user/external.xml b/doc/user/external.xml
index 5f88f5a..b483196 100644
--- a/doc/user/external.xml
+++ b/doc/user/external.xml
@@ -110,7 +110,7 @@
             The entries in this file can be filtered by using
 
             <envar>COMPILATIONDB_PATH_FILTER='pattern'</envar>
-            where the filter pattern is a string following the Python
+            where the filter pattern is a string following the &Python;
             <ulink url="https://docs.python.org/3/library/fnmatch.html">
                 <systemitem>fnmatch</systemitem>
             </ulink>
@@ -306,54 +306,90 @@
 
         <note>
             <para>
-                This is an experimental new feature. It is subject to change and/or removal without depreciation cycle
-            </para>
-            <para>
-                To use this tool you must install pypi's <ulink url="https://pypi.org/project/ninja/">ninja
-                package</ulink>.
-                This can be done via
-                <command>pip install ninja</command>
+                This is an experimental new feature.
+                It is subject to change and/or removal without a depreciation cycle.
             </para>
+
             <para>
-                To enable this feature you'll need to use one of the following
+                To enable this feature you'll need to use one of the following:
             </para>
+<!--        NOTE DO NOT INDENT example_commands CONTENTS AS IT WILL ALTER THE FORMATTING-->
             <example_commands>
-                # On the command line
-                --experimental=ninja
+# On the command line
+--experimental=ninja
 
-                # Or in your SConstruct
-                SetOption('experimental', 'ninja')
+# Or in your SConstruct
+SetOption('experimental', 'ninja')
             </example_commands>
-
         </note>
 
         <para>
-            This tool will enabled creating a ninja build file from your SCons based build system. It can then invoke
-            ninja to run your build. For most builds ninja will be significantly faster, but you may have to give up
-            some accuracy. You are NOT advised to use this for production builds. It can however significantly speed up
-            your build/debug/compile iterations.
+            Ninja is a small build system that tries to be fast
+            by not making decisions. &SCons; can at times be slow
+            because it makes lots of decisions to carry out its goal
+            of "correctness".  The two tools can be paired to benefit
+            some build scenarios: by using the &t-link-ninja; tool,
+            &SCons; can generate the build file &ninja; uses (basically
+            doing the decision-making ahead of time and recording that
+            for &ninja;), and can invoke &ninja; to perform a build.
+            For situations where relationships are not changing, such
+            as edit/build/debug iterations, this works fine and should
+            provide considerable speedups for more complex builds.
+            The implication is if there are larger changes taking place,
+            &ninja; is not as appropriate - but you can always use &SCons;
+            to regenerate the build file.  You are NOT advised to use
+            this for production builds.
+        </para>
+
+        <para>
+            To use the &t-link-ninja; tool you'll need to first install the
+            &Python; &ninja; package, as the tool depends on being able to do an
+            <systemitem>import</systemitem> of the package.
+            This can be done via:
         </para>
+
+        <example_commands>
+# In a virtualenv, or "python" is the native executable:
+python -m pip install ninja
+
+# Windows using Python launcher:
+py -m pip install ninja
+
+# Anaconda:
+conda install -c conda-forge ninja
+        </example_commands>
+
         <para>
-            It's not expected that the ninja builder will work for all builds at this point. It's still under active
-            development. If you find that your build doesn't work with ninja please bring this to the users mailing list
-            or devel channel on our discord server.
+            Reminder that like any non-default tool, you need to initialize it before use
+            (e.g. <code>env.Tool('ninja')</code>).
         </para>
+
         <para>
-            Specifically if your build has many (or even any) python function actions you may find that the ninja build
-            will be slower as it will run ninja, which will then run SCons for each target created by a python action.
-            To alleviate some of these, especially those python based actions built into SCons there is special logic to
-            implement those actions via shell commands in the ninja build file.
+            It is not expected that the &b-link-Ninja; builder will work for all builds at this point. It is still under active
+            development. If you find that your build doesn't work with &ninja; please bring this to the users mailing list
+            or <literal>#scons-help</literal> channel on our Discord server.
         </para>
+
         <para>
+            Specifically if your build has many (or even any) &Python; function actions you may find that the &ninja; build
+            will be slower as it will run &ninja;, which will then run SCons for each target created by a &Python; action.
+            To alleviate some of these, especially those &Python; based actions built into SCons there is special logic to
+            implement those actions via shell commands in the &ninja; build file.
+        </para>
+
+        <para>See:</para>
+
+        <simplelist type="vert">
+            <member>
             <ulink url="https://ninja-build.org/">
                 <citetitle>Ninja Build System</citetitle>
             </ulink>
-        </para>
-
-        <para>
+            </member>
+            <member>
             <ulink url="https://ninja-build.org/manual.html#ref_ninja_file">
                 <citetitle>Ninja File Format Specification</citetitle>
             </ulink>
-        </para>
+            </member>
+        </simplelist>
     </section>
 </chapter>
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml
index 3906af6..24020ab 100644
--- a/doc/user/troubleshoot.xml
+++ b/doc/user/troubleshoot.xml
@@ -261,13 +261,13 @@ file3.c
   </section>
 
   <section>
-  <title>What's in That Construction Environment?  the &Dump; Method</title>
+  <title>What's in That Construction Environment?  the &f-Dump; Method</title>
 
     <para>
 
-    When you create a construction environment,
+    When you create a &consenv;,
     &SCons; populates it
-    with construction variables that are set up
+    with &consvars; that are set up
     for various compilers, linkers and utilities
     that it finds on your system.
     Although this is usually helpful and what you want,
@@ -276,10 +276,10 @@ file3.c
     expect to be set.
     In situations like this,
     it's sometimes helpful to use the
-    construction environment &Dump; method
+    &consenv; &f-link-Dump; method
     to print all or some of
-    the construction variables.
-    Note that the &Dump; method
+    the &consvars;.
+    Note that the &f-Dump; method
     <emphasis>returns</emphasis>
     the representation of the variables
     in the environment
@@ -318,11 +318,11 @@ print(env.Dump())
 
     <para>
 
-    The construction environments in these examples have
+    The &consenvs; in these examples have
     actually been restricted to just gcc and Visual C++,
     respectively.
     In a real-life situation,
-    the construction environments will
+    the &consenvs; will
     likely contain a great many more variables.
     Also note that we've massaged the example output above
     to make the memory address of all objects a constant 0x700000.
@@ -336,7 +336,7 @@ print(env.Dump())
     To make it easier to see just what you're
     interested in,
     the &Dump; method allows you to
-    specify a specific constrcution variable
+    specify a specific &consvar;
     that you want to disply.
     For example,
     it's not unusual to want to verify