Regenerated docs for 4.6.0 release.

15 files changed, 514 insertions, 248 deletions

diff --git a/SConstruct b/SConstruct
index b41453270..472ae1893 100644
--- a/SConstruct
+++ b/SConstruct
@@ -36,7 +36,7 @@ copyright_years = strftime('2001 - %Y')
 # This gets inserted into the man pages to reflect the month of release.
 month_year = strftime('%B %Y')
 project = 'scons'
-default_version = '4.5.3'
+default_version = '4.6.0'
 copyright = f"Copyright (c) {copyright_years} The SCons Foundation"
 
 # We let the presence or absence of various utilities determine whether
diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
index deccae72a..25254b2a3 100644
--- a/doc/generated/builders.gen
+++ b/doc/generated/builders.gen
@@ -27,10 +27,12 @@ Example:
 
 <example_commands>
 # builds foo.c
-env.CFile(target = 'foo.c', source = 'foo.l')
+env.CFile(target='foo.c', source='foo.l')
+
 # builds bar.c
-env.CFile(target = 'bar', source = 'bar.y')
+env.CFile(target='bar', source='bar.y')
 </example_commands>
+
 </listitem>
   </varlistentry>
   <varlistentry id="b-Command">
@@ -124,10 +126,12 @@ Example:
 
 <example_commands>
 # builds foo.cc
-env.CXXFile(target = 'foo.cc', source = 'foo.ll')
+env.CXXFile(target='foo.cc', source='foo.ll')
+
 # builds bar.cc
-env.CXXFile(target = 'bar', source = 'bar.yy')
+env.CXXFile(target='bar', source='bar.yy')
 </example_commands>
+
 </listitem>
   </varlistentry>
   <varlistentry id="b-DocbookEpub">
@@ -1535,10 +1539,9 @@ the top directory of the project.
     <listitem><para>
 Builds a Microsoft Visual C++ precompiled header.
 Calling this builder
-returns a list of two targets: the PCH as the first element, and the object
-file as the second element. Normally the object file is ignored.
-This builder is only
-provided when Microsoft Visual C++ is being used as the compiler.
+returns a list of two target nodes: the PCH as the first element,
+and the object file as the second element.
+Normally the object file is ignored.
 The &b-PCH; builder is generally used in
 conjunction with the &cv-link-PCH; &consvar; to force object files to use
 the precompiled header:
@@ -1547,6 +1550,42 @@ the precompiled header:
 <example_commands>
 env['PCH'] = env.PCH('StdAfx.cpp')[0]
 </example_commands>
+
+<note>
+<para>
+This builder is specific to the PCH implementation
+in  Microsoft Visual C++.
+Other compiler chains also implement precompiled header support,
+but &b-PCH; does not work with them at this time.
+As a result, the builder is only generated into the
+construction environment when
+Microsoft Visual C++ is being used as the compiler.
+</para>
+<para>
+The builder only works correctly in a C++ project.
+The Microsoft implementation distinguishes between
+precompiled headers from C and C++.
+Use of the builder will cause the PCH generation to happen with a flag
+that tells <application>cl.exe</application> all of the
+files are C++ files; if that PCH file is then supplied when
+compiling a C source file,
+<application>cl.exe</application> will fail the build with
+a compatibility violation.
+</para>
+<para>
+If possible, arrange the project so that a
+C++ source file passed to the &b-PCH; builder
+is not also included in the list of sources
+to be otherwise compiled in the project.
+&SCons; will correctly track that file in the dependency tree
+as a result of the &b-PCH; call,
+and (for MSVC 11.0 and greater) automatically add the
+corresponding object file to the link line.
+If the source list is automatically generated,
+for example using the &f-link-Glob; function,
+it may be necessary to remove that file from the list.
+</para>
+</note>
 </listitem>
   </varlistentry>
   <varlistentry id="b-PDF">
diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml
index 422f37d59..940377d24 100644
--- a/doc/generated/examples/caching_ex-random_1.xml
+++ b/doc/generated/examples/caching_ex-random_1.xml
@@ -1,8 +1,8 @@
 <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
-cc -o f4.o -c f4.c
 cc -o f2.o -c f2.c
-cc -o f1.o -c f1.c
-cc -o f5.o -c f5.c
 cc -o f3.o -c f3.c
+cc -o f5.o -c f5.c
+cc -o f1.o -c f1.c
+cc -o f4.o -c f4.c
 cc -o prog f1.o f2.o f3.o f4.o f5.o
 </screen>
diff --git a/doc/generated/examples/commandline_EnumVariable_3.xml b/doc/generated/examples/commandline_EnumVariable_3.xml
index 154c041d2..6c0359828 100644
--- a/doc/generated/examples/commandline_EnumVariable_3.xml
+++ b/doc/generated/examples/commandline_EnumVariable_3.xml
@@ -4,5 +4,5 @@ COLOR: Set background color (red|green|blue)
     default: red
     actual: red
 
-Use scons -H for help about command-line options.
+Use scons -H for help about SCons built-in command-line options.
 </screen>
diff --git a/doc/generated/examples/commandline_Variables_Help_1.xml b/doc/generated/examples/commandline_Variables_Help_1.xml
index 1bbf2fb67..005c014a9 100644
--- a/doc/generated/examples/commandline_Variables_Help_1.xml
+++ b/doc/generated/examples/commandline_Variables_Help_1.xml
@@ -4,5 +4,5 @@ RELEASE: Set to 1 to build for release
     default: 0
     actual: 0
 
-Use scons -H for help about command-line options.
+Use scons -H for help about SCons built-in command-line options.
 </screen>
diff --git a/doc/generated/examples/output_ex1_1.xml b/doc/generated/examples/output_ex1_1.xml
index 1558b0118..5a3123d91 100644
--- a/doc/generated/examples/output_ex1_1.xml
+++ b/doc/generated/examples/output_ex1_1.xml
@@ -5,5 +5,5 @@ scons: done reading SConscript files.
 Type: 'scons program' to build the production program,
       'scons debug' to build the debug version.
 
-Use scons -H for help about command-line options.
+Use scons -H for help about SCons built-in command-line options.
 </screen>
diff --git a/doc/generated/examples/output_ex2_1.xml b/doc/generated/examples/output_ex2_1.xml
index d832a522f..b3b3fdb24 100644
--- a/doc/generated/examples/output_ex2_1.xml
+++ b/doc/generated/examples/output_ex2_1.xml
@@ -6,5 +6,5 @@ Type: 'scons program' to build the production program.
 
 Type: 'scons windebug' to build the Windows debug version.
 
-Use scons -H for help about command-line options.
+Use scons -H for help about SCons built-in command-line options.
 </screen>
