Tweak some things about Command() docs

Adjust the description of the Command function (and builder entry),
mainly to try out new terminology.  We've said it's not really a builder,
but it feels better to me to admit it is *exactly* a builder call, just
not to one of the existing named builders. So the term introduced is
"anonymous builder". Changes in docstring for Command, too, plus a
little tweak to kwarg processing.

This change actually started with reformatting some examples in the
manpage, which used Command, which used the chdir argument which didn't
seem to be mentioned in the description of how to use Command, which
lists four keyword args and says all the rest are treated as construction
variable settings (not true for chdir, which isn't one of the four).
That led to thinking about rewording.

The original code reformatting changes, no longer directly related to the
current change subject, are left in just because they seem low burden,
tough could back them out if it makes reviewing to hard.

A couple of other small tweaks:

* some places referred to a section named "File and Directory Nodes"
  but it's no longer named that.  Actual links to the section updated
  fine when it was renamed, but in Environment.xml, which produces shared
  content, you can't use manpage-specific links, so the _textual_
  references needed updating.
* the code example for a warning was moved inside the warning -
  the effect on output is just an indent to match the warning.
* Configure used both terms "custom checks" and "custom tests", now
  only the former; plus a link reference added.

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

9 files changed, 290 insertions, 234 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 0a36b94..3fe676a 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -70,6 +70,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       on a given page *before* the submodule docs, not after. Also
       tweaked the Util package doc build so it's structured more like the
       other packages (a missed part of the transition when it was split).
+    - Updated manpage description of Command "builder" and function.
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700
diff --git a/RELEASE.txt b/RELEASE.txt
index 6841210..92e31ab 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -74,6 +74,7 @@ DOCUMENTATION
 - Update manpage and user guide for Variables usage.
 - Restructured API Docs build so main package contents are listed
   before contents of package submodules.
+- Updated manpage description of Command "builder" and function.
 
 
 
diff --git a/SCons/Builder.py b/SCons/Builder.py
index 75cebc0..3efcc82 100644
--- a/SCons/Builder.py
+++ b/SCons/Builder.py
@@ -387,7 +387,7 @@ class BuilderBase:
                         target_scanner = None,
                         source_scanner = None,
                         emitter = None,
-                        multi: int = 0,
+                        multi: bool = False,
                         env = None,
                         single_source: bool = False,
                         name = None,
diff --git a/SCons/Environment.py b/SCons/Environment.py
index 2def741..5bf763d 100644
--- a/SCons/Environment.py
+++ b/SCons/Environment.py
@@ -2208,52 +2208,44 @@ class Base(SubstitutionEnvironment):
         return SCons.SConf.SConf(*nargs, **nkw)
 
     def Command(self, target, source, action, **kw):
-        """Builds the supplied target files from the supplied
-        source files using the supplied action.  Action may
-        be any type that the Builder constructor will accept
-        for an action."""
+        """Set up a one-off build command.
+
+        Builds *target* from *source* using *action*, which may be
+        be any type that the Builder factory will accept for an action.
+        Generates an anonymous builder and calls it, to add the details
+        to the build graph. The builder is not named, added to ``BUILDERS``,
+        or otherwise saved.
+
+        Recognizes the :func:`~SCons.Builder.Builder` keywords
+        ``source_scanner``, ``target_scanner``, ``source_factory`` and
+        ``target_factory``.  All other arguments from *kw* are passed on
+        to the builder when it is called.
+        """
+        # Build a kwarg dict for the builder construction
         bkw = {
             'action': action,
             'target_factory': self.fs.Entry,
             'source_factory': self.fs.Entry,
         }
-        # source scanner
-        try:
-            bkw['source_scanner'] = kw['source_scanner']
-        except KeyError:
-            pass
-        else:
-            del kw['source_scanner']
-
-        # target scanner
-        try:
-            bkw['target_scanner'] = kw['target_scanner']
-        except KeyError:
-            pass
-        else:
-            del kw['target_scanner']
-
-        # source factory
-        try:
-            bkw['source_factory'] = kw['source_factory']
-        except KeyError:
-            pass
-        else:
-            del kw['source_factory']
 
-        # target factory
-        try:
-            bkw['target_factory'] = kw['target_factory']
-        except KeyError:
-            pass
-        else:
-            del kw['target_factory']
+        # Recognize these kwargs for the builder construction and take
+        # them out of the args for the subsequent builder call.
+        for arg in [
+            'source_scanner',
+            'target_scanner',
+            'source_factory',
+            'target_factory',
+        ]:
+            try:
+                bkw[arg] = kw.pop(arg)
+            except KeyError:
+                pass
 
         bld = SCons.Builder.Builder(**bkw)
         return bld(self, target, source, **kw)
 
     def Depends(self, target, dependency):
-        """Explicity specify that 'target's depend on 'dependency'."""
+        """Explicity specify that *target* depends on *dependency*."""
         tlist = self.arg2nodes(target, self.fs.Entry)
         dlist = self.arg2nodes(dependency, self.fs.Entry)
         for t in tlist:
@@ -2281,7 +2273,7 @@ class Base(SubstitutionEnvironment):
         return self.fs.PyPackageDir(s)
 
     def NoClean(self, *targets):
-        """Tags a target so that it will not be cleaned by -c"""
+        """Tag target(s) so that it will not be cleaned by -c."""
         tlist = []
         for t in targets:
             tlist.extend(self.arg2nodes(t, self.fs.Entry))
@@ -2290,7 +2282,7 @@ class Base(SubstitutionEnvironment):
         return tlist
 
     def NoCache(self, *targets):
-        """Tags a target so that it will not be cached"""
+        """Tag target(s) so that it will not be cached."""
         tlist = []
         for t in targets:
             tlist.extend(self.arg2nodes(t, self.fs.Entry))
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index da8a192..5f152f2 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -1125,15 +1125,16 @@ wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
 <builder name="Command">
 <summary>
 <para>
-The &b-Command; "Builder" is actually
-a function that looks like a Builder,
-but takes a required third argument, which is the
-action to take to construct the target
-from the source, used for "one-off" builds
-where a full builder is not needed.
-Thus it does not follow the builder
-calling rules described at the start of this section.
-See instead the &f-link-Command; function description
+There is actually no Builder named &Command;,
+rather the term "Command Builder" refers to
+a function which, on each call, creates and calls
+an anonymous Builder.
+This is useful for "one-off" builds
+where a full Builder is not needed.
+Since the anonymous Builder is never hooked
+into the standard Builder framework,
+an Action must always be specfied.
+See the &f-link-Command; function description
 for the calling syntax and details.
 </para>
 </summary>
@@ -1145,49 +1146,69 @@ for the calling syntax and details.
 </arguments>
 <summary>
 <para>
-Executes a specific <parameter>action</parameter>
-(or list of actions)
-to build a <parameter>target</parameter> file or files
-from a <parameter>source</parameter> file or files.
-This is more convenient
-than defining a separate Builder object
-for a single special-case build.
+Creates an anonymous builder and calls it,
+thus recording <parameter>action</parameter>
+to build <parameter>target</parameter>
+from <parameter>source</parameter>
+into the dependency tree.
+This can be more convenient for a single special-case build
+than having to define and add a new named Builder.
 </para>
 
 <para>
 The
-&Command; function accepts
-<parameter>source_scanner</parameter>,
-<parameter>target_scanner</parameter>,
-<parameter>source_factory</parameter>, and
-<parameter>target_factory</parameter>
-keyword arguments. These arguments can
-be used to specify
-a Scanner object
-that will be used to apply a custom
-scanner for a source or target.
+&Command; function accepts the
+<parameter>source_scanner</parameter> and
+<parameter>target_scanner</parameter>
+keyword arguments which are used to specify
+custom scanners for the specified sources or targets.
+The value must be a Scanner object.
 For example, the global
 <literal>DirScanner</literal>
 object can be used
 if any of the sources will be directories
 that must be scanned on-disk for
 changes to files that aren't
-already specified in other Builder of function calls.
-The <parameter>*_factory</parameter> arguments take a factory function that
-&Command; will use to turn any sources or targets
-specified as strings into SCons Nodes.
+already specified in other Builder or function calls.
+</para>
+
+<para>
+The
+&Command; function also accepts the
+<parameter>source_factory</parameter> and
+<parameter>target_factory</parameter>
+keyword arguments which are used to specify
+factory functions to create &SCons; Nodes
+from any sources or targets specified as strings.
+If any sources or targets are already Node objects,
+they are not further transformed even if
+a factory is specified for them.
+The default for each is the &Entry; factory.
+</para>
+
+<para>
+These four arguments, if given, are used
+in the creation of the Builder.
+Other Builder-specific keyword arguments
+are not recognized as such.
 See the manpage section "Builder Objects"
 for more information about how these
 arguments work in a Builder.
 </para>
 
 <para>
-Any other keyword arguments specified override any
-same-named existing construction variables.
+Any remaining keyword arguments are passed on to the
+generated builder when it is called,
+and behave as described in the manpage section "Builder Methods",
+in short:
+recognized arguments have their specified meanings,
+while the rest are used to override
+any same-named existing &consvars;
+from the &consenv;.
 </para>
 
 <para>
-An action can be an external command,
+<parameter>action</parameter> can be an external command,
 specified as a string,
 or a callable &Python; object;
 see the manpage section "Action Objects"
@@ -1649,7 +1670,7 @@ would supply a string as a directory name
 to a Builder method or function.
 Directory Nodes have attributes and methods
 that are useful in many situations;
-see manpage section "File and Directory Nodes"
+see manpage section "Filesystem Nodes"
 for more information.
 </para>
 </summary>
@@ -1849,7 +1870,7 @@ would supply a string as a file name
 to a Builder method or function.
 File Nodes have attributes and methods
 that are useful in many situations;
-see manpage section "File and Directory Nodes"
+see manpage section "Filesystem Nodes"
 for more information.
 </para>
 </summary>
diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
index 45b4711..4febbcf 100644
--- a/doc/generated/builders.gen
+++ b/doc/generated/builders.gen
@@ -39,15 +39,16 @@ env.CFile(target='bar', source='bar.y')
     <term><function>Command</function>()</term>
     <term><replaceable>env</replaceable>.<methodname>Command</methodname>()</term>
     <listitem><para>
-The &b-Command; "Builder" is actually
-a function that looks like a Builder,
-but takes a required third argument, which is the
-action to take to construct the target
-from the source, used for "one-off" builds
-where a full builder is not needed.
-Thus it does not follow the builder
-calling rules described at the start of this section.
-See instead the &f-link-Command; function description
+There is actually no Builder named &Command;,
+rather the term "Command Builder" refers to
+a function which, on each call, creates and calls
+an anonymous Builder.
+This is useful for "one-off" builds
+where a full Builder is not needed.
+Since the anonymous Builder is never hooked
+into the standard Builder framework,
+an Action must always be specfied.
+See the &f-link-Command; function description
 for the calling syntax and details.
 </para>
 </listitem>
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
index 6fd0bb1..4a5a391 100644
--- a/doc/generated/functions.gen
+++ b/doc/generated/functions.gen
@@ -1027,49 +1027,69 @@ wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
     <term><function>Command</function>(<parameter>target, source, action, [key=val, ...]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Command</methodname>(<parameter>target, source, action, [key=val, ...]</parameter>)</term>
     <listitem><para>
-Executes a specific <parameter>action</parameter>
-(or list of actions)
-to build a <parameter>target</parameter> file or files
-from a <parameter>source</parameter> file or files.
-This is more convenient
-than defining a separate Builder object
-for a single special-case build.
+Creates an anonymous builder and calls it,
+thus recording <parameter>action</parameter>
+to build <parameter>target</parameter>
+from <parameter>source</parameter>
+into the dependency tree.
+This can be more convenient for a single special-case build
+than having to define and add a new named Builder.
 </para>
 
 <para>
 The
-&Command; function accepts
-<parameter>source_scanner</parameter>,
-<parameter>target_scanner</parameter>,
-<parameter>source_factory</parameter>, and
-<parameter>target_factory</parameter>
-keyword arguments. These arguments can
-be used to specify
-a Scanner object
-that will be used to apply a custom
-scanner for a source or target.
+&Command; function accepts the
+<parameter>source_scanner</parameter> and
+<parameter>target_scanner</parameter>
+keyword arguments which are used to specify
+custom scanners for the specified sources or targets.
+The value must be a Scanner object.
 For example, the global
 <literal>DirScanner</literal>
 object can be used
 if any of the sources will be directories
 that must be scanned on-disk for
 changes to files that aren't
-already specified in other Builder of function calls.
-The <parameter>*_factory</parameter> arguments take a factory function that
-&Command; will use to turn any sources or targets
-specified as strings into SCons Nodes.
+already specified in other Builder or function calls.
+</para>
+
+<para>
+The
+&Command; function also accepts the
+<parameter>source_factory</parameter> and
+<parameter>target_factory</parameter>
+keyword arguments which are used to specify
+factory functions to create &SCons; Nodes
+from any sources or targets specified as strings.
+If any sources or targets are already Node objects,
+they are not further transformed even if
+a factory is specified for them.
+The default for each is the &Entry; factory.
+</para>
+
+<para>
+These four arguments, if given, are used
+in the creation of the Builder.
+Other Builder-specific keyword arguments
+are not recognized as such.
 See the manpage section "Builder Objects"
 for more information about how these
 arguments work in a Builder.
 </para>
 
 <para>
-Any other keyword arguments specified override any
-same-named existing construction variables.
+Any remaining keyword arguments are passed on to the
+generated builder when it is called,
+and behave as described in the manpage section "Builder Methods",
+in short:
+recognized arguments have their specified meanings,
+while the rest are used to override
+any same-named existing &consvars;
+from the &consenv;.
 </para>
 
 <para>
-An action can be an external command,
+<parameter>action</parameter> can be an external command,
 specified as a string,
 or a callable &Python; object;
 see the manpage section "Action Objects"
@@ -1614,7 +1634,7 @@ would supply a string as a directory name
 to a Builder method or function.
 Directory Nodes have attributes and methods
 that are useful in many situations;
-see manpage section "File and Directory Nodes"
+see manpage section "Filesystem Nodes"
 for more information.
 </para>
 </listitem>
@@ -1937,7 +1957,7 @@ would supply a string as a file name
 to a Builder method or function.
 File Nodes have attributes and methods
 that are useful in many situations;
-see manpage section "File and Directory Nodes"
+see manpage section "Filesystem Nodes"
 for more information.
 </para>
 </listitem>
@@ -2545,6 +2565,15 @@ processed prior to the &f-GetOption; call in the &SConscript; files.
 </informaltable>
 </listitem>
   </varlistentry>
+  <varlistentry id="f-GetSConsVersion">
+    <term><function>GetSConsVersion</function>()</term>
+    <listitem><para>
+Returns the current SCons version in the form of a Tuple[int, int, int],
+representing the major, minor, and revision values respectively.
+<emphasis>Added in 4.7.1</emphasis>.
+</para>
+</listitem>
+  </varlistentry>
   <varlistentry id="f-Glob">
     <term><function>Glob</function>(<parameter>pattern, [ondisk=True, source=False, strings=False, exclude=None]</parameter>)</term>
     <term><replaceable>env</replaceable>.<methodname>Glob</methodname>(<parameter>pattern, [ondisk=True, source=False, strings=False, exclude=None]</parameter>)</term>
@@ -3176,6 +3205,7 @@ and added to the following construction variables:
 -openmp                 CCFLAGS, LINKFLAGS
 -pthread                CCFLAGS, LINKFLAGS
 -std=                   CFLAGS
+-stdlib=                CXXFLAGS
 -Wa,                    ASFLAGS, CCFLAGS
 -Wl,-rpath=             RPATH
 -Wl,-R,                 RPATH
@@ -4565,32 +4595,43 @@ Tag('file2.txt', DOC)
     <listitem><para>
 Locates the tool specification module <parameter>name</parameter>
 and returns a callable tool object for that tool.
-The tool module is searched for in standard locations
-and in any paths specified by the optional
-<parameter>toolpath</parameter> parameter.
-The standard locations are &SCons;' own internal
-path for tools plus the toolpath, if any (see the
-<emphasis role="bold">Tools</emphasis> section in the manual page
-for more details).
-Any additional keyword arguments
-<parameter>kwargs</parameter> are passed
-to the tool module's <function>generate</function> function
-during tool object construction.
+When the environment method (&f-env-Tool;) form is used,
+the tool object is automatically called before the method returns
+to update <varname>env</varname>,
+and <parameter>name</parameter> is
+appended to the &cv-link-TOOLS;
+&consvar; in that environment.
+When the global function &f-Tool; form is used,
+the tool object is constructed but not called,
+as it lacks the context of an environment to update,
+and the returned object needs to be used to arrange for the call.
 </para>
 
 <para>
-When called, the tool object
-updates a &consenv; with &consvars; and arranges
+The tool module is searched for in the tool search paths (see the
+<emphasis role="bold">Tools</emphasis> section in the manual page
+for details)
+and in any paths specified by the optional
+<parameter>toolpath</parameter> parameter,
+which must be a list of strings.
+If <parameter>toolpath</parameter> is omitted,
+the <parameter>toolpath</parameter>
+supplied when the environment was created,
+if any, is used.
+</para>
+
+<para>
+Any remaining keyword arguments are saved in
+the tool object,
+and will be passed to the tool module's
+<function>generate</function> function
+when the tool object is actually called.
+The <function>generate</function> function
+can update the &consenv; with &consvars; and arrange
 any other initialization
-needed to use the mechanisms that tool describes.
-</para>
-
-<para>
-When the &f-env-Tool; form is used,
-the tool object is automatically called to update <varname>env</varname>
-and the value of <parameter>tool</parameter> is
-appended to the &cv-link-TOOLS;
-&consvar; in that environment.
+needed to use the mechanisms that tool describes,
+and can use these extra arguments to help
+guide its actions.
 </para>
 
 <para>
@@ -4609,10 +4650,7 @@ env.Tool('opengl', toolpath=['build/tools'])
 </example_commands>
 
 <para>
-When the global function &f-Tool; form is used,
-the tool object is constructed but not called,
-as it lacks the context of an environment to update.
-The tool object can be passed to an
+The returned tool object can be passed to an
 &f-link-Environment; or &f-link-Clone; call
 as part of the <parameter>tools</parameter> keyword argument,
 in which case the tool is applied to the environment being constructed,
@@ -4714,33 +4752,22 @@ except SConsBadOptionError as e:
     <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
-Nodes can be used as dependencies of targets.  If the result of
-calling
-<function>str</function>(<parameter>value</parameter>)
-changes between SCons runs, any targets depending on
-<function>Value</function>(<parameter>value</parameter>)
-will be rebuilt.
-(This is true even when using timestamps to decide if
-files are up-to-date.)
-When using timestamp source signatures, Value Nodes'
-timestamps are equal to the system time when the Node is created.
+Returns a Node object representing the specified &Python;
+<parameter>value</parameter>.
+Value Nodes can be used as dependencies of targets.
+If the string representation of the Value Node
+changes between &SCons; runs, it is considered
+out of date and any targets depending it will be rebuilt.
+Since Value Nodes have no filesystem representation,
+timestamps are not used; the timestamp deciders
+perform the same content-based up to date check.
 </para>
-
 <para>
-The returned Value Node object has a
-<function>write</function>()
-method that can be used to "build" a Value Node
-by setting a new value.
 The optional
 <parameter>built_value</parameter>
 argument can be specified
 when the Value Node is created
-to indicate the Node should already be considered
-"built."
-There is a corresponding
-<function>read</function>()
-method that will return the built value of the Node.
+to indicate the Node should already be considered "built."
 </para>
 
 <para>
@@ -4751,6 +4778,16 @@ cannot be converted to a string.
 </para>
 
 <para>
+Value Nodes have a
+<methodname>write</methodname>
+method that can be used to "build" a Value Node
+by setting a new value.
+The corresponding
+<methodname>read</methodname>
+method returns the built value of the Node.
+</para>
+
+<para>
 <emphasis>Changed in version 4.0:</emphasis>
 the <parameter>name</parameter> parameter was added.
 </para>
@@ -4763,32 +4800,34 @@ Examples:
 env = Environment()
 
 def create(target, source, env):
-    # A function that will write a 'prefix=$SOURCE'
-    # string into the file name specified as the
-    # $TARGET.
+    """Action function to create a file from a Value.
+
+    Writes 'prefix=$SOURCE' into the file name given as $TARGET.
+    """
     with open(str(target[0]), 'wb') as f:
-        f.write('prefix=' + source[0].get_contents())
+        f.write(b'prefix=' + source[0].get_contents() + b'\n')
 
-# Fetch the prefix= argument, if any, from the command
-# line, and use /usr/local as the default.
+# Fetch the prefix= argument, if any, from the command line.
+# Use /usr/local as the default.
 prefix = ARGUMENTS.get('prefix', '/usr/local')
 
-# Attach a .Config() builder for the above function action
-# to the construction environment.
+# Attach builder named Config to the construction environment
+# using the 'create' action function above.
 env['BUILDERS']['Config'] = Builder(action=create)
 env.Config(target='package-config', source=Value(prefix))
 
 def build_value(target, source, env):
-    # A function that "builds" a Python Value by updating
-    # the Python value with the contents of the file
-    # specified as the source of the Builder call ($SOURCE).
+    """Action function to "build" a Value.
+
+    Writes contents of $SOURCE into $TARGET, thus updating if it existed.
+    """
     target[0].write(source[0].get_contents())
 
 output = env.Value('before')
 input = env.Value('after')
 
-# Attach a .UpdateValue() builder for the above function
-# action to the construction environment.
+# Attach a builder named UpdateValue to the construction environment
+# using the 'build_value' action function above.
 env['BUILDERS']['UpdateValue'] = Builder(action=build_value)
 env.UpdateValue(target=Value(output), source=Value(input))
 </example_commands>
@@ -4800,7 +4839,7 @@ env.UpdateValue(target=Value(output), source=Value(input))
     <listitem><para>
 Sets up a mapping to define a variant build directory in
 <parameter>variant_dir</parameter>.
-<parameter>src_dir</parameter> may not be underneath
+<parameter>src_dir</parameter> must not be underneath
 <parameter>variant_dir</parameter>.
 A &f-VariantDir; mapping is global, even if called using the
 &f-env-VariantDir; form.
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index 4d5e1e3..8c89616 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -9801,8 +9801,11 @@ The suffix used for &b-link-Textfile; file names;
       <envar>TOOLS</envar>
     </term>
     <listitem><para>
-A list of the names of the Tool specifications
-that are part of this construction environment.
+A list of the names of the Tool specification modules
+that were actually initialized in the current &consenv;.
+This may be useful as a diagnostic aid
+to see if a tool did (or did not) run.
+The value is informative and is not guaranteed to be complete.
 </para>
 </listitem>
   </varlistentry>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 0f914a2..cdaaa44 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -3042,7 +3042,6 @@ option,
 because individual worker threads spawned
 by &SCons; interfere with each other
 when they start changing directory.</para>
-</warning>
 
 <programlisting language="python">
 # scons will change to the "sub" subdirectory
@@ -3059,6 +3058,7 @@ env.Command(
 # "cp" command.
 env.Command('sub/dir/foo.out', 'sub/dir/foo.in', "cp foo.in foo.out", chdir=True)
 </programlisting>
+</warning>
 
 <para>Note that &SCons; will
 <emphasis>not</emphasis>
@@ -3887,10 +3887,10 @@ for the &consenv; method form the instance provides the values.
 on an attempt to create a new context when there is an active context.
 </para>
 <para><parameter>custom_tests</parameter>
-specifies a dictionary containing custom tests
-(see the section on custom tests below).
+specifies a dictionary containing custom checks
+(see  <link linkend="custom_checks">details below</link>).
 The default value is <constant>None</constant>,
-meaning no custom tests are added to the &configure_context;.</para>
+to indicate there are no custom checks in the &configure_context;.</para>
 <para>
 <parameter>conf_dir</parameter>
 specifies a directory where the test cases are built.
@@ -4504,7 +4504,8 @@ conf.Define("A_SYMBOL", 1, "Set to 1 if you have a symbol")
   </varlistentry>
 </variablelist>
 
-<para>You can define your own custom checks
+<para id="custom_checks" xreflabel="custom checks">
+You can define your own custom checks
 in addition to using the predefined checks.
 To enable custom checks,
 pass a dictionary to the &f-link-Configure; function
@@ -4637,7 +4638,7 @@ is set to the build target node if the build was successful.</para>
   </listitem>
   </varlistentry>
 </variablelist>
-<para>Example of implementing and using custom tests:</para>
+<para>Example of implementing and using custom checks:</para>
 
 <programlisting language="python">
 def CheckQt(chk_ctx, qtdir):
@@ -5425,9 +5426,8 @@ and a matching environment method to create instances:
 <para>
 The &f-link-File; and &f-link-Dir;
 functions/methods return
-File and Directory Nodes, respectively.
-File and Directory Nodes
-(collectively, Filesystem Nodes)
+File Nodes and Directory Nodes, respectively.
+Such <firstterm>Filesystem Nodes</firstterm>
 represent build components that correspond to an entry
 in the computer's filesystem,
 whether or not such an entry exists at the time the Node is created.
@@ -5514,7 +5514,7 @@ print("foo will be built in", foo[0].path)
 
 <para>
 Filesystem Node objects have methods to create new
-File and Directory Nodes relative to the original Node.
+Filesystem Nodes relative to the original Node.
 There are also times when you may need to refer to an entry
 in a filesystem without knowing in advance whether it's a
 file or a directory.
@@ -5796,17 +5796,17 @@ may also be a callable object.  The default target prefix
 may be indicated by a dictionary entry with a key of <constant>None</constant>.</para>
 
 <programlisting language="python">
-b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
-            prefix="file-")
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET", prefix="file-")
 
 def gen_prefix(env, sources):
     return "file-" + env['PLATFORM'] + '-'
 
-b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
-            prefix=gen_prefix)
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET", prefix=gen_prefix)
 
-b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
-            suffix={None: "file-", "$SRC_SFX_A": gen_prefix})
+b = Builder(
+    "build_it &lt; $SOURCE &gt; $TARGET",
+    suffix={None: "file-", "$SRC_SFX_A": gen_prefix},
+)
 </programlisting>
   </listitem>
   </varlistentry>
