Doc: mention Fortran "dialects"

Add to the existing manpage section on Fortran system-specific behavior
notes that SCons provides construction environment sets for six "dialects",
so that each can be individually tuned based on the file suffix.

The PR author considers this system to be of dubious utlity - it only has
any real effect in a project with files of many different suffixes where
each suffix indicates different handling, within a single build. Since
such builds might theoretically exist (there must have been some reason
this setup was designed), just try to document what there is.

Related in a proximate way only (i.e. next item in manpage),
the note on cygwin+Python is amended to also mention msys2.

Fixes #4173

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

6 files changed, 824 insertions, 409 deletions

diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
index e21c782..ff3bb39 100644
--- a/doc/generated/builders.gen
+++ b/doc/generated/builders.gen
@@ -1247,31 +1247,34 @@ env.MSVSSolution(
     <term><function>Ninja</function>()</term>
     <term><replaceable>env</replaceable>.<methodname>Ninja</methodname>()</term>
     <listitem><para>
-                &b-Ninja; is a special builder which
-                adds a target to create a ninja build file.
+                A special builder which
+                adds a target to create a Ninja build file.
                 The builder does not require any source files to be specified.
             </para>
             <note>
                 <para>This is an experimental feature. To enable it you must use one of the following methods
                 </para>
 
-<!--                NOTE DO NOT INDENT THE FOLLOWING AS IT WILL ALTER THE FORMATTING-->
+<!--            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>
 
                 <para>This functionality is subject to change and/or removal without deprecation 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>
+                    To use this tool you need to install the &Python; &ninja; package,
+                    as the tool by default depends on being able to do an
+                    <systemitem>import</systemitem> of the package
+<!--                    (although see &cv-link-__NINJA_NO;).-->
+                    This can be done via:
+                    <example_commands>
+python -m pip install ninja
+                    </example_commands>
                 </para>
 
             </note>
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
index c982b96..a2d9acd 100644
--- a/doc/generated/functions.gen
+++ b/doc/generated/functions.gen
@@ -63,7 +63,7 @@ Added methods propagate through &f-env-Clone; calls.
 </para>
 
 <para>
-Examples:
+More examples:
 </para>
 
 <example_commands>
@@ -472,7 +472,7 @@ and/or suffix,
 so the contents are treated as a list of strings, that is,
 adding a string will result in a separate string entry,
 not a combined string. For &cv-CPPDEFINES; as well as
-for &cv-link-LIBS;, and the various <varname>*PATH</varname>
+for &cv-link-LIBS;, and the various <literal>*PATH</literal>;
 variables, &SCons; will supply the compiler-specific
 syntax (e.g. adding a <literal>-D</literal> or <literal>/D</literal>
 prefix for &cv-CPPDEFINES;), so this syntax should be omitted when
@@ -550,7 +550,7 @@ do not make sense and a &Python; exception will be raised.
 <para>
 When using &f-env-Append; to modify &consvars;
 which are path specifications (conventionally,
-the names of such end in <varname>PATH</varname>),
+the names of such end in <literal>PATH</literal>),
 it is recommended to add the values as a list of strings,
 even if there is only a single string to add.
 The same goes for adding library names to &cv-LIBS;.
@@ -570,26 +570,26 @@ See also &f-link-env-AppendUnique;,
   <varlistentry id="f-AppendENVPath">
     <term><replaceable>env</replaceable>.<methodname>AppendENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing=False]</parameter>)</term>
     <listitem><para>
-Append new path elements to the given path in the
-specified external environment (&cv-link-ENV; by default).
-This will only add
-any particular path once (leaving the last one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
-<function>os.path.normpath</function>
+Append path elements specified by <parameter>newpath</parameter>
+to the given search path string or list <parameter>name</parameter>
+in mapping <parameter>envname</parameter> in the &consenv;.
+Supplying <parameter>envname</parameter> is optional:
+the default is the execution environment &cv-link-ENV;.
+Optional <parameter>sep</parameter> is used as the search path separator,
+the default is the platform's separator (<systemitem>os.pathsep</systemitem>).
+A path element will only appear once.
+Any duplicates in <parameter>newpath</parameter> are dropped,
+keeping the last appearing (to preserve path order).
+If <parameter>delete_existing</parameter>
+is <constant>False</constant> (the default)
+any addition duplicating an existing path element is ignored;
+if <parameter>delete_existing</parameter>
+is <constant>True</constant> the existing value will
+be dropped and the path element will be added at the end.
+To help maintain uniqueness all paths are normalized (using
+<systemitem>os.path.normpath</systemitem>
 and
-<function>os.path.normcase</function>).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-</para>
-
-<para>
-If
-<parameter>delete_existing</parameter>
-is <constant>False</constant>, then adding a path that already exists
-will not move it to the end; it will stay where it is in the list.
+<systemitem>os.path.normcase</systemitem>).
 </para>
 
 <para>
@@ -608,6 +608,11 @@ print('after:', env['ENV']['INCLUDE'])
 before: /foo:/biz
 after: /biz:/foo/bar:/foo
 </screen>
+
+<para>
+See also &f-link-env-PrependENVPath;.
+</para>
+
 </listitem>
   </varlistentry>
   <varlistentry id="f-AppendUnique">
@@ -718,7 +723,7 @@ is being used and
 &scons;
 finds a derived file that needs to be rebuilt,
 it will first look in the cache to see if a
-file with matching build signature exists
+file with matching &buildsig; exists
 (indicating the input file(s) and build action(s)
 were identical to those for the current target),
 and if so, will retrieve the file from the cache.
@@ -730,7 +735,7 @@ If the derived file is not present in the cache,
 &scons;
 will build it and
 then place a copy of the built file in the cache,
-identified by its build signature, for future use.
+identified by its &buildsig;, for future use.
 </para>
 
 <para>
@@ -787,6 +792,13 @@ method can be used to disable caching of specific files.  This can be
 useful if inputs and/or outputs of some tool are impossible to
 predict or prohibitively large.
 </para>
+
+<para>
+Note that (at this time) &SCons; provides no facilities
+for managing the derived-file cache. It is up to the developer
+to arrange for cache pruning, expiry, etc. if needed.
+</para>
+
 </listitem>
   </varlistentry>
   <varlistentry id="f-Clean">
@@ -1194,7 +1206,7 @@ was built.
 This can be consulted to match various
 file characteristics
 such as the timestamp,
-size, or content signature.
+size, or &contentsig;.
 </para>
 </listitem>
 </varlistentry>
@@ -1390,10 +1402,11 @@ Find an executable from one or more choices:
 <parameter>progs</parameter> may be a string or a list of strings.
 Returns the first value from <parameter>progs</parameter>
 that was found, or <constant>None</constant>.
-Executable is searched by checking the paths specified
-by <varname>env</varname><literal>['ENV']['PATH']</literal>.
+Executable is searched by checking the paths in the execution environment
+(<varname>env</varname><literal>['ENV']['PATH']</literal>).
 On Windows systems, additionally applies the filename suffixes found in
-<varname>env</varname><literal>['ENV']['PATHEXT']</literal>
+the execution environment
+(<varname>env</varname><literal>['ENV']['PATHEXT']</literal>)
 but will not include any such extension in the return value.
 &f-env-Detect; is a wrapper around &f-link-env-WhereIs;.
 </para>
@@ -2640,12 +2653,8 @@ not as separate arguments to
 </para>
 
 <para>
-By default,
-duplicate values are eliminated;
-you can, however, specify
-<literal>unique=False</literal>
-to allow duplicate
-values to be added.
+If <literal>unique</literal> is true (the default),
+duplicate values are not stored.
 When eliminating duplicate values,
 any &consvars; that end with
 the string
@@ -2653,6 +2662,8 @@ the string
 keep the left-most unique value.
 All other &consvars; keep
 the right-most unique value.
+If <literal>unique</literal> is false,
+values are added even if they are duplicates.
 </para>
 
 <para>
@@ -2669,9 +2680,13 @@ env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
 
 # Combine an optimization flag with the flags returned from running pkg-config
 # twice and merge the result into the construction variables.
-env.MergeFlags(['-O3',
-               '!pkg-config gtk+-2.0 --cflags --libs',
-               '!pkg-config libpng12 --cflags --libs'])
+env.MergeFlags(
+    [
+        '-O3',
+        '!pkg-config gtk+-2.0 --cflags --libs',
+        '!pkg-config libpng12 --cflags --libs',
+    ]
+)
 </example_commands>
 </listitem>
   </varlistentry>
@@ -2773,15 +2788,13 @@ NoClean(env.Program('hello', 'hello.c'))
     <term><replaceable>env</replaceable>.<methodname>ParseConfig</methodname>(<parameter>command, [function, unique]</parameter>)</term>
     <listitem><para>
 Updates the current &consenv; with the values extracted
-from the output from running external <parameter>command</parameter>,
-by calling a helper function <parameter>function</parameter>
-which understands
-the output of <parameter>command</parameter>.
+from the output of running external <parameter>command</parameter>,
+by passing it to a helper <parameter>function</parameter>.
 <parameter>command</parameter> may be a string
 or a list of strings representing the command and
 its arguments.
 If <parameter>function</parameter>
-is not given,
+is omitted or <constant>None</constant>,
 &f-link-env-MergeFlags; is used.
 By default,
 duplicate values are not
@@ -2792,33 +2805,32 @@ to allow duplicate values to be added.
 </para>
 
 <para>
-If &f-env-MergeFlags; is used,
-it expects a response in the style of a
-<command>*-config</command>
-command typical of the POSIX programming environment
-(for example,
-<application>gtk-config</application>)
-and adds the options
-to the appropriate construction variables.
-Interpreted options
-and the construction variables they affect
-are as specified for the
-&f-link-env-ParseFlags;
-method (which
-&f-env-MergeFlags; calls).
-See that method's description
-for a table of options and corresponding construction variables.
+<parameter>command</parameter> is executed using the
+SCons execution environment (that is, the &consvar;
+&cv-link-ENV; in the current &consenv;).
+If <parameter>command</parameter> needs additional information
+to operate properly, that needs to be set in the execution environment.
+For example, <command>pkg-config</command>
+may need a custom value set in the <envar>PKG_CONFIG_PATH</envar>
+environment variable.
 </para>
 
 <para>
-If &f-env-MergeFlags; cannot interpret the results of
+&f-env-MergeFlags; needs to understand
+the output produced by <parameter>command</parameter>
+in order to distribute it to appropriate &consvars;.
+&f-env-MergeFlags; uses a separate function to
+do that processing -
+see &f-link-env-ParseFlags; for the details, including a
+a table of options and corresponding construction variables.
+To provide alternative processing of the output of
 <parameter>command</parameter>,
 you can suppply a custom
-<parameter>function</parameter> to do so.
-<parameter>function</parameter>
-must accept three arguments:
-the &consenv; to modify, the string returned
-by running <parameter>command</parameter>,
+<parameter>function</parameter>,
+which must accept three arguments:
+the &consenv; to modify,
+a string argument containing the output from running
+<parameter>command</parameter>,
 and the optional
 <parameter>unique</parameter> flag.
 </para>
@@ -2828,8 +2840,7 @@ and the optional
     <term><function>ParseDepends</function>(<parameter>filename, [must_exist, only_one]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>ParseDepends</methodname>(<parameter>filename, [must_exist, only_one]</parameter>)</term>
     <listitem><para>
-Parses the contents of the specified
-<parameter>filename</parameter>
+Parses the contents of <parameter>filename</parameter>
 as a list of dependencies in the style of
 &Make;
 or
@@ -2840,27 +2851,21 @@ and explicitly establishes all of the listed dependencies.
 <para>
 By default,
 it is not an error
-if the specified
-<parameter>filename</parameter>
+if <parameter>filename</parameter>
 does not exist.
 The optional
 <parameter>must_exist</parameter>
-argument may be set to a non-zero
-value to have
-scons
-throw an exception and
-generate an error if the file does not exist,
+argument may be set to <constant>True</constant>
+to have &SCons;
+raise an exception if the file does not exist,
 or is otherwise inaccessible.
 </para>
 
 <para>
 The optional
 <parameter>only_one</parameter>
-argument may be set to a non-zero
-value to have
-scons
-thrown an exception and
-generate an error
+argument may be set to <constant>True</constant>
+to have &SCons; raise an exception
 if the file contains dependency
 information for more than one target.
 This can provide a small sanity check
@@ -2876,7 +2881,6 @@ file.
 </para>
 
 <para>
-The
 <parameter>filename</parameter>
 and all of the files listed therein
 will be interpreted relative to
@@ -2892,10 +2896,10 @@ function.
     <term><replaceable>env</replaceable>.<methodname>ParseFlags</methodname>(<parameter>flags, ...</parameter>)</term>
     <listitem><para>
 Parses one or more strings containing
-typical command-line flags for GCC tool chains
+typical command-line flags for GCC-style tool chains
 and returns a dictionary with the flag values
 separated into the appropriate SCons construction variables.
-This is intended as a companion to the
+Intended as a companion to the
 &f-link-env-MergeFlags;
 method, but allows for the values in the returned dictionary
 to be modified, if necessary,
@@ -2910,11 +2914,20 @@ directly unless you want to manipulate the values.)
 
 <para>
 If the first character in any string is
