Rework wording of {HOST,TAGET}_{ARCH_OS}.

Also some wording tweaks on environment creation in manpage;

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

4 files changed, 153 insertions, 150 deletions

diff --git a/SCons/Environment.py b/SCons/Environment.py
index 4868e75..7713bb7 100644
--- a/SCons/Environment.py
+++ b/SCons/Environment.py
@@ -970,13 +970,13 @@ class Base(SubstitutionEnvironment):
         self._dict['PLATFORM'] = str(platform)
         platform(self)
 
-        self._dict['HOST_OS']      = self._dict.get('HOST_OS',None)
-        self._dict['HOST_ARCH']    = self._dict.get('HOST_ARCH',None)
-
-        # Now set defaults for TARGET_{OS|ARCH}
-        self._dict['TARGET_OS']      = self._dict.get('TARGET_OS',None)
-        self._dict['TARGET_ARCH']    = self._dict.get('TARGET_ARCH',None)
+        # these should be set by the platform, backstop just in case
+        self._dict['HOST_OS'] = self._dict.get('HOST_OS', None)
+        self._dict['HOST_ARCH'] = self._dict.get('HOST_ARCH', None)
 
+        # these are not currently set by the platform, give them a default
+        self._dict['TARGET_OS'] = self._dict.get('TARGET_OS', None)
+        self._dict['TARGET_ARCH'] = self._dict.get('TARGET_ARCH', None)
 
         # Apply the passed-in and customizable variables to the
         # environment before calling the tools, because they may use
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index a21a8d7..43e3b25 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -3090,14 +3090,12 @@ 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).
+returns the list or tuple unchanged.
 If <parameter>arg</parameter> is any other type of object,
 returns a list containing just the object.
+These non-string cases do not actually do any spliting,
+but allow an argument variable to be passed to
+&f-Split; without having to first check its type.
 </para>
 
 <para>
@@ -3108,9 +3106,9 @@ Example:
 files = Split("f1.c f2.c f3.c")
 files = env.Split("f4.c f5.c f6.c")
 files = Split("""
-       f7.c
-       f8.c
-       f9.c
+    f7.c
+    f8.c
+    f9.c
 """)
 </example_commands>
 </summary>