@@ -5824,17 +5824,16 @@ dictionary is untouched and you need to manually prepend a <literal>'.'</literal
 if one is required.</para>
 
 <programlisting language="python">
-b = Builder("build_it &lt; $SOURCE &gt; $TARGET"
-            suffix="-file")
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET", suffix="-file")
 
 def gen_suffix(env, sources):
     return "." + env['PLATFORM'] + "-file"
 
-b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
-            suffix=gen_suffix)
-
-b = Builder("build_it &lt; $SOURCE &gt; $TARGET",
-            suffix={None: ".sfx1", "$SRC_SFX_A": gen_suffix})
+b = Builder("build_it &lt; $SOURCE &gt; $TARGET", suffix=gen_suffix)
+b = Builder(
+    "build_it &lt; $SOURCE &gt; $TARGET",
+    suffix={None: ".sfx1", "$SRC_SFX_A": gen_suffix},
+)
 </programlisting>
   </listitem>
   </varlistentry>
@@ -5852,11 +5851,10 @@ is to leave unchanged
 any target string that looks like it already has a suffix.</para>
 
 <programlisting language="python">
-b1 = Builder("build_it &lt; $SOURCE &gt; $TARGET"
-             suffix = ".out")
-b2 = Builder("build_it &lt; $SOURCE &gt; $TARGET"
-             suffix = ".out",
-             ensure_suffix=True)
+b1 = Builder("build_it &lt; $SOURCE &gt; $TARGET", suffix=".out")
+b2 = Builder(
+    "build_it &lt; $SOURCE &gt; $TARGET", suffix=".out", ensure_suffix=True
+)
 env = Environment()
 env['BUILDERS']['B1'] = b1
 env['BUILDERS']['B2'] = b2
