Documentation updates [ci skip]

2 files changed, 234 insertions, 164 deletions

diff --git a/SCons/Tool/msvc.xml b/SCons/Tool/msvc.xml
index 6663aab..de82db0 100644
--- a/SCons/Tool/msvc.xml
+++ b/SCons/Tool/msvc.xml
@@ -349,8 +349,15 @@ Sets the preferred  version of Microsoft Visual C/C++ to use.
 If &cv-MSVC_VERSION; is not set, SCons will (by default) select the
 latest version of Visual C/C++ installed on your system.  If the
 specified version isn't installed, tool initialization will fail.
-This variable must be passed as an argument to the &f-link-Environment;
-constructor; setting it later has no effect.
+</para>
+
+<para>
+&cv-MSVC_VERSION; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_VERSION; must be set before the first msvc tool is
+loaded into the environment.
 </para>
 
 <para>
@@ -410,7 +417,7 @@ is, if you are sure everything is set correctly already and
 you don't want &SCons; to change anything.
 </para>
 <para>
-&cv-MSVC_USE_SCRIPT; overrides &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
+&cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
 </para>
 </summary>
 </cvar>
@@ -485,8 +492,12 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_USE_SETTINGS</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_USE_SETTINGS; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_USE_SETTINGS; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
@@ -529,13 +540,13 @@ Build with the Universal Windows Platform (UWP) application Visual C++ libraries
 </para>
 
 <para>
-The valid values for <envar>MSVC_UWP_APP</envar> are <literal>True</literal>,
+The valid values for &cv-MSVC_UWP_APP; are: <literal>True</literal>,
 <literal>'1'</literal>, <literal>False</literal>, <literal>'0'</literal>,
 or <literal>None</literal>.
 </para>
 
 <para>
-When <envar>MSVC_UWP_APP</envar> is enabled (i.e., <literal>True</literal> or
+When &cv-MSVC_UWP_APP; is enabled (i.e., <literal>True</literal> or
 <literal>'1'</literal>), the Visual C++ environment will be set up to point
 to the Windows Store compatible libraries and Visual C++ runtimes. In doing so,
 any libraries that are built will be able to be used in a UWP App and published
@@ -549,11 +560,11 @@ constructor; setting it later has no effect. -->
 An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 <listitem><para>
-<envar>MSVC_UWP_APP</envar> is enabled for Visual Studio 2013 and earlier.
+&cv-MSVC_UWP_APP; is enabled for Visual Studio 2013 and earlier.
 </para></listitem>
 <listitem><para>
-<envar>MSVC_UWP_APP</envar> is enabled and a UWP argument is specified in
-&cv-link-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via <envar>MSVC_UWP_APP</envar>
+&cv-MSVC_UWP_APP; is enabled and a UWP argument is specified in
+&cv-link-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via &cv-MSVC_UWP_APP;
 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 </itemizedlist>
@@ -571,13 +582,17 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_UWP_APP</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_UWP_APP; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_UWP_APP; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
 <emphasis>
-The existence of the UWP libraries is not verified when <envar>MSVC_UWP_APP</envar> is enabled
+The existence of the UWP libraries is not verified when &cv-MSVC_UWP_APP; is enabled
 which could result in build failures.
 </emphasis>
 The burden is on the user to ensure the requisite UWP libraries are installed.
@@ -645,12 +660,12 @@ Specify the &scons; behavior when the Microsoft Visual C/C++ compiler is not det
 </para>
 
 <para>
-    The <envar>MSVC_NOTFOUND_POLICY</envar> specifies the &scons; behavior when no msvc versions are detected or
+    The &cv-MSVC_NOTFOUND_POLICY; 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:
+The valid values for &cv-MSVC_NOTFOUND_POLICY; and the corresponding &scons; behavior are:
 </para>
 
 <variablelist>
@@ -691,7 +706,7 @@ Note: in addition to the camel case values shown above, lower case and upper cas
 </para>
 
 <para>
-The <envar>MSVC_NOTFOUND_POLICY</envar> is applied when any of the following conditions are satisfied:
+The &cv-MSVC_NOTFOUND_POLICY; 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),
@@ -708,7 +723,7 @@ A non-default tools list is specified that contains one or more of the msvc tool
 </para>
 
 <para>
-The <envar>MSVC_NOTFOUND_POLICY</envar> is ignored when any of the following conditions are satisfied:
+The &cv-MSVC_NOTFOUND_POLICY; 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).
@@ -727,15 +742,19 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_NOTFOUND_POLICY</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_NOTFOUND_POLICY; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_NOTFOUND_POLICY; must be set before the first msvc tool is
+loaded into the environment.
 </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
+When &cv-MSVC_NOTFOUND_POLICY; 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>
 
@@ -749,25 +768,25 @@ Pass user-defined arguments to the Visual C++ batch file determined via autodete
 </para>
 
 <para>
-<envar>MSVC_SCRIPT_ARGS</envar> is available for msvc batch file arguments that do not have first-class support
+&cv-MSVC_SCRIPT_ARGS; is available for msvc batch file arguments that do not have first-class support
 via construction variables or when there is an issue with the appropriate construction variable validation.
 When available, it is recommended to use the appropriate construction variables (e.g., &cv-link-MSVC_TOOLSET_VERSION;)
-rather than <envar>MSVC_SCRIPT_ARGS</envar> arguments.
+rather than &cv-MSVC_SCRIPT_ARGS; arguments.
 </para>
 
 <para>
