Update docs for HOST_OS, TEMPFILE and Split [skip travis] [skip appveyor]

The HOST_ARCH/TARGET_ARCH functions have been defined in two
places, generic and Windows, these are consolidated into one,
leaving a comment in the msvc.xml file to show where that version
went to.  HOST_OS/TARGET_OS also got some tweaks - this was in
line with these now being set by default for all platforms.

The $TERMPFILE construction var was not defined; added and the
whole family had docs updated.

A small tweak to Split wording.

References to Python changed to entity references (there are still
more of these to change).

lambda as an entity reference is not correct (generated docs show
the symbol, but Python does not use the lambda symbol to refer
to lambda expressions).

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

6 files changed, 355 insertions, 230 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 547fdc0..a21a8d7 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -499,12 +499,12 @@ Multiple targets can be passed in to a single call to
 Intelligently append values to &consvars; in the &consenv;
 named by <varname>env</varname>.
 The &consvars; and values to add to them are passed as
-<parameter>key=val</parameter> pairs (Python keyword arguments).
+<parameter>key=val</parameter> pairs (&Python; keyword arguments).
 &f-env-Append; is designed to allow adding values
 without normally having to know the data type of an existing &consvar;.
-Regular Python syntax can also be used to manipulate the &consvar;,
+Regular &Python; syntax can also be used to manipulate the &consvar;,
 but for that you must know the type of the &consvar;:
-for example, different Python syntax is needed to combine
+for example, different &Python; syntax is needed to combine
 a list of values with a single string value, or vice versa.
 Some pre-defined &consvars; do have type expectations
 based on how &SCons; will use them,
@@ -615,7 +615,7 @@ described above.
 <para>
 Although most combinations of types work without
 needing to know the details, some combinations
-do not make sense and a Python exception will be raised.
+do not make sense and a &Python; exception will be raised.
 </para>
 
 <para>
@@ -1056,7 +1056,7 @@ same-named existing construction variables.
 <para>
 An action can be an external command,
 specified as a string,
-or a callable Python object;
+or a callable &Python; object;
 see the manpage section "Action Objects"
 for more complete information.
 Also note that a string specifying an external command
@@ -1270,7 +1270,7 @@ env.Decider('content')
 <para>
 In addition to the above already-available functions, the
 <parameter>function</parameter>
-argument may be a Python function you supply.
+argument may be a &Python; function you supply.
 Such a function must accept the following four arguments:
 </para>
 
@@ -1626,7 +1626,7 @@ may be an Action object
 for an explanation of behavior),
 or it may be a command-line string,
 list of commands,
-or executable Python function,
+or executable &Python; function,
 each of which will be converted
 into an Action object
 and then executed.
@@ -1635,7 +1635,7 @@ Any additional arguments to &f-Execute;
 are passed on to the &f-link-Action; factory function
 which actually creates the Action object.
 The exit value of the command
-or return value of the Python function
+or return value of the &Python; function
 will be returned.
 </para>
 
@@ -1824,7 +1824,7 @@ will also be returned by this function.
 </arguments>
 <summary>
 <para>
-Takes a sequence (that is, a Python list or tuple)
+Takes a sequence (that is, a &Python; list or tuple)
 that may contain nested sequences
 and returns a flattened list containing
 all of the individual elements in any sequence.
@@ -1832,7 +1832,7 @@ This can be helpful for collecting
 the lists returned by calls to Builders;
 other Builders will automatically
 flatten lists specified as input,
-but direct Python manipulation of
+but direct &Python; manipulation of
 these lists does not.
 </para>
 
@@ -1852,7 +1852,7 @@ objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
 # the Builder will flatten the list automatically:
 Program(source = objects)
 
-# If you need to manipulate the list directly using Python, you need to
+# If you need to manipulate the list directly using &Python;, you need to
 # call Flatten() yourself, or otherwise handle nested lists:
 for object in Flatten(objects):
     print(str(object))
@@ -2914,7 +2914,7 @@ by the chosen
 <para>
 The optional <parameter>dbm_module</parameter>
 argument specifies which
-Python database module to use
+&Python; database module to use
 for reading/writing the file.
 The module must be imported first;
 then the imported module name
@@ -2922,9 +2922,9 @@ is passed as the argument.
 The default is a custom
 <systemitem>SCons.dblite</systemitem>
 module that uses pickled
-Python data structures,
-which works on all Python versions.
-See documentation of the Python
+&Python; data structures,
+which works on all &Python; versions.
+See documentation of the &Python;
 <systemitem>dbm</systemitem> module
 for other available types.
 </para>
