Some small doc fiddles [ci skip]

* Use os.environ.copy() in examples - better not to get the
  Python proxy class that is os.environ, and instead a real dict.
* Fix spelling on a python dict method: set_default -> setdefault
* Update some wording on prepending in the user guide (where it
  still said "append to the beginning")
* Change the rather oblique note in the recently modified section
  on Append of values to CPPDEFINES with something more explicit.
* And, modify the sphinx config to get the version from SCons
  rather than hardcoding.

Fixes #3867

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

5 files changed, 29 insertions, 27 deletions

diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index a185815..cfa99db 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -87,7 +87,7 @@ Note that, by default,
 &scons;
 does
 <emphasis>not</emphasis>
-propagate the environment in force when you
+propagate the environment in effect when you
 execute
 &scons;
 to the commands used to build target files.
@@ -108,7 +108,7 @@ you must do so explicitly:
 
 <example_commands>
 import os
-env = Environment(ENV = os.environ)
+env = Environment(ENV=os.environ.copy())
 </example_commands>
 
 <para>
@@ -126,7 +126,7 @@ as the invoking shell (or other process):
 
 <example_commands>
 import os
-env = Environment(ENV = {'PATH' : os.environ['PATH']})
+env = Environment(ENV={'PATH': os.environ['PATH']})
 </example_commands>
 </summary>
 </cvar>
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index a16efae..1ac53fe 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -1636,7 +1636,7 @@ you must do so explicitly:
 
 <example_commands>
 import os
-env = Environment(ENV = os.environ)
+env = Environment(ENV=os.environ.copy())
 </example_commands>
 
 <para>
@@ -1654,7 +1654,7 @@ as the invoking shell (or other process):
 
 <example_commands>
 import os
-env = Environment(ENV = {'PATH' : os.environ['PATH']})
+env = Environment(ENV={'PATH': os.environ['PATH']})
 </example_commands>
 </listitem>
   </varlistentry>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 8da4cc9..57bd209 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -269,7 +269,7 @@ complete external environment:</para>
 
 <programlisting language="python">
 import os
-env = Environment(ENV=os.environ)
+env = Environment(ENV=os.environ.copy())
 </programlisting>
 
 <para>This comes at the expense of making your build
@@ -2574,7 +2574,7 @@ A nested tool name uses a dot to represent a directory separator</para>
 
 <programlisting language="python">
 # namespaced builder
-env = Environment(ENV=os.environ, tools=['SubDir1.SubDir2.SomeTool'])
+env = Environment(ENV=os.environ.copy(), tools=['SubDir1.SubDir2.SomeTool'])
 env.SomeTool(targets, sources)
 
 # Search Paths
@@ -5060,7 +5060,7 @@ arguments must not both be used for the same Builder.</para>
   <varlistentry>
   <term><parameter>prefix</parameter></term>
   <listitem>
-<para>The prefix that will be prepended to the target file name.
+<para>The prefix to prepend to the target file name.
 <parameter>prefix</parameter> may be:</para>
 
   <itemizedlist>
@@ -5098,13 +5098,13 @@ b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
   <varlistentry>
   <term><parameter>suffix</parameter></term>
   <listitem>
-<para>The suffix that will be appended to the target file name.
+<para>The suffix to append to the target file name.
 This may be specified in the same manner as the prefix above.
 If the suffix is a string, then
 &scons;
-will append a '.' to the beginning of the suffix if it's not already
-there.  The string returned by callable object (or obtained from the
-dictionary) is untouched and must append its own '.'  to the beginning
+prepends a '.' to the suffix if it's not already there.
+The string returned by the callable object (or obtained from the
+dictionary) is untouched and you need to manually prepend a '.'
 if one is desired.</para>
 
 <programlisting language="python">
@@ -6961,7 +6961,7 @@ such as Linux or UNIX,
 <filename>.F</filename>
 as a Fortran source file
 that is to be first run through
-the standard C preprocessor, 
+the standard C preprocessor,
 while the lower-case version is not.
 This matches the convention of <command>gfortran</command>,
 which may also be followed by other Fortran compilers.
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
index 27e18b7..517af50 100644
--- a/doc/sphinx/conf.py
+++ b/doc/sphinx/conf.py
@@ -76,11 +76,12 @@ author = 'SCons Project Team'
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# TODO: fill these in externally
+from SCons import __version__
+# The full version, including alpha/beta/rc tags:
+release = __version__
 # The short X.Y version.
-version = '4.1'
-# The full version, including alpha/beta/rc tags.
-release = '4.1.0'
+major, minor, _ = __version__.split('.')
+version = '.'.join([major, minor])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 2dae752..3c3eeae 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -1383,7 +1383,7 @@ int main() { }
       set to a value only if the construction environment
       does not already have that variable defined
       You can do this with the &f-link-env-SetDefault; method,
-      which behaves similarly to the <function>set_default</function>
+      which behaves similarly to the <function>setdefault</function>
       method of &Python; dictionary objects:
 
       </para>
@@ -1431,10 +1431,11 @@ int main() { }
 
       <para>
 
-      &SCons; then generates the preprocessor define arguments from &CPPDEFINES; values with the correct
-      prefix/suffix. For example on Linux or POSIX, the following arguments would be generated:
-      <literal>-DMY_VALUE</literal> and
-      <literal>-DLAST</literal>
+      Note &cv-link-CPPDEFINES; is the preferred way to set preprocessor defines,
+      as &SCons; will generate the command line arguments using the correct
+      prefix/suffix for the platform, leaving the usage portable.
+      If you use &cv-link-CCFLAGS; and &cv-link-SHCCFLAGS;,
+      you need to include them in their final form, which is less portable.
 
       </para>
 
@@ -1487,7 +1488,7 @@ print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
 
       <para>
 
-      Some times it's useful to add a new value
+      Sometimes it's useful to add a new value
       only if the existing construction variable
       doesn't already contain the value.
       This can be done using the &f-link-env-AppendUnique; method:
@@ -1510,11 +1511,11 @@ env.AppendUnique(CCFLAGS=['-g'])
     </section>
 
     <section>
-    <title>Appending to the Beginning of Values:  the &Prepend; Method</title>
+    <title>Prepending to the Beginning of Values:  the &Prepend; Method</title>
 
       <para>
 
-      You can append a value to the beginning of
+      You can prepend a value to the beginning of
       an existing construction variable
       using the &f-link-env-Prepend; method:
 
@@ -1912,7 +1913,7 @@ env = Environment(ENV={'PATH': os.environ['PATH']})
 
       <sconstruct>
 import os
-env = Environment(ENV=os.environ)
+env = Environment(ENV=os.environ.copy())
       </sconstruct>
 
       <para>
@@ -1959,7 +1960,7 @@ env = Environment(ENV=os.environ)
       </para>
 
       <sconstruct>
-env = Environment(ENV=os.environ)
+env = Environment(ENV=os.environ.copy())
 env.PrependENVPath('PATH', '/usr/local/bin')
 env.AppendENVPath('LIB', '/usr/local/lib')
       </sconstruct>