-The valid values for <envar>MSVC_SCRIPT_ARGS</envar> are: <literal>None</literal>, a string,
+The valid values for &cv-MSVC_SCRIPT_ARGS; are: <literal>None</literal>, a string,
 or a list of strings.
 </para>
 
 <para>
-The <envar>MSVC_SCRIPT_ARGS</envar> value is converted to a scalar string (i.e., "flattened").
+The &cv-MSVC_SCRIPT_ARGS; value is converted to a scalar string (i.e., "flattened").
 The resulting scalar string, if not empty, is passed as an argument to the msvc batch file determined
 via autodetection subject to the validation conditions listed below.
 </para>
 
 <para>
-<envar>MSVC_SCRIPT_ARGS</envar> is ignored when the value is <literal>None</literal> and when the
+&cv-MSVC_SCRIPT_ARGS; is ignored when the value is <literal>None</literal> and when the
 result from argument conversion is an empty string.  The validation conditions below do not apply.
 </para>
 
@@ -776,54 +795,54 @@ An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SCRIPT_ARGS</envar> is specified for Visual Studio 2013 and earlier.
+&cv-MSVC_SCRIPT_ARGS; is specified for Visual Studio 2013 and earlier.
 </para></listitem>
 
 <listitem><para>
 Multiple SDK version arguments (e.g., <literal>'10.0.20348.0'</literal>) are specified
-in <envar>MSVC_SCRIPT_ARGS</envar>.
+in &cv-MSVC_SCRIPT_ARGS;.
 </para></listitem>
 
 <listitem><para>
 &cv-link-MSVC_SDK_VERSION; is specified and an SDK version argument