@@ -3082,16 +3082,22 @@ they are not added and included in the returned list.
 <arguments>(arg)</arguments>
 <summary>
 <para>
-Returns a list of file names or other objects.
 If <parameter>arg</parameter> is a string,
-it will be split on strings of white-space characters
-within the string,
-making it easier to write long lists of file names.
-If <parameter>arg</parameter> is already a list,
-the list will be returned untouched.
+splits on whitespace and returns a list of
+strings without whitespace.
+This mode is the most common case,
+and can be used to split a list of filenames
+(for example) rather than having to type them as a
+list of individually quoted words.
+If <parameter>arg</parameter> is a list or tuple
+returns <parameter>arg</parameter> unchanged.
+Use this form to specify strings where whitespace
+should be preserved
+(it is not necessary to call &f-Split; at all in this case,
+but as a convenience it just works as a pass-through
+so you don't have to check whether to call &f-Split; or not).
 If <parameter>arg</parameter> is any other type of object,
-it will be returned as a list
-containing just the object.
+returns a list containing just the object.
 </para>
 
 <para>
@@ -3179,7 +3185,7 @@ to be available for expansion.
 This is usually necessary if you are
 calling
 &f-env-subst;
-from within a Python function used
+from within a &Python; function used
 as an SCons action.
 </para>
 
@@ -3192,12 +3198,11 @@ argument
 may specify a conversion function
 that will be used in place of
 the default.
-For example, if you want Python objects
+For example, if you want &Python; objects
 (including SCons Nodes)
-to be returned as Python objects,
-you can use the Python
-&lambda;
-idiom to pass in an unnamed function
+to be returned as &Python; objects,
+you can use a &Python;
+lambda expression to pass in an unnamed function
 that simply returns its unconverted argument.
 </para>
 
@@ -3309,7 +3314,7 @@ the tool object, previously it did not return
 </arguments>
 <summary>
 <para>
-Returns a Node object representing the specified Python value.  Value
+Returns a Node object representing the specified &Python; value.  Value
 Nodes can be used as dependencies of targets.  If the result of
 calling
 <function>str</function>(<parameter>value</parameter>)
diff --git a/SCons/Platform/Platform.xml b/SCons/Platform/Platform.xml
index 343b2eb..ef516f1 100644
--- a/SCons/Platform/Platform.xml
+++ b/SCons/Platform/Platform.xml
@@ -121,34 +121,67 @@ else:
 <cvar name="HOST_OS">
     <summary>
 <para>
-        The name of the host operating system used to create the Environment.
-        If a platform is specified when creating the Environment, then
-        that Platform's logic will handle setting this value.
-        This value is immutable, and should not be changed by the user after
-        the Environment is initialized.
+        The name of the host operating system.
+        Can be set when creating a &consenv; by passing as a keyword
+        argument in the &f-link-Environment; call; should not be
+        changed otherwise.
+        If not specified in the &f-Environment; call, will be set to
+        the defaults for the particular platform, which is in turn
+        auto-detected unless the <parameter>platform</parameter>
+        argument to &f-Environment; is given.
+</para>
+<para>
+        This &consvar; is informational and does not currently
+        affect construction activities.
 </para>
     </summary>
 </cvar>
 
-<cvar name="HOST_ARCH">
+<cvar name="TARGET_OS">
     <summary>
 <para>
-        The name of the host hardware architecture used to create the Environment.
-        If a platform is specified when creating the Environment, then
-        that Platform's logic will handle setting this value.
-        This value is immutable, and should not be changed by the user after
-        the Environment is initialized.
+        The name of the operating system compiled objects
+        created by this &consenv; should target.
+        Can be set when creating a &consenv; by passing as a keyword
+        argument in the &f-link-Environment; call; should not be
+        changed otherwise.
+        If not specified in the &f-Environment; call, will be set to
+        the defaults for the particular platform, which is in turn
+        auto-detected unless the <parameter>platform</parameter>
+        argument to &f-Environment; is given.
+        Defaults to the same value as &cv-HOST_OS;.
+</para>
+<para>
+        This &consvar; is informational and does not currently
+        affect construction activities.
 </para>
     </summary>
 </cvar>
 
-<cvar name="TARGET_OS">
+<cvar name="HOST_ARCH">
     <summary>
 <para>
-        The name of the target operating system for the compiled objects
-        created by this Environment.
-        This defaults to the value of HOST_OS, and the user can override it.
-        Currently only set for Win32.
+        The name of the host hardware architecture.
+        Can be set when creating a &consenv; by passing as a keyword
+        argument in the &f-link-Environment; call; should not be
+        changed otherwise.
+        If not specified in the &f-Environment; call, will be set to
+        the defaults for the particular platform, which is in turn
+        auto-detected unless the <parameter>platform</parameter>
+        argument to &f-Environment; is given.
+        Note the detected value of the architecture may not be identical to
+        that from the &Python; <systemitem>platform.machine</systemitem> method.
+</para>
+<para>
+        On the Windows platform, if the Microsoft Visual C++ compiler
+        is available, &t-link-msvc; tool setup is done using
+        &cv-HOST_ARCH; and &cv-link-TARGET_ARCH;. Changing the values at
+        any later time will not cause the tool to be reinitialized.
+        Valid values for this usage are the same as for &cv-link-TARGET_ARCH;.
+</para>
+<para>
+        On other platforms, this &consvar; is informational and does
+        not currently affect construction activities.
 </para>
     </summary>
 </cvar>
@@ -156,15 +189,55 @@ else:
 <cvar name="TARGET_ARCH">
     <summary>
 <para>
-        The name of the target hardware architecture for the compiled objects
-        created by this Environment.
-        This defaults to the value of HOST_ARCH, and the user can override it.
-        Currently only set for Win32.
+        The name of the hardware architecture compiled objects
+        created by this &consenv; should target.
+        Can be set when creating a &consenv; by passing as a keyword
+        argument in the &f-link-Environment; call; should not be
+        changed otherwise.
+        If not specified in the &f-Environment; call, will be set to
+        the defaults for the particular platform, which is in turn
+        auto-detected unless the <parameter>platform</parameter>
+        argument to &f-Environment; is given.
+        Defaults to the same value as &cv-link-HOST_ARCH;.
 </para>
-    </summary>
+<para>
+        On the Windows platform, if the Microsoft Visual C++ compiler
+        is available, &t-link-msvc; tool setup is done using
+        &cv-link-HOST_ARCH; and &cv-TARGET_ARCH;. Changing the values at
+        any later time will not cause the tool to be reinitialized.
+        Compiled objects will be in the target architecture if
+        the compilation system supports generating for that target.
+        The latest compiler which can fulfill the requirement will
+        be selected, unless a different version is directed by the
+        value of the &cv-link-MSVC_VERSION; &consvar;.
+</para>
+<para>
+        On the Windows/msvc combination, valid target values are
+        <literal>x86</literal>,
+        <literal>arm</literal>,
+        <literal>i386</literal>
+        for 32-bit targets and
+        <literal>amd64</literal>,
+        <literal>arm64</literal>,
+        <literal>em64t</literal>,
+        <literal>x86_64</literal>
+        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> when creating the &consenv;.
+</para>
+<para>
+        On other platforms, this &consvar; is informational and does
+        not currently affect construction activities.
+</para>
+</summary>
 </cvar>
 
-
 <cvar name="PROGPREFIX">
 <summary>
 <para>
@@ -226,19 +299,40 @@ The suffix used for shared object file names.
 </summary>
 </cvar>
 
+<cvar name="TEMPFILE">
+<summary>
+<para>
+A callable object used to handle overly long command line strings,
+since operations which call out to a shell will fail
+if the line is longer than the shell can accept.
+This tends to particularly impact linking.
+The tempfile object stores the command line in a temporary
+file in the appropriate format, and returns
+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-TEMPFILEPREFIX;,
+&cv-link-TEMPFILESUFFIX;,
+&cv-link-TEMPFILEARGJOIN;,
+&cv-link-TEMPFILEDIR;
+and
+&cv-link-TEMPFILEARGESCFUNC;.
+</para>
+</summary>
+</cvar>
+
 <cvar name="TEMPFILEPREFIX">
 <summary>
 <para>
-The prefix for a temporary file used
-to store lines lines longer than $MAXLINELENGTH
-as operations which call out to a shell will fail
-if the line is too long, which particularly
-impacts linking.
-The default is '@', which works for the Microsoft
+The prefix for the name of the temporary file used
+to store command lines exceeding &cv-link-MAXLINELENGTH;.
+The default prefix is <literal>'@'</literal>, which works for the Microsoft
 and GNU toolchains on Windows.
 Set this appropriately for other toolchains,
-for example '-@' for the diab compiler
-or '-via' for ARM toolchain.
+for example <literal>'-@'</literal> for the diab compiler
+or <literal>'-via'</literal> for ARM toolchain.
 </para>
 </summary>
 </cvar>
@@ -246,11 +340,11 @@ or '-via' for ARM toolchain.
 <cvar name="TEMPFILESUFFIX">
 <summary>
 <para>
-The suffix used for the temporary file name
-used for long command lines. The name should
-include the dot ('.') if one is wanted as
+The suffix for the name of the temporary file used
+to store command lines exceeding &cv-link-MAXLINELENGTH;.
+The suffix shouldinclude the dot ('.') if one is wanted as
 it will not be added automatically.
-The default is '.lnk'.
+The default is <filename>.lnk</filename>.
 </para>
 </summary>
 </cvar>
@@ -258,8 +352,12 @@ The default is '.lnk'.
 <cvar name="TEMPFILEARGJOIN">
 <summary>
 <para>
-The string (or character) to be used to join the arguments passed to TEMPFILE when command line exceeds the limit set by &cv-MAXLINELENGTH;.
-The default value is a space. However for MSVC, MSLINK the default is a line seperator characters as defined by os.linesep.
+The string to use to join the arguments passed to
+&cv-link-TEMPFILE; when the command line exceeds the limit set by
+&cv-link-MAXLINELENGTH;.
+The default value is a space.
+However for MSVC, MSLINK the default is a line separator
+as defined by <systemitem>os.linesep</systemitem>.
 Note this value is used literally and not expanded by the subst logic.
 </para>
 </summary>
@@ -268,7 +366,7 @@ Note this value is used literally and not expanded by the subst logic.
 <cvar name="TEMPFILEDIR">
 <summary>
 <para>
-The directory to create the tempfile in.
+The directory to create the long-lines temporary file in.
 </para>
 </summary>
 </cvar>
@@ -276,10 +374,15 @@ The directory to create the tempfile in.
 <cvar name="TEMPFILEARGESCFUNC">
 <summary>
 <para>
-A default argument escape function is ``SCons.Subst.quote_spaces``.
-If you need to apply extra operations on a command argument before
-writing to a temporary file(fix Windows slashes, normalize paths, etc.),
-please set `TEMPFILEARGESCFUNC` variable to a custom function. Example::
+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.)
+before writing to the temporary file,
+you can set the &cv-TEMPFILEARGESCFUNC; variable to a custom function.
+Such a function takes a single string argument and returns
+a new string with any modifications applied.
+Example:
 </para>
 
 <example_commands>