-an exclamation mark (!),
+an exclamation mark (<literal>!</literal>),
 the rest of the string is executed as a command,
 and the output from the command is
 parsed as GCC tool chain command-line flags
 and added to the resulting dictionary.
+This can be used to call a <filename>*-config</filename>
+command typical of the POSIX programming environment
+(for example,
+<command>pkg-config</command>).
+Note that such a comamnd is executed using the
+SCons execution environment;
+if the command needs additional information,
+that information needs to be explcitly provided.
+See &f-link-ParseConfig; for more details.
 </para>
 
 <para>
@@ -3051,30 +3064,28 @@ and &f-link-env-PrependUnique;.
 </listitem>
   </varlistentry>
   <varlistentry id="f-PrependENVPath">
-    <term><replaceable>env</replaceable>.<methodname>PrependENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing]</parameter>)</term>
+    <term><replaceable>env</replaceable>.<methodname>PrependENVPath</methodname>(<parameter>name, newpath, [envname, sep, delete_existing=True]</parameter>)</term>
     <listitem><para>
-Prepend new path elements to the given path in the
-specified external environment (&cv-link-ENV; by default).
-This will only add
-any particular path once (leaving the first one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
+Prepend path elements specified by <parameter>newpath</parameter>
+to the given search path string or list <parameter>name</parameter>
+in mapping <parameter>envname</parameter> in the &consenv;.
+Supplying <parameter>envname</parameter> is optional:
+the default is the execution environment &cv-link-ENV;.
+Optional <parameter>sep</parameter> is used as the search path separator,
+the default is the platform's separator (<systemitem>os.pathsep</systemitem>).
+A path element will only appear once.
+Any duplicates in <parameter>newpath</parameter> are dropped,
+keeping the first appearing (to preserve path order).
+If <parameter>delete_existing</parameter>
+is <constant>False</constant>
+any addition duplicating an existing path element is ignored;
+if <parameter>delete_existing</parameter>
+is <constant>True</constant> (the default) the existing value will
+be dropped and the path element will be inserted at the beginning.
+To help maintain uniqueness all paths are normalized (using
 <systemitem>os.path.normpath</systemitem>
 and
 <systemitem>os.path.normcase</systemitem>).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-</para>
-
-<para>
-If
-<parameter>delete_existing</parameter>
-is <constant>False</constant>,
-then adding a path that already exists
-will not move it to the beginning;
-it will stay where it is in the list.
 </para>
 
 <para>
@@ -3094,6 +3105,11 @@ print('after:', env['ENV']['INCLUDE'])
 before: /biz:/foo
 after: /foo/bar:/foo:/biz
 </screen>
+
+<para>
+See also &f-link-env-AppendENVPath;.
+</para>
+
 </listitem>
   </varlistentry>
   <varlistentry id="f-PrependUnique">
@@ -3103,7 +3119,7 @@ Prepend values to &consvars; in the current &consenv;,
 maintaining uniqueness.
 Works like &f-link-env-Append; (see for details),
 except that values are added to the front,
-rather than the end, of any existing value of the the &consvar;,
+rather than the end, of any existing value of the &consvar;,
 and values already present in the &consvar;
 will not be added again.
 If <parameter>delete_existing</parameter>
@@ -3461,40 +3477,36 @@ for a complete explanation of the arguments and behavior.
   <varlistentry id="f-SConscript">
     <term><function>SConscript</function>(<parameter>scripts, [exports, variant_dir, duplicate, must_exist]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>SConscript</methodname>(<parameter>scripts, [exports, variant_dir, duplicate, must_exist]</parameter>)</term>
-    <term><function>SConscript</function>(<parameter>dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist]</parameter>)</term>
-    <term><replaceable>env</replaceable>.<methodname>SConscript</methodname>(<parameter>dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist]</parameter>)</term>
+    <term><function>SConscript</function>(<parameter>dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist]</parameter>)</term>
+    <term><replaceable>env</replaceable>.<methodname>SConscript</methodname>(<parameter>dirs=subdirs, [name=scriptname, exports, variant_dir, duplicate, must_exist]</parameter>)</term>
     <listitem><para>
-Execute one or more subsidiary SConscript (configuration) files.
+Executes one or more subsidiary SConscript (configuration) files.
 There are two ways to call the
 &f-SConscript; function.
 </para>
 
 <para>
-The first calling style
-is to explicitly specify one or more
-<varname>scripts</varname>
-as the first argument.
+The first calling style is to supply
+one or more SConscript file names
+as the first (positional) argument.
 A single script may be specified as a string;
-multiple scripts must be specified as a list
+multiple scripts must be specified as a list of strings
 (either explicitly or as created by
 a function like
 &f-link-Split;).
 Examples:
 </para>
 <example_commands>
-SConscript('SConscript')      # run SConscript in the current directory
+SConscript('SConscript')  # run SConscript in the current directory
 SConscript('src/SConscript')  # run SConscript in the src directory
 SConscript(['src/SConscript', 'doc/SConscript'])
 config = SConscript('MyConfig.py')
 </example_commands>
 
 <para>
-The second way to call
-&f-SConscript;
-is to specify a list of (sub)directory names
-as a
-<varname>dirs</varname>=<replaceable>subdirs</replaceable>
-keyword argument.
+The other calling style is to omit the positional argument naming
+scripts and instead specify a list of directory names using the
+<varname>dirs</varname> keyword argument.
 In this case,
 &scons;
 will
@@ -3504,14 +3516,14 @@ in each of the specified directories.
 You may specify a name other than
 &SConscript;
 by supplying an optional
-<varname>name</varname>=<replaceable>script</replaceable>
+<varname>name</varname>=<replaceable>scriptname</replaceable>
 keyword argument.
 The first three examples below have the same effect
 as the first three examples above:
 </para>
 <example_commands>
-SConscript(dirs='.')      # run SConscript in the current directory
-SConscript(dirs='src')    # run SConscript in the src directory
+SConscript(dirs='.')  # run SConscript in the current directory
+SConscript(dirs='src')  # run SConscript in the src directory
 SConscript(dirs=['src', 'doc'])
 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
 </example_commands>
@@ -3519,8 +3531,12 @@ SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
 <para>
 The optional
 <varname>exports</varname>
-argument provides a string or list of strings representing
+keyword argument provides a string or list of strings representing
 variable names, or a dictionary of named values, to export.
+For the first calling style only, a second positional argument
+will be interpreted as <varname>exports</varname>; the
+second calling style must use the keyword argument form
+for <varname>exports</varname>.
 These variables are locally exported only to the called
 SConscript file(s)
 and do not affect the global pool of variables managed by the
@@ -3544,38 +3560,24 @@ SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
 If the optional
 <varname>variant_dir</varname>
 argument is present, it causes an effect equivalent to the
-&f-link-VariantDir; function.
+&f-link-VariantDir; function,
+but in effect only within the scope of the &f-SConscript; call.
 The <varname>variant_dir</varname>
-argument is interpreted relative to the directory of the calling
-SConscript file.
-The optional
-<varname>duplicate</varname> argument is
-interpreted as for &f-link-VariantDir;.
-If <varname>variant_dir</varname>
-is omitted, the <varname>duplicate</varname> argument is ignored.
-See the description of
-&f-link-VariantDir;
-below for additional details and restrictions.
-</para>
-
-<para>
-If
-<varname>variant_dir</varname>
-is present,
-the source directory is the directory in which the
-SConscript
-file resides and the
-SConscript
+argument is interpreted relative to the directory of the
+<emphasis>calling</emphasis> SConscript file.
+The source directory is the directory in which the
+<emphasis>called</emphasis> SConscript
+file resides and the SConscript
 file is evaluated as if it were in the
 <varname>variant_dir</varname>
-directory:
+directory. Thus:
 </para>
 <example_commands>
 SConscript('src/SConscript', variant_dir='build')
 </example_commands>
 
 <para>
-is equivalent to
+is equivalent to:
 </para>
 
 <example_commands>
@@ -3584,9 +3586,8 @@ SConscript('build/SConscript')
 </example_commands>
 
 <para>
-This later paradigm is often used when the sources are
-in the same directory as the
-&SConstruct;:
+If the sources are in the same directory as the
+&SConstruct;,
 </para>
 
 <example_commands>
@@ -3594,7 +3595,7 @@ SConscript('SConscript', variant_dir='build')
 </example_commands>
 
 <para>
-is equivalent to
+is equivalent to:
 </para>
 
 <example_commands>
@@ -3603,6 +3604,17 @@ SConscript('build/SConscript')
 </example_commands>
 
 <para>
+The optional
+<varname>duplicate</varname> argument is
+interpreted as for &f-link-VariantDir;.
+If the <varname>variant_dir</varname> argument
+is omitted, the <varname>duplicate</varname> argument is ignored.
+See the description of
+&f-link-VariantDir;
+for additional details and restrictions.
+</para>
+
+<para>
 <!--
 If
 <varname>variant_dir</varname>
@@ -3685,11 +3697,11 @@ SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
 
 <para>
 &f-SConscript; returns the values of any variables
-named by the executed SConscript(s) in arguments
-to the &f-link-Return; function (see above for details).
+named by the executed SConscript file(s) in arguments
+to the &f-link-Return; function.
 If a single &f-SConscript; call causes multiple scripts to
 be executed, the return value is a tuple containing
-the returns of all of the scripts. If an executed
+the returns of each of the scripts. If an executed
 script does not explicitly call &Return;, it returns
 <constant>None</constant>.
 </para>
@@ -3724,7 +3736,7 @@ when all the directories in which SConscript files may be found
 don't necessarily exist locally.)
 You may enable and disable
 this ability by calling
-SConscriptChdir()
+&f-SConscriptChdir;
 multiple times.
 </para>
 