diff --git a/doc/generated/examples/output_ex2_2.xml b/doc/generated/examples/output_ex2_2.xml
index 4cbccc134..528caddca 100644
--- a/doc/generated/examples/output_ex2_2.xml
+++ b/doc/generated/examples/output_ex2_2.xml
@@ -4,5 +4,5 @@ scons: done reading SConscript files.
 
 Type: 'scons program' to build the production program.
 
-Use scons -H for help about command-line options.
+Use scons -H for help about SCons built-in command-line options.
 </screen>
diff --git a/doc/generated/examples/troubleshoot_Dump_1.xml b/doc/generated/examples/troubleshoot_Dump_1.xml
index 6a0fa822b..54d1288d2 100644
--- a/doc/generated/examples/troubleshoot_Dump_1.xml
+++ b/doc/generated/examples/troubleshoot_Dump_1.xml
@@ -36,6 +36,7 @@ scons: Reading SConscript files ...
   'IDLSUFFIXES': ['.idl', '.IDL'],
   'INSTALL': &lt;function copyFunc at 0x700000&gt;,
   'INSTALLVERSIONEDLIB': &lt;function copyFuncVersionedLib at 0x700000&gt;,
+  'LIBLITERALPREFIX': '',
   'LIBPREFIX': 'lib',
   'LIBPREFIXES': ['$LIBPREFIX'],
   'LIBSUFFIX': '.a',
diff --git a/doc/generated/examples/troubleshoot_Dump_2.xml b/doc/generated/examples/troubleshoot_Dump_2.xml
index c952602f4..a29772a2b 100644
--- a/doc/generated/examples/troubleshoot_Dump_2.xml
+++ b/doc/generated/examples/troubleshoot_Dump_2.xml
@@ -61,6 +61,7 @@ scons: Reading SConscript files ...
   'INSTALL': &lt;function copyFunc at 0x700000&gt;,
   'INSTALLVERSIONEDLIB': &lt;function copyFuncVersionedLib at 0x700000&gt;,
   'LEXUNISTD': ['--nounistd'],
+  'LIBLITERALPREFIX': '',
   'LIBPREFIX': '',
   'LIBPREFIXES': ['$LIBPREFIX'],
   'LIBSUFFIX': '.lib',
diff --git a/doc/generated/examples/troubleshoot_explain1_3.xml b/doc/generated/examples/troubleshoot_explain1_3.xml
index a0aec9ff9..e658d89fd 100644
--- a/doc/generated/examples/troubleshoot_explain1_3.xml
+++ b/doc/generated/examples/troubleshoot_explain1_3.xml
@@ -2,5 +2,5 @@
 cp file.in file.oout
 
 scons: warning: Cannot find target file.out after building
