1 files changed, 43 insertions, 23 deletions

diff --git a/SCons/Tool/msvc.xml b/SCons/Tool/msvc.xml
index 776c361..2dec9c5 100644
--- a/SCons/Tool/msvc.xml
+++ b/SCons/Tool/msvc.xml
@@ -371,7 +371,7 @@ Valid values for Windows are
 <literal>7.1</literal>,
 <literal>7.0</literal>,
 and <literal>6.0</literal>.
-Versions ending in <literal>Exp</literal> refer to "Express" or 
+Versions ending in <literal>Exp</literal> refer to "Express" or
 "Express for Desktop" editions.
 </para>
 
@@ -381,17 +381,32 @@ Versions ending in <literal>Exp</literal> refer to "Express" or
 <cvar name="MSVC_USE_SCRIPT">
 <summary>
 <para>
-Use a batch script to set up Microsoft Visual Studio compiler
+Use a batch script to set up Microsoft Visual Studio compiler.
 </para>
 
 <para>
-&cv-MSVC_USE_SCRIPT; overrides &cv-MSVC_VERSION; and &cv-TARGET_ARCH;.
-If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
-SCons will run that bat file and extract the relevant variables from
-the result (typically %INCLUDE%, %LIB%, and %PATH%).  Setting
-MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection
-entirely; use this if you are running SCons in a Visual Studio cmd
-window and importing the shell's environment variables.
+If set to the name of a Visual Studio <filename>.bat</filename> file
+(e.g. <filename>vcvars.bat</filename>),
+&SCons; will run that batch file instead of the auto-detected one,
+and extract the relevant variables from the result (typically
+<envar>%INCLUDE%</envar>,
+<envar>%LIB%</envar>, and
+<envar>%PATH%</envar>) for supplying to the build.
+This can be useful to force the use of a compiler version that
+&SCons; does not detect.
+</para>
+
+<para>
+Setting
+&cv-MSVC_USE_SCRIPT; to <constant>None</constant> bypasses the
+Visual Studio autodetection entirely;
+use this if you are running SCons in a Visual Studio cmd
+window and importing the shell's environment variables - that
+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;.
 </para>
 </summary>
 </cvar>
@@ -403,15 +418,15 @@ Sets the host architecture for Visual Studio compiler. If not set,
 default to the detected host architecture: note that this may depend
 on the python you are using.
 This variable must be passed as an argument to the Environment()
-constructor; setting it later has no effect. 
+constructor; setting it later has no effect.
 </para>
 
 <para>
-Valid values are the same as for &cv-TARGET_ARCH;.
+Valid values are the same as for &cv-link-TARGET_ARCH;.
 </para>
 
 <para>
-This is currently only used on Windows, but in the future it will be
+This is currently only used on Windows, but in the future it may be
 used on other OSes as well.
 </para>
 </summary>
@@ -421,31 +436,36 @@ used on other OSes as well.
 <para>
 Sets the target architecture for Visual Studio compiler (i.e. the arch
 of the binaries generated by the compiler). If not set, default to
-&cv-HOST_ARCH;, or, if that is unset, to the architecture of the
+&cv-link-HOST_ARCH;, or, if that is unset, to the architecture of the
 running machine's OS (note that the python build or architecture has no
 effect).
 This variable must be passed as an argument to the Environment()
-constructor; setting it later has no effect.  
+constructor; setting it later has no effect.
 This is currently only used on Windows, but in the future it will be
 used on other OSes as well.
-If this is set and MSVC_VERSION is not set, this will search for 
-all installed MSVC's that support the TARGET_ARCH, selecting the 
+If this is set and &cv-link-MSVC_VERSION; is not set, this will search for
+all installed MSVC's that support the &cv-TARGET_ARCH;, selecting the
 latest version for use.
 </para>
 
 <para>
-Valid values for Windows are
+On Windows, valid target values are
 <literal>x86</literal>,
 <literal>arm</literal>,
 <literal>i386</literal>
-(for 32 bits); 
+for 32-bit targets and
 <literal>amd64</literal>,
 <literal>arm64</literal>,
-<literal>emt64</literal>,
+<literal>em64t</literal>,
 <literal>x86_64</literal>
-(for 64 bits);
-and <literal>ia64</literal> (Itanium).
+and <literal>ia64</literal> (Itanium)
+for 64-bit targets.
+Note that not all target architectures are
+supported for all Visual Studio / MSVC versions
+check the relevant Microsoft documentation.
+</para>
 
+<para>
 For example, if you want to compile 64-bit binaries, you would set
 <literal>TARGET_ARCH='x86_64'</literal> in your SCons environment.
 </para>
@@ -463,7 +483,7 @@ If &cv-MSVC_UWP_APP; is set, the Visual Studio environment will be set up to poi
 to the Windows Store compatible libraries and Visual Studio runtimes. In doing so,
 any libraries that are built will be able to be used in a UWP App and published
 to the Windows Store.
-This flag will only have an effect with Visual Studio 2015+.
+This flag will only have an effect with Visual Studio 2015 or later.
 This variable must be passed as an argument to the Environment()
 constructor; setting it later has no effect.
 </para>
@@ -478,7 +498,7 @@ Valid values are '1' or '0'
 <cvar name="VSWHERE">
 <summary>
 <para>
-Specify the location of <filename>vswhere.exe</filename>. 
+Specify the location of <filename>vswhere.exe</filename>.
 </para>
 
 <para>