diff --git a/SCons/Tool/msvc.xml b/SCons/Tool/msvc.xml
index e18bd76..7c86456 100644
--- a/SCons/Tool/msvc.xml
+++ b/SCons/Tool/msvc.xml
@@ -411,66 +411,23 @@ you don't want &SCons; to change anything.
 </summary>
 </cvar>
 
+<!-- This has moved to Platform/Platform.xml to avoid duplication
 <cvar name="HOST_ARCH">
 <summary>
 <para>
-Sets the host architecture for the Visual C++ 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.
-</para>
-
-<para>
-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 may be
-used on other OSes as well.
 </para>
 </summary>
 </cvar>
+-->
+
+<!-- This has moved to Platform/Platform.xml to avoid duplication
 <cvar name="TARGET_ARCH">
 <summary>
 <para>
-Sets the target architecture for the Visual C++ compiler (i.e. the arch
-of the binaries generated by the compiler). If not set, default to
-&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.
-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 &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>
-On Windows, valid target values are
-<literal>x86</literal>,
-<literal>arm</literal>,
-<literal>i386</literal>
-for 32-bit targets and
-<literal>amd64</literal>,
-<literal>arm64</literal>,
-<literal>em64t</literal>,
-<literal>x86_64</literal>
-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>
 </summary>
 </cvar>