-(e.g., <literal>'10.0.20348.0'</literal>) is specified in <envar>MSVC_SCRIPT_ARGS</envar>.
-Multiple SDK version declarations via &cv-link-MSVC_SDK_VERSION; and <envar>MSVC_SCRIPT_ARGS</envar>
+(e.g., <literal>'10.0.20348.0'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
+Multiple SDK version declarations via &cv-link-MSVC_SDK_VERSION; and &cv-MSVC_SCRIPT_ARGS;
 are not allowed.
 </para></listitem>
 
 <listitem><para>
 Multiple toolset version arguments (e.g., <literal>'-vcvars_ver=14.29'</literal>)
-are specified in <envar>MSVC_SCRIPT_ARGS</envar>.
+are specified in &cv-MSVC_SCRIPT_ARGS;.
 </para></listitem>
 
 <listitem><para>
 &cv-link-MSVC_TOOLSET_VERSION; is specified and a toolset version argument
-(e.g., <literal>'-vcvars_ver=14.29'</literal>) is specified in <envar>MSVC_SCRIPT_ARGS</envar>.
+(e.g., <literal>'-vcvars_ver=14.29'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
 Multiple toolset version declarations via &cv-link-MSVC_TOOLSET_VERSION; and
-<envar>MSVC_SCRIPT_ARGS</envar> are not allowed.
+&cv-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 <listitem><para>
 Multiple spectre library arguments (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>)
-are specified in <envar>MSVC_SCRIPT_ARGS</envar>.
+are specified in &cv-MSVC_SCRIPT_ARGS;.
 </para></listitem>
 
 <listitem><para>
 &cv-link-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument
 (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>) is specified in
-<envar>MSVC_SCRIPT_ARGS</envar>. Multiple spectre library declarations via &cv-link-MSVC_SPECTRE_LIBS;
-and <envar>MSVC_SCRIPT_ARGS</envar> are not allowed.
+&cv-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-link-MSVC_SPECTRE_LIBS;
+and &cv-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 <listitem><para>
 Multiple UWP arguments (e.g., <literal>uwp</literal> or <literal>store</literal>) are specified
-in <envar>MSVC_SCRIPT_ARGS</envar>.
+in &cv-MSVC_SCRIPT_ARGS;.
 </para></listitem>
 
 <listitem><para>
 &cv-link-MSVC_UWP_APP; is enabled and a UWP argument (e.g., <literal>uwp</literal> or
-<literal>store</literal>) is specified in <envar>MSVC_SCRIPT_ARGS</envar>. Multiple UWP declarations
-via &cv-link-MSVC_UWP_APP; and <envar>MSVC_SCRIPT_ARGS</envar> are not allowed.
+<literal>store</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple UWP declarations
+via &cv-link-MSVC_UWP_APP; and &cv-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 </itemizedlist>
@@ -850,18 +869,22 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SCRIPT_ARGS</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_SCRIPT_ARGS; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_SCRIPT_ARGS; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
-Other than checking for multiple declarations as described above, <envar>MSVC_SCRIPT_ARGS</envar> arguments
+Other than checking for multiple declarations as described above, &cv-MSVC_SCRIPT_ARGS; arguments
 are not validated.
 </para></listitem>
 
 <listitem><para>
 <emphasis>
-Erroneous, inconsistent, and/or version incompatible <envar>MSVC_SCRIPT_ARGS</envar> arguments are likely
+Erroneous, inconsistent, and/or version incompatible &cv-MSVC_SCRIPT_ARGS; arguments are likely
 to result in build failures for reasons that are not readily apparent and may be difficult to diagnose.
 </emphasis>
 The burden is on the user to ensure that the arguments provided to the msvc batch file are valid, consistent
@@ -881,12 +904,12 @@ Build with a specific version of the Microsoft Software Development Kit (SDK).
 </para>
 
 <para>
-The valid values for <envar>MSVC_SDK_VERSION</envar> are: <literal>None</literal>
-or a string containing the requested SDK version (e.g., '10.0.20348.0').
+The valid values for &cv-MSVC_SDK_VERSION; are: <literal>None</literal>
+or a string containing the requested SDK version (e.g., <literal>'10.0.20348.0'</literal>).
 </para>
 
 <para>
-<envar>MSVC_SDK_VERSION</envar> is ignored when the value is <literal>None</literal> and when
+&cv-MSVC_SDK_VERSION; is ignored when the value is <literal>None</literal> and when
 the value is an empty string.  The validation conditions below do not apply.
 </para>
 
@@ -895,17 +918,17 @@ An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SDK_VERSION</envar> is specified for Visual Studio 2013 and earlier.
+&cv-MSVC_SDK_VERSION; is specified for Visual Studio 2013 and earlier.
 </para></listitem>
 
 <listitem><para>
-<envar>MSVC_SDK_VERSION</envar> is specified and an SDK version argument is specified in
-&cv-link-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via <envar>MSVC_SDK_VERSION</envar>
+&cv-MSVC_SDK_VERSION; is specified and an SDK version argument is specified in
+&cv-link-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via &cv-MSVC_SDK_VERSION;
 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 <listitem><para>
-The <envar>MSVC_SDK_VERSION</envar> specified does not match any of the supported formats:
+The &cv-MSVC_SDK_VERSION; specified does not match any of the supported formats:
 <itemizedlist>
 <listitem><para>
 <literal>'10.0.XXXXX.Y'</literal> [SDK 10.0]
@@ -917,12 +940,12 @@ The <envar>MSVC_SDK_VERSION</envar> specified does not match any of the supporte
 </para></listitem>
 
 <listitem><para>
-The system folder for the corresponding <envar>MSVC_SDK_VERSION</envar> version is not found.
+The system folder for the corresponding &cv-MSVC_SDK_VERSION; version is not found.
 The requested SDK version does not appear to be installed.
 </para></listitem>
 
 <listitem><para>
-The <envar>MSVC_SDK_VERSION</envar> version does not appear to support the requested platform
+The &cv-MSVC_SDK_VERSION; version does not appear to support the requested platform
 type (i.e., <literal>UWP</literal> or <literal>Desktop</literal>).  The requested SDK version
 platform type components do not appear to be installed.
 </para></listitem>
@@ -949,8 +972,12 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SDK_VERSION</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_SDK_VERSION; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_SDK_VERSION; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem>
@@ -969,7 +996,7 @@ the requested SDK version is installed with the necessary platform type componen
 <listitem><para>
 There is a known issue with the Microsoft libraries for SDK version <literal>'10.0.22000.0'</literal>
 when using the <literal>v141</literal> build tools and the target architecture is <literal>ARM64</literal>.
-Should build failures arise with this combination of settings, <envar>MSVC_SDK_VERSION</envar> may be
+Should build failures arise with this combination of settings, &cv-MSVC_SDK_VERSION; may be
 employed to specify a different SDK version for the build.
 </para></listitem>
 
@@ -986,19 +1013,19 @@ Build with a specific Visual C++ toolset version.
 </para>
 
 <para><emphasis>
-Specifying <envar>MSVC_TOOLSET_VERSION</envar> does not affect the autodetection and selection
-of msvc instances. The <envar>MSVC_TOOLSET_VERSION</envar> is applied <emphasis>after</emphasis>
+Specifying &cv-MSVC_TOOLSET_VERSION; does not affect the autodetection and selection
+of msvc instances. The &cv-MSVC_TOOLSET_VERSION; is applied <emphasis>after</emphasis>
 an msvc instance is selected. This could be the default version of msvc if &cv-link-MSVC_VERSION;
 is not specified.
 </emphasis></para>
 
 <para>
-The valid values for <envar>MSVC_TOOLSET_VERSION</envar> are: <literal>None</literal>
-or a string containing the requested toolset version (e.g., '14.29').
+The valid values for &cv-MSVC_TOOLSET_VERSION; are: <literal>None</literal>
+or a string containing the requested toolset version (e.g., <literal>'14.29'</literal>).
 </para>
 
 <para>
-<envar>MSVC_TOOLSET_VERSION</envar> is ignored when the value is <literal>None</literal> and when
+&cv-MSVC_TOOLSET_VERSION; is ignored when the value is <literal>None</literal> and when
 the value is an empty string.  The validation conditions below do not apply.
 </para>
 
@@ -1007,18 +1034,18 @@ An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_TOOLSET_VERSION</envar> is specified for Visual Studio 2015 and earlier.
+&cv-MSVC_TOOLSET_VERSION; is specified for Visual Studio 2015 and earlier.
 </para></listitem>
 
 <listitem><para>
-<envar>MSVC_TOOLSET_VERSION</envar> is specified and a toolset version argument is specified in
-&cv-link-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via <envar>MSVC_TOOLSET_VERSION</envar>
+&cv-MSVC_TOOLSET_VERSION; is specified and a toolset version argument is specified in
+&cv-link-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via &cv-MSVC_TOOLSET_VERSION;
 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 <listitem>
 <para>
-The <envar>MSVC_TOOLSET_VERSION</envar> specified does not match any of the supported formats:
+The &cv-MSVC_TOOLSET_VERSION; specified does not match any of the supported formats:
 </para>
 
 <itemizedlist>
@@ -1055,17 +1082,17 @@ The <envar>MSVC_TOOLSET_VERSION</envar> specified does not match any of the supp
 </listitem>
 
 <listitem><para>
-The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the <envar>MSVC_TOOLSET_VERSION</envar> specified
-is for Visual Studio 2013 and earlier (e.g., '12.0').
+The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
+is for Visual Studio 2013 and earlier (e.g., <literal>'12.0'</literal>).
 </para></listitem>
 
 <listitem><para>
-The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the <envar>MSVC_TOOLSET_VERSION</envar> specified
-is greater than the msvc version selected (e.g., '99.0').
+The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
+is greater than the msvc version selected (e.g., <literal>'99.0'</literal>).
 </para></listitem>
 
 <listitem><para>
-A system folder for the corresponding <envar>MSVC_TOOLSET_VERSION</envar> version is not found.
+A system folder for the corresponding &cv-MSVC_TOOLSET_VERSION; version is not found.
 The requested toolset version does not appear to be installed.
 </para></listitem>
 
@@ -1084,13 +1111,13 @@ mapped to toolset version <literal>14.16.27023</literal>.
 </para></listitem>
 
 <listitem><para>
-When <envar>MSVC_TOOLSET_VERSION</envar> is not an SxS version number or a full toolset version number:
-the first toolset version, ranked in descending order, that matches the <envar>MSVC_TOOLSET_VERSION</envar>
+When &cv-MSVC_TOOLSET_VERSION; is not an SxS version number or a full toolset version number:
+the first toolset version, ranked in descending order, that matches the &cv-MSVC_TOOLSET_VERSION;
 prefix is selected.
 </para></listitem>
 
 <listitem><para>
-When <envar>MSVC_TOOLSET_VERSION</envar> is specified using the major msvc version prefix
+When &cv-MSVC_TOOLSET_VERSION; is specified using the major msvc version prefix
 (i.e., <literal>'XX.Y'</literal>) and the major msvc version is that of the latest release of
 Visual Studio, the selected toolset version may not be the same as the default Visual C++ toolset version.
 </para><para>
@@ -1116,14 +1143,18 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_TOOLSET_VERSION</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_TOOLSET_VERSION; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_TOOLSET_VERSION; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
 <emphasis>
 The existence of the toolset host architecture and target architecture folders are not verified
-when <envar>MSVC_TOOLSET_VERSION</envar> is specified which could result in build failures.
+when &cv-MSVC_TOOLSET_VERSION; is specified which could result in build failures.
 </emphasis>
 The burden is on the user to ensure the requisite toolset target architecture build tools are installed.
 </para></listitem>
@@ -1141,12 +1172,12 @@ Build with the spectre-mitigated Visual C++ libraries.
 </para>
 
 <para>
-The valid values for <envar>MSVC_SPECTRE_LIBS</envar> are: <literal>True</literal>,
+The valid values for &cv-MSVC_SPECTRE_LIBS; are: <literal>True</literal>,
 <literal>False</literal>, or <literal>None</literal>.
 </para>
 
 <para>
-When <envar>MSVC_SPECTRE_LIBS</envar> is enabled (i.e., <literal>True</literal>),
+When &cv-MSVC_SPECTRE_LIBS; is enabled (i.e., <literal>True</literal>),
 the Visual C++ environment will include the paths to the spectre-mitigated implementations
 of the Microsoft Visual C++ libraries.
 </para>
@@ -1156,12 +1187,12 @@ An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SPECTRE_LIBS</envar> is enabled for Visual Studio 2015 and earlier.
+&cv-MSVC_SPECTRE_LIBS; is enabled for Visual Studio 2015 and earlier.
 </para></listitem>
 
 <listitem><para>
-<envar>MSVC_SPECTRE_LIBS</envar> is enabled and a spectre library argument is specified in
-&cv-link-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via <envar>MSVC_SPECTRE_LIBS</envar>
+&cv-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument is specified in
+&cv-link-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-MSVC_SPECTRE_LIBS;
 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
@@ -1180,8 +1211,12 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SPECTRE_LIBS</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_SPECTRE_LIBS; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_SPECTRE_LIBS; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
@@ -1192,7 +1227,7 @@ details.
 
 <listitem><para>
 <emphasis>
-The existence of the spectre mitigations libraries is not verified when <envar>MSVC_SPECTRE_LIBS</envar>
+The existence of the spectre mitigations libraries is not verified when &cv-MSVC_SPECTRE_LIBS;
 is enabled which could result in build failures.
 </emphasis>
 The burden is on the user to ensure the requisite libraries with spectre mitigations are installed.
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index f1b3fff..a0c2dc4 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -4690,12 +4690,12 @@ Specify the &scons; behavior when the Microsoft Visual C/C++ compiler is not det
 </para>
 
 <para>
-    The <envar>MSVC_NOTFOUND_POLICY</envar> specifies the &scons; behavior when no msvc versions are detected or
+    The &cv-MSVC_NOTFOUND_POLICY; 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:
+The valid values for &cv-MSVC_NOTFOUND_POLICY; and the corresponding &scons; behavior are:
 </para>
 
 <variablelist>
@@ -4736,7 +4736,7 @@ Note: in addition to the camel case values shown above, lower case and upper cas
 </para>
 
 <para>
-The <envar>MSVC_NOTFOUND_POLICY</envar> is applied when any of the following conditions are satisfied:
+The &cv-MSVC_NOTFOUND_POLICY; 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),
@@ -4753,7 +4753,7 @@ A non-default tools list is specified that contains one or more of the msvc tool
 </para>
 
 <para>
-The <envar>MSVC_NOTFOUND_POLICY</envar> is ignored when any of the following conditions are satisfied:
+The &cv-MSVC_NOTFOUND_POLICY; 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).
@@ -4772,15 +4772,19 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_NOTFOUND_POLICY</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_NOTFOUND_POLICY; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_NOTFOUND_POLICY; must be set before the first msvc tool is
+loaded into the environment.
 </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