@@ -5886,15 +5884,15 @@ may be a string or a list of strings.</para>
 <para>A Scanner object that
 will be invoked to find
 implicit dependencies for this target file.
-This keyword argument should be used
-for Scanner objects that find
+Use only to specify Scanner objects that find
 implicit dependencies
-based only on the target file
-and the &consenv;,
+based on the target file
+and &consenv;,
 <emphasis>not</emphasis>
-for implicit dependencies based on source files.
+for implicit dependencies based on source files
+(use <xref linkend="source_scanner"/> for those).
 See <xref linkend="scanner_objects"/>
-for information about creating Scanner objects.</para>
+for information about creating your own Scanner objects.</para>
   </listitem>
   </varlistentry>
 
@@ -5906,8 +5904,7 @@ will be invoked to
 find implicit dependencies in
 any source files
 used to build this target file.
-This is where you would
-specify a scanner to
+Use to specify a scanner to
 find things like
 <literal>#include</literal>
 lines in source files.
@@ -5931,31 +5928,33 @@ for information about creating your own Scanner objects.</para>
 <para>A factory function that the Builder will use
 to turn any targets specified as strings into SCons Nodes.
 By default,
-SCons assumes that all targets are files.
-Other useful target_factory
-values include
-<emphasis role="bold">Dir</emphasis>,
+SCons assumes that all targets are files
+(that is, the default factory is &File;).
+Other useful <parameter>target_factory</parameter>
+values include &Dir;
 for when a Builder creates a directory target,