+-->
 
 <cvar name="MSVC_UWP_APP">
 <summary>
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
index f48c088..40de496 100644
--- a/doc/generated/functions.gen
+++ b/doc/generated/functions.gen
@@ -428,12 +428,12 @@ Multiple targets can be passed in to a single call to
 Intelligently append values to &consvars; in the &consenv;
 named by <varname>env</varname>.
 The &consvars; and values to add to them are passed as
-<parameter>key=val</parameter> pairs (Python keyword arguments).
+<parameter>key=val</parameter> pairs (&Python; keyword arguments).
 &f-env-Append; is designed to allow adding values
 without normally having to know the data type of an existing &consvar;.
-Regular Python syntax can also be used to manipulate the &consvar;,
+Regular &Python; syntax can also be used to manipulate the &consvar;,
 but for that you must know the type of the &consvar;:
-for example, different Python syntax is needed to combine
+for example, different &Python; syntax is needed to combine
 a list of values with a single string value, or vice versa.
 Some pre-defined &consvars; do have type expectations
 based on how &SCons; will use them,
@@ -544,7 +544,7 @@ described above.
 <para>
 Although most combinations of types work without
 needing to know the details, some combinations
-do not make sense and a Python exception will be raised.
+do not make sense and a &Python; exception will be raised.
 </para>
 
 <para>