+When &cv-MSVC_NOTFOUND_POLICY; 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>
 
@@ -4795,25 +4799,25 @@ Pass user-defined arguments to the Visual C++ batch file determined via autodete
 </para>
 
 <para>
-<envar>MSVC_SCRIPT_ARGS</envar> is available for msvc batch file arguments that do not have first-class support
+&cv-MSVC_SCRIPT_ARGS; is available for msvc batch file arguments that do not have first-class support
 via construction variables or when there is an issue with the appropriate construction variable validation.
 When available, it is recommended to use the appropriate construction variables (e.g., &cv-link-MSVC_TOOLSET_VERSION;)
-rather than <envar>MSVC_SCRIPT_ARGS</envar> arguments.
+rather than &cv-MSVC_SCRIPT_ARGS; arguments.
 </para>
 
 <para>
-The valid values for <envar>MSVC_SCRIPT_ARGS</envar> are: <literal>None</literal>, a string,
+The valid values for &cv-MSVC_SCRIPT_ARGS; are: <literal>None</literal>, a string,
 or a list of strings.
 </para>
 
 <para>
-The <envar>MSVC_SCRIPT_ARGS</envar> value is converted to a scalar string (i.e., "flattened").
+The &cv-MSVC_SCRIPT_ARGS; value is converted to a scalar string (i.e., "flattened").
 The resulting scalar string, if not empty, is passed as an argument to the msvc batch file determined
 via autodetection subject to the validation conditions listed below.
 </para>
 
 <para>