-File "/Users/bdbaddog/devel/scons/git/scons-2/scripts/scons.py", line 97, in &lt;module&gt;
+File "/Users/bdbaddog/devel/scons/git/as_scons/scripts/scons.py", line 97, in &lt;module&gt;
 </screen>
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
index 90d263da1..2068b5594 100644
--- a/doc/generated/functions.gen
+++ b/doc/generated/functions.gen
@@ -328,17 +328,32 @@ file into an object file.
     <term><function>Alias</function>(<parameter>alias, [source, [action]]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Alias</methodname>(<parameter>alias, [source, [action]]</parameter>)</term>
     <listitem><para>
-Creates a phony target (or targets) that
-can be used as references to zero or more other targets,
-as specified by the optional <parameter>source</parameter>
-parameter.
-<parameter>alias</parameter> and
-<parameter>source</parameter>
+Creates an <firstterm>alias</firstterm> target that
+can be used as a reference to zero or more other targets,
+specified by the optional <parameter>source</parameter> parameter.
+Aliases provide a way to give a shorter or more descriptive
+name to specific targets,
+and to group multiple targets under a single name.
+The alias name, or an Alias Node object,
+may be used as a dependency of any other target,
+including another alias.
+</para>
+
+<para>
+<parameter>alias</parameter> and <parameter>source</parameter>
 may each be a string or Node object,
 or a list of strings or Node objects;
 if Nodes are used for
 <parameter>alias</parameter>
 they must be Alias nodes.
+If <parameter>source</parameter> is omitted,
+the alias is created but has no reference;
+if selected for building this will result in a
+<quote>Nothing to be done.</quote> message.
+An empty alias can be used to define the alias
+in a visible place in the project;
+it can later be appended to in a subsidiary SConscript file
+with the actual target(s) to refer to.
 The optional
 <parameter>action</parameter>
 parameter specifies an action or list of actions
@@ -347,20 +362,18 @@ whenever the any of the alias targets are out-of-date.
 </para>
 
 <para>
-Returns a list of Alias Node objects representing the alias(es),
-which exist outside of any physical file system.
+&f-Alias; can be called for an existing alias,
+which appends the <parameter>alias</parameter>
+and/or <parameter>action</parameter> arguments
+to the existing lists for that alias.
 </para>
 
 <para>
-The alias name, or an Alias Node object,
-may be used as a dependency of any other target,
-including another alias.
-&f-Alias;
-can be called multiple times for the same
-alias to add additional targets to the alias,
-or additional actions to the list for this alias.
-Aliases are global even if set through
-the construction environment method.
+Returns a list of Alias Node objects representing the alias(es),
+which exist outside of any physical file system.
+The alias name space is separate from the name space for
+tangible targets; to avoid confusion do not reuse
+target names as alias names.
 </para>
 
 <para>
@@ -795,15 +808,6 @@ disables derived file caching.
 </para>
 
 <para>
-When specifying a
-<parameter>custom_class</parameter> which should be a class type which is a subclass of
-<classname>SCons.CacheDir.CacheDir</classname>, SCons will
-internally invoke this class to use for performing caching operations.
-This argument is optional and if left to default <constant>None</constant>, will use the
-default <classname>SCons.CacheDir.CacheDir</classname> class.
-</para>
-
-<para>
 Calling the environment method
 &f-link-env-CacheDir;
 limits the effect to targets built
@@ -818,6 +822,18 @@ caching by calling &f-env-CacheDir;.
 </para>
 
 <para>
+Caching behavior can be configured by passing a specialized cache
+class as the optional <parameter>custom_class</parameter> parameter.
+This class must be a subclass of
+<classname>SCons.CacheDir.CacheDir</classname>.
+&SCons; will internally invoke the custom class for performing
+caching operations.
+If the parameter is omitted or set to
+<constant>None</constant>, &SCons; will use the default
+<classname>SCons.CacheDir.CacheDir</classname> class.
+</para>
+
+<para>
 When derived-file caching
 is being used and
 &scons;
@@ -842,15 +858,14 @@ identified by its &buildsig;, for future use.
 The
 <computeroutput>Retrieved `file' from cache</computeroutput>
 messages are useful for human consumption,
-but less so when comparing log files between
+but less useful when comparing log files between
 &scons; runs which will show differences that are
 noisy and not actually significant.
 To disable,
 use the <option>--cache-show</option> option.
-With this option, &scons;
-will print the action that would
-have been used to build the file without
-considering cache retrieval.
+With this option, &scons; changes printing
+to always show the action that would
+have been used to build the file without caching.
 </para>
 
 <para>
@@ -858,10 +873,10 @@ Derived-file caching
 may be disabled for any invocation
 of &scons; by giving the
 <option>--cache-disable</option>
-command line option.
-Cache updating may be disabled, leaving cache
+command line option;
+cache updating may be disabled, leaving cache
 fetching enabled, by giving the
-<option>--cache-readonly</option>.
+<option>--cache-readonly</option> option.
 </para>
 
 <para>
@@ -871,7 +886,7 @@ option is used,
 &scons;
 will place a copy of
 <emphasis>all</emphasis>
-derived files in the cache,
+derived files into the cache,
 even if they already existed
 and were not built by this invocation.
 This is useful to populate a cache
@@ -896,7 +911,7 @@ predict or prohibitively large.
 <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.
+to arrange for cache pruning, expiry, access control, etc. if needed.
 </para>
 
 </listitem>
@@ -1447,26 +1462,39 @@ env.Default(hello)
   <varlistentry id="f-DefaultEnvironment">
     <term><function>DefaultEnvironment</function>(<parameter>[**kwargs]</parameter>)</term>
     <listitem><para>
-Instantiates and returns the default &consenv; object.
-The &defenv; is used internally by SCons
-in order to execute many of the global functions in this list
+Instantiates and returns the global &consenv; object.
+This environment is used internally by SCons
+when it executes many of the global functions listed in this section
 (that is, those not called as methods of a specific &consenv;).
+The &defenv; is a singleton:
+the keyword arguments are used only on the first call;
+on subsequent calls the already-constructed object is returned
+and any keyword arguments are silently ignored.
+The &defenv; can still be modified after instantiation
+in the same way as any other &consenv;.
+The &defenv; is independent:
+modifying it has no effect on any other &consenv;
+constructed by an &f-link-Environment; or &f-link-Clone; call.
+</para>
+
+<para>
 It is not mandatory to call &f-DefaultEnvironment;:
-the &defenv; will be instantiated automatically when the
-build phase begins if the function has not been called,
+the &defenv; is instantiated automatically when the
+build phase begins if this function has not been called;
 however calling it explicitly gives the opportunity to
 affect and examine the contents of the &defenv;.
+Instantiation happens even if no build instructions
+appar to use it, as there are internal uses.
+If there are no uses in the project &SConscript; files,
+a small performance gain may be seen by calling
+&f-DefaultEnvironment; with an empty tools list,
+thus avoiding that part of the initialization cost.
+This is mainly of interest in testing when &scons; is
+launched repeatedly in a short time period:
 </para>
-<para>
-The &defenv; is a singleton, so the keyword
-arguments affect it only on the first call, on subsequent
-calls the already-constructed object is returned and
-any keyword arguments are silently ignored.
-The &defenv; can be modified after instantiation
-in the same way as any &consenv;.
-Modifying the &defenv; has no effect on the &consenv;
-constructed by an &f-link-Environment; or &f-link-Clone; call.
-</para>
+<example_commands>
+DefaultEnvironment(tools=[])
+</example_commands>
 </listitem>
   </varlistentry>
   <varlistentry id="f-Depends">
@@ -1805,26 +1833,46 @@ is used if no value is specified.
     <term><function>Export</function>(<parameter>[vars...], [key=value...]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Export</methodname>(<parameter>[vars...], [key=value...]</parameter>)</term>
     <listitem><para>
-Exports variables from the current
-SConscript file to a global collection where they can be
-imported by other SConscript files.
+Exports variables for sharing with other SConscript files.
+The variables are added to a global collection where
+they can be imported by other SConscript files.
 <parameter>vars</parameter> may be one or more
-strings representing variable names to be exported.
-If a string contains whitespace, it is split into
-separate strings, as if multiple string arguments
-had been given.  A <parameter>vars</parameter> argument
-may also be a dictionary, which can be used to map variables
-to different names when exported.
-Keyword arguments can be used to provide names and their values.
+strings, or a list of strings. If any string
+contains whitespace, it is split automatically
+into individual strings. Each string must
+match the name of a variable that is in scope
+during evaluation of the current SConscript file,
+or an exception is raised.
+</para>
+
+<para>
+A <parameter>vars</parameter> argument
+may also be a dictionary or
+individual keyword arguments;
+in accordance with &Python; syntax rules,
+keyword arguments must come after any
+non-keyword arguments.
+The dictionary/keyword form can be used
+to map the local name of a variable to
+a different name to be used for imports.
+See the Examples for an illustration of the syntax.
 </para>
 
 <para>
 &f-Export; calls are cumulative. Specifying a previously
-exported variable will overwrite the earlier value.
+exported variable will replace the previous value in the collection.
 Both local variables and global variables can be exported.
 </para>
 
 <para>
+To use an exported variable, an SConscript must
+call &f-link-Import; to bring it into its own scope.
+Importing creates an additional reference to the object that
+was originally exported, so if that object is mutable,
+changes made will be visible to other users of that object.
+</para>
+
+<para>
 Examples:
 </para>
 
@@ -1850,10 +1898,10 @@ Export({"debug": env})
 <para>
 Note that the
 &f-link-SConscript;
-function supports an &exports;
-argument that allows exporting a variable or
-set of variables to a specific SConscript file or files.
-See the description below.
+function also supports an &exports;
+argument that allows exporting one or more variables
+to the SConscript files invoked by that call (only).
+See the description of that function for details.
 </para>
 </listitem>
   </varlistentry>
@@ -2657,28 +2705,41 @@ sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) \
 </listitem>
   </varlistentry>
   <varlistentry id="f-Help">
-    <term><function>Help</function>(<parameter>text, append=False</parameter>)</term>
-    <term><replaceable>env</replaceable>.<methodname>Help</methodname>(<parameter>text, append=False</parameter>)</term>
+    <term><function>Help</function>(<parameter>text, append=False, local_only=False</parameter>)</term>
+    <term><replaceable>env</replaceable>.<methodname>Help</methodname>(<parameter>text, append=False, local_only=False</parameter>)</term>
     <listitem><para>
-Specifies a local help message to be printed if the
-<option>-h</option>
-argument is given to
-&scons;.
-Subsequent calls to
-&f-Help;
-append <parameter>text</parameter> to the previously
-defined local help text.
+Adds <parameter>text</parameter> to the help message shown when
+&scons; is called with the
+<option>-h</option> or <option>--help</option>
+argument.
 </para>
 <para>
-For the first call to &f-Help; only,
+On the first call to &f-Help;,
 if <parameter>append</parameter> is <constant>False</constant>
-(the default)
-any local help message generated through
-&f-link-AddOption; calls is replaced.
+(the default), any existing help text is discarded.
+The default help text is the help for the &scons;
+command itself plus help collected from any
+project-local &f-link-AddOption; calls.
+This is the help printed if &f-Help; has never been called.
 If <parameter>append</parameter> is <constant>True</constant>,
 <parameter>text</parameter> is appended to
 the existing help text.
+If <parameter>local_only</parameter> is also <constant>True</constant>
+(the default is <constant>False</constant>),
+the project-local help from &f-AddOption; calls is preserved
+in the help message but the &scons; command help is not.
+</para>
+<para>
+Subsequent calls to
+&f-Help; ignore the keyword arguments
+<parameter>append</parameter> and
+<parameter>local_only</parameter>
+and always append to the existing help text.
+</para>
+<para>
+<emphasis>Changed in 4.6.0</emphasis>: added <parameter>local_only</parameter>.
 </para>
+
 </listitem>
   </varlistentry>
   <varlistentry id="f-Ignore">
@@ -2724,24 +2785,32 @@ env.Ignore('bar', 'bar/foobar.obj')
     <term><function>Import</function>(<parameter>vars...</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Import</methodname>(<parameter>vars...</parameter>)</term>
     <listitem><para>
-Imports variables into the current SConscript file.
+Imports variables into the scope of the current SConscript file.
 <parameter>vars</parameter>
 must be strings representing names of variables
 which have been previously exported either by the
 &f-link-Export; function or by the
-&exports; argument to
-&f-link-SConscript;.
-Variables exported by
-&f-SConscript;
+&exports; argument to the
+&f-link-SConscript; function.
+Variables exported by the
+&f-SConscript; call
 take precedence.
 Multiple variable names can be passed to
 &f-Import;
-as separate arguments or as words in a space-separated string.
+as separate arguments, as a list of strings,
+or as words in a space-separated string.
 The wildcard <literal>"*"</literal> can be used to import all
 available variables.
 </para>
 
 <para>
+If the imported variable is mutable,
+changes made locally will be reflected in the object the
+variable is bound to. This allows subsidiary SConscript files
+to contribute to building up, for example, a &consenv;.
+</para>
+
+<para>
 Examples:
 </para>
 
@@ -3623,12 +3692,12 @@ for a complete explanation of the arguments and behavior.
 </listitem>
   </varlistentry>
   <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>scriptnames, [exports, variant_dir, duplicate, must_exist]</parameter>)</term>
+    <term><replaceable>env</replaceable>.<methodname>SConscript</methodname>(<parameter>scriptnames, [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>
-Executes one or more subsidiary SConscript (configuration) files.
+Executes subsidiary SConscript (build configuration) file(s).
 There are two ways to call the
 &f-SConscript; function.
 </para>
@@ -3636,30 +3705,31 @@ There are two ways to call the
 <para>
 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 of strings
-(either explicitly or as created by
-a function like
-&f-link-Split;).
+as the first positional argument,
+which can be a string or a list of strings.
+If there is a second positional argument,
+it is treated as if the
+<varname>exports</varname>
+keyword argument had been given (see below).
 Examples:
 </para>
 <example_commands>
 SConscript('SConscript')  # run SConscript in the current directory
 SConscript('src/SConscript')  # run SConscript in the src directory
 SConscript(['src/SConscript', 'doc/SConscript'])
+SConscript(Split('src/SConscript doc/SConscript'))
 config = SConscript('MyConfig.py')
 </example_commands>
 
 <para>
-The other calling style is to omit the positional argument naming
-scripts and instead specify a list of directory names using the
+The second calling style is to omit the positional argument naming
+the script and instead specify directory names using the
 <varname>dirs</varname> keyword argument.
+The value can be a string or list of strings.
 In this case,
 &scons;
-will
-execute a subsidiary configuration file named
-&SConscript;
+will execute a subsidiary configuration file named
+&SConscript; (by default)
 in each of the specified directories.
 You may specify a name other than
 &SConscript;
@@ -3679,22 +3749,29 @@ SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
 <para>
 The optional
 <varname>exports</varname>
-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>.
+keyword argument specifies variables to make available
+for use by the called SConscripts,
+which are evaluated in an isolated context
+and otherwise do not have access to local variables
+from the calling SConscript.
+The value may be a string or list of strings representing
+variable names, or a dictionary mapping local names to
+the names they can be imported by.
+For the first (scriptnames) calling style,
+a second positional argument will also be interpreted as
+<varname>exports</varname>;
+the second (directory) calling style accepts no
+positional arguments and must use the keyword form.
 These variables are locally exported only to the called
-SConscript file(s)
-and do not affect the global pool of variables managed by the
+SConscript file(s), and take precedence over any same-named
+variables in the global pool managed by the
 &f-link-Export;
 function.
 <!-- If multiple dirs are provided, each script gets a fresh export. -->
 The subsidiary SConscript files
 must use the
 &f-link-Import;
-function to import the variables.
+function to import the variables into their local scope.
 Examples:
 </para>
 <example_commands>
@@ -3798,15 +3875,18 @@ TODO??? SConscript('build/SConscript', src_dir='src')
 <para>
 If the optional
 <varname>must_exist</varname>
-is <constant>True</constant>,
-causes an exception to be raised if a requested
-SConscript file is not found. The current default is
-<constant>False</constant>,
-causing only a warning to be emitted, but this default is deprecated
-(<emphasis>since 3.1</emphasis>).
-For scripts which truly intend to be optional, transition to
-explicitly supplying
-<literal>must_exist=False</literal> to the &f-SConscript; call.
+is <constant>True</constant> (the default),
+an exception is raised if a requested
+SConscript file is not found.
+To allow missing scripts to be silently ignored
+(the default behavior prior to &SCons; version 3.1),
+pass
+<literal>must_exist=False</literal> in the &f-SConscript; call.
+</para>
+
+<para>
+<emphasis>Changed in 4.6.0</emphasis>: <parameter>must_exist</parameter>
+now defaults to <constant>True</constant>.
 </para>
 
 <para>
diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen
index c3b4cfc51..3e1b0dcf6 100644
--- a/doc/generated/tools.gen
+++ b/doc/generated/tools.gen
@@ -1078,7 +1078,7 @@ Sets construction variables for the TeX formatter and typesetter.
   <varlistentry id="t-textfile">
     <term>textfile</term>
     <listitem><para>
-Set &consvars; for the &b-Textfile; and &b-Substfile; builders.
+Set &consvars; for the &b-link-Textfile; and &b-link-Substfile; builders.
 </para>
 <para>Sets: &cv-link-FILE_ENCODING;, &cv-link-LINESEPARATOR;, &cv-link-SUBSTFILEPREFIX;, &cv-link-SUBSTFILESUFFIX;, &cv-link-TEXTFILEPREFIX;, &cv-link-TEXTFILESUFFIX;.</para><para>Uses: &cv-link-SUBST_DICT;.</para></listitem>
   </varlistentry>
@@ -1104,9 +1104,9 @@ provides &b-POTUpdate; builder to make  <literal>PO</literal>
   <varlistentry id="t-yacc">
     <term>yacc</term>
     <listitem><para>
-Sets construction variables for the &yacc; parse generator.
+Sets construction variables for the &yacc; parser generator.
 </para>
-<para>Sets: &cv-link-YACC;, &cv-link-YACCCOM;, &cv-link-YACCFLAGS;, &cv-link-YACCHFILESUFFIX;, &cv-link-YACCHXXFILESUFFIX;, &cv-link-YACCVCGFILESUFFIX;.</para><para>Uses: &cv-link-YACCCOMSTR;, &cv-link-YACCFLAGS;, &cv-link-YACC_GRAPH_FILE;, &cv-link-YACC_HEADER_FILE;.</para></listitem>
+<para>Sets: &cv-link-YACC;, &cv-link-YACCCOM;, &cv-link-YACCFLAGS;, &cv-link-YACCHFILESUFFIX;, &cv-link-YACCHXXFILESUFFIX;, &cv-link-YACCVCGFILESUFFIX;, &cv-link-YACC_GRAPH_FILE_SUFFIX;.</para><para>Uses: &cv-link-YACCCOMSTR;, &cv-link-YACCFLAGS;, &cv-link-YACC_GRAPH_FILE;, &cv-link-YACC_HEADER_FILE;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-zip">
     <term>zip</term>
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index 86395a70e..621853d5f 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -375,8 +375,8 @@ env['BUILDERS']['NewBuilder'] = bld
     </term>
     <listitem><para>
 The class type that SCons should use when instantiating a
-new &f-link-CacheDir; for the given environment. It must be
-a subclass of the SCons.CacheDir.CacheDir class.
+new &f-link-CacheDir; in this &consenv;. Must be
+a subclass of the <classname>SCons.CacheDir.CacheDir</classname> class.
         </para>
     </listitem>
   </varlistentry>
@@ -466,7 +466,7 @@ when the &cv-link-PDB; &consvar; is set.
 </para>
 
 <para>
-The Visual C++ compiler option that SCons uses by default
+The Visual C++ compiler option that &SCons; uses by default
 to generate PDB information is <option>/Z7</option>.
 This works correctly with parallel (<option>-j</option>) builds
 because it embeds the debug information in the intermediate object files,
@@ -895,23 +895,23 @@ to each directory in &cv-link-CPPPATH;.
     <listitem><para>
 The list of directories that the C preprocessor will search for include
 directories. The C/C++ implicit dependency scanner will search these
-directories for include files. 
+directories for include files.
 In general it's not advised to put include directory directives
 directly into &cv-link-CCFLAGS; or &cv-link-CXXFLAGS;
 as the result will be non-portable
 and the directories will not be searched by the dependency scanner.
 &cv-CPPPATH; should be a list of path strings,
 or a single string, not a pathname list joined by
-Python's <systemitem>os.sep</systemitem>.
+Python's <systemitem>os.pathsep</systemitem>.
 </para>
 
 <para>
 Note:
 directory names in &cv-CPPPATH;
 will be looked-up relative to the directory of the SConscript file
-when they are used in a command. 
+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
 the <literal>#</literal> prefix:
 </para>
 
@@ -1184,6 +1184,42 @@ DFLAGSUFFIX.
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-DI_FILE_DIR">
+    <term>
+      <envar>DI_FILE_DIR</envar>
+    </term>
+    <listitem><para>
+Path where .di files will be generated
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="cv-DI_FILE_DIR_PREFIX">
+    <term>
+      <envar>DI_FILE_DIR_PREFIX</envar>
+    </term>
+    <listitem><para>
+Prefix to send the di path argument to compiler
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="cv-DI_FILE_DIR_SUFFFIX">
+    <term>
+      <envar>DI_FILE_DIR_SUFFFIX</envar>
+    </term>
+    <listitem><para>
+Suffix to send the di path argument to compiler
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="cv-DI_FILE_SUFFIX">
+    <term>
+      <envar>DI_FILE_SUFFIX</envar>
+    </term>
+    <listitem><para>
+Suffix of d include files default is .di
+</para>
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-DINCPREFIX">
     <term>
       <envar>DINCPREFIX</envar>
@@ -2706,8 +2742,11 @@ target being built.
       <envar>FILE_ENCODING</envar>
     </term>
     <listitem><para>
-File encoding used for files written by &b-link-Textfile; and &b-link-Substfile;.  Set to "utf-8" by default.
-<emphasis>Added in version  4.5.0.</emphasis>
+File encoding used for files written by &b-link-Textfile; and &b-link-Substfile;.
+Set to "utf-8" by default.
+</para>
+<para>
+<emphasis>New in version  4.5.0.</emphasis>
 </para>
 </listitem>
   </varlistentry>
@@ -3183,7 +3222,7 @@ is <quote><literal>-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</literal></quote>
       and <literal>x86_64</literal> for 64-bit hosts.
     </para>
     <para>
-      Should be considered immutable. 
+      Should be considered immutable.
       &cv-HOST_ARCH; is not currently used by other platforms,
       but the option is reserved to do so in future
     </para>
@@ -3201,7 +3240,7 @@ is <quote><literal>-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</literal></quote>
       <parameter>platform</parameter> argument to &f-link-Environment;).
     </para>
     <para>
-      Should be considered immutable. 
+      Should be considered immutable.
       &cv-HOST_OS; is not currently used by &SCons;,
       but the option is reserved to do so in future
     </para>
@@ -4204,7 +4243,7 @@ general information on specifying emitters.
 An automatically-generated construction variable
 containing the linker command-line options
 for specifying libraries to be linked with the resulting target.
-The value of &cv-link-_LIBFLAGS; is created
+The value of &cv-_LIBFLAGS; is created
 by respectively prepending and appending &cv-link-LIBLINKPREFIX;
 and &cv-link-LIBLINKSUFFIX;
 to each filename in &cv-link-LIBS;.
@@ -4235,6 +4274,48 @@ when the &cv-link-_LIBFLAGS; variable is automatically generated.
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-LIBLITERALPREFIX">
+    <term>
+      <envar>LIBLITERALPREFIX</envar>
+    </term>
+    <listitem><para>
+If the linker supports command line syntax directing
+that the argument specifying a library should be
+searched for literally (without modification),
+&cv-LIBLITERALPREFIX; can be set to that indicator.
+For example, the GNU linker follows this rule:
+<quote>
+<literal>-l:foo</literal> searches the library path
+for a filename called <literal>foo</literal>,
+without converting it to
+<literal>libfoo.so</literal> or
+<literal>libfoo.a</literal>.
+</quote>
+If &cv-LIBLITERALPREFIX; is set,
+&SCons; will not transform a string-valued entry in
+&cv-link-LIBS; that starts with that string.
+The entry will still be surrounded with
+&cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX;
+on the command line.
+This is useful, for example,
+in directing that a static library
+be used when both a static and dynamic library are available
+and linker policy is to prefer dynamic libraries.
+Compared to the example in &cv-link-LIBS;,
+</para>
+<example_commands>
+env.Append(LIBS=":libmylib.a")
+</example_commands>
+<para>
+will let the linker select that specific (static)
+library name if found in the library search path.
+This differs from using a
+<classname>File</classname> object
+to specify the static library,
+as the latter bypasses the library search path entirely.
+</para>
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-LIBPATH">
     <term>
       <envar>LIBPATH</envar>
@@ -4244,7 +4325,7 @@ The list of directories that will be searched for libraries
 specified by the &cv-link-LIBS; &consvar;.
 &cv-LIBPATH; should be a list of path strings,
 or a single string, not a pathname list joined by
-Python's <systemitem>os.sep</systemitem>.
+Python's <systemitem>os.pathsep</systemitem>.
 <!-- XXX OLD
 The implicit dependency scanner will search these
 directories for include files. Don't explicitly put include directory
@@ -4263,9 +4344,9 @@ as the result will be non-portable.
 Note:
 directory names in &cv-LIBPATH; will be looked-up relative to the
 directory of the SConscript file
-when they are used in a command. 
+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
 the <literal>#</literal> prefix:
 </para>
 
@@ -4322,7 +4403,8 @@ to reflect the names of the libraries they create.
       <envar>LIBPREFIXES</envar>
     </term>
     <listitem><para>
-A list of all legal prefixes for library file names.
+A list of all legal prefixes for library file names
+on the current platform.
 When searching for library dependencies,
 SCons will look for files with these prefixes,
 the base library name,
@@ -4335,51 +4417,54 @@ and suffixes from the &cv-link-LIBSUFFIXES; list.
       <envar>LIBS</envar>
     </term>
     <listitem><para>
-A list of one or more libraries
+The list of libraries
 that will be added to the link line
-for linking with any executable program, shared library, or loadable module 
+for linking with any executable program, shared library, or loadable module
 created by the &consenv; or override.
 </para>
 
 <para>
-String-valued library names should include
-only the library base names,
+For portability,
+a string-valued library name should include
+only the base library name,
 without prefixes such as <filename>lib</filename>
 or suffixes such as <filename>.so</filename> or <filename>.dll</filename>.
-The library list will be added to command lines
-through the automatically-generated
-&cv-_LIBFLAGS; &consvar;
-which is constructed by
-respectively prepending and appending the values of the
-&cv-LIBLINKPREFIX; and &cv-LIBLINKSUFFIX; &consvars;
-to each library name in &cv-LIBS;.
-Library name strings should not include a
-path component, instead the compiler will be
-directed to look for libraries in the paths
-specified by &cv-link-LIBPATH;.
-</para>
-
-<para>
-Any command lines you define that need
-the &cv-LIBS; library list should
-include &cv-_LIBFLAGS;:
-</para>
-
-<example_commands>
-env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-</example_commands>
-
-<para>
-If you add a
-<classname>File</classname>
-object to the
-&cv-LIBS;
-list, the name of that file will be added to
+&SCons; <emphasis>will</emphasis> attempt to
+strip prefixes from the &cv-link-LIBPREFIXES; list
+and suffixes from the &cv-link-LIBSUFFIXES; list,
+but depending on that behavior will make the build
+less portable:
+for example, on a POSIX system,
+no attempt will be made to strip a suffix like
+<filename>.dll</filename>.
+Library name strings in &cv-LIBS; should not include a path component:
+instead use &cv-link-LIBPATH; to direct the compiler
+to look for libraries in those paths,
+plus any default paths the linker searches in.
+If &cv-link-LIBLITERALPREFIX; is set to a non-empty string,
+then a string-valued &cv-LIBS; entry
+that starts with &cv-link-LIBLITERALPREFIX;
+will cause the rest of the entry
+to be searched for for unmodified,
+but respecting normal library search paths
+(this is an exception to the guideline above
+about leaving off the prefix/suffix from the library name).
+</para>
+
+<para>
+If a &cv-LIBS; entry is a Node object
+(either as returned by a previous Builder call,
+or as the result of an explicit call to &f-link-File;),
+the pathname from that Node will be added to
 &cv-_LIBFLAGS;,
-and thus to the link line, as-is, without
+and thus to the link line,
+unmodified - without adding
 &cv-LIBLINKPREFIX;
 or
 &cv-LIBLINKSUFFIX;.
+Such entries are searched for literally
+(including any path component);
+the library search paths are not used.
 For example:
 </para>
 
@@ -4388,9 +4473,34 @@ env.Append(LIBS=File('/tmp/mylib.so'))
 </example_commands>
 
 <para>
-In all cases, scons will add dependencies from the executable program to
-all the libraries in this list.
+<!-- is this actually true? -->
+For each &Builder; call that causes linking with libraries,
+&SCons; will add the libraries in the setting of &cv-LIBS;
+in effect at that moment to the dependecy graph
+as dependencies of the target being generated.
 </para>
+
+<para>
+The library list will transformed to command line
+arguments through the automatically-generated
+&cv-link-_LIBFLAGS; &consvar;
+which is constructed by
+respectively prepending and appending the values of the
+&cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; &consvars;
+to each library name.
+</para>
+
+<para>
+Any command lines you define yourself that need
+the libraries from &cv-LIBS; should include &cv-_LIBFLAGS;
+(as well as &cv-link-_LIBDIRFLAGS;)
+rather than &cv-LIBS;.
+For example:
+</para>
+
+<example_commands>
+env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
+</example_commands>
 </listitem>
   </varlistentry>
   <varlistentry id="cv-LIBSUFFIX">
@@ -4413,6 +4523,7 @@ to reflect the names of the libraries they create.
     </term>
     <listitem><para>
 A list of all legal suffixes for library file names.
+on the current platform.
 When searching for library dependencies,
 SCons will look for files with prefixes from the &cv-link-LIBPREFIXES; list,
 the base library name,
@@ -4852,12 +4963,12 @@ and
     </term>
     <listitem><para>
 When set to any true value,
-specifies that SCons should batch
+specifies that &SCons; should batch
 compilation of object files
 when calling the Microsoft Visual C/C++ compiler.
 All compilations of source files from the same source directory
 that generate target files in a same output directory
-and were configured in SCons using the same &consenv;
+and were configured in &SCons; using the same &consenv;
 will be built in a single call to the compiler.
 Only source files that have changed since their
 object files were built will be passed to each compiler invocation
@@ -5850,7 +5961,7 @@ The burden is on the user to ensure the requisite UWP libraries are installed.
 Sets the preferred  version of Microsoft Visual C/C++ to use.
 If the specified version is unavailable (not installed,
 or not discoverable), tool initialization will fail.
-If &cv-MSVC_VERSION; is not set, SCons will (by default) select the
+If &cv-MSVC_VERSION; is not set, &SCons; will (by default) select the
 latest version of Visual C/C++ installed on your system.
 </para>
 
@@ -6774,17 +6885,19 @@ not the underlying project code itself.
       <envar>PCH</envar>
     </term>
     <listitem><para>
-The Microsoft Visual C++ precompiled header that will be used when compiling
-object files. This variable is ignored by tools other than Microsoft Visual C++.
+A node for the Microsoft Visual C++ precompiled header that will be
+used when compiling object files.
+This variable is ignored by tools other than Microsoft Visual C++.
 When this variable is
-defined SCons will add options to the compiler command line to
+defined, &SCons; will add options to the compiler command line to
 cause it to use the precompiled header, and will also set up the
 dependencies for the PCH file.
-Example:
+Examples:
 </para>
 
 <example_commands>
 env['PCH'] = File('StdAfx.pch')
+env['PCH'] = env.PCH('pch.cc')[0]
 </example_commands>
 </listitem>
   </varlistentry>
@@ -6805,7 +6918,7 @@ builder to generated a precompiled header.
     </term>
     <listitem><para>
 The string displayed when generating a precompiled header.
-If this is not set, then &cv-link-PCHCOM; (the command line) is displayed.
+If not set, then &cv-link-PCHCOM; (the command line) is displayed.
 </para>
 </listitem>
   </varlistentry>
@@ -9488,7 +9601,7 @@ an alternate command line so the invoked tool will make
 use of the contents of the temporary file.
 If you need to replace the default tempfile object,
 the callable should take into account the settings of
-&cv-link-MAXLINELENGTH;, 
+&cv-link-MAXLINELENGTH;,
 &cv-link-TEMPFILEPREFIX;,
 &cv-link-TEMPFILESUFFIX;,
 &cv-link-TEMPFILEARGJOIN;,
@@ -9503,7 +9616,7 @@ and
       <envar>TEMPFILEARGESCFUNC</envar>
     </term>
     <listitem><para>
-The default argument escape function is 
+The default argument escape function is
 <function>SCons.Subst.quote_spaces</function>.
 If you need to apply extra operations on a command argument
 (to fix Windows slashes, normalize paths, etc.)
@@ -9732,10 +9845,10 @@ Specify the location of <filename>vswhere.exe</filename>.
     It provides full information about installations of 2017 and later editions.
     With the <option>-legacy</option> argument, <filename>vswhere.exe</filename> can detect installations of the 2010 through 2015
     editions with limited data returned.
-If <envar>VSWHERE</envar> is set, SCons will use that location.
+If <envar>VSWHERE</envar> is set, &SCons; will use that location.
 </para>
 <para>
-    Otherwise SCons will look in the following locations and set <envar>VSWHERE</envar> to the path of the first <filename>vswhere.exe</filename>
+    Otherwise &SCons; will look in the following locations and set <envar>VSWHERE</envar> to the path of the first <filename>vswhere.exe</filename>
 located.
 </para>
 
@@ -10146,7 +10259,9 @@ to disable debug package generation.
 To enable debug package generation, include this
 variable set either to None, or to a custom
 list that does not include the default line.
-Added in version 3.1.
+</para>
+<para>
+<emphasis>New in version  3.1.</emphasis>
 </para>
 
 <example_commands>
@@ -10502,6 +10617,30 @@ Will be emitted as a <option>--graph=</option>
 command-line option. Use this in preference to including
 <option>--graph=</option> in &cv-link-YACCFLAGS; directly.
 </para>
+<para><emphasis>New in version 4.4.0.</emphasis></para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="cv-YACC_GRAPH_FILE_SUFFIX">
+    <term>
+      <envar>YACC_GRAPH_FILE_SUFFIX</envar>
+    </term>
+    <listitem><para>
+Previously specified by &cv-link-YACCVCGFILESUFFIX;.
+</para>
+<para>
+The suffix of the file
+containing a graph of the grammar automaton
+when the <option>-g</option> option
+(or <option>--graph=</option> without an option-argument)
+is used in &cv-link-YACCFLAGS;.
+Note that setting this variable informs &SCons;
+how to construct the graph filename for tracking purposes,
+it does not affect the actual generated filename.
+Various yacc tools have emitted various formats
+at different times.
+Set this to match what your parser generator produces.
+</para>
+<para><emphasis>New in version 4.X.Y</emphasis>. </para>
 </listitem>
   </varlistentry>
   <varlistentry id="cv-YACC_HEADER_FILE">
@@ -10514,6 +10653,7 @@ Will be emitted as a <option>--header=</option>
 command-line option. Use this in preference to including
 <option>--header=</option> in &cv-link-YACCFLAGS; directly.
 </para>
+<para><emphasis>New in version 4.4.0.</emphasis></para>
 </listitem>
   </varlistentry>
   <varlistentry id="cv-YACCCOM">
@@ -10554,12 +10694,19 @@ and adds those to the target list.
 </para>
 
 <para>
-If a <option>-d</option> option is present,
+If the <option>-d</option> option is present in &cv-YACCFLAGS;
 &scons; assumes that the call will also create a header file
 with the suffix defined by &cv-link-YACCHFILESUFFIX;
 if the yacc source file ends in a <filename>.y</filename> suffix,
 or a file with the suffix defined by &cv-link-YACCHXXFILESUFFIX;
 if the yacc source file ends in a <filename>.yy</filename> suffix.
+The header will have the same base name as the requested target.
+This is only correct if the executable is <command>bison</command>
+(or <command>win_bison</command>).
+If using Berkeley yacc (<command>byacc</command>),
+<filename>y.tab.h</filename> is always written -
+avoid the <option>-d</option> in this case and
+use &cv-link-YACC_HEADER_FILE; instead.
 </para>
 
 <para>
@@ -10576,22 +10723,31 @@ with the suffix <filename>.output</filename>.
 
 <para>
 Also recognized are GNU &bison; options
-<option>--header=</option> and its deprecated synonym
-<option>--defines=</option>,
+<option>--header</option>
+(and its deprecated synonym <option>--defines</option>),
 which is similar to
 <option>-d</option>
-but the output filename is named by the option argument;
-and <option>--graph=</option>,
+but gives the option to explicitly name the output header file
+through an option argument;
+and <option>--graph</option>,
 which is similar to
 <option>-g</option>
-but the output filename is named by the option argument.
+but gives the option to explicitly name the output graph file
+through an option argument.
+The file suffixes described for
+<option>-d</option> and <option>-g</option> above
+are not applied if these are used in the option=argument form.
 </para>
 
 <para>
 Note that files specified by <option>--header=</option> and
 <option>--graph=</option> may not be properly handled
-by &SCons; in all situations. Consider using
-&cv-link-YACC_HEADER_FILE; and &cv-link-YACC_GRAPH_FILE; instead.
+by &SCons; in all situations, and using those in &cv-YACCFLAGS;
+should be considered legacy support only.
+Consider using &cv-link-YACC_HEADER_FILE;
+and &cv-link-YACC_GRAPH_FILE; instead
+if the files need to be explicitly named
+(<emphasis>new in version 4.4.0</emphasis>).
 </para>
 </listitem>
   </varlistentry>
@@ -10602,14 +10758,13 @@ by &SCons; in all situations. Consider using
     <listitem><para>
 The suffix of the C
 header file generated by the parser generator
-when the
-<option>-d</option>
-option is used.
-Note that setting this variable does not cause
-the parser generator to generate a header
-file with the specified suffix,
-it exists to allow you to specify
-what suffix the parser generator will use of its own accord.
+when the <option>-d</option> option
+(or <option>--header</option> without an option-argument)
+is used in &cv-link-YACCFLAGS;.
+Note that setting this variable informs &SCons;
+how to construct the header filename for tracking purposes,
+it does not affect the actual generated filename.
+Set this to match what your parser generator produces.
 The default value is
 <filename>.h</filename>.
 </para>
@@ -10622,22 +10777,14 @@ The default value is
     <listitem><para>
 The suffix of the C++
 header file generated by the parser generator
-when the
-<option>-d</option>
-option is used.
-Note that setting this variable does not cause
-the parser generator to generate a header
-file with the specified suffix,
-it exists to allow you to specify
-what suffix the parser generator will use of its own accord.
-The default value is
-<filename>.hpp</filename>,
-except on Mac OS X,
-where the default is
-<filename>${TARGET.suffix}.h</filename>.
-because the default &bison; parser generator just
-appends <filename>.h</filename>
-to the name of the generated C++ file.
+when the <option>-d</option> option
+(or <option>--header</option> without an option-argument)
+is used in &cv-link-YACCFLAGS;.
+Note that setting this variable informs &SCons;
+how to construct the header filename for tracking purposes,
+it does not affect the actual generated filename.
+Set this to match what your parser generator produces.
+The default value is <filename>.hpp</filename>.
 </para>
 </listitem>
   </varlistentry>
@@ -10646,18 +10793,14 @@ to the name of the generated C++ file.
       <envar>YACCVCGFILESUFFIX</envar>
     </term>
     <listitem><para>
-The suffix of the file
-containing the VCG grammar automaton definition
-when the
-<option>--graph=</option>
-option is used.
-Note that setting this variable does not cause
-the parser generator to generate a VCG
-file with the specified suffix,
-it exists to allow you to specify
-what suffix the parser generator will use of its own accord.
-The default value is
-<filename>.vcg</filename>.
+Obsoleted. Use &cv-link-YACC_GRAPH_FILE_SUFFIX; instead.
+The value is used only if &cv-YACC_GRAPH_FILE_SUFFIX; is not set.
+The default value is <filename>.gv</filename>.
+</para>
+<para>
+<emphasis>Changed in version 4.X.Y</emphasis>: deprecated. The default value
+changed from <filename>.vcg</filename> (&bison; stopped generating
+<filename>.vcg</filename> output with version 2.4, in 2006).
 </para>
 </listitem>
   </varlistentry>
diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod
index c3787ea8e..3b3e81eb5 100644
--- a/doc/generated/variables.mod
+++ b/doc/generated/variables.mod
@@ -286,6 +286,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-_LIBFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$_LIBFLAGS</envar>">
 <!ENTITY cv-LIBLINKPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LIBLINKPREFIX</envar>">
 <!ENTITY cv-LIBLINKSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LIBLINKSUFFIX</envar>">
+<!ENTITY cv-LIBLITERALPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LIBLITERALPREFIX</envar>">
 <!ENTITY cv-LIBPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LIBPATH</envar>">
 <!ENTITY cv-LIBPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LIBPREFIX</envar>">
 <!ENTITY cv-LIBPREFIXES "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LIBPREFIXES</envar>">
@@ -967,6 +968,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-link-_LIBFLAGS "<link linkend='cv-_LIBFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$_LIBFLAGS</envar></link>">
 <!ENTITY cv-link-LIBLINKPREFIX "<link linkend='cv-LIBLINKPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LIBLINKPREFIX</envar></link>">
 <!ENTITY cv-link-LIBLINKSUFFIX "<link linkend='cv-LIBLINKSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LIBLINKSUFFIX</envar></link>">
+<!ENTITY cv-link-LIBLITERALPREFIX "<link linkend='cv-LIBLITERALPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LIBLITERALPREFIX</envar></link>">
 <!ENTITY cv-link-LIBPATH "<link linkend='cv-LIBPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LIBPATH</envar></link>">
 <!ENTITY cv-link-LIBPREFIX "<link linkend='cv-LIBPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LIBPREFIX</envar></link>">
 <!ENTITY cv-link-LIBPREFIXES "<link linkend='cv-LIBPREFIXES' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LIBPREFIXES</envar></link>">