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 <[email protected]>

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

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.
 
 
 

SCons/Builder.py

@@ -387,7 +387,7 @@ def __init__(self,  action = None,
                         target_scanner = None,
                         source_scanner = None,
                         emitter = None,
-                        multi: int = 0,
+                        multi: bool = False,
                         env = None,
                         single_source: bool = False,
                         name = None,

SCons/Environment.py

@@ -2208,52 +2208,44 @@ def Configure(self, *args, **kw):
         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 @@ def PyPackageDir(self, modulename):
         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 @@ def NoClean(self, *targets):
         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))

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>

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>