-<envar>MSVC_SCRIPT_ARGS</envar> is ignored when the value is <literal>None</literal> and when the
+&cv-MSVC_SCRIPT_ARGS; is ignored when the value is <literal>None</literal> and when the
 result from argument conversion is an empty string.  The validation conditions below do not apply.
 </para>
 
@@ -4822,54 +4826,54 @@ An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SCRIPT_ARGS</envar> is specified for Visual Studio 2013 and earlier.
+&cv-MSVC_SCRIPT_ARGS; is specified for Visual Studio 2013 and earlier.
 </para></listitem>
 
 <listitem><para>
 Multiple SDK version arguments (e.g., <literal>'10.0.20348.0'</literal>) are specified
-in <envar>MSVC_SCRIPT_ARGS</envar>.
+in &cv-MSVC_SCRIPT_ARGS;.
 </para></listitem>
 
 <listitem><para>
 &cv-link-MSVC_SDK_VERSION; is specified and an SDK version argument
-(e.g., <literal>'10.0.20348.0'</literal>) is specified in <envar>MSVC_SCRIPT_ARGS</envar>.
-Multiple SDK version declarations via &cv-link-MSVC_SDK_VERSION; and <envar>MSVC_SCRIPT_ARGS</envar>
+(e.g., <literal>'10.0.20348.0'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
+Multiple SDK version declarations via &cv-link-MSVC_SDK_VERSION; and &cv-MSVC_SCRIPT_ARGS;
 are not allowed.
 </para></listitem>
 
 <listitem><para>
 Multiple toolset version arguments (e.g., <literal>'-vcvars_ver=14.29'</literal>)
-are specified in <envar>MSVC_SCRIPT_ARGS</envar>.
+are specified in &cv-MSVC_SCRIPT_ARGS;.
 </para></listitem>
 
 <listitem><para>
 &cv-link-MSVC_TOOLSET_VERSION; is specified and a toolset version argument
-(e.g., <literal>'-vcvars_ver=14.29'</literal>) is specified in <envar>MSVC_SCRIPT_ARGS</envar>.
+(e.g., <literal>'-vcvars_ver=14.29'</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;.
 Multiple toolset version declarations via &cv-link-MSVC_TOOLSET_VERSION; and
-<envar>MSVC_SCRIPT_ARGS</envar> are not allowed.
+&cv-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 <listitem><para>
 Multiple spectre library arguments (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>)
-are specified in <envar>MSVC_SCRIPT_ARGS</envar>.
+are specified in &cv-MSVC_SCRIPT_ARGS;.
 </para></listitem>
 
 <listitem><para>
 &cv-link-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument
 (e.g., <literal>'-vcvars_spectre_libs=spectre'</literal>) is specified in
-<envar>MSVC_SCRIPT_ARGS</envar>. Multiple spectre library declarations via &cv-link-MSVC_SPECTRE_LIBS;
-and <envar>MSVC_SCRIPT_ARGS</envar> are not allowed.
+&cv-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-link-MSVC_SPECTRE_LIBS;
+and &cv-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 <listitem><para>
 Multiple UWP arguments (e.g., <literal>uwp</literal> or <literal>store</literal>) are specified
-in <envar>MSVC_SCRIPT_ARGS</envar>.
+in &cv-MSVC_SCRIPT_ARGS;.
 </para></listitem>
 
 <listitem><para>
 &cv-link-MSVC_UWP_APP; is enabled and a UWP argument (e.g., <literal>uwp</literal> or
-<literal>store</literal>) is specified in <envar>MSVC_SCRIPT_ARGS</envar>. Multiple UWP declarations
-via &cv-link-MSVC_UWP_APP; and <envar>MSVC_SCRIPT_ARGS</envar> are not allowed.
+<literal>store</literal>) is specified in &cv-MSVC_SCRIPT_ARGS;. Multiple UWP declarations
+via &cv-link-MSVC_UWP_APP; and &cv-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 </itemizedlist>
@@ -4896,18 +4900,22 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SCRIPT_ARGS</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_SCRIPT_ARGS; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_SCRIPT_ARGS; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
-Other than checking for multiple declarations as described above, <envar>MSVC_SCRIPT_ARGS</envar> arguments
+Other than checking for multiple declarations as described above, &cv-MSVC_SCRIPT_ARGS; arguments
 are not validated.
 </para></listitem>
 
 <listitem><para>
 <emphasis>
-Erroneous, inconsistent, and/or version incompatible <envar>MSVC_SCRIPT_ARGS</envar> arguments are likely
+Erroneous, inconsistent, and/or version incompatible &cv-MSVC_SCRIPT_ARGS; arguments are likely
 to result in build failures for reasons that are not readily apparent and may be difficult to diagnose.
 </emphasis>
 The burden is on the user to ensure that the arguments provided to the msvc batch file are valid, consistent
@@ -4928,12 +4936,12 @@ Build with a specific version of the Microsoft Software Development Kit (SDK).
 </para>
 
 <para>
-The valid values for <envar>MSVC_SDK_VERSION</envar> are: <literal>None</literal>
-or a string containing the requested SDK version (e.g., '10.0.20348.0').
+The valid values for &cv-MSVC_SDK_VERSION; are: <literal>None</literal>
+or a string containing the requested SDK version (e.g., <literal>'10.0.20348.0'</literal>).
 </para>
 
 <para>
-<envar>MSVC_SDK_VERSION</envar> is ignored when the value is <literal>None</literal> and when
+&cv-MSVC_SDK_VERSION; is ignored when the value is <literal>None</literal> and when
 the value is an empty string.  The validation conditions below do not apply.
 </para>
 
@@ -4942,17 +4950,17 @@ An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SDK_VERSION</envar> is specified for Visual Studio 2013 and earlier.
+&cv-MSVC_SDK_VERSION; is specified for Visual Studio 2013 and earlier.
 </para></listitem>
 
 <listitem><para>
-<envar>MSVC_SDK_VERSION</envar> is specified and an SDK version argument is specified in
-&cv-link-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via <envar>MSVC_SDK_VERSION</envar>
+&cv-MSVC_SDK_VERSION; is specified and an SDK version argument is specified in
+&cv-link-MSVC_SCRIPT_ARGS;. Multiple SDK version declarations via &cv-MSVC_SDK_VERSION;
 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 <listitem><para>
-The <envar>MSVC_SDK_VERSION</envar> specified does not match any of the supported formats:
+The &cv-MSVC_SDK_VERSION; specified does not match any of the supported formats:
 <itemizedlist>
 <listitem><para>
 <literal>'10.0.XXXXX.Y'</literal> [SDK 10.0]
@@ -4964,12 +4972,12 @@ The <envar>MSVC_SDK_VERSION</envar> specified does not match any of the supporte
 </para></listitem>
 
 <listitem><para>
-The system folder for the corresponding <envar>MSVC_SDK_VERSION</envar> version is not found.
+The system folder for the corresponding &cv-MSVC_SDK_VERSION; version is not found.
 The requested SDK version does not appear to be installed.
 </para></listitem>
 
 <listitem><para>
-The <envar>MSVC_SDK_VERSION</envar> version does not appear to support the requested platform
+The &cv-MSVC_SDK_VERSION; version does not appear to support the requested platform
 type (i.e., <literal>UWP</literal> or <literal>Desktop</literal>).  The requested SDK version
 platform type components do not appear to be installed.
 </para></listitem>
@@ -4996,8 +5004,12 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SDK_VERSION</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_SDK_VERSION; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_SDK_VERSION; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem>
@@ -5016,7 +5028,7 @@ the requested SDK version is installed with the necessary platform type componen
 <listitem><para>
 There is a known issue with the Microsoft libraries for SDK version <literal>'10.0.22000.0'</literal>
 when using the <literal>v141</literal> build tools and the target architecture is <literal>ARM64</literal>.
-Should build failures arise with this combination of settings, <envar>MSVC_SDK_VERSION</envar> may be
+Should build failures arise with this combination of settings, &cv-MSVC_SDK_VERSION; may be
 employed to specify a different SDK version for the build.
 </para></listitem>
 
@@ -5034,12 +5046,12 @@ Build with the spectre-mitigated Visual C++ libraries.
 </para>
 
 <para>
-The valid values for <envar>MSVC_SPECTRE_LIBS</envar> are: <literal>True</literal>,
+The valid values for &cv-MSVC_SPECTRE_LIBS; are: <literal>True</literal>,
 <literal>False</literal>, or <literal>None</literal>.
 </para>
 
 <para>
-When <envar>MSVC_SPECTRE_LIBS</envar> is enabled (i.e., <literal>True</literal>),
+When &cv-MSVC_SPECTRE_LIBS; is enabled (i.e., <literal>True</literal>),
 the Visual C++ environment will include the paths to the spectre-mitigated implementations
 of the Microsoft Visual C++ libraries.
 </para>
@@ -5049,12 +5061,12 @@ An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SPECTRE_LIBS</envar> is enabled for Visual Studio 2015 and earlier.
+&cv-MSVC_SPECTRE_LIBS; is enabled for Visual Studio 2015 and earlier.
 </para></listitem>
 
 <listitem><para>
-<envar>MSVC_SPECTRE_LIBS</envar> is enabled and a spectre library argument is specified in
-&cv-link-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via <envar>MSVC_SPECTRE_LIBS</envar>
+&cv-MSVC_SPECTRE_LIBS; is enabled and a spectre library argument is specified in
+&cv-link-MSVC_SCRIPT_ARGS;. Multiple spectre library declarations via &cv-MSVC_SPECTRE_LIBS;
 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
@@ -5073,8 +5085,12 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_SPECTRE_LIBS</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_SPECTRE_LIBS; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_SPECTRE_LIBS; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
@@ -5085,7 +5101,7 @@ details.
 
 <listitem><para>
 <emphasis>
-The existence of the spectre mitigations libraries is not verified when <envar>MSVC_SPECTRE_LIBS</envar>
+The existence of the spectre mitigations libraries is not verified when &cv-MSVC_SPECTRE_LIBS;
 is enabled which could result in build failures.
 </emphasis>
 The burden is on the user to ensure the requisite libraries with spectre mitigations are installed.
@@ -5105,19 +5121,19 @@ Build with a specific Visual C++ toolset version.
 </para>
 
 <para><emphasis>
-Specifying <envar>MSVC_TOOLSET_VERSION</envar> does not affect the autodetection and selection
-of msvc instances. The <envar>MSVC_TOOLSET_VERSION</envar> is applied <emphasis>after</emphasis>
+Specifying &cv-MSVC_TOOLSET_VERSION; does not affect the autodetection and selection
+of msvc instances. The &cv-MSVC_TOOLSET_VERSION; is applied <emphasis>after</emphasis>
 an msvc instance is selected. This could be the default version of msvc if &cv-link-MSVC_VERSION;
 is not specified.
 </emphasis></para>
 
 <para>
-The valid values for <envar>MSVC_TOOLSET_VERSION</envar> are: <literal>None</literal>
-or a string containing the requested toolset version (e.g., '14.29').
+The valid values for &cv-MSVC_TOOLSET_VERSION; are: <literal>None</literal>
+or a string containing the requested toolset version (e.g., <literal>'14.29'</literal>).
 </para>
 
 <para>
-<envar>MSVC_TOOLSET_VERSION</envar> is ignored when the value is <literal>None</literal> and when
+&cv-MSVC_TOOLSET_VERSION; is ignored when the value is <literal>None</literal> and when
 the value is an empty string.  The validation conditions below do not apply.
 </para>
 
@@ -5126,18 +5142,18 @@ An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_TOOLSET_VERSION</envar> is specified for Visual Studio 2015 and earlier.
+&cv-MSVC_TOOLSET_VERSION; is specified for Visual Studio 2015 and earlier.
 </para></listitem>
 
 <listitem><para>
-<envar>MSVC_TOOLSET_VERSION</envar> is specified and a toolset version argument is specified in
-&cv-link-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via <envar>MSVC_TOOLSET_VERSION</envar>
+&cv-MSVC_TOOLSET_VERSION; is specified and a toolset version argument is specified in
+&cv-link-MSVC_SCRIPT_ARGS;. Multiple toolset version declarations via &cv-MSVC_TOOLSET_VERSION;
 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 
 <listitem>
 <para>
-The <envar>MSVC_TOOLSET_VERSION</envar> specified does not match any of the supported formats:
+The &cv-MSVC_TOOLSET_VERSION; specified does not match any of the supported formats:
 </para>
 
 <itemizedlist>
@@ -5174,17 +5190,17 @@ The <envar>MSVC_TOOLSET_VERSION</envar> specified does not match any of the supp
 </listitem>
 
 <listitem><para>
-The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the <envar>MSVC_TOOLSET_VERSION</envar> specified
-is for Visual Studio 2013 and earlier (e.g., '12.0').
+The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
+is for Visual Studio 2013 and earlier (e.g., <literal>'12.0'</literal>).
 </para></listitem>
 
 <listitem><para>
-The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the <envar>MSVC_TOOLSET_VERSION</envar> specified
-is greater than the msvc version selected (e.g., '99.0').
+The major msvc version prefix (i.e., <literal>'XX.Y'</literal>) of the &cv-MSVC_TOOLSET_VERSION; specified
+is greater than the msvc version selected (e.g., <literal>'99.0'</literal>).
 </para></listitem>
 
 <listitem><para>
-A system folder for the corresponding <envar>MSVC_TOOLSET_VERSION</envar> version is not found.
+A system folder for the corresponding &cv-MSVC_TOOLSET_VERSION; version is not found.
 The requested toolset version does not appear to be installed.
 </para></listitem>
 
@@ -5203,13 +5219,13 @@ mapped to toolset version <literal>14.16.27023</literal>.
 </para></listitem>
 
 <listitem><para>
-When <envar>MSVC_TOOLSET_VERSION</envar> is not an SxS version number or a full toolset version number:
-the first toolset version, ranked in descending order, that matches the <envar>MSVC_TOOLSET_VERSION</envar>
+When &cv-MSVC_TOOLSET_VERSION; is not an SxS version number or a full toolset version number:
+the first toolset version, ranked in descending order, that matches the &cv-MSVC_TOOLSET_VERSION;
 prefix is selected.
 </para></listitem>
 
 <listitem><para>
-When <envar>MSVC_TOOLSET_VERSION</envar> is specified using the major msvc version prefix
+When &cv-MSVC_TOOLSET_VERSION; is specified using the major msvc version prefix
 (i.e., <literal>'XX.Y'</literal>) and the major msvc version is that of the latest release of
 Visual Studio, the selected toolset version may not be the same as the default Visual C++ toolset version.
 </para><para>
@@ -5235,14 +5251,18 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_TOOLSET_VERSION</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_TOOLSET_VERSION; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_TOOLSET_VERSION; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
 <emphasis>
 The existence of the toolset host architecture and target architecture folders are not verified
-when <envar>MSVC_TOOLSET_VERSION</envar> is specified which could result in build failures.
+when &cv-MSVC_TOOLSET_VERSION; is specified which could result in build failures.
 </emphasis>
 The burden is on the user to ensure the requisite toolset target architecture build tools are installed.
 </para></listitem>
@@ -5283,7 +5303,7 @@ is, if you are sure everything is set correctly already and
 you don't want &SCons; to change anything.
 </para>
 <para>
-&cv-MSVC_USE_SCRIPT; overrides &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
+&cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;.
 </para>
 </listitem>
   </varlistentry>
@@ -5360,8 +5380,12 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_USE_SETTINGS</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_USE_SETTINGS; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_USE_SETTINGS; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
@@ -5387,13 +5411,13 @@ Build with the Universal Windows Platform (UWP) application Visual C++ libraries
 </para>
 
 <para>
-The valid values for <envar>MSVC_UWP_APP</envar> are <literal>True</literal>,
+The valid values for &cv-MSVC_UWP_APP; are: <literal>True</literal>,
 <literal>'1'</literal>, <literal>False</literal>, <literal>'0'</literal>,
 or <literal>None</literal>.
 </para>
 
 <para>
-When <envar>MSVC_UWP_APP</envar> is enabled (i.e., <literal>True</literal> or
+When &cv-MSVC_UWP_APP; is enabled (i.e., <literal>True</literal> or
 <literal>'1'</literal>), the Visual C++ environment will be set up to point
 to the Windows Store compatible libraries and Visual C++ runtimes. In doing so,
 any libraries that are built will be able to be used in a UWP App and published
@@ -5407,11 +5431,11 @@ constructor; setting it later has no effect. -->
 An exception is raised when any of the following conditions are satisfied:
 <itemizedlist>
 <listitem><para>
-<envar>MSVC_UWP_APP</envar> is enabled for Visual Studio 2013 and earlier.
+&cv-MSVC_UWP_APP; is enabled for Visual Studio 2013 and earlier.
 </para></listitem>
 <listitem><para>
-<envar>MSVC_UWP_APP</envar> is enabled and a UWP argument is specified in
-&cv-link-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via <envar>MSVC_UWP_APP</envar>
+&cv-MSVC_UWP_APP; is enabled and a UWP argument is specified in
+&cv-link-MSVC_SCRIPT_ARGS;. Multiple UWP declarations via &cv-MSVC_UWP_APP;
 and &cv-link-MSVC_SCRIPT_ARGS; are not allowed.
 </para></listitem>
 </itemizedlist>
@@ -5429,13 +5453,17 @@ Important usage details:
 <itemizedlist>
 
 <listitem><para>
-<envar>MSVC_UWP_APP</envar> must be passed as an argument to the Environment() constructor;
-setting it later has no effect.
+&cv-MSVC_UWP_APP; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_UWP_APP; must be set before the first msvc tool is
+loaded into the environment.
 </para></listitem>
 
 <listitem><para>
 <emphasis>
-The existence of the UWP libraries is not verified when <envar>MSVC_UWP_APP</envar> is enabled
+The existence of the UWP libraries is not verified when &cv-MSVC_UWP_APP; is enabled
 which could result in build failures.
 </emphasis>
 The burden is on the user to ensure the requisite UWP libraries are installed.
@@ -5458,8 +5486,15 @@ Sets the preferred  version of Microsoft Visual C/C++ to use.
 If &cv-MSVC_VERSION; is not set, SCons will (by default) select the
 latest version of Visual C/C++ installed on your system.  If the
 specified version isn't installed, tool initialization will fail.
-This variable must be passed as an argument to the &f-link-Environment;
-constructor; setting it later has no effect.
+</para>
+
+<para>
+&cv-MSVC_VERSION; must be passed as an argument to the &f-link-Environment;
+constructor when an msvc tool (e.g., &t-link-msvc;, &t-link-msvs;, etc.) is
+loaded via the default tools list or via a tools list passed to the
+&f-link-Environment; constructor.
+Otherwise, &cv-MSVC_VERSION; must be set before the first msvc tool is
+loaded into the environment.
 </para>
 
 <para>