Tweak User Guide environment descriptions

Reword/clarify the section on `AllowSubstExceptions` and the sidebar
on Python dictionaries.  Add an additonal piece to `env.Replace`.

Also, some entity replacements, and more explicit `id` tags added to
`section` elements.

One unittest change to make sure passing a dict to `env.Replace` works.

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

2 files changed, 18 insertions, 12 deletions

diff --git a/SCons/EnvironmentTests.py b/SCons/EnvironmentTests.py
index 6a69e3c..361dda9 100644
--- a/SCons/EnvironmentTests.py
+++ b/SCons/EnvironmentTests.py
@@ -1037,7 +1037,8 @@ class BaseTestCase(unittest.TestCase,TestEnvironmentFixture):
     # underlying method it tests (Environment.BuilderWrapper.execute())
     # is necessary, but we're leaving the code here for now in case
     # that's mistaken.
-    def _DO_NOT_test_Builder_execs(self) -> None:
+    @unittest.skip("BuilderWrapper.execute method not needed")
+    def test_Builder_execs(self) -> None:
         """Test Builder execution through different environments
 
         One environment is initialized with a single
@@ -1291,10 +1292,14 @@ env4.builder1.env, env3)
         ]
         assert flags == expect, flags
 
-        env.Replace(F77PATH = [ 'foo', '$FOO/bar', blat ],
-                    INCPREFIX = 'foo ',
-                    INCSUFFIX = 'bar',
-                    FOO = 'baz')
+        # do a Replace using the dict form
+        newvalues = {
+            "F77PATH": ['foo', '$FOO/bar', blat],
+            "INCPREFIX": 'foo ',
+            "INCSUFFIX": 'bar',
+            "FOO": 'baz',
+        }
+        env.Replace(**newvalues)
         flags = env.subst_list('$_F77INCFLAGS', 1)[0]
         expect = [ '$(',
                    normalize_path('foo'),
diff --git a/SCons/Subst.xml b/SCons/Subst.xml
index 00ed135..4ac4f7d 100644
--- a/SCons/Subst.xml
+++ b/SCons/Subst.xml
@@ -31,16 +31,16 @@ This file is processed by the bin/SConsDoc.py module.
 </arguments>
 <summary>
 <para>
-Specifies the exceptions that will be allowed
-when expanding construction variables.
+Specifies the exceptions that will be ignored
+when expanding &consvars;.
 By default,
-any construction variable expansions that generate a
-<literal>NameError</literal>
+any &consvar; expansions that generate a
+&NameError;
 or
-<literal>IndexError</literal>
+&IndexError;
 exception will expand to a
 <literal>''</literal>
-(an empty string) and not cause scons to fail.
+(an empty string) and not cause &scons; to fail.
 All exceptions not in the specified list
 will generate an error message
 and terminate processing.
@@ -51,7 +51,8 @@ If
 &f-AllowSubstExceptions;
 is called multiple times,
 each call completely overwrites the previous list
-of allowed exceptions.
+of ignored exceptions.
+Calling it with no arguments means no exceptions will be ignored.
 </para>
 
 <para>