@@ -3123,14 +3121,14 @@ files = Split("""
 <summary>
 <para>
 Performs construction variable interpolation
-on the specified string or sequence argument
-<parameter>input</parameter>.
+on <parameter>input</parameter>,
+which can be a string or a sequence.
 </para>
 
 <para>
 By default,
 leading or trailing white space will
-be removed from the result.
+be removed from the result,
 and all sequences of white space
 will be compressed to a single space character.
 Additionally, any
@@ -3149,9 +3147,8 @@ The
 <parameter>raw</parameter>
 argument may be set to
 <literal>2</literal>
-if you want to strip
-all characters between
-any
+if you want to additionally discard
+all characters between any
 <literal>$(</literal>
 and
 <literal>$)</literal>
diff --git a/SCons/Platform/Platform.xml b/SCons/Platform/Platform.xml
index ef516f1..08199f4 100644
--- a/SCons/Platform/Platform.xml
+++ b/SCons/Platform/Platform.xml
@@ -100,142 +100,135 @@ The suffix used for (static) object file names.
 </cvar>
 
 <cvar name="PLATFORM">
-<summary>
-<para>
-The name of the platform used to create the Environment.  If no platform is
-specified when the Environment is created,
-&scons;
-autodetects the platform.
-</para>
-
-<example_commands>
-env = Environment(tools = [])
+  <summary>
+    <para>
+      The name of the platform used to create this &consenv;.
+      &SCons; sets this when initializing the platform,
+      which by default is auto-detected
+      (see the <parameter>platform</parameter>
+      argument to &f-link-Environment;).
+    </para>
+
+    <example_commands>
+env = Environment(tools=[])
 if env['PLATFORM'] == 'cygwin':
     Tool('mingw')(env)
 else:
     Tool('msvc')(env)
-</example_commands>
-</summary>
+    </example_commands>
+  </summary>
 </cvar>
 
 <cvar name="HOST_OS">
-    <summary>
-<para>
-        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>
+  <summary>
+    <para>
+      The name of the host operating system for the platform
+      used to create this &consenv;.
+      The platform code sets this when initializing
+      (see &cv-link-PLATFORM; and the
+      <parameter>platform</parameter> argument to &f-link-Environment;).
+    </para>
+    <para>
+      Should be considered immutable. 
+      &cv-HOST_OS; is not currently used by &SCons;,
+      but the option is reserved to do so in future
+    </para>
+  </summary>
 </cvar>
 
 <cvar name="TARGET_OS">
-    <summary>
-<para>
-        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>
+  <summary>
+    <para>
+      The name of the operating system that objects
+      created using this &consenv; should target.
+      Can be set when creating a &consenv; by passing as a keyword
+      argument in the &f-link-Environment; call;.
+    </para>
+    <para>
+      &cv-TARGET_OS; is not currently used by &SCons;
+      but the option is reserved to do so in future
+    </para>
+  </summary>
 </cvar>
 
 <cvar name="HOST_ARCH">
-    <summary>
-<para>
-        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>
+  <summary>
+    <para>
+      The name of the host hardware architecture
+      used to create this &consenv;.
+      The platform code sets this when initializing
+      (see &cv-link-PLATFORM; and the
+      <parameter>platform</parameter> argument to &f-link-Environment;).
+      Note the detected name of the architecture may not be identical to
+      that returned by the &Python;
+      <systemitem>platform.machine</systemitem> method.
+    </para>
+    <para>
+      On the <literal>win32</literal> 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 host arch values are
+      <literal>x86</literal> and <literal>arm</literal>
+      for 32-bit hosts and
+      <literal>amd64</literal> and <literal>x86_64</literal>
+      for 64-bit hosts.
+    </para>
+    <para>
+      Should be considered immutable. 
+      &cv-HOST_ARCH; is not currently used by other platforms,
+      but the option is reserved to do so in future
+    </para>
+  </summary>
 </cvar>
 
 <cvar name="TARGET_ARCH">
-    <summary>
-<para>
-        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>
-        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>
+  <summary>
+    <para>
+      The name of the hardware architecture that objects
+      created using this &consenv; should target.
+      Can be set when creating a &consenv; by passing as a keyword
+      argument in the &f-link-Environment; call.
+    </para>
+    <para>
+      On the <literal>win32</literal> 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;.
+      If a value is not specified,
+      will be set to the same value as &cv-link-HOST_ARCH;.
+      Changing the value after the environment is initialized
+      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 win32/msvc combination, valid target arch values are
+      <literal>x86</literal>,
+      <literal>arm</literal>,
+      <literal>i386</literal>
+      for 32-bit targets and
+      <literal>amd64</literal>,
+      <literal>arm64</literal>,
+      <literal>x86_64</literal>
+      and <literal>ia64</literal> (Itanium)
+      for 64-bit targets.
+      For example, if you want to compile 64-bit binaries, you would set
+      <literal>TARGET_ARCH='x86_64'</literal> when creating the &consenv;.
+      Note that not all target architectures are
+      supported for all Visual Studio / MSVC versions.
+      Check the relevant Microsoft documentation.
+    </para>
+    <para>
+      &cv-TARGET_ARCH; is not currently used by other compilation tools,
+      but the option is reserved to do so in future
+    </para>
+  </summary>
 </cvar>
 
 <cvar name="PROGPREFIX">
@@ -342,7 +335,7 @@ or <literal>'-via'</literal> for ARM toolchain.
 <para>
 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
+The suffix should include the dot ('.') if one is wanted as
 it will not be added automatically.
 The default is <filename>.lnk</filename>.
 </para>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 1f53892..f5c77c2 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -2316,8 +2316,8 @@ env = Environment()
 <para>&Consenv; attributes called
 <firstterm>&ConsVars;</firstterm> may be set
 either by specifying them as keyword arguments when the object is created
-or by assigning them a value after the object is created. These two are
-nominally equivalent:</para>
+or by assigning them a value after the object is created.
+These two are nominally equivalent:</para>
 
 <programlisting language="python">
 env = Environment(FOO='foo')
@@ -2326,13 +2326,26 @@ env['FOO'] = 'foo'
 
 <!--TODO: how can the user tell which settings are init-only? -->
 <para>Note that certain settings which affect tool detection are
-referenced only during initialization, and so need to
-be supplied as part of the call to &f-link-Environment;.
-For example, setting &cv-link-MSVC_VERSION; in the &f-Environment;
-call selects the version of Microsoft Visual C++ you wish to use,
-but setting it after the &consenv; is constructed has no effect.
+referenced only when the tools are initializided,
+so you either need either to supply them as part of the call to
+&f-link-Environment;, or defer tool initialization.
+For example, initializing the Microsoft Visual C++ version you wish to use:
 </para>
 
+<programlisting language="python">
+# initializes msvc to v14.1
+env = Environment(MSVC_VERSION="14.1")
+
+env = Environment()
+# msvc tool was initialized to default, does not reinitialize
+env['MSVC_VERSION'] = "14.1"
+
+env = Environment(tools=[])
+env['MSVC_VERSION'] = "14.1"
+# msvc tool initialization was deferred, so will pick up new value
+env.Tool('default')
+</programlisting>
+
 <para>As a convenience,
 &consvars; may also be set or modified by the
 <parameter>parse_flags</parameter>
@@ -2440,7 +2453,7 @@ may bypass settings that should happen for the host system
 and should be used with care.
 It is most useful in the case where the platform is an alternative for
 the one that would be auto-detected,
-such as <literal>cygwin</literal>
+such as <literal>platform="cygwin"</literal>
 on a system which would otherwise
 identify as <literal>win32</literal>.
 </para>