-and
-<emphasis role="bold">Entry</emphasis>,
+and &Entry;
 for when a Builder can create either a file
 or directory target.</para>
 
 <para>Example:</para>
 
 <programlisting language="python">
+def my_mkdir(target, source, env):
+    # target[0] will be a Dir node for 'new_directory'
+
 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
 env = Environment()
 env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder})
 env.MakeDirectory('new_directory', [])
 </programlisting>
 
-<para>Note that the call to this <function>MakeDirectory</function> Builder
+<para>Note that the call to the <function>MakeDirectory</function> Builder
 needs to specify an empty source list
-to make the string represent the builder's target;
-without that, it would assume the argument is the source,
-and would try to deduce the target name from it,
-which in the absence of an automatically-added prefix or suffix
+to make the filename string represent the builder's target.
+&SCons; assumes a single positional argument to a builder
+is the source, and would try to deduce the target name from it,
+which, in the absence of an automatically-added prefix or suffix,
 would lead to a matching target and source name
 and a circular dependency.</para>
   </listitem>
@@ -5967,23 +5966,26 @@ and a circular dependency.</para>
 <para>A factory function that the Builder will use
 to turn any sources specified as strings into SCons Nodes.
 By default,
-SCons assumes that all source are files.
-Other useful source_factory
-values include
-<emphasis role="bold">Dir</emphasis>,
+SCons assumes that all source are files
+(that is, the default factory is &File;).
+Other useful <parameter>source_factory</parameter>
+values include &Dir;
 for when a Builder uses a directory as a source,