@@ -4159,9 +4171,16 @@ files = Split("""
   <varlistentry id="f-subst">
     <term><replaceable>env</replaceable>.<methodname>subst</methodname>(<parameter>input, [raw, target, source, conv]</parameter>)</term>
     <listitem><para>
-Performs construction variable interpolation
+Performs &consvar; interpolation
+(<firstterm>substitution</firstterm>)
 on <parameter>input</parameter>,
 which can be a string or a sequence.
+Substitutable elements take the form
+<literal>${<replaceable>expression</replaceable>}</literal>,
+although if there is no ambiguity in recognizing the element,
+the braces can be omitted.
+A literal <emphasis role="bold">$</emphasis> can be entered by
+using <emphasis role="bold">$$</emphasis>.
 </para>
 
 <para>
@@ -4196,7 +4215,7 @@ pairs
 </para>
 
 <para>
-If the input is a sequence
+If <parameter>input</parameter> is a sequence
 (list or tuple),
 the individual elements of
 the sequence will be expanded,
@@ -4424,7 +4443,7 @@ env.Config(target = 'package-config', source = Value(prefix))
 
 def build_value(target, source, env):
     # A function that "builds" a Python Value by updating
-    # the the Python value with the contents of the file
+    # the Python value with the contents of the file
     # specified as the source of the Builder call ($SOURCE).
     target[0].write(source[0].get_contents())
 
@@ -4442,42 +4461,41 @@ env.UpdateValue(target = Value(output), source = Value(input))
     <term><function>VariantDir</function>(<parameter>variant_dir, src_dir, [duplicate]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>VariantDir</methodname>(<parameter>variant_dir, src_dir, [duplicate]</parameter>)</term>
     <listitem><para>
-Sets up an alternate build location.
-When building in the <parameter>variant_dir</parameter>,
-&SCons; backfills as needed with files from <parameter>src_dir</parameter>
-to create a complete build directory.
+Sets up a mapping to define a variant build directory in
+<parameter>variant_dir</parameter>.
+<parameter>src_dir</parameter> may not be underneath
+<parameter>variant_dir</parameter>.
+A &f-VariantDir; mapping is global, even if called using the
+&f-env-VariantDir; form.
 &f-VariantDir;
 can be called multiple times with the same
 <parameter>src_dir</parameter>
-to set up multiple builds with different options
-(<emphasis>variants</emphasis>).
+to set up multiple variant builds with different options.
 </para>
 
 <para>
-The
-<parameter>variant</parameter>
-location must be in or underneath the project top directory,
-and <parameter>src_dir</parameter>
-may not be underneath
-<parameter>variant_dir</parameter>.
+Note if <parameter>variant_dir</parameter>
+is not under the project top directory,
+target selection rules will not pick targets in the
+variant directory unless they are explicitly specified.
 </para>
 
 <para>
+When files in <parameter>variant_dir</parameter> are referenced,
+&SCons; backfills as needed with files from <parameter>src_dir</parameter>
+to create a complete build directory.
 By default, &SCons;
-physically duplicates the source files and SConscript files
-as needed into the variant tree.
-Thus, a build performed in the variant tree is guaranteed to be identical
-to a build performed in the source tree even if
+physically duplicates the source files, SConscript files,
+and directory structure as needed into the variant directory.
+Thus, a build performed in the variant directory is guaranteed to be identical
+to a build performed in the source directory even if
 intermediate source files are generated during the build,
 or if preprocessors or other scanners search for included files
-relative to the source file,
+using paths relative to the source file,
 or if individual compilers or other invoked tools are hard-coded
 to put derived files in the same directory as source files.
 Only the files &SCons; calculates are needed for the build are
 duplicated into <parameter>variant_dir</parameter>.
-</para>
-
-<para>
 If possible on the platform,
 the duplication is performed by linking rather than copying.
 This behavior is affected by the
@@ -4496,44 +4514,46 @@ to invoke Builders using the path names of source files in
 <parameter>src_dir</parameter>
 and the path names of derived files within
 <parameter>variant_dir</parameter>.
-This is more efficient than
-<literal>duplicate=True</literal>,
+This is more efficient than duplicating,
 and is safe for most builds;
-revert to <constant>True</constant>
+revert to <literal>duplicate=True</literal>
 if it causes problems.
 </para>
 
 <para>
 &f-VariantDir;
-works most naturally with used with a subsidiary SConscript file.
-The subsidiary SConscript file is called as if it
-were in
+works most naturally when used with a subsidiary SConscript file.
+The subsidiary SConscript file must be called as if it were in
 <parameter>variant_dir</parameter>,
 regardless of the value of
 <parameter>duplicate</parameter>.
-This is how you tell
-&scons;
-which variant of a source tree to build:
+When calling an SConscript file, you can use the 
+<parameter>exports</parameter> keyword argument
+to pass parameters (individually or as an appropriately set up environment)
+so the SConscript can pick up the right settings for that variant build.
+The SConscript must &f-link-Import; these to use them. Example:
 </para>
 
 <example_commands>
+env1 = Environment(...settings for variant1...)
+env2 = Environment(...settings for variant2...)
+
 # run src/SConscript in two variant directories
 VariantDir('build/variant1', 'src')
-SConscript('build/variant1/SConscript')
+SConscript('build/variant1/SConscript', exports={"env": env1})
 VariantDir('build/variant2', 'src')
-SConscript('build/variant2/SConscript')
+SConscript('build/variant2/SConscript', exports={"env": env2})
 </example_commands>
 
 <para>
 See also the
-&f-link-SConscript;
-function, described above,
+&f-link-SConscript; function
 for another way to specify a variant directory
 in conjunction with calling a subsidiary SConscript file.
 </para>
 
 <para>
-Examples:
+More examples:
 </para>
 
 <example_commands>
diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen
index 43c6531..ecc301a 100644
--- a/doc/generated/tools.gen
+++ b/doc/generated/tools.gen
@@ -82,14 +82,14 @@ Sets construction variables for the bcc32 compiler.
     <listitem><para>
 Sets construction variables for generic POSIX C compilers.
 </para>
-<para>Sets: &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCFLAGS;, &cv-link-CFILESUFFIX;, &cv-link-CFLAGS;, &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-FRAMEWORKPATH;, &cv-link-FRAMEWORKS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-SHCC;, &cv-link-SHCCCOM;, &cv-link-SHCCFLAGS;, &cv-link-SHCFLAGS;, &cv-link-SHOBJSUFFIX;.</para><para>Uses: &cv-link-CCCOMSTR;, &cv-link-PLATFORM;, &cv-link-SHCCCOMSTR;.</para></listitem>
+<para>Sets: &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCDEPFLAGS;, &cv-link-CCFLAGS;, &cv-link-CFILESUFFIX;, &cv-link-CFLAGS;, &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-FRAMEWORKPATH;, &cv-link-FRAMEWORKS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-SHCC;, &cv-link-SHCCCOM;, &cv-link-SHCCFLAGS;, &cv-link-SHCFLAGS;, &cv-link-SHOBJSUFFIX;.</para><para>Uses: &cv-link-CCCOMSTR;, &cv-link-PLATFORM;, &cv-link-SHCCCOMSTR;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-clang">
     <term>clang</term>
     <listitem><para>
 Set construction variables for the Clang C compiler.
 </para>
-<para>Sets: &cv-link-CC;, &cv-link-CCVERSION;, &cv-link-SHCCFLAGS;.</para></listitem>
+<para>Sets: &cv-link-CC;, &cv-link-CCDEPFLAGS;, &cv-link-CCVERSION;, &cv-link-SHCCFLAGS;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-clangxx">
     <term>clangxx</term>
@@ -422,9 +422,9 @@ Set construction variables for generic POSIX Fortran 95 compilers.
   <varlistentry id="t-fortran">
     <term>fortran</term>
     <listitem><para>
-Set construction variables for generic POSIX Fortran compilers.
+Set &consvars; for generic POSIX Fortran compilers.
 </para>
-<para>Sets: &cv-link-FORTRAN;, &cv-link-FORTRANCOM;, &cv-link-FORTRANFLAGS;, &cv-link-SHFORTRAN;, &cv-link-SHFORTRANCOM;, &cv-link-SHFORTRANFLAGS;, &cv-link-SHFORTRANPPCOM;.</para><para>Uses: &cv-link-FORTRANCOMSTR;, &cv-link-FORTRANPPCOMSTR;, &cv-link-SHFORTRANCOMSTR;, &cv-link-SHFORTRANPPCOMSTR;.</para></listitem>
+<para>Sets: &cv-link-FORTRAN;, &cv-link-FORTRANCOM;, &cv-link-FORTRANFLAGS;, &cv-link-SHFORTRAN;, &cv-link-SHFORTRANCOM;, &cv-link-SHFORTRANFLAGS;, &cv-link-SHFORTRANPPCOM;.</para><para>Uses: &cv-link-CPPFLAGS;, &cv-link-FORTRANCOMSTR;, &cv-link-FORTRANPPCOMSTR;, &cv-link-SHFORTRANCOMSTR;, &cv-link-SHFORTRANPPCOMSTR;, &cv-link-_CPPDEFFLAGS;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-gXX">
     <term>g++</term>
@@ -455,7 +455,7 @@ Calls the &t-link-as; tool.
     <listitem><para>
 Set construction variables for the &gcc; C compiler.
 </para>
-<para>Sets: &cv-link-CC;, &cv-link-CCVERSION;, &cv-link-SHCCFLAGS;.</para></listitem>
+<para>Sets: &cv-link-CC;, &cv-link-CCDEPFLAGS;, &cv-link-CCVERSION;, &cv-link-SHCCFLAGS;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-gdc">
     <term>gdc</term>
@@ -782,7 +782,7 @@ the Microsoft toolchain:
     <listitem><para>
 Sets construction variables for the Microsoft Visual C/C++ compiler.
 </para>
-<para>Sets: &cv-link-BUILDERS;, &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCFLAGS;, &cv-link-CCPCHFLAGS;, &cv-link-CCPDBFLAGS;, &cv-link-CFILESUFFIX;, &cv-link-CFLAGS;, &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-CXXFILESUFFIX;, &cv-link-CXXFLAGS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-OBJPREFIX;, &cv-link-OBJSUFFIX;, &cv-link-PCHCOM;, &cv-link-PCHPDBFLAGS;, &cv-link-RC;, &cv-link-RCCOM;, &cv-link-RCFLAGS;, &cv-link-SHCC;, &cv-link-SHCCCOM;, &cv-link-SHCCFLAGS;, &cv-link-SHCFLAGS;, &cv-link-SHCXX;, &cv-link-SHCXXCOM;, &cv-link-SHCXXFLAGS;, &cv-link-SHOBJPREFIX;, &cv-link-SHOBJSUFFIX;.</para><para>Uses: &cv-link-CCCOMSTR;, &cv-link-CXXCOMSTR;, &cv-link-PCH;, &cv-link-PCHSTOP;, &cv-link-PDB;, &cv-link-SHCCCOMSTR;, &cv-link-SHCXXCOMSTR;.</para></listitem>
+<para>Sets: &cv-link-BUILDERS;, &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCDEPFLAGS;, &cv-link-CCFLAGS;, &cv-link-CCPCHFLAGS;, &cv-link-CCPDBFLAGS;, &cv-link-CFILESUFFIX;, &cv-link-CFLAGS;, &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-CXXFILESUFFIX;, &cv-link-CXXFLAGS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-OBJPREFIX;, &cv-link-OBJSUFFIX;, &cv-link-PCHCOM;, &cv-link-PCHPDBFLAGS;, &cv-link-RC;, &cv-link-RCCOM;, &cv-link-RCFLAGS;, &cv-link-SHCC;, &cv-link-SHCCCOM;, &cv-link-SHCCFLAGS;, &cv-link-SHCFLAGS;, &cv-link-SHCXX;, &cv-link-SHCXXCOM;, &cv-link-SHCXXFLAGS;, &cv-link-SHOBJPREFIX;, &cv-link-SHOBJSUFFIX;.</para><para>Uses: &cv-link-CCCOMSTR;, &cv-link-CXXCOMSTR;, &cv-link-MSVC_NOTFOUND_POLICY;, &cv-link-PCH;, &cv-link-PCHSTOP;, &cv-link-PDB;, &cv-link-SHCCCOMSTR;, &cv-link-SHCXXCOMSTR;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-msvs">
     <term>msvs</term>
@@ -814,15 +814,15 @@ Sets construction variables for the
   <varlistentry id="t-ninja">
     <term>ninja</term>
     <listitem><para>
-                Sets up &b-link-Ninja; builder which generates a ninja build file, and then optionally runs &ninja;.
+                Sets up the &b-link-Ninja; builder, which generates a &ninja; build file, and then optionally runs &ninja;.
             </para>
             <note>
                 <para>This is an experimental feature.
+                    This functionality is subject to change and/or removal without a deprecation cycle.
                 </para>
-                <para>This functionality is subject to change and/or removal without deprecation cycle.</para>
             </note>
 
-        <para>Sets: &cv-link-IMPLICIT_COMMAND_DEPENDENCIES;, &cv-link-NINJA_ALIAS_NAME;, &cv-link-NINJA_COMPDB_EXPAND;, &cv-link-NINJA_DIR;, &cv-link-NINJA_DISABLE_AUTO_RUN;, &cv-link-NINJA_ENV_VAR_CACHE;, &cv-link-NINJA_FILE_NAME;, &cv-link-NINJA_FORCE_SCONS_BUILD;, &cv-link-NINJA_GENERATED_SOURCE_SUFFIXES;, &cv-link-NINJA_MSVC_DEPS_PREFIX;, &cv-link-NINJA_POOL;, &cv-link-NINJA_REGENERATE_DEPS;, &cv-link-NINJA_SYNTAX;, &cv-link-_NINJA_REGENERATE_DEPS_FUNC;, &cv-link-__NINJA_NO;.</para><para>Uses: &cv-link-AR;, &cv-link-ARCOM;, &cv-link-ARFLAGS;, &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCFLAGS;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-ESCAPE;, &cv-link-LINK;, &cv-link-LINKCOM;, &cv-link-PLATFORM;, &cv-link-PRINT_CMD_LINE_FUNC;, &cv-link-PROGSUFFIX;, &cv-link-RANLIB;, &cv-link-RANLIBCOM;, &cv-link-SHCCCOM;, &cv-link-SHCXXCOM;, &cv-link-SHLINK;, &cv-link-SHLINKCOM;.</para></listitem>
+        <para>Sets: &cv-link-IMPLICIT_COMMAND_DEPENDENCIES;, &cv-link-NINJA_ALIAS_NAME;, &cv-link-NINJA_CMD_ARGS;, &cv-link-NINJA_COMPDB_EXPAND;, &cv-link-NINJA_DEPFILE_PARSE_FORMAT;, &cv-link-NINJA_DIR;, &cv-link-NINJA_DISABLE_AUTO_RUN;, &cv-link-NINJA_ENV_VAR_CACHE;, &cv-link-NINJA_FILE_NAME;, &cv-link-NINJA_FORCE_SCONS_BUILD;, &cv-link-NINJA_GENERATED_SOURCE_ALIAS_NAME;, &cv-link-NINJA_GENERATED_SOURCE_SUFFIXES;, &cv-link-NINJA_MSVC_DEPS_PREFIX;, &cv-link-NINJA_POOL;, &cv-link-NINJA_REGENERATE_DEPS;, &cv-link-NINJA_SCONS_DAEMON_KEEP_ALIVE;, &cv-link-NINJA_SCONS_DAEMON_PORT;, &cv-link-NINJA_SYNTAX;, &cv-link-_NINJA_REGENERATE_DEPS_FUNC;.</para><para>Uses: &cv-link-AR;, &cv-link-ARCOM;, &cv-link-ARFLAGS;, &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCDEPFLAGS;, &cv-link-CCFLAGS;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-ESCAPE;, &cv-link-LINK;, &cv-link-LINKCOM;, &cv-link-PLATFORM;, &cv-link-PRINT_CMD_LINE_FUNC;, &cv-link-PROGSUFFIX;, &cv-link-RANLIB;, &cv-link-RANLIBCOM;, &cv-link-SHCCCOM;, &cv-link-SHCXXCOM;, &cv-link-SHLINK;, &cv-link-SHLINKCOM;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-packaging">
     <term>packaging</term>
@@ -1049,7 +1049,7 @@ Sets construction variables for the Sun linker.
   <varlistentry id="t-swig">
     <term>swig</term>
     <listitem><para>
-Sets construction variables for the SWIG interface generator.
+Sets construction variables for the &swig; interface compiler.
 </para>
 <para>Sets: &cv-link-SWIG;, &cv-link-SWIGCFILESUFFIX;, &cv-link-SWIGCOM;, &cv-link-SWIGCXXFILESUFFIX;, &cv-link-SWIGDIRECTORSUFFIX;, &cv-link-SWIGFLAGS;, &cv-link-SWIGINCPREFIX;, &cv-link-SWIGINCSUFFIX;, &cv-link-SWIGPATH;, &cv-link-SWIGVERSION;, &cv-link-_SWIGINCFLAGS;.</para><para>Uses: &cv-link-SWIGCOMSTR;.</para></listitem>
   </varlistentry>
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index cf7751f..996e35a 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -22,16 +22,6 @@ if &cv-link-LDMODULEVERSION; is set. Othervise it evaluates to an empty string.
 </para>
 </listitem>
   </varlistentry>
-  <varlistentry id="cv-__NINJA_NO">
-    <term>
-      <envar>__NINJA_NO</envar>
-    </term>
-    <listitem><para>
-                Internal flag. Used to tell SCons whether or not to try to import pypi's ninja python package.
-                This is set to True when being called by Ninja?
-            </para>
-        </listitem>
-  </varlistentry>
   <varlistentry id="cv-__SHLIBVERSIONFLAGS">
     <term>
       <envar>__SHLIBVERSIONFLAGS</envar>
@@ -427,6 +417,18 @@ env = Environment(CCCOMSTR = "Compiling static object $TARGET")
 </example_commands>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-CCDEPFLAGS">
+    <term>
+      <envar>CCDEPFLAGS</envar>
+    </term>
+    <listitem><para>
+Options to pass to C or C++ compiler to generate list of dependency files.
+</para>
+ <para>
+  This is set only by compilers which support this functionality. (&t-link-gcc;, &t-link-clang;, and &t-link-msvc; currently)
+ </para>
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-CCFLAGS">
     <term>
       <envar>CCFLAGS</envar>
@@ -1641,56 +1643,59 @@ General options passed to the TeX DVI file to PostScript converter.
       <envar>ENV</envar>
     </term>
     <listitem><para>
-A dictionary of environment variables
-to use when invoking commands. When
-&cv-ENV; is used in a command all list
-values will be joined using the path separator and any other non-string
-values will simply be coerced to a string.
-Note that, by default,
-&scons;
+The <firstterm>execution environment</firstterm> -
+a dictionary of environment variables
+used when &SCons; invokes external commands
+to build targets defined in this &consenv;.
+When &cv-ENV; is passed to a command,
+all list values are assumed to be path lists and
+are joined using the search path separator.
+Any other non-string values are coerced to a string.
+</para>
+
+<para>
+Note that by default
+&SCons;
 does
 <emphasis>not</emphasis>
-propagate the environment in effect when you
-execute
-&scons;
-to the commands used to build target files.
+propagate the environment in effect when you execute
+&scons; (the "shell environment")
+to the execution environment.
 This is so that builds will be guaranteed
 repeatable regardless of the environment
 variables set at the time
 &scons;
 is invoked.
-</para>
-
-<para>
-If you want to propagate your
-environment variables
+If you want to propagate a
+shell environment variable
 to the commands executed
 to build target files,
-you must do so explicitly:
+you must do so explicitly.
+A common example is
+the system &PATH;
+environment variable,
+so that
+&scons;
+will find utilities the same way
+as the invoking shell (or other process):
 </para>
 
 <example_commands>
 import os
-env = Environment(ENV=os.environ.copy())
+env = Environment(ENV={'PATH': os.environ['PATH']})
 </example_commands>
 
 <para>
-Note that you can choose only to propagate
-certain environment variables.
-A common example is
-the system
-<envar>PATH</envar>
-environment variable,
-so that
-&scons;
-uses the same utilities
-as the invoking shell (or other process):
+Although it is usually not recommended,
+you can propagate the entire shell environment
+in one go:
 </para>
 
 <example_commands>
 import os
-env = Environment(ENV={'PATH': os.environ['PATH']})
+env = Environment(ENV=os.environ.copy())
 </example_commands>
+
 </listitem>
   </varlistentry>
   <varlistentry id="cv-ESCAPE">
@@ -2671,11 +2676,9 @@ for all versions of Fortran.
 The command line used to compile a Fortran source file to an object file.
 By default, any options specified
 in the &cv-link-FORTRANFLAGS;,
-&cv-link-CPPFLAGS;,
-&cv-link-_CPPDEFFLAGS;,
 &cv-link-_FORTRANMODFLAG;, and
-&cv-link-_FORTRANINCFLAGS; construction variables
-are included on this command line.
+&cv-link-_FORTRANINCFLAGS;
+&consvars; are included on this command line.
 </para>
 </listitem>
   </varlistentry>
@@ -2725,7 +2728,7 @@ for the variables that expand those options.
       <envar>_FORTRANINCFLAGS</envar>
     </term>
     <listitem><para>
-An automatically-generated construction variable
+An automatically-generated &consvar;
 containing the Fortran compiler command-line options
 for specifying directories to be searched for include
 files and module files.
@@ -2757,7 +2760,7 @@ for module files, as well.
 The prefix used to specify a module directory on the Fortran compiler command
 line.
 This will be prepended to the beginning of the directory
-in the &cv-link-FORTRANMODDIR; construction variables
+in the &cv-link-FORTRANMODDIR; &consvars;
 when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
 </para>
 </listitem>
@@ -2770,7 +2773,7 @@ when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
 The suffix used to specify a module directory on the Fortran compiler command
 line.
 This will be appended to the end of the directory
-in the &cv-link-FORTRANMODDIR; construction variables
+in the &cv-link-FORTRANMODDIR; &consvars;
 when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
 </para>
 </listitem>
@@ -2780,7 +2783,7 @@ when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
       <envar>_FORTRANMODFLAG</envar>
     </term>
     <listitem><para>
-An automatically-generated construction variable
+An automatically-generated &consvar;
 containing the Fortran compiler command-line option
 for specifying the directory location where the Fortran
 compiler should place any module files that happen to get
@@ -2861,11 +2864,11 @@ env = Environment(FORTRANPATH=include)
 The directory list will be added to command lines
 through the automatically-generated
 &cv-link-_FORTRANINCFLAGS;
-construction variable,
+&consvar;,
 which is constructed by
 respectively prepending and appending the values of the
 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
-construction variables
+&consvars;
 to the beginning and end
 of each directory in &cv-link-FORTRANPATH;.
 Any command lines you define that need
@@ -2890,7 +2893,7 @@ By default, any options specified in the &cv-link-FORTRANFLAGS;,
 &cv-link-_CPPDEFFLAGS;,
 &cv-link-_FORTRANMODFLAG;, and
 &cv-link-_FORTRANINCFLAGS;
-construction variables are included on this command line.
+&consvars; are included on this command line.
 </para>
 </listitem>
   </varlistentry>
@@ -3551,15 +3554,6 @@ env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
                 <filename>;</filename>
                 on Windows).
             </para>
-
-            <para>
-                Note that this currently just adds the specified
-                directory via the <option>-classpath</option> option.
-                &SCons; does not currently search the
-                &cv-JAVACLASSPATH; directories for dependency
-                <filename>.class</filename>
-                files.
-            </para>
         </listitem>
   </varlistentry>
   <varlistentry id="cv-JAVACLASSSUFFIX">
@@ -4687,6 +4681,100 @@ will be compiled separately.
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-MSVC_NOTFOUND_POLICY">
+    <term>
+      <envar>MSVC_NOTFOUND_POLICY</envar>
+    </term>
+    <listitem><para>
+Specify the scons behavior when the Microsoft Visual C/C++ compiler is not detected.
+</para>
+
+<para>
+    The <envar>MSVC_NOTFOUND_POLICY</envar> specifies the &scons; behavior when no msvc versions are detected or
+    when the requested msvc version is not detected.
+</para>
+
+<para> 
+The valid values for <envar>MSVC_NOTFOUND_POLICY</envar> and the corresponding &scons; behavior are:
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term><parameter>'Error' or 'Exception'</parameter></term>
+<listitem>
+<para>
+Raise an exception when no msvc versions are detected or when the requested msvc version is not detected.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>'Warning' or 'Warn'</parameter></term>
+<listitem>
+<para>
+Issue a warning and continue when no msvc versions are detected or when the requested msvc version is not detected.
+Depending on usage, this could result in build failure(s).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>'Ignore' or 'Suppress'</parameter></term>
+<listitem>
+<para>
+Take no action and continue when no msvc versions are detected or when the requested msvc version is not detected.
+Depending on usage, this could result in build failure(s).
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>
+Note: in addition to the camel case values shown above, lower case and upper case values are accepted as well.
+</para>
+
+<para>
+The <envar>MSVC_NOTFOUND_POLICY</envar> is applied when any of the following conditions are satisfied:
+<itemizedlist>
+<listitem><para>
+&cv-MSVC_VERSION; is specified, the default tools list is implicitly defined (i.e., the tools list is not specified),
+and the default tools list contains one or more of the msvc tools.
+</para></listitem>
+<listitem><para>
+&cv-MSVC_VERSION; is specified, the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>),
+and the default tools list contains one or more of the msvc tools.
+</para></listitem>
+<listitem><para>
+A non-default tools list is specified that contains one or more of the msvc tools (e.g., <literal>tools=['msvc', 'mslink']</literal>).
+</para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+The <envar>MSVC_NOTFOUND_POLICY</envar> is ignored when any of the following conditions are satisfied:
+<itemizedlist>
+<listitem><para>
+&cv-MSVC_VERSION; is not specified and the default tools list is implicitly defined (i.e., the tools list is not specified).
+</para></listitem>
+<listitem><para>
+&cv-MSVC_VERSION; is not specified and the default tools list is explicitly specified (e.g., <literal>tools=['default']</literal>).
+</para></listitem>
+<listitem><para>
+A non-default tool list is specified that does not contain any of the msvc tools (e.g., <literal>tools=['mingw']</literal>).
+</para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+When <envar>MSVC_NOTFOUND_POLICY</envar> is not specified, the default &scons; behavior is to issue a warning and continue
+subject to the conditions listed above. The default &scons; behavior may change in the future.
+</para>
+
+
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-MSVC_USE_SCRIPT">
     <term>
       <envar>MSVC_USE_SCRIPT</envar>
@@ -4705,6 +4793,7 @@ and extract the relevant variables from the result (typically
 <envar>%PATH%</envar>) for supplying to the build.
 This can be useful to force the use of a compiler version that
 &SCons; does not detect.
+&cv-link-MSVC_USE_SCRIPT_ARGS; provides arguments passed to this script.
 </para>
 
 <para>
@@ -4721,6 +4810,82 @@ you don't want &SCons; to change anything.
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-MSVC_USE_SCRIPT_ARGS">
+    <term>
+      <envar>MSVC_USE_SCRIPT_ARGS</envar>
+    </term>
+    <listitem><para>
+Provides arguments passed to the script &cv-link-MSVC_USE_SCRIPT;.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="cv-MSVC_USE_SETTINGS">
+    <term>
+      <envar>MSVC_USE_SETTINGS</envar>
+    </term>
+    <listitem><para>
+Use a dictionary to set up the Microsoft Visual C++ compiler.
+</para>
+
+<para>
+&cv-MSVC_USE_SETTINGS; is ignored when &cv-link-MSVC_USE_SCRIPT; is defined
+and/or when &cv-MSVC_USE_SETTINGS; is set to <constant>None</constant>.
+</para>
+
+<para>
+The dictionary is used to populate the environment with the relevant variables
+(typically <envar>%INCLUDE%</envar>, <envar>%LIB%</envar>, and <envar>%PATH%</envar>)
+for supplying to the build. This can be useful to force the use of a compiler environment
+that &SCons; does not configure correctly. This is an alternative to manually configuring
+the environment when bypassing Visual Studio autodetection entirely by setting
+&cv-link-MSVC_USE_SCRIPT; to <constant>None</constant>.
+</para>
+
+<para>
+Here is an example of configuring a build environment using the Microsoft Visual C/C++ compiler
+included in the Microsoft SDK on a 64-bit host and building for a 64-bit architecture:
+<programlisting>
+# Microsoft SDK 6.0 (MSVC 8.0): 64-bit host and 64-bit target
+msvc_use_settings = {
+    "PATH": [
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Bin\\x64",
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin\\x64",
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin",
+        "C:\\Windows\\Microsoft.NET\\Framework\\v2.0.50727",
+        "C:\\Windows\\system32",
+        "C:\\Windows",
+        "C:\\Windows\\System32\\Wbem",
+        "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\"
+    ],
+    "INCLUDE": [
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include",
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include\\Sys",
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include",
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include\\gl",
+    ],
+    "LIB": [
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Lib\\x64",
+        "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Lib\\x64",
+    ],
+    "LIBPATH": [],
+    "VSCMD_ARG_app_plat": [],
+    "VCINSTALLDIR": [],
+    "VCToolsInstallDir": []
+}
+
+# Specifying MSVC_VERSION is recommended
+env = Environment(MSVC_VERSION='8.0', MSVC_USE_SETTINGS=msvc_use_settings)
+</programlisting>
+</para>
+
+<para>
+Note: the dictionary content requirements are based on the internal msvc implementation and
+therefore may change at any time. The burden is on the user to ensure the dictionary contents
+are minimally sufficient to ensure successful builds.
+</para>
+
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-MSVC_UWP_APP">
     <term>
       <envar>MSVC_UWP_APP</envar>
@@ -5190,23 +5355,55 @@ Specfies the name of the project to package.
       <envar>NINJA_ALIAS_NAME</envar>
     </term>
     <listitem><para>
-                Name of the Alias() which is will cause SCons to create the <filename>ninja.build</filename> file, and
-                then (optionally) run ninja.
+                The name of the alias target which will cause &SCons; to create the &ninja; build file,
+                and then (optionally) run &ninja;.
+                The default value is <literal>generate-ninja</literal>.
             </para>
         </listitem>
   </varlistentry>
+  <varlistentry id="cv-NINJA_CMD_ARGS">
+    <term>
+      <envar>NINJA_CMD_ARGS</envar>
+    </term>
+    <listitem><para>
+                A string which will pass arguments through SCons to the ninja command when scons executes ninja.
+                Has no effect if &cv-NINJA_DISABLE_AUTO_RUN; is set.
+            </para>
+            <para>
+                This value can also be passed on the command line:
+            </para>
+            <example_commands>
+scons NINJA_CMD_ARGS=-v
+or
+scons NINJA_CMD_ARGS="-v -j 3"
+            </example_commands>
+        </listitem>
+  </varlistentry>
   <varlistentry id="cv-NINJA_COMPDB_EXPAND">
     <term>
       <envar>NINJA_COMPDB_EXPAND</envar>
     </term>
     <listitem><para>
-                Boolean value (True|False) to instruct ninja to expand the command line arguments normally put into
+                Boolean value to instruct &ninja; to expand the command line arguments normally put into
                 response files.
-                This prevents lines in the compilation database like <quote>gcc @rsp_file</quote> and instead yields
-                <quote>gcc -c -o myfile.o myfile.c -Ia -DXYZ</quote>
+                If true, prevents unexpanded lines in the compilation database like
+                <quote><literal>gcc @rsp_file</literal></quote> and instead yields expanded lines like
+                <quote><literal>gcc -c -o myfile.o myfile.c -Ia -DXYZ</literal></quote>.
             </para>
             <para>
-                Ninja's compdb tool added the <quote>-x</quote> flag in Ninja V1.9.0
+                Ninja's compdb tool added the <option>-x</option> flag in Ninja V1.9.0
+            </para>
+        </listitem>
+  </varlistentry>
+  <varlistentry id="cv-NINJA_DEPFILE_PARSE_FORMAT">
+    <term>
+      <envar>NINJA_DEPFILE_PARSE_FORMAT</envar>
+    </term>
+    <listitem><para>
+                Determines the type of format ninja should expect when parsing header
+                include depfiles. Can be <option>msvc</option>, <option>gcc</option>, or <option>clang</option>.
+                The <option>msvc</option> option corresponds to <option>/showIncludes</option> format, and 
+                <option>gcc</option> or <option>clang</option> correspond to <option>-MMD -MF</option>.
             </para>
         </listitem>
   </varlistentry>
@@ -5215,15 +5412,14 @@ Specfies the name of the project to package.
       <envar>NINJA_DIR</envar>
     </term>
     <listitem><para>
-                This propagates directly into the generated <filename>ninja.build</filename> file.
+                The <parameter>builddir</parameter> value.
+                Propagates directly into the generated &ninja; build file.
                 From Ninja's docs:
-                <blockquote>
-                    <para>
-                        builddir
-                        A directory for some Ninja output files. ... (You can also store other build output in this
-                        directory.)
-                    </para>
-                </blockquote>
+                <quote>
+                    A directory for some Ninja output files. ... (You can also store other build output in this
+                    directory.)
+                </quote>
+            The default value is <filename>.ninja</filename>.
             </para>
         </listitem>
   </varlistentry>
@@ -5232,11 +5428,14 @@ Specfies the name of the project to package.
       <envar>NINJA_DISABLE_AUTO_RUN</envar>
     </term>
     <listitem><para>
-                Boolean (True|False). Default: False
-                When True, SCons will not run ninja automatically after creating the <filename>ninja.build</filename> file.
+                Boolean. Default: <constant>False</constant>.
+                If true, &SCons; will not run &ninja; automatically after creating the &ninja; build file.
+            </para>
 
-                If not set, this will be set to True if <quote>--disable_execute_ninja</quote> or
-                <code>SetOption('disable_execute_ninja', True)</code>
+            <para>
+                If not explicitly set, this will be set to <constant>True</constant>
+                if <option>--disable_execute_ninja</option> or
+                <code>SetOption('disable_execute_ninja', True)</code> is seen.
             </para>
         </listitem>
   </varlistentry>
@@ -5246,12 +5445,17 @@ Specfies the name of the project to package.
     </term>
     <listitem><para>
                 A string that sets the environment for any environment variables that
-                differ between the OS environment and the SCons command ENV.
+                differ between the OS environment and the &SCons; execution environment.
+            </para>
 
+            <para>
                 It will be compatible with the default shell of the operating system.
+            </para>
 
-                If not explicitly specified, SCons will generate this dynamically from the Environment()'s 'ENV'
-                <quote>env['ENV']</quote>
+            <para>
+                If not explicitly set, &SCons; will generate this dynamically from the
+                execution environment stored in the current &consenv;
+                (e.g. <literal>env['ENV']</literal>)
                 where those values differ from the existing shell..
             </para>
         </listitem>
@@ -5261,8 +5465,8 @@ Specfies the name of the project to package.
       <envar>NINJA_FILE_NAME</envar>
     </term>
     <listitem><para>
-                The filename for the generated Ninja build file defaults to
-                <filename>ninja.build</filename>
+                The filename for the generated Ninja build file.
+                The default is <filename>ninja.build</filename>.
             </para>
         </listitem>
   </varlistentry>
@@ -5271,9 +5475,21 @@ Specfies the name of the project to package.
       <envar>NINJA_FORCE_SCONS_BUILD</envar>
     </term>
     <listitem><para>
-                When NINJA_FORCE_SCONS_BUILD is True, this will cause the build nodes to callback to scons instead of using
-                ninja to build them. This is intended to be passed to the environment on the builder invocation.
-                It is useful if you have a build node which does something which is not easily translated into ninja.
+                If true, causes the build nodes to callback to scons instead of using
+                &ninja; to build them. This is intended to be passed to the environment on the builder invocation.
+                It is useful if you have a build node which does something which is not easily translated into &ninja;.
+            </para>
+        </listitem>
+  </varlistentry>
+  <varlistentry id="cv-NINJA_GENERATED_SOURCE_ALIAS_NAME">
+    <term>
+      <envar>NINJA_GENERATED_SOURCE_ALIAS_NAME</envar>
+    </term>
+    <listitem><para>
+                A string matching the name of a user defined alias which represents a list of all generated sources.
+                This will prevent the auto-detection of generated sources from &cv-NINJA_GENERATED_SOURCE_SUFFIXES;.
+                Then all other source files will be made to depend on this in the &ninja; build file, forcing the
+                generated sources to be built first.
             </para>
         </listitem>
   </varlistentry>
@@ -5282,10 +5498,10 @@ Specfies the name of the project to package.
       <envar>NINJA_GENERATED_SOURCE_SUFFIXES</envar>
     </term>
     <listitem><para>
-                The list of source file suffixes which are generated by SCons build steps.
+                The list of source file suffixes which are generated by &SCons; build steps.
                 All source files which match these suffixes will be added to the _generated_sources alias in the output
-                <filename>ninja.build</filename> file.
-                Then all other source files will be made to depend on this in the <filename>ninja.build</filename> file, forcing the
+                &ninja; build file.
+                Then all other source files will be made to depend on this in the &ninja; build file, forcing the
                 generated sources to be built first.
             </para>
         </listitem>
@@ -5295,9 +5511,10 @@ Specfies the name of the project to package.
       <envar>NINJA_MSVC_DEPS_PREFIX</envar>
     </term>
     <listitem><para>
-                This propagates directly into the generated <filename>ninja.build</filename> file.
-                From Ninja's docs
-                <quote>defines the string which should be stripped from msvc’s /showIncludes output</quote>
+                The <parameter>msvc_deps_prefix</parameter> string.
+                Propagates directly into the generated &ninja; build file.
+                From Ninja's docs:
+                <quote>defines the string which should be stripped from msvc's <option>/showIncludes</option> output</quote>
             </para>
         </listitem>
   </varlistentry>
@@ -5306,7 +5523,7 @@ Specfies the name of the project to package.
       <envar>NINJA_POOL</envar>
     </term>
     <listitem><para>
-                Set the <quote>ninja_pool</quote> for this or all targets in scope for this env var.
+                Set the <parameter>ninja_pool</parameter> for this or all targets in scope for this env var.
             </para>
         </listitem>
   </varlistentry>
@@ -5315,8 +5532,9 @@ Specfies the name of the project to package.
       <envar>NINJA_REGENERATE_DEPS</envar>
     </term>
     <listitem><para>
-                A generator function used to create a ninja depsfile which includes all the files which would require
-                SCons to be invoked if they change.
+                A generator function used to create a &ninja; depfile which
+                includes all the files which would require
+                &SCons; to be invoked if they change.
                 Or a list of said files.
             </para>
         </listitem>
@@ -5327,7 +5545,28 @@ Specfies the name of the project to package.
     </term>
     <listitem><para>
                 Internal value used to specify the function to call with argument env to generate the list of files
-                which if changed would require the ninja file to be regenerated.
+                which if changed would require the &ninja; build file to be regenerated.
+            </para>
+        </listitem>
+  </varlistentry>
+  <varlistentry id="cv-NINJA_SCONS_DAEMON_KEEP_ALIVE">
+    <term>
+      <envar>NINJA_SCONS_DAEMON_KEEP_ALIVE</envar>
+    </term>
+    <listitem><para>
+                The number of seconds for the SCons deamon launched by ninja to stay alive.
+                (Default: 180000)
+            </para>
+        </listitem>
+  </varlistentry>
+  <varlistentry id="cv-NINJA_SCONS_DAEMON_PORT">
+    <term>
+      <envar>NINJA_SCONS_DAEMON_PORT</envar>
+    </term>
+    <listitem><para>
+                The TCP/IP port for the SCons daemon to listen on.
+                <emphasis>NOTE: You cannot use a port already being listened to on your build machine.</emphasis>
+                (Default: random number between 10000,60000)
             </para>
         </listitem>
   </varlistentry>
@@ -5336,9 +5575,9 @@ Specfies the name of the project to package.
       <envar>NINJA_SYNTAX</envar>
     </term>
     <listitem><para>
-                Theres also NINJA_SYNTAX which is the path to a custom ninja_syntax.py file which is used in generation.
-                The tool currently assumes you have ninja installed through pip, and grabs the syntax file from that
-                installation if none specified.
+                The path to a custom <filename>ninja_syntax.py</filename> file which is used in generation.
+                The tool currently assumes you have &ninja; installed as a &Python; module and grabs the syntax file from that
+                installation if &cv-NINJA_SYNTAX; is not explicitly set.
             </para>
         </listitem>
   </varlistentry>
@@ -6751,6 +6990,56 @@ construction variable for more information.
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-SHELL_ENV_GENERATORS">
+    <term>
+      <envar>SHELL_ENV_GENERATORS</envar>
+    </term>
+    <listitem><para>
+Must be a list (or an iterable) containing functions where each function generates or
+alters the environment dictionary which will be used
+when executing the &cv-link-SPAWN; function. The functions will initially 
+be passed a reference of the current execution environment (e.g. env['ENV']), 
+and each called while iterating the list. Each function must return a dictionary
+which will then be passed to the next function iterated. The return dictionary 
+should contain keys which represent the environment variables and their respective
+values.
+
+This primary purpose of this construction variable is to give the user the ability
+to substitute execution environment variables based on env, targets, and sources. 
+If desired, the user can completely customize the execution environment for particular
+targets.
+    </para>
+
+    <example_commands>
+def custom_shell_env(env, target, source, shell_env):
+    """customize shell_env if desired"""
+    if str(target[0]) == 'special_target':
+      shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=target, source=source)
+    return shell_env
+  
+env["SHELL_ENV_GENERATORS"] = [custom_shell_env]
+    </example_commands>
+
+    <para>
+      <varname>env</varname>
+The SCons construction environment from which the
+execution environment can be derived from.
+    </para>
+    <para>
+    <varname>target</varname>
+The list of targets associated with this action.
+    </para>
+    <para>
+    <varname>source</varname>
+The list of sources associated with this action.
+    </para>
+    <para>
+    <varname>shell_env</varname>
+The current shell_env after iterating other SHELL_ENV_GENERATORS functions. This can be compared
+to the passed env['ENV'] to detect any changes.
+    </para>
+  </listitem>
+  </varlistentry>
   <varlistentry id="cv-SHF03">
     <term>
       <envar>SHF03</envar>
@@ -7207,6 +7496,12 @@ The default Fortran compiler used for generating shared-library objects.
     <listitem><para>
 The command line used to compile a Fortran source file
 to a shared-library object file.
+By default, any options specified
+in the &cv-link-SHFORTRANFLAGS;,
+&cv-link-_FORTRANMODFLAG;, and
+&cv-link-_FORTRANINCFLAGS;
+&consvars; are included on this command line.
+See also &cv-link-FORTRANCOM;.
 </para>
 </listitem>
   </varlistentry>
@@ -7240,10 +7535,13 @@ to generate shared-library objects.
 The command line used to compile a Fortran source file to a
 shared-library object file
 after first running the file through the C preprocessor.
-Any options specified
-in the &cv-link-SHFORTRANFLAGS; and
-&cv-link-CPPFLAGS; construction variables
-are included on this command line.
+By default, any options specified in the &cv-link-SHFORTRANFLAGS;,
+&cv-link-CPPFLAGS;,
+&cv-link-_CPPDEFFLAGS;,
+&cv-link-_FORTRANMODFLAG;, and
+&cv-link-_FORTRANINCFLAGS;
+&consvars; are included on this command line.
+See also &cv-link-SHFORTRANCOM;.
 </para>
 </listitem>
   </varlistentry>
@@ -7604,7 +7902,7 @@ field in MSI packages.
       <envar>SWIG</envar>
     </term>
     <listitem><para>
-The scripting language wrapper and interface generator.
+The name of the &swig; compiler to use.
 </para>
 </listitem>
   </varlistentry>
@@ -7614,10 +7912,11 @@ The scripting language wrapper and interface generator.
     </term>
     <listitem><para>
 The suffix that will be used for intermediate C
-source files generated by
-the scripting language wrapper and interface generator.
-The default value is
-<filename>_wrap</filename>&cv-link-CFILESUFFIX;.
+source files generated by &swig;.
+The default value is <literal>'_wrap$CFILESUFFIX'</literal> -
+that is, the concatenation of the string
+<literal>_wrap</literal>
+and the current C suffix &cv-link-CFILESUFFIX;.
 By default, this value is used whenever the
 <option>-c++</option>
 option is
@@ -7633,8 +7932,7 @@ construction variable.
       <envar>SWIGCOM</envar>
     </term>
     <listitem><para>
-The command line used to call
-the scripting language wrapper and interface generator.
+The command line used to call &swig;.
 </para>
 </listitem>
   </varlistentry>
@@ -7643,8 +7941,7 @@ the scripting language wrapper and interface generator.
       <envar>SWIGCOMSTR</envar>
     </term>
     <listitem><para>
-The string displayed when calling
-the scripting language wrapper and interface generator.
+The string displayed when calling &swig;.
 If this is not set, then &cv-link-SWIGCOM; (the command line) is displayed.
 </para>
 </listitem>
@@ -7655,12 +7952,13 @@ If this is not set, then &cv-link-SWIGCOM; (the command line) is displayed.
     </term>
     <listitem><para>
 The suffix that will be used for intermediate C++
-source files generated by
-the scripting language wrapper and interface generator.
-The default value is
-<filename>_wrap</filename>&cv-link-CFILESUFFIX;.
+source files generated by &swig;.
+The default value is <literal>'_wrap$CXXFILESUFFIX'</literal> -
+that is, the concatenation of the string
+<literal>_wrap</literal>
+and the current C++ suffix &cv-link-CXXFILESUFFIX;.
 By default, this value is used whenever the
-<filename>-c++</filename>
+<option>-c++</option>
 option is specified as part of the
 &cv-link-SWIGFLAGS;
 construction variable.
@@ -7673,8 +7971,8 @@ construction variable.
     </term>
     <listitem><para>
 The suffix that will be used for intermediate C++ header
-files generated by the scripting language wrapper and interface generator.
-These are only generated for C++ code when the SWIG 'directors' feature is
+files generated by &swig;.
+These are only generated for C++ code when the &swig; 'directors' feature is
 turned on.
 The default value is
 <filename>_wrap.h</filename>.
@@ -7686,22 +7984,14 @@ The default value is
       <envar>SWIGFLAGS</envar>
     </term>
     <listitem><para>
-General options passed to
-the scripting language wrapper and interface generator.
-This is where you should set
-<option>-python</option>,
+General options passed to &swig;.
+This is where you should set the target language
+(<option>-python</option>,
 <option>-perl5</option>,
-<option>-tcl</option>,
-or whatever other options you want to specify to SWIG.
-If you set the
-<option>-c++</option>
-option in this variable,
-&scons;
-will, by default,
-generate a C++ intermediate source file
-with the extension that is specified as the
-&cv-link-CXXFILESUFFIX;
-variable.
+<option>-tcl</option>, etc.)
+and whatever other options you want to specify to &swig;,
+such as the <option>-c++</option> to generate C++ code
+instead of C Code.
 </para>
 </listitem>
   </varlistentry>
@@ -7711,7 +8001,7 @@ variable.
     </term>
     <listitem><para>
 An automatically-generated construction variable
-containing the SWIG command-line options
+containing the &swig; command-line options
 for specifying directories to be searched for included files.
 The value of &cv-_SWIGINCFLAGS; is created
 by respectively prepending and appending
@@ -7726,7 +8016,7 @@ of each directory in &cv-SWIGPATH;.
       <envar>SWIGINCPREFIX</envar>
     </term>
     <listitem><para>
-The prefix used to specify an include directory on the SWIG command line.
+The prefix used to specify an include directory on the &swig; command line.
 This will be prepended to the beginning of each directory
 in the &cv-SWIGPATH; construction variable
 when the &cv-_SWIGINCFLAGS; variable is automatically generated.
@@ -7738,7 +8028,7 @@ when the &cv-_SWIGINCFLAGS; variable is automatically generated.
       <envar>SWIGINCSUFFIX</envar>
     </term>
     <listitem><para>
-The suffix used to specify an include directory on the SWIG command line.
+The suffix used to specify an include directory on the &swig; command line.
 This will be appended to the end of each directory
 in the &cv-SWIGPATH; construction variable
 when the &cv-_SWIGINCFLAGS; variable is automatically generated.
@@ -7750,8 +8040,7 @@ when the &cv-_SWIGINCFLAGS; variable is automatically generated.
       <envar>SWIGOUTDIR</envar>
     </term>
     <listitem><para>
-Specifies the output directory in which
-the scripting language wrapper and interface generator
+Specifies the output directory in which &swig;
 should place generated language-specific files.
 This will be used by SCons to identify
 the files that will be generated by the &swig; call,
@@ -7765,22 +8054,24 @@ and translated into the
       <envar>SWIGPATH</envar>
     </term>
     <listitem><para>
-The list of directories that the scripting language wrapper
-and interface generate will search for included files.
-The SWIG implicit dependency scanner will search these
+The list of directories that &swig;
+will search for included files.
+&SCons;' SWIG implicit dependency scanner will search these
 directories for include files. The default value is an empty list.
 </para>
 
 <para>
 Don't explicitly put include directory
-arguments in SWIGFLAGS;
+arguments in &cv-link-SWIGFLAGS;
 the result will be non-portable
 and the directories will not be searched by the dependency scanner.
-Note: directory names in SWIGPATH will be looked-up relative to the SConscript
+Note: directory names in &cv-link-SWIGPATH;
+will be looked-up relative to the SConscript
 directory when they are used in a command.
 To force
 &scons;
-to look-up a directory relative to the root of the source tree use #:
+to look-up a directory relative to the root of the source tree use
+a top-relative path (<literal>#</literal>):
 </para>
 
 <example_commands>
@@ -7824,7 +8115,7 @@ env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
       <envar>SWIGVERSION</envar>
     </term>
     <listitem><para>
-The version number of the SWIG tool.
+The detected version string of the &swig; tool.
 </para>
 </listitem>
   </varlistentry>
diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod
index cd4e2a4..c5cd0cd 100644
--- a/doc/generated/variables.mod
+++ b/doc/generated/variables.mod
@@ -9,7 +9,6 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 -->
 
 <!ENTITY cv-__LDMODULEVERSIONFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$__LDMODULEVERSIONFLAGS</envar>">
-<!ENTITY cv-__NINJA_NO "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$__NINJA_NO</envar>">
 <!ENTITY cv-__SHLIBVERSIONFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$__SHLIBVERSIONFLAGS</envar>">
 <!ENTITY cv-APPLELINK_COMPATIBILITY_VERSION "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$APPLELINK_COMPATIBILITY_VERSION</envar>">
 <!ENTITY cv-_APPLELINK_COMPATIBILITY_VERSION "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$_APPLELINK_COMPATIBILITY_VERSION</envar>">
@@ -38,6 +37,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-CC "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$CC</envar>">
 <!ENTITY cv-CCCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$CCCOM</envar>">
 <!ENTITY cv-CCCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$CCCOMSTR</envar>">
+<!ENTITY cv-CCDEPFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$CCDEPFLAGS</envar>">
 <!ENTITY cv-CCFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$CCFLAGS</envar>">
 <!ENTITY cv-CCPCHFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$CCPCHFLAGS</envar>">
 <!ENTITY cv-CCPDBFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$CCPDBFLAGS</envar>">
@@ -320,7 +320,10 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-MSSDK_DIR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSSDK_DIR</envar>">
 <!ENTITY cv-MSSDK_VERSION "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSSDK_VERSION</envar>">
 <!ENTITY cv-MSVC_BATCH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_BATCH</envar>">
+<!ENTITY cv-MSVC_NOTFOUND_POLICY "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_NOTFOUND_POLICY</envar>">
 <!ENTITY cv-MSVC_USE_SCRIPT "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_USE_SCRIPT</envar>">
+<!ENTITY cv-MSVC_USE_SCRIPT_ARGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_USE_SCRIPT_ARGS</envar>">
+<!ENTITY cv-MSVC_USE_SETTINGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_USE_SETTINGS</envar>">
 <!ENTITY cv-MSVC_UWP_APP "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_UWP_APP</envar>">
 <!ENTITY cv-MSVC_VERSION "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_VERSION</envar>">
 <!ENTITY cv-MSVS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVS</envar>">
@@ -351,17 +354,22 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-MWCW_VERSIONS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MWCW_VERSIONS</envar>">
 <!ENTITY cv-NAME "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NAME</envar>">
 <!ENTITY cv-NINJA_ALIAS_NAME "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_ALIAS_NAME</envar>">
+<!ENTITY cv-NINJA_CMD_ARGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_CMD_ARGS</envar>">
 <!ENTITY cv-NINJA_COMPDB_EXPAND "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_COMPDB_EXPAND</envar>">
+<!ENTITY cv-NINJA_DEPFILE_PARSE_FORMAT "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_DEPFILE_PARSE_FORMAT</envar>">
 <!ENTITY cv-NINJA_DIR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_DIR</envar>">
 <!ENTITY cv-NINJA_DISABLE_AUTO_RUN "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_DISABLE_AUTO_RUN</envar>">
 <!ENTITY cv-NINJA_ENV_VAR_CACHE "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_ENV_VAR_CACHE</envar>">
 <!ENTITY cv-NINJA_FILE_NAME "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_FILE_NAME</envar>">
 <!ENTITY cv-NINJA_FORCE_SCONS_BUILD "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_FORCE_SCONS_BUILD</envar>">
+<!ENTITY cv-NINJA_GENERATED_SOURCE_ALIAS_NAME "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_GENERATED_SOURCE_ALIAS_NAME</envar>">
 <!ENTITY cv-NINJA_GENERATED_SOURCE_SUFFIXES "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_GENERATED_SOURCE_SUFFIXES</envar>">
 <!ENTITY cv-NINJA_MSVC_DEPS_PREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_MSVC_DEPS_PREFIX</envar>">
 <!ENTITY cv-NINJA_POOL "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_POOL</envar>">
 <!ENTITY cv-NINJA_REGENERATE_DEPS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_REGENERATE_DEPS</envar>">
 <!ENTITY cv-_NINJA_REGENERATE_DEPS_FUNC "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$_NINJA_REGENERATE_DEPS_FUNC</envar>">
+<!ENTITY cv-NINJA_SCONS_DAEMON_KEEP_ALIVE "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_SCONS_DAEMON_KEEP_ALIVE</envar>">
+<!ENTITY cv-NINJA_SCONS_DAEMON_PORT "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_SCONS_DAEMON_PORT</envar>">
 <!ENTITY cv-NINJA_SYNTAX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$NINJA_SYNTAX</envar>">
 <!ENTITY cv-no_import_lib "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$no_import_lib</envar>">
 <!ENTITY cv-OBJPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$OBJPREFIX</envar>">
@@ -480,6 +488,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-SHDLINKCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$SHDLINKCOM</envar>">
 <!ENTITY cv-SHDLINKFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$SHDLINKFLAGS</envar>">
 <!ENTITY cv-SHELL "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$SHELL</envar>">
+<!ENTITY cv-SHELL_ENV_GENERATORS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$SHELL_ENV_GENERATORS</envar>">
 <!ENTITY cv-SHF03 "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$SHF03</envar>">
 <!ENTITY cv-SHF03COM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$SHF03COM</envar>">
 <!ENTITY cv-SHF03COMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$SHF03COMSTR</envar>">
@@ -664,7 +673,6 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 -->
 
 <!ENTITY cv-link-__LDMODULEVERSIONFLAGS "<link linkend='cv-__LDMODULEVERSIONFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$__LDMODULEVERSIONFLAGS</envar></link>">
-<!ENTITY cv-link-__NINJA_NO "<link linkend='cv-__NINJA_NO' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$__NINJA_NO</envar></link>">
 <!ENTITY cv-link-__SHLIBVERSIONFLAGS "<link linkend='cv-__SHLIBVERSIONFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$__SHLIBVERSIONFLAGS</envar></link>">
 <!ENTITY cv-link-APPLELINK_COMPATIBILITY_VERSION "<link linkend='cv-APPLELINK_COMPATIBILITY_VERSION' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$APPLELINK_COMPATIBILITY_VERSION</envar></link>">
 <!ENTITY cv-link-_APPLELINK_COMPATIBILITY_VERSION "<link linkend='cv-_APPLELINK_COMPATIBILITY_VERSION' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$_APPLELINK_COMPATIBILITY_VERSION</envar></link>">
@@ -693,6 +701,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-link-CC "<link linkend='cv-CC' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$CC</envar></link>">
 <!ENTITY cv-link-CCCOM "<link linkend='cv-CCCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$CCCOM</envar></link>">
 <!ENTITY cv-link-CCCOMSTR "<link linkend='cv-CCCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$CCCOMSTR</envar></link>">
+<!ENTITY cv-link-CCDEPFLAGS "<link linkend='cv-CCDEPFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$CCDEPFLAGS</envar></link>">
 <!ENTITY cv-link-CCFLAGS "<link linkend='cv-CCFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$CCFLAGS</envar></link>">
 <!ENTITY cv-link-CCPCHFLAGS "<link linkend='cv-CCPCHFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$CCPCHFLAGS</envar></link>">
 <!ENTITY cv-link-CCPDBFLAGS "<link linkend='cv-CCPDBFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$CCPDBFLAGS</envar></link>">
@@ -975,7 +984,10 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-link-MSSDK_DIR "<link linkend='cv-MSSDK_DIR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSSDK_DIR</envar></link>">
 <!ENTITY cv-link-MSSDK_VERSION "<link linkend='cv-MSSDK_VERSION' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSSDK_VERSION</envar></link>">
 <!ENTITY cv-link-MSVC_BATCH "<link linkend='cv-MSVC_BATCH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_BATCH</envar></link>">
+<!ENTITY cv-link-MSVC_NOTFOUND_POLICY "<link linkend='cv-MSVC_NOTFOUND_POLICY' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_NOTFOUND_POLICY</envar></link>">
 <!ENTITY cv-link-MSVC_USE_SCRIPT "<link linkend='cv-MSVC_USE_SCRIPT' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_USE_SCRIPT</envar></link>">
+<!ENTITY cv-link-MSVC_USE_SCRIPT_ARGS "<link linkend='cv-MSVC_USE_SCRIPT_ARGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_USE_SCRIPT_ARGS</envar></link>">
+<!ENTITY cv-link-MSVC_USE_SETTINGS "<link linkend='cv-MSVC_USE_SETTINGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_USE_SETTINGS</envar></link>">
 <!ENTITY cv-link-MSVC_UWP_APP "<link linkend='cv-MSVC_UWP_APP' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_UWP_APP</envar></link>">
 <!ENTITY cv-link-MSVC_VERSION "<link linkend='cv-MSVC_VERSION' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_VERSION</envar></link>">
 <!ENTITY cv-link-MSVS "<link linkend='cv-MSVS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVS</envar></link>">
@@ -1006,17 +1018,22 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-link-MWCW_VERSIONS "<link linkend='cv-MWCW_VERSIONS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MWCW_VERSIONS</envar></link>">
 <!ENTITY cv-link-NAME "<link linkend='cv-NAME' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NAME</envar></link>">
 <!ENTITY cv-link-NINJA_ALIAS_NAME "<link linkend='cv-NINJA_ALIAS_NAME' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_ALIAS_NAME</envar></link>">
+<!ENTITY cv-link-NINJA_CMD_ARGS "<link linkend='cv-NINJA_CMD_ARGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_CMD_ARGS</envar></link>">
 <!ENTITY cv-link-NINJA_COMPDB_EXPAND "<link linkend='cv-NINJA_COMPDB_EXPAND' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_COMPDB_EXPAND</envar></link>">
+<!ENTITY cv-link-NINJA_DEPFILE_PARSE_FORMAT "<link linkend='cv-NINJA_DEPFILE_PARSE_FORMAT' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_DEPFILE_PARSE_FORMAT</envar></link>">
 <!ENTITY cv-link-NINJA_DIR "<link linkend='cv-NINJA_DIR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_DIR</envar></link>">
 <!ENTITY cv-link-NINJA_DISABLE_AUTO_RUN "<link linkend='cv-NINJA_DISABLE_AUTO_RUN' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_DISABLE_AUTO_RUN</envar></link>">
 <!ENTITY cv-link-NINJA_ENV_VAR_CACHE "<link linkend='cv-NINJA_ENV_VAR_CACHE' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_ENV_VAR_CACHE</envar></link>">
 <!ENTITY cv-link-NINJA_FILE_NAME "<link linkend='cv-NINJA_FILE_NAME' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_FILE_NAME</envar></link>">
 <!ENTITY cv-link-NINJA_FORCE_SCONS_BUILD "<link linkend='cv-NINJA_FORCE_SCONS_BUILD' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_FORCE_SCONS_BUILD</envar></link>">
+<!ENTITY cv-link-NINJA_GENERATED_SOURCE_ALIAS_NAME "<link linkend='cv-NINJA_GENERATED_SOURCE_ALIAS_NAME' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_GENERATED_SOURCE_ALIAS_NAME</envar></link>">
 <!ENTITY cv-link-NINJA_GENERATED_SOURCE_SUFFIXES "<link linkend='cv-NINJA_GENERATED_SOURCE_SUFFIXES' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_GENERATED_SOURCE_SUFFIXES</envar></link>">
 <!ENTITY cv-link-NINJA_MSVC_DEPS_PREFIX "<link linkend='cv-NINJA_MSVC_DEPS_PREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_MSVC_DEPS_PREFIX</envar></link>">
 <!ENTITY cv-link-NINJA_POOL "<link linkend='cv-NINJA_POOL' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_POOL</envar></link>">
 <!ENTITY cv-link-NINJA_REGENERATE_DEPS "<link linkend='cv-NINJA_REGENERATE_DEPS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_REGENERATE_DEPS</envar></link>">
 <!ENTITY cv-link-_NINJA_REGENERATE_DEPS_FUNC "<link linkend='cv-_NINJA_REGENERATE_DEPS_FUNC' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$_NINJA_REGENERATE_DEPS_FUNC</envar></link>">
+<!ENTITY cv-link-NINJA_SCONS_DAEMON_KEEP_ALIVE "<link linkend='cv-NINJA_SCONS_DAEMON_KEEP_ALIVE' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_SCONS_DAEMON_KEEP_ALIVE</envar></link>">
+<!ENTITY cv-link-NINJA_SCONS_DAEMON_PORT "<link linkend='cv-NINJA_SCONS_DAEMON_PORT' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_SCONS_DAEMON_PORT</envar></link>">
 <!ENTITY cv-link-NINJA_SYNTAX "<link linkend='cv-NINJA_SYNTAX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$NINJA_SYNTAX</envar></link>">
 <!ENTITY cv-link-no_import_lib "<link linkend='cv-no_import_lib' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$no_import_lib</envar></link>">
 <!ENTITY cv-link-OBJPREFIX "<link linkend='cv-OBJPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$OBJPREFIX</envar></link>">
@@ -1135,6 +1152,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-link-SHDLINKCOM "<link linkend='cv-SHDLINKCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$SHDLINKCOM</envar></link>">
 <!ENTITY cv-link-SHDLINKFLAGS "<link linkend='cv-SHDLINKFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$SHDLINKFLAGS</envar></link>">
 <!ENTITY cv-link-SHELL "<link linkend='cv-SHELL' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$SHELL</envar></link>">
+<!ENTITY cv-link-SHELL_ENV_GENERATORS "<link linkend='cv-SHELL_ENV_GENERATORS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$SHELL_ENV_GENERATORS</envar></link>">
 <!ENTITY cv-link-SHF03 "<link linkend='cv-SHF03' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$SHF03</envar></link>">
 <!ENTITY cv-link-SHF03COM "<link linkend='cv-SHF03COM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$SHF03COM</envar></link>">
 <!ENTITY cv-link-SHF03COMSTR "<link linkend='cv-SHF03COMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$SHF03COMSTR</envar></link>">
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index a98f4e8..4578d1c 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -5207,7 +5207,7 @@ the dependency graph related to their sources.
 An alias is checked for up to date by checking if
 its sources are up to date.
 An alias is built by making sure its sources have been built,
-and if any building took place, 
+and if any building took place,
 applying any Actions that are defined as part of the alias.
 </para>
 
@@ -7470,7 +7470,7 @@ There are, however, a few portability
 issues waiting to trap the unwary.</para>
 
 <refsect2 id='c_file_suffix'>
-<title>.C file suffix</title>
+<title>.C File Suffix</title>
 
 <para>&scons; handles the upper-case
 <filename>.C</filename>
@@ -7490,50 +7490,125 @@ suffix as a C source file.</para>
 </refsect2>
 
 <refsect2 id='f_file_suffix'>
-<title>Fortran file suffixes</title>
+<title>Fortran File Suffixes</title>
 
-<para>&scons; handles upper-case
-Fortran file suffixes differently
-depending on the capabilities of
-the underlying system.
-On a case-sensitive system
-such as Linux or UNIX,
-&scons; treats a file with a
-<filename>.F</filename>
-as a Fortran source file
-that is to be first run through
-the standard C preprocessor,
-while the lower-case version is not.
-This matches the convention of <command>gfortran</command>,
-which may also be followed by other Fortran compilers.
-This also applies to other naming variants,
+<para>
+There are several ways source file suffixes impact the
+behavior of &SCons; when working with Fortran language code
+(not all are system-specific, but they are included here
+for completeness).
+</para>
+
+<para>
+As the Fortran language has evolved through multiple
+standards editions, projects might have a need to handle
+files from different language generations differently.
+To this end, &SCons; dispatches to  a different compiler
+dialect setup (expressed as a set of &consvars;)
+depending on the file suffix.
+By default, all of these setups start out the same,
+but individual &consvars; can be modified as needed to tune a given dialect.
+Each of these dialacts has a tool specification module
+whose documentation describes the &consvars; associated
+with that dialect: <filename>.f</filename>
+(as well as <filename>.for</filename> and <filename>.ftn</filename>)
+in &t-link-fortran;; (&consvars; start with <literal>FORTRAN</literal>)
+<filename>.f77</filename> in &t-link-f77;;
+(&consvars; start with <literal>F77</literal>)
+<filename>.f90</filename> in &t-link-f90;;
+(&consvars; start with <literal>F90</literal>)
+<filename>.f95</filename> in &t-link-f95;;
+(&consvars; start with <literal>F95</literal>)
+<filename>.f03</filename> in &t-link-f03;;
+(&consvars; start with <literal>F03</literal>)
+<filename>.f08</filename> in &t-link-f08;
+(&consvars; start with <literal>F08</literal>).
+</para>
+
+<para>
+While &SCons; recognizes multiple internal dialects
+based on filename suffixes,
+the convention of various available Fortran compilers is
+to assign an actual meaning to only two of these suffixes:
+<filename>.f</filename>
+(as well as <filename>.for</filename> and <filename>.ftn</filename>)
+refers to the fixed-format source
+code that was the only available option in FORTRAN 77 and earlier,
+and <filename>.f90</filename> refers to free-format source code
+which became available as of the Fortran 90 standard.
+Some compilers recognize suffixes which correspond to Fortran
+specifications later then F90 as equivalent to
+<filename>.f90</filename> for this purpose,
+while some do not - check the documentation for your compiler.
+An occasionally suggested policy suggestion is to use only
+<filename>.f</filename> and <filename>.f90</filename>
+as Fortran filename suffixes.
+The fixed/free form determination can usually be controlled
+explicitly with compiler flags
+(e.g. <option>-ffixed-form</option> for gfortran),
+overriding any assumption that may be made based on the source file suffix.
+</para>
+
+<para>
+The source file suffix does not imply conformance
+with the similarly-named Fortran standard - a suffix of
+<filename>.f08</filename> does not mean you are compiling
+specifically for Fortran 2008.  Normally, compilers
+provide command-line options for making this selection
+(e.g. <option>-std=f2008</option> for gfortran).
+</para>
+
+<para>
+For dialects from F90 on (including the generic FORTRAN dialect),
+a suffix of <filename>.mod</filename> is recognized for Fortran modules.
+These files are a side effect of compiling a Fortran
+source file containing module declarations,
+and must be available when other code which declares
+that it uses the module is processed.
+&SCons; does not currently have integrated support for submodules,
+introduced in the Fortran 2008 standard -
+the invoked compiler will produce results,
+but &SCons; will not recognize
+<filename>.smod</filename> files as tracked objects.
+</para>
+
+<para>
+On a case-sensitive system such as Linux or UNIX,
+a file with a an upper-cased suffix from the set
+<filename>.F</filename>,
 <filename>.FOR</filename>,
 <filename>.FTN</filename>,
 <filename>.F90</filename>,
 <filename>.F95</filename>,
 <filename>.F03</filename> and
-<filename>.F08</filename>;
-files suffixed with
+<filename>.F08</filename>
+is treated as a Fortran source file
+which shall first be run through
+the standard C preprocessor.
+The lower-cased versions of these suffixes do not
+trigger this behavior.
+On systems which do not distinguish between uppper
+and lower case in filenames,
+this behavior is not available,
+but files suffixed with either
 <filename>.FPP</filename>
-and <filename>.fpp</filename>
-are both run through the preprocessor,
-as indicated by the <literal>pp</literal>
-part of the name.
-On a case-insensitive system
-such as Windows,
-&scons; treats a file with a
-<filename>.F</filename>
-suffix as a Fortran source file that should
-<emphasis>not</emphasis>
-be run through the C preprocessor.</para>
+or <filename>.fpp</filename>
+are always passed to the preprocessor first.
+This matches the convention of <command>gfortran</command>
+from the GNU Compiler Collection,
+and also followed by certain other Fortran compilers.
+For these two suffixes,
+the generic <emphasis>FORTRAN</emphasis> dialect will be selected.
+</para>
+
 <para>
-<emphasis>Run through the C preprocessor</emphasis>
-here means that a different set of &consvars; will
-be applied in constructed commands, for example
+&SCons; itself does not invoke the preprocessor,
+that is handled by the compiler,
+but it adds &consvars; which are applicable to the preprocessor run.
+You can see this difference by examining
 &cv-link-FORTRANPPCOM; and &cv-link-FORTRANPPCOMSTR;
-instead of
-&cv-link-FORTRANCOM; and &cv-link-FORTRANCOMSTR;.
-See the Fortran-related &consvars; for more details.
+which are used instead of
+&cv-link-FORTRANCOM; and &cv-link-FORTRANCOMSTR; for that dialect.
 </para>
 </refsect2>
 
@@ -7542,10 +7617,10 @@ See the Fortran-related &consvars; for more details.
 
 <para>Cygwin supplies a set of tools and utilities
 that let users work on a
-Windows system using a more POSIX-like environment.
-The Cygwin tools, including Cygwin Python,
+Windows system using a POSIX-like environment.
+The Cygwin tools, including Cygwin &Python;,
 do this, in part,
-by sharing an ability to interpret UNIX-like path names.
+by sharing an ability to interpret POSIX-style path names.
 For example, the Cygwin tools
 will internally translate a Cygwin path name
 like <filename>/cygdrive/c/mydir</filename>
@@ -7553,11 +7628,11 @@ to an equivalent Windows pathname
 of <filename>C:/mydir</filename> (equivalent to <filename>C:\mydir</filename>).
 </para>
 
-<para>Versions of Python
+<para>Versions of &Python;
 that are built for native Windows execution,
 such as the python.org and ActiveState versions,
-do not have the Cygwin path name semantics.
-This means that using a native Windows version of Python
+do not understand the Cygwin path name semantics.
+This means that using a native Windows version of &Python;
 to build compiled programs using Cygwin tools
 (such as &gcc;, &bison; and &flex;)
 may yield unpredictable results.
@@ -7567,14 +7642,22 @@ but it requires careful attention to the use of path names
 in your SConscript files.</para>
 
 <para>In practice, users can sidestep
-the issue by adopting the following rules:
+the issue by adopting the following guidelines:
 When using Cygwin's &gcc; for compiling,
-use the Cygwin-supplied Python interpreter
+use the Cygwin-supplied &Python; interpreter
 to run &scons;;
 when using Microsoft Visual C/C++
-(or some other Windows compiler)
-use the python.org or Microsoft Store or ActiveState version of Python
-to run &scons;.</para>
+(or some other "native" Windows compiler)
+use the python.org, Microsoft Store, ActiveState or other
+native version of &Python; to run &scons;.
+</para>
+
+<para>
+This discussion largely applies to the msys2 environment
+as well (with the use of the mingw compiler toolchain),
+in particular the recommendation to use the msys2 version of
+&Python; if running &scons; from inside an msys2 shell.
+</para>
 </refsect2>
 
 <refsect2 id='windows_sconsbat_file'>
@@ -7584,7 +7667,7 @@ to run &scons;.</para>
 <filename>scons.bat</filename> batch file,
 there are (at least) two ramifications.
 Note this is no longer the default - &scons; installed
-via Python's <command>pip</command> installer
+via &Python;''s <command>pip</command> installer
 will have an <command>scons.exe</command> which does
 not have these limitations:
 </para>
@@ -7624,7 +7707,7 @@ directory must be in your <envar>PATH</envar>
 environment variable or the
 <varname>['ENV']['PATH']</varname> &consvar; for &scons;
 to detect and use the MinGW tools. When running under the native Windows
-Python interpreter, &scons; will prefer the MinGW tools over the Cygwin
+Python; interpreter, &scons; will prefer the MinGW tools over the Cygwin
 tools, if they are both installed, regardless of the order of the bin
 directories in the <envar>PATH</envar> variable.
 If you have both MSVC and MinGW