@@ -944,7 +944,7 @@ same-named existing construction variables.
 <para>
 An action can be an external command,
 specified as a string,
-or a callable Python object;
+or a callable &Python; object;
 see the manpage section "Action Objects"
 for more complete information.
 Also note that a string specifying an external command
@@ -1149,7 +1149,7 @@ env.Decider('content')
 <para>
 In addition to the above already-available functions, the
 <parameter>function</parameter>
-argument may be a Python function you supply.
+argument may be a &Python; function you supply.
 Such a function must accept the following four arguments:
 </para>
 
@@ -1609,7 +1609,7 @@ may be an Action object
 for an explanation of behavior),
 or it may be a command-line string,
 list of commands,
-or executable Python function,
+or executable &Python; function,
 each of which will be converted
 into an Action object
 and then executed.
@@ -1618,7 +1618,7 @@ Any additional arguments to &f-Execute;
 are passed on to the &f-link-Action; factory function
 which actually creates the Action object.
 The exit value of the command
-or return value of the Python function
+or return value of the &Python; function
 will be returned.
 </para>
 
@@ -1924,7 +1924,7 @@ will also be returned by this function.
     <term><function>Flatten</function>(<parameter>sequence</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Flatten</methodname>(<parameter>sequence</parameter>)</term>
     <listitem><para>
-Takes a sequence (that is, a Python list or tuple)
+Takes a sequence (that is, a &Python; list or tuple)
 that may contain nested sequences
 and returns a flattened list containing
 all of the individual elements in any sequence.
@@ -1932,7 +1932,7 @@ This can be helpful for collecting
 the lists returned by calls to Builders;
 other Builders will automatically
 flatten lists specified as input,
-but direct Python manipulation of
+but direct &Python; manipulation of
 these lists does not.
 </para>
 
@@ -1952,7 +1952,7 @@ objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
 # the Builder will flatten the list automatically:
 Program(source = objects)
 
-# If you need to manipulate the list directly using Python, you need to
+# If you need to manipulate the list directly using &Python;, you need to
 # call Flatten() yourself, or otherwise handle nested lists:
 for object in Flatten(objects):
     print(str(object))
@@ -3780,7 +3780,7 @@ by the chosen
 <para>
 The optional <parameter>dbm_module</parameter>
 argument specifies which
-Python database module to use
+&Python; database module to use
 for reading/writing the file.
 The module must be imported first;
 then the imported module name
@@ -3788,9 +3788,9 @@ is passed as the argument.
 The default is a custom
 <systemitem>SCons.dblite</systemitem>
 module that uses pickled
-Python data structures,
-which works on all Python versions.
-See documentation of the Python
+&Python; data structures,
+which works on all &Python; versions.
+See documentation of the &Python;
 <systemitem>dbm</systemitem> module
 for other available types.
 </para>
@@ -4139,16 +4139,22 @@ they are not added and included in the returned list.
     <term><function>Split</function>(<parameter>arg</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Split</methodname>(<parameter>arg</parameter>)</term>
     <listitem><para>
-Returns a list of file names or other objects.
 If <parameter>arg</parameter> is a string,
-it will be split on strings of white-space characters
-within the string,
-making it easier to write long lists of file names.
-If <parameter>arg</parameter> is already a list,
-the list will be returned untouched.
+splits on whitespace and returns a list of
+strings without whitespace.
+This mode is the most common case,
+and can be used to split a list of filenames
+(for example) rather than having to type them as a
+list of individually quoted words.
+If <parameter>arg</parameter> is a list or tuple
+returns <parameter>arg</parameter> unchanged.
+Use this form to specify strings where whitespace
+should be preserved
+(it is not necessary to call &f-Split; at all in this case,
+but as a convenience it just works as a pass-through
+so you don't have to check whether to call &f-Split; or not).
 If <parameter>arg</parameter> is any other type of object,
-it will be returned as a list
-containing just the object.
+returns a list containing just the object.
 </para>
 
 <para>
@@ -4232,7 +4238,7 @@ to be available for expansion.
 This is usually necessary if you are
 calling
 &f-env-subst;
-from within a Python function used
+from within a &Python; function used
 as an SCons action.
 </para>
 
@@ -4245,12 +4251,11 @@ argument
 may specify a conversion function
 that will be used in place of
 the default.
-For example, if you want Python objects
+For example, if you want &Python; objects
 (including SCons Nodes)
-to be returned as Python objects,
-you can use the Python
-&lambda;
-idiom to pass in an unnamed function
+to be returned as &Python; objects,
+you can use a &Python;
+lambda expression to pass in an unnamed function
 that simply returns its unconverted argument.
 </para>
 
@@ -4378,7 +4383,7 @@ the tool object, previously it did not return
     <term><function>Value</function>(<parameter>value, [built_value], [name]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Value</methodname>(<parameter>value, [built_value], [name]</parameter>)</term>
     <listitem><para>
-Returns a Node object representing the specified Python value.  Value
+Returns a Node object representing the specified &Python; value.  Value
 Nodes can be used as dependencies of targets.  If the result of
 calling
 <function>str</function>(<parameter>value</parameter>)
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index eea6554..8c17084 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -3092,40 +3092,47 @@ is <quote><literal>-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</literal></quote>
       <envar>HOST_ARCH</envar>
     </term>
     <listitem><para>
-        The name of the host hardware architecture used to create the Environment.
-        If a platform is specified when creating the Environment, then
-        that Platform's logic will handle setting this value.
-        This value is immutable, and should not be changed by the user after
-        the Environment is initialized.
-</para>
-    <para>
-Sets the host architecture for the Visual C++ 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.
+        The name of the host hardware architecture.
+        Can be set when creating a &consenv; by passing as a keyword
+        argument in the &f-link-Environment; call; should not be
+        changed otherwise.
+        If not specified in the &f-Environment; call, will be set to
+        the defaults for the particular platform, which is in turn
+        auto-detected unless the <parameter>platform</parameter>
+        argument to &f-Environment; is given.
+        Note the detected value of the architecture may not be identical to
+        that from the &Python; <systemitem>platform.machine</systemitem> method.
 </para>
-
 <para>
-Valid values are the same as for &cv-link-TARGET_ARCH;.
+        On the Windows platform, if the Microsoft Visual C++ compiler
+        is available, &t-link-msvc; tool setup is done using
+        &cv-HOST_ARCH; and &cv-link-TARGET_ARCH;. Changing the values at
+        any later time will not cause the tool to be reinitialized.
+        Valid values for this usage are the same as for &cv-link-TARGET_ARCH;.
 </para>
-
 <para>
-This is currently only used on Windows, but in the future it may be
-used on other OSes as well.
+        On other platforms, this &consvar; is informational and does
+        not currently affect construction activities.
 </para>
-</listitem>
+    </listitem>
   </varlistentry>
   <varlistentry id="cv-HOST_OS">
     <term>
       <envar>HOST_OS</envar>
     </term>
     <listitem><para>
-        The name of the host operating system used to create the Environment.
-        If a platform is specified when creating the Environment, then
-        that Platform's logic will handle setting this value.
-        This value is immutable, and should not be changed by the user after
-        the Environment is initialized.
+        The name of the host operating system.
+        Can be set when creating a &consenv; by passing as a keyword
+        argument in the &f-link-Environment; call; should not be
+        changed otherwise.
+        If not specified in the &f-Environment; call, will be set to
+        the defaults for the particular platform, which is in turn
+        auto-detected unless the <parameter>platform</parameter>
+        argument to &f-Environment; is given.
+</para>
+<para>
+        This &consvar; is informational and does not currently
+        affect construction activities.
 </para>
     </listitem>
   </varlistentry>
@@ -7905,46 +7912,51 @@ for more information).
       <envar>TARGET_ARCH</envar>
     </term>
     <listitem><para>
-        The name of the target hardware architecture for the compiled objects
-        created by this Environment.
-        This defaults to the value of HOST_ARCH, and the user can override it.
-        Currently only set for Win32.
+        The name of the hardware architecture compiled objects
+        created by this &consenv; should target.
+        Can be set when creating a &consenv; by passing as a keyword
+        argument in the &f-link-Environment; call; should not be
+        changed otherwise.
+        If not specified in the &f-Environment; call, will be set to
+        the defaults for the particular platform, which is in turn
+        auto-detected unless the <parameter>platform</parameter>
+        argument to &f-Environment; is given.
+        Defaults to the same value as &cv-link-HOST_ARCH;.
 </para>
-    <para>
-Sets the target architecture for the Visual C++ compiler (i.e. the arch
-of the binaries generated by the compiler). If not set, default to
-&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.
-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 &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>
+        On the Windows platform, if the Microsoft Visual C++ compiler
+        is available, &t-link-msvc; tool setup is done using
+        &cv-link-HOST_ARCH; and &cv-TARGET_ARCH;. Changing the values at
+        any later time will not cause the tool to be reinitialized.
+        Compiled objects will be in the target architecture if
+        the compilation system supports generating for that target.
+        The latest compiler which can fulfill the requirement will
+        be selected, unless a different version is directed by the
+        value of the &cv-link-MSVC_VERSION; &consvar;.
 </para>
-
 <para>
-On Windows, valid target values are
-<literal>x86</literal>,
-<literal>arm</literal>,
-<literal>i386</literal>
-for 32-bit targets and
-<literal>amd64</literal>,
-<literal>arm64</literal>,
-<literal>em64t</literal>,
-<literal>x86_64</literal>
-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.
+        On the Windows/msvc combination, valid target values are
+        <literal>x86</literal>,
+        <literal>arm</literal>,
+        <literal>i386</literal>
+        for 32-bit targets and
+        <literal>amd64</literal>,
+        <literal>arm64</literal>,
+        <literal>em64t</literal>,
+        <literal>x86_64</literal>
+        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.
+        For example, if you want to compile 64-bit binaries, you would set
+        <literal>TARGET_ARCH='x86_64'</literal> when creating the &consenv;.
+</para>
+<para>
+        On other platforms, this &consvar; is informational and does
+        not currently affect construction activities.
 </para>
 </listitem>
   </varlistentry>
@@ -7953,10 +7965,20 @@ For example, if you want to compile 64-bit binaries, you would set
       <envar>TARGET_OS</envar>
     </term>
     <listitem><para>
-        The name of the target operating system for the compiled objects
-        created by this Environment.
-        This defaults to the value of HOST_OS, and the user can override it.
-        Currently only set for Win32.
+        The name of the operating system compiled objects
+        created by this &consenv; should target.
+        Can be set when creating a &consenv; by passing as a keyword
+        argument in the &f-link-Environment; call; should not be
+        changed otherwise.
+        If not specified in the &f-Environment; call, will be set to
+        the defaults for the particular platform, which is in turn
+        auto-detected unless the <parameter>platform</parameter>
+        argument to &f-Environment; is given.
+        Defaults to the same value as &cv-HOST_OS;.
+</para>
+<para>
+        This &consvar; is informational and does not currently
+        affect construction activities.
 </para>
     </listitem>
   </varlistentry>
@@ -7981,15 +8003,45 @@ The suffix used for tar file names.
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-TEMPFILE">
+    <term>
+      <envar>TEMPFILE</envar>
+    </term>
+    <listitem><para>
+A callable object used to handle overly long command line strings,
+since operations which call out to a shell will fail
+if the line is longer than the shell can accept.
+This tends to particularly impact linking.
+The tempfile object stores the command line in a temporary
+file in the appropriate format, and returns
+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-TEMPFILEPREFIX;,
+&cv-link-TEMPFILESUFFIX;,
+&cv-link-TEMPFILEARGJOIN;,
+&cv-link-TEMPFILEDIR;
+and
+&cv-link-TEMPFILEARGESCFUNC;.
+</para>
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-TEMPFILEARGESCFUNC">
     <term>
       <envar>TEMPFILEARGESCFUNC</envar>
     </term>
     <listitem><para>
-A default argument escape function is ``SCons.Subst.quote_spaces``.
-If you need to apply extra operations on a command argument before
-writing to a temporary file(fix Windows slashes, normalize paths, etc.),
-please set `TEMPFILEARGESCFUNC` variable to a custom function. Example::
+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.)
+before writing to the temporary file,
+you can set the &cv-TEMPFILEARGESCFUNC; variable to a custom function.
+Such a function takes a single string argument and returns
+a new string with any modifications applied.
+Example:
 </para>
 
 <example_commands>
@@ -8015,8 +8067,12 @@ env["TEMPFILEARGESCFUNC"] = tempfile_arg_esc_func
       <envar>TEMPFILEARGJOIN</envar>
     </term>
     <listitem><para>
-The string (or character) to be used to join the arguments passed to TEMPFILE when command line exceeds the limit set by &cv-MAXLINELENGTH;.
-The default value is a space. However for MSVC, MSLINK the default is a line seperator characters as defined by os.linesep.
+The string to use to join the arguments passed to
+&cv-link-TEMPFILE; when the command line exceeds the limit set by
+&cv-link-MAXLINELENGTH;.
+The default value is a space.
+However for MSVC, MSLINK the default is a line separator
+as defined by <systemitem>os.linesep</systemitem>.
 Note this value is used literally and not expanded by the subst logic.
 </para>
 </listitem>
@@ -8026,7 +8082,7 @@ Note this value is used literally and not expanded by the subst logic.
       <envar>TEMPFILEDIR</envar>
     </term>
     <listitem><para>
-The directory to create the tempfile in.
+The directory to create the long-lines temporary file in.
 </para>
 </listitem>
   </varlistentry>
@@ -8035,16 +8091,13 @@ The directory to create the tempfile in.
       <envar>TEMPFILEPREFIX</envar>
     </term>
     <listitem><para>
-The prefix for a temporary file used
-to store lines lines longer than $MAXLINELENGTH
-as operations which call out to a shell will fail
-if the line is too long, which particularly
-impacts linking.
-The default is '@', which works for the Microsoft
+The prefix for the name of the temporary file used
+to store command lines exceeding &cv-link-MAXLINELENGTH;.
+The default prefix is <literal>'@'</literal>, which works for the Microsoft
 and GNU toolchains on Windows.
 Set this appropriately for other toolchains,
-for example '-@' for the diab compiler
-or '-via' for ARM toolchain.
+for example <literal>'-@'</literal> for the diab compiler
+or <literal>'-via'</literal> for ARM toolchain.
 </para>
 </listitem>
   </varlistentry>
@@ -8053,11 +8106,11 @@ or '-via' for ARM toolchain.
       <envar>TEMPFILESUFFIX</envar>
     </term>
     <listitem><para>
-The suffix used for the temporary file name
-used for long command lines. The name should
-include the dot ('.') if one is wanted as
+The suffix for the name of the temporary file used
+to store command lines exceeding &cv-link-MAXLINELENGTH;.
+The suffix shouldinclude the dot ('.') if one is wanted as
 it will not be added automatically.
-The default is '.lnk'.
+The default is <filename>.lnk</filename>.
 </para>
 </listitem>
   </varlistentry>
diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod
index 08aa21d..e54b7d8 100644
--- a/doc/generated/variables.mod
+++ b/doc/generated/variables.mod
@@ -562,6 +562,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-TARGET_OS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$TARGET_OS</envar>">
 <!ENTITY cv-TARGETS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$TARGETS</envar>">
 <!ENTITY cv-TARSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$TARSUFFIX</envar>">
+<!ENTITY cv-TEMPFILE "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$TEMPFILE</envar>">
 <!ENTITY cv-TEMPFILEARGESCFUNC "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$TEMPFILEARGESCFUNC</envar>">
 <!ENTITY cv-TEMPFILEARGJOIN "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$TEMPFILEARGJOIN</envar>">
 <!ENTITY cv-TEMPFILEDIR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$TEMPFILEDIR</envar>">
@@ -1215,6 +1216,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-link-TARGET_OS "<link linkend='cv-TARGET_OS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$TARGET_OS</envar></link>">
 <!ENTITY cv-link-TARGETS "<link linkend='cv-TARGETS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$TARGETS</envar></link>">
 <!ENTITY cv-link-TARSUFFIX "<link linkend='cv-TARSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$TARSUFFIX</envar></link>">
+<!ENTITY cv-link-TEMPFILE "<link linkend='cv-TEMPFILE' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$TEMPFILE</envar></link>">
 <!ENTITY cv-link-TEMPFILEARGESCFUNC "<link linkend='cv-TEMPFILEARGESCFUNC' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$TEMPFILEARGESCFUNC</envar></link>">
 <!ENTITY cv-link-TEMPFILEARGJOIN "<link linkend='cv-TEMPFILEARGJOIN' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$TEMPFILEARGJOIN</envar></link>">
 <!ENTITY cv-link-TEMPFILEDIR "<link linkend='cv-TEMPFILEDIR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$TEMPFILEDIR</envar></link>">