-and
-<emphasis role="bold">Entry</emphasis>,
+and &Entry;
 for when a Builder can use files
 or directories (or both) as sources.</para>
 
 <para>Example:</para>
 
 <programlisting language="python">
-CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
+def collect(target, source, env):
+    # target[0] will default to a File node for 'archive' (no target_factory)
+    # source[0] will be a Dir node for 'directory_name'
+
+CollectBuilder = Builder(action=collect, source_factory=Dir)
 env = Environment()
 env.Append(BUILDERS={'Collect': CollectBuilder})
-env.Collect('archive', ['directory_name', 'file_name'])
+env.Collect('archive', 'directory_name')
 </programlisting>
   </listitem>
   </varlistentry>
@@ -6185,10 +6187,8 @@ and
 <filename>foo.extra</filename>.</para>
 
 <programlisting language="python">
-b = Builder(action={'.in' : 'build $SOURCES &gt; $TARGET'},
-            source_ext_match=False)
-
-env = Environment(BUILDERS={'MyBuild':b})
+b = Builder(action={'.in': 'build $SOURCES &gt; $TARGET'}, source_ext_match=False)
+env = Environment(BUILDERS={'MyBuild': b})
 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
 </programlisting>
 
@@ -6258,8 +6258,7 @@ to use just the filename portion of the
 targets and source.</para>
 
 <programlisting language="python">
-b = Builder(action="build &lt; ${SOURCE.file} &gt; ${TARGET.file}",
-            chdir=1)
+b = Builder(action="build &lt; ${SOURCE.file} &gt; ${TARGET.file}", chdir=True)
 env = Environment(BUILDERS={'MyBuild' : b})
 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
 </programlisting>
@@ -6636,8 +6635,7 @@ def always_succeed(s):
     # Always return 0, which indicates success.
     return 0
 
-a = Action("build &lt; ${SOURCE.file} &gt; ${TARGET.file}",
-           exitstatfunc=always_succeed)
+a = Action("build &lt; ${SOURCE.file} &gt; ${TARGET.file}", exitstatfunc=always_succeed)
 </programlisting>
   </listitem>
   </varlistentry>