From a256ab3a43e3c92fb678a1e1d86b8dd6eca81ba2 Mon Sep 17 00:00:00 2001
From: Mats Wichmann <mats@linux.com>
Date: Wed, 31 Jul 2024 09:12:38 -0600
Subject: [PATCH] Modify the Builder Methods manpage section

In clarifying the detail on when a builder's target can be deduced,
it seemed like the concept of a single-source builder ought to be
introduced in this context. So now those builders we know are
single-source have that notation in their entry in this section.

Also mentions that pseudo-Builders may have a diffeent calling sequence.

A chunk of text about dependencies previously appeared after the
listing of builder methods, where it would be hard to spot. Moved up
into the text before the listing, and integrate in a bit more smoothly.

A couple of very minor typing things adjusted along the way - mainly
using single_source consistently as a bool.

Signed-off-by: Mats Wichmann <mats@linux.com>
---
 CHANGES.txt            |   2 +
 RELEASE.txt            |   3 +
 SCons/BuilderTests.py  |   4 +-
 SCons/Node/__init__.py |   2 +-
 SCons/Tool/Tool.xml    |  81 ++---
 SCons/Tool/__init__.py |   4 +-
 doc/man/scons.xml      | 691 +++++++++++++++++------------------------
 7 files changed, 343 insertions(+), 444 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index ed6905ba7..0eab29a67 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -198,6 +198,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       attribute and to explain what's being done in the example.
     - Test framework reformatted using settings from pyproject.toml.
       Includes code embedded in docstrings.
+    - Improve the Builder Methods intro section in manpage, making sure
+      all prose appears before the listing of methods.
 
     From Adam Scott:
     - Changed Ninja's TEMPLATE rule pool to use `install_pool` instead of
diff --git a/RELEASE.txt b/RELEASE.txt
index 19927a3c2..6b6b6644f 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -224,6 +224,9 @@ DOCUMENTATION
   being created from '${SOURCE.base}.out' to use a valid special
   attribute and to explain what's being done in the example.
 
+- Improve the descriptive portion of the Builder Methods section in
+  the manpage: reword, reorganize.
+
 DEVELOPMENT
 -----------
 
diff --git a/SCons/BuilderTests.py b/SCons/BuilderTests.py
index adfa64828..6b8c9eec0 100644
--- a/SCons/BuilderTests.py
+++ b/SCons/BuilderTests.py
@@ -714,8 +714,8 @@ def func(target, source, env) -> None:
             infiles.append(test.workpath('%d.in' % i))
             outfiles.append(test.workpath('%d.out' % i))
             test.write(infiles[-1], "\n")
-        builder = SCons.Builder.Builder(action=SCons.Action.Action(func,None),
-                                        single_source = 1, suffix='.out')
+        builder = SCons.Builder.Builder(action=SCons.Action.Action(func, None),
+                                        single_source=True, suffix='.out')
         env['CNT'] = [0]
         tgt = builder(env, target=outfiles[0], source=infiles[0])[0]
         s = str(tgt)
diff --git a/SCons/Node/__init__.py b/SCons/Node/__init__.py
index 055c3090c..48e62746d 100644
--- a/SCons/Node/__init__.py
+++ b/SCons/Node/__init__.py
@@ -215,7 +215,7 @@ def get_contents_dir(node):
         contents.append('%s %s\n' % (n.get_csig(), n.name))
     return ''.join(contents)
 
-def get_contents_file(node):
+def get_contents_file(node) -> bytes:
     if not node.rexists():
         return b''
     fname = node.rfile().get_abspath()
diff --git a/SCons/Tool/Tool.xml b/SCons/Tool/Tool.xml
index fcd33fe93..19511fe14 100644
--- a/SCons/Tool/Tool.xml
+++ b/SCons/Tool/Tool.xml
@@ -36,13 +36,13 @@ if it is not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 # builds foo.c
 env.CFile(target='foo.c', source='foo.l')
 
 # builds bar.c
 env.CFile(target='bar', source='bar.y')
-</example_commands>
+</programlisting>
 
 <!--para>  ** Left here for reference, does not need to be user-visible. **
 Note that for yacc files,
@@ -67,13 +67,13 @@ if it is not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 # builds foo.cc
 env.CXXFile(target='foo.cc', source='foo.ll')
 
 # builds bar.cc
 env.CXXFile(target='bar', source='bar.yy')
-</example_commands>
+</programlisting>
 
 <!--para>  ** Left here for reference, does not need to be user-visible. **
 Note that for yacc files,
@@ -141,9 +141,9 @@ are automatically added to the target if not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
-</example_commands>
+</programlisting>
 </summary>
 </builder>
 
@@ -187,9 +187,9 @@ it is appended (following a period) to the resulting library name.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
-</example_commands>
+</programlisting>
 
 <para>
 On Windows systems, the
@@ -228,9 +228,9 @@ adds the version number to the library name, and creates any
 symbolic links that are needed.
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
-</example_commands>
+</programlisting>
 
 <para>
 On a POSIX system, supplying a simple version string (no dots)
@@ -264,9 +264,9 @@ up and requiring user attention when it is run.  If you change
 For example,
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
-</example_commands>
+</programlisting>
 
 <para>
 will register <filename>bar.dll</filename> as a COM object
@@ -281,38 +281,41 @@ when it is done linking it.
 Builds an object file intended for
 inclusion in a shared library.
 Source files must have one of the same set of extensions
-specified above for the
-&b-StaticObject;
+specified for the
+&b-link-StaticObject;
 builder method.
-On some platforms building a shared object requires additional
-compiler option
-(e.g. <option>-fPIC</option> for <command>gcc</command>)
-in addition to those needed to build a
-normal (static) object, but on some platforms there is no difference between a
-shared object and a normal (static) one. When there is a difference, SCons
-will only allow shared objects to be linked into a shared library, and will
-use a different suffix for shared objects. On platforms where there is no
-difference, SCons will allow both normal (static)
-and shared objects to be linked into a
-shared library, and will use the same suffix for shared and normal
-(static) objects.
 The target object file prefix,
 specified by the &cv-link-SHOBJPREFIX; &consvar;
 (by default, the same as &cv-link-OBJPREFIX;),
 and suffix,
 specified by the &cv-link-SHOBJSUFFIX; &consvar;,
 are automatically added to the target if not already present.
+&b-SharedObject; is a single-source builder.
 Examples:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedObject(target='ddd', source='ddd.c')
 env.SharedObject(target='eee.o', source='eee.cpp')
 env.SharedObject(target='fff.obj', source='fff.for')
-</example_commands>
+env.SharedObject(source=Glob('*.c'))
+</programlisting>
 
 <para>
-Note that the source files will be scanned
+On some platforms building a shared object requires additional
+compiler option(s)
+(e.g. <option>-fPIC</option> for <command>gcc</command>)
+in addition to those needed to build a
+normal (static) object.
+If shared and static objects differ,
+&SCons; will allow only shared objects
+to be linked into a shared library,
+and will use a different suffix for shared objects
+to help indicate and track the difference.
+</para>
+
+<para>
+Source files will be scanned
 according to the suffix mappings in the
 <classname>SourceFileScanner</classname>
 object.
@@ -342,9 +345,9 @@ are automatically added to the target if not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
-</example_commands>
+</programlisting>
 
 <para>
 Any object files listed in the
@@ -364,10 +367,10 @@ will raise an error if there is any mismatch.
 <para>
 Builds a static object file
 from one or more C, C++, D, or Fortran source files.
-Source files must have one of the following extensions:
+The file extension mapping is shown in the table:
 </para>
 
-<example_commands>
+<literallayout><literal>
   .asm    assembly language file
   .ASM    assembly language file
   .c      C file
@@ -396,28 +399,30 @@ Source files must have one of the following extensions:
           POSIX:  assembly language file + C pre-processor
   .spp    assembly language file + C pre-processor
   .SPP    assembly language file + C pre-processor
-</example_commands>
+</literal></literallayout>
 
 <para>
 The target object file prefix,
 specified by the &cv-link-OBJPREFIX; &consvar;
-(nothing by default),
+(empty string by default),
 and suffix,
 specified by the &cv-link-OBJSUFFIX; &consvar;
 (<filename>.obj</filename> on Windows systems,
 <filename>.o</filename> on POSIX systems),
 are automatically added to the target if not already present.
+&b-StaticObject; is a single-source builder.
 Examples:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.StaticObject(target='aaa', source='aaa.c')
 env.StaticObject(target='bbb.o', source='bbb.c++')
 env.StaticObject(target='ccc.obj', source='ccc.f')
-</example_commands>
+env.StaticObject(source=Glob('*.c'))
+</programlisting>
 
 <para>
-Note that the source files will be scanned
+Source files will be scanned
 according to the suffix mappings in the
 <classname>SourceFileScanner</classname>
 object.
diff --git a/SCons/Tool/__init__.py b/SCons/Tool/__init__.py
index 23b7eeba2..75a69ec2c 100644
--- a/SCons/Tool/__init__.py
+++ b/SCons/Tool/__init__.py
@@ -408,7 +408,7 @@ def createObjBuilders(env):
                                            suffix='$OBJSUFFIX',
                                            src_builder=['CFile', 'CXXFile'],
                                            source_scanner=SourceFileScanner,
-                                           single_source=1)
+                                           single_source=True)
         env['BUILDERS']['StaticObject'] = static_obj
         env['BUILDERS']['Object'] = static_obj
 
@@ -421,7 +421,7 @@ def createObjBuilders(env):
                                            suffix='$SHOBJSUFFIX',
                                            src_builder=['CFile', 'CXXFile'],
                                            source_scanner=SourceFileScanner,
-                                           single_source=1)
+                                           single_source=True)
         env['BUILDERS']['SharedObject'] = shared_obj
 
     return (static_obj, shared_obj)
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 979f67d38..6eebf5914 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1135,7 +1135,7 @@ when encountering an otherwise unexplained error.</para>
 (When
 &scons;
 is executed without the
-<option>-j</option>
+<link linkend="opt-jobs"><option>-j</option></link>
 option,
 the elapsed wall-clock time will typically
 be slightly longer than the total time spent
@@ -1147,7 +1147,7 @@ When
 is executed
 <emphasis>with</emphasis>
 the
-<option>-j</option>
+<link linkend="opt-jobs"><option>-j</option></link>
 option,
 and your build configuration allows good parallelization,
 the elapsed wall-clock time should
@@ -2294,7 +2294,7 @@ which can yield unpredictable behavior with some compilers.</para>
   <varlistentry>
   <term><emphasis role="bold">future-reserved-variable</emphasis></term>
   <listitem>
-<para>Warnings about construction variables which
+<para>Warnings about &consvars; which
 are currently allowed,
 but will become reserved variables in a future release.
 </para>
@@ -2382,7 +2382,7 @@ Add another "-no" to disable.
   <listitem>
 <para>Warnings about the version of &Python;
 not being able to support parallel builds when the
-<option>-j</option>
+<link linkend="opt-jobs"><option>-j</option></link>
 option is used.
 These warnings are enabled by default.</para>
 <para>
@@ -2624,7 +2624,7 @@ settings. Otherwise, &f-env-Clone; takes the same arguments as
 &SCons; provides a special &consenv; called the
 <firstterm>&DefEnv;</firstterm>.
 The &defenv; is used only for global functions, that is,
-construction activities called without the context of a regular &consenv;.
+build requests called without the context of a regular &consenv;.
 See &f-link-DefaultEnvironment; for more information.
 </para>
 
@@ -2820,71 +2820,59 @@ method (see below).
 <refsect2 id='builder_methods'>
 <title>Builder Methods</title>
 
-<para>You tell &SCons; what to build
-by calling <firstterm>Builders</firstterm>,
-functions which take particular action(s)
-to produce target(s) of a particular type
-(conventionally hinted at by the builder name, e.g. &Program;)
-from the specified source files.
-A builder call is a declaration: &SCons; enters the
-specified relationship into its internal dependency node graph,
-and only later makes the decision on whether anything is actually built,
-since this depends on command-line options,
-target selection rules, and whether the target(s) are
-out-of-date with respect to the sources.
+<para>
+Builder methods in &SCons; are special functions
+used to declare relationships in the dependency graph.
+Calling a Builder does not build anything directly,
+but records the target (what you want built),
+sources (what it’s built from),
+the &consenv; to use for build settings,
+and information the builder itself
+knows about the type of build.
+The &SCons; job runner later decides if and when
+to initiate a build using this information.
 </para>
 
 <para>
-&SCons;
-provides a number of builders, and you can also write your own
-(see <link linkend='builder_objects'>Builder Objects</link>).
-Builders are created dynamically at run-time,
-often (though not always) by tools which determine
-whether the external dependencies for the builder are satisfied,
-and which perform the necessary setup
-(see <link linkend='tools'>Tools</link>).
-Builders are attached to a &consenv; as methods.
-The available builder methods are registered as
-key-value pairs in the
-&cv-link-BUILDERS; attribute of the &consenv;,
-so the available builders can be examined.
-This example displays them for debugging purposes:
+All true Builder methods share the same function calling syntax.
+For the sake of brevity, this common signature is not included in
+the listing of Builders.
+Pseudo-Builders have more flexibility in how they are called,
+and do not necessarily follow this convention,
+as described in the text of the respective entries.
 </para>
 
 <programlisting language="python">
-env = Environment()
-print("Builders:", list(env['BUILDERS']))
+<function>Buildername</function>(<parameter>target, source, [key=val, ...]</parameter>)
 </programlisting>
 
 <para>
-Builder methods take two required arguments:
-<parameter>target</parameter>
-and
-<parameter>source</parameter>.
 The <parameter>target</parameter> and
 <parameter>source</parameter> arguments
-can be specified either as positional arguments,
-in which case <parameter>target</parameter> comes first, or as
-keyword arguments, using <parameter>target=</parameter>
-and <parameter>source=</parameter>.
-Although both arguments are nominally required,
-if there is a single source and the target can be inferred
-the <parameter>target</parameter> argument can be omitted (see below).
-Builder methods also take a variety of
-keyword arguments, described below.
-</para>
-
-<para>Because long lists of file names
-can lead to a lot of quoting in a builder call,
-&SCons;
-supplies a &f-link-Split;
-global function
-and a same-named environment method
-that splits a single string
-into a list, using
-strings of white-space characters as the delimiter
-(similar to the &Python; string <function>split</function>
-method, but succeeds even if the input isn't a string).</para>
+can be specified either as positional or keyword arguments.
+Some additional keyword arguments are recognized for all builders,
+and any unknown keyword arguments are treated as temporary
+&consvar; assignments.
+You can specify sources and targets as a scalar or a list,
+composed of either strings or nodes.
+For convenience, the &SCons; &f-link-Split; method
+can be used to split a single string into a list,
+using strings of white-space characters as the delimiter.
+</para>
+
+<para>
+When specifying path strings,
+&SCons; follows the platform's pathname conventions
+for absolute and relative paths.
+Relative paths are interpreted relative to the directory
+of the &SConscript; file being evaluated.
+&SCons; also recognizes a third way to specify path strings:
+if the string begins with the <literal>#</literal>
+character, it is evaluated relative to the top directory of the project
+(<firstterm>top-relative</firstterm>).
+Note top-relative path strings work only in &SCons; contexts,
+pure &Python; functions will not interpret them correctly.
+</para>
 
 <para>
 The following are equivalent examples of calling the
@@ -2901,47 +2889,13 @@ env.Program(target='bar', source=env.Split('bar.c foo.c'))
 env.Program('bar', source='bar.c foo.c'.split())
 </programlisting>
 
-<para>
-Sources and targets can be specified as a scalar or as a list,
-composed of either strings or nodes (more on nodes below).
-When specifying path strings,
-&Python; follows the POSIX pathname convention:
-if a string begins with the operating system pathname separator
-(on Windows both the slash and backslash separator are accepted,
-and any leading drive specifier is ignored for
-the determination) it is considered an absolute path,
-otherwise it is a relative path.
-If the path string contains no separator characters,
-it is searched for as a file in the current directory. If it
-contains separator characters, the search follows down
-from the starting point, which is the top of the directory tree for
-an absolute path and the current directory for a relative path.
-The "current directory" in this context is the directory
-of the &SConscript; file currently being processed.
-</para>
-
-<para>
-&SCons; also recognizes a third way to specify
-path strings: if the string begins with
-the <emphasis role="bold">#</emphasis> character it is
-<firstterm>top-relative</firstterm> - it works like a relative path, but the
-search follows down from the project top directory rather than
-from the current directory. The <emphasis role="bold">#</emphasis>
-can optionally be followed by a pathname separator,
-which is ignored if found in that position.
-Top-relative paths only work in places where &scons; will
-interpret the path (see some examples below).  To be
-used in other contexts the string will need to be converted
-to a relative or absolute path first.
+<para>Here are some examples showing source and target path manipulation
+by &SCons; - assume this code would be in an &SConscript;
+file in <filename>subdir</filename>, called by
+<userinput>SConscript("subdir")</userinput>:
 </para>
 
-<para>Examples:</para>
-
 <programlisting language="python">
-# The comments describing the targets that will be built
-# assume these calls are in a SConscript file in the
-# a subdirectory named "subdir".
-
 # Builds the program "subdir/foo" from "subdir/foo.c":
 env.Program('foo', 'foo.c')
 
@@ -2959,42 +2913,35 @@ env.Program('#/bar', 'bar.c')
 # SConstruct directory) from "subdir/foo.c":
 env.Program('#other/foo', 'foo.c')
 
-# This will not work, only SCons interfaces understand '#',
-# os.path.exists is pure Python:
+# Will not work, only SCons interfaces understand '#',
+# while os.path.exists is pure Python:
 if os.path.exists('#inc/foo.h'):
     env.Append(CPPPATH='#inc')
 </programlisting>
 
-<para>When the target shares the same base name
-as the source and only the suffix varies,
-and if the builder method has a suffix defined for the target file type,
-then the target argument may be omitted completely,
-and
-&scons;
-will deduce the target file name from
-the source file name.
-The following examples all build the
-executable program
-<emphasis role="bold">bar</emphasis>
-(on POSIX systems)
-or
-<emphasis role="bold">bar.exe</emphasis>
-(on Windows systems)
-from the <filename>bar.c</filename> source file:</para>
-
-<programlisting language="python">
-env.Program(target='bar', source='bar.c')
-env.Program('bar', source='bar.c')
-env.Program(source='bar.c')
-env.Program('bar.c')
-</programlisting>
+<para>
+If &SCons; can deduce the target name from the source(s),
+the <parameter>target</parameter> argument may be omitted.
+If the Builder supports it,
+&SCons; will take the base name of the first source file
+and use it as the base name of the target,
+adding the appropriate prefix/suffix.
+For Builders designated as single-source,
+a separate target is built for each source file,
+rather than multiple sources contributing to a single target.
+If multiple sources are passed to a single-source builder,
+the target argument <emphasis>must</emphasis> be omitted,
+and each target will be given a name deduced from
+the corresponding source file.
+</para>
 
-<para>The optional
+<para>
+The optional
 <parameter>srcdir</parameter>
 keyword argument specifies that
-all source file strings that are not absolute paths
+source file strings that are not absolute
 or top-relative paths
-shall be interpreted relative to the specified
+should be interpreted relative to the value of
 <parameter>srcdir</parameter>.
 The following example will build the
 <filename>build/prog</filename>
@@ -3004,33 +2951,35 @@ on Windows)
 program from the files
 <filename>src/f1.c</filename>
 and
-<filename>src/f2.c</filename>:
+<filename>src/f2.c</filename>,
+rather than looking for them in the directory of
+of the &SConscript; file being evaluated.
 </para>
 
 <programlisting language="python">
 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
 </programlisting>
 
-<para>The optional
+<para>
+The optional
 <parameter>parse_flags</parameter>
 keyword argument causes behavior similar to the
 &f-link-env-MergeFlags; method, where the argument value is
 broken into individual settings and merged into the appropriate &consvars;.
+The following example adds <literal>'include'</literal> to
+the &cv-link-CPPPATH; &consvar;,
+<literal>'EBUG'</literal> to
+&cv-link-CPPDEFINES;,
+and <literal>'m'</literal> to
+&cv-link-LIBS;:
 </para>
 
 <programlisting language="python">
 env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
 </programlisting>
 
-<para>This example adds 'include' to
-the &cv-link-CPPPATH; &consvar;,
-'EBUG' to
-&cv-link-CPPDEFINES;,
-and 'm' to
-&cv-link-LIBS;.
-</para>
-
-<para>The optional
+<para>
+The optional
 <parameter>chdir</parameter>
 keyword argument
 specifies that the Builder's action(s)
@@ -3046,23 +2995,10 @@ If the
 is not a string or Node
 and evaluates true,
 then &scons; will change to the
-target file's directory.</para>
-
-<warning>
-<para>
-&Python; only keeps one current directory
-location even if there are multiple threads.
-This means that use of the
-<parameter>chdir</parameter>
-argument
-will
-<emphasis>not</emphasis>
-work with the SCons
-<option>-j</option>
-option,
-because individual worker threads spawned
-by &SCons; interfere with each other
-when they start changing directory.</para>
+target file's directory.
+The original directory is restored
+after the action is complete.
+</para>
 
 <programlisting language="python">
 # scons will change to the "sub" subdirectory
@@ -3079,20 +3015,29 @@ 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
+<warning>
+<para>
+&Python; only tracks one current directory location,
+even if there are multiple executing threads.
+This means that use of the
+<parameter>chdir</parameter>
+argument will
 <emphasis>not</emphasis>
-automatically modify
-its expansion of
-&consvars; like &cv-link-TARGET;
-and &cv-link-SOURCE;
-when using the <parameter>chdir</parameter>
-keyword argument--that is,
-the expanded file names
-will still be relative to
-the project top directory,
-and consequently incorrect
+work with &SCons; in multi-threaded mode
+(the <link linkend="opt-jobs"><option>-j</option></link> option),
+because individual worker threads spawned
+by &SCons; interfere with each other
+when they start changing directory.</para>
+</warning>
+
+<note>
+<para>
+&SCons; does not account for
+<parameter>chdir</parameter>
+when it expands &consvars;
+like &cv-link-TARGET; and &cv-link-SOURCE;,
+so they will be incorrect
 relative to the chdir directory.
 If you use the <parameter>chdir</parameter> keyword argument,
 you will typically need to supply a different
@@ -3102,15 +3047,19 @@ expansions like
 and
 <literal>${SOURCE.file}</literal>
 to use just the filename portion of the
-target and source.</para>
-
-<para>Keyword arguments that are not specifically
-recognized are treated as &consvar;
-<firstterm>overrides</firstterm>,
-which replace or add those variables on a limited basis.
-These overrides
-will only be in effect when building the target of the builder call,
-and will not affect other parts of the build.
+target and source,
+which will then evaluated be relative to the
+<parameter>chdir</parameter> directory.
+</para>
+</note>
+
+<para>
+Keyword arguments that are not specifically
+recognized are treated as &consvar; assignments,
+creating an <firstterm>override</firstterm>
+for the &consenv; which is only used
+when building the target of the builder call.
+These temporary assignments do not affect the &consenv; itself.
 For example, if you want to specify
 some libraries needed by just one program:</para>
 
@@ -3118,211 +3067,191 @@ some libraries needed by just one program:</para>
 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
 </programlisting>
 
-<para>or generate a shared library with a non-standard suffix:</para>
-
-<programlisting language="python">
-env.SharedLibrary(
-    target='word',
-    source='word.cpp',
-    SHLIBSUFFIX='.ocx',
-    LIBSUFFIXES=['.ocx'],
-)
-</programlisting>
-
-<para>Note that both the &cv-link-SHLIBSUFFIX;
-and &cv-link-LIBSUFFIXES;
-&consvars; must be set if you want &scons; to search automatically
-for dependencies on the non-standard library names;
-see the descriptions of these variables for more information.</para>
-
-<para>Although the builder methods defined by
-&scons;
-are, in fact,
-methods of a &consenv; object,
-many may also be called without an explicit environment:</para>
-
-<programlisting language="python">
-Program('hello', 'hello.c')
-SharedLibrary('word', 'word.cpp')
-</programlisting>
-
-<para>If called this way, the builder will internally use the
-&DefEnv; that consists of the tools and values that
-&scons;
-has determined are appropriate for the local system.</para>
-
-<para>Builder methods that can be called without an explicit
-environment (indicated in the listing of builders below
-without a leading <varname>env.</varname>)
-may be called from custom &Python; modules that you
-import into an &SConscript; file by adding the following
-to the &Python; module:</para>
-
-<programlisting language="python">
-from SCons.Script import *
-</programlisting>
-
 <para>
 A builder <emphasis>may</emphasis> add additional targets
-beyond those requested
+beyond those requested,
 if an attached <firstterm>Emitter</firstterm> chooses to do so
-(see <xref linkend="builder_objects"/> for more information.
-&cv-link-PROGEMITTER; is an example).
-For example, the GNU linker takes a command-line argument
-<option>-Map=<replaceable>mapfile</replaceable></option>,
-which causes it to produce a linker map file in addition
-to the executable file actually being linked.
-If the &b-link-Program; builder's emitter is configured
-to add this mapfile if the option is set,
-then two targets will be returned when you only provided for one.
-</para>
-
-<para>
+(see <xref linkend="builder_objects"/> for more information).
 For this reason,
 builder methods always return a <classname>NodeList</classname>,
 a list-like object whose elements are Nodes.
-Nodes are the internal representation of build targets or sources
+A Node is the internal representation of a target, source,
+or other entity that is included in the build graph
 (see <xref linkend="node_objects"/> for more information).
+</para>
+
+<para>
 The returned <classname>NodeList</classname> object
 can be passed to other builder methods as source(s)
 or to other &SCons; functions or methods
-where a path string would normally be accepted.
+where a path string would normally be accepted,
+for example &f-link-Default;, &f-link-Alias; or
+&f-link-AddPostAction;.
+Using a NodeList or Node obtained from a Builder call
+makes for a more portable build,
+since platform-specific names can be avoided.
+Examples:
 </para>
 
-<para> For example,
-to add a specific preprocessor define
-when compiling one specific object file
-but not the others:</para>
-
 <programlisting language="python">
+# build "bar" object with a special compiler flag:
 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
-env.Program("prog", ['foo.c', bar_obj_list, 'main.c'])
-</programlisting>
-
-<para>Using a Node as in this example
-makes for a more portable build
-by avoiding having to specify
-a platform-specific object suffix
-when calling the &b-link-Program; builder method.
-</para>
 
-<para>The <classname>NodeList</classname> object
-is also convenient to pass to the &f-link-Default; function,
-for the same reason of avoiding a platform-specific name:
-</para>
+# include that object when building "prog":
+tgt = env.Program("prog", ['foo.c', bar_obj_list, 'main.c'])
 
-<programlisting language="python">
-tgt = env.Program("prog", ["foo.c", "bar.c", "main.c"])
+# add the resulting program to default targets and an alias:
 Default(tgt)
+Alias("targets", tgt)
 </programlisting>
 
-<para>Builder calls will automatically "flatten"
-lists passed as source and target, so they are free to
-contain elements which are themselves lists, such as
-<varname>bar_obj_list</varname>
-returned by the &b-link-StaticObject; call.
+<para>
+Builder calls automatically "flatten"
+lists passed as source and target,
+so they are free to contain elements which are themselves lists,
+such as a NodeList object returned by another Builder call.
 If you need to manipulate a list of lists returned by builders
 directly in &Python; code,
-you can either build a new list by hand:</para>
+you can either build a new list by hand
+or use the &SCons; &f-link-Flatten; function,
+which returns a flattened list:
+</para>
 
 <programlisting language="python">
-foo = Object('foo.c')
-bar = Object('bar.c')
+foo = Object('foo.c')  # returns a NodeList
+bar = Object('bar.c')  # returns a NodeList
+
 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
-for obj in objects:
-    print(str(obj))
-</programlisting>
-
-<para>Or you can use the &f-link-Flatten;
-function supplied by &SCons;
-to create a list containing just the Nodes,
-which may be more convenient:</para>
-
-<programlisting language="python">
-foo = Object('foo.c')
-bar = Object('bar.c')
-objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
-for obj in objects:
-    print(str(obj))
-</programlisting>
-
-<para>Since builder calls return
-a list-like object, not an actual &Python; list,
-it is not appropriate to use the &Python; add
-operator (<literal>+</literal> or <literal>+=</literal>)
-to append builder results to a &Python; list.
-Because the list and the object are different types,
-&Python; will not update the original list in place,
-but will instead create a new <classname>NodeList</classname> object
-containing the concatenation of the list
-elements and the builder results.
-This will cause problems for any other &Python; variables
-in your SCons configuration
-that still hold on to a reference to the original list.
-Instead, use the &Python; list
-<function>extend</function>
-method to make sure the list is updated in-place.
-Example:</para>
+print(', '.join(str(obj) for obj in objects))
+# shows: begin.o, foo.o, middle.o, bar.o, end.o
+
+objects = Flatten(('begin.o', foo, 'middle.o', bar, 'end.o'))
+print(', '.join(str(obj) for obj in objects))
+# shows: begin.o, foo.o, middle.o, bar.o, end.o
+</programlisting>
+
+<note>
+<para>
+Do not use the &Python;
+in-place addition operator (<literal>+=</literal>)
+to append a NodeList builder result to a an existing &Python; list -
+this causes a conversion to a new <classname>NodeList</classname> object.
+If the original list has other references,
+they will continue to refer to the unmodified version,
+which can have undesired results.
+Use the &Python; list <methodname>extend</methodname> method instead.
+In-place addition is fine if the object being added to
+is already a <classname>NodeList</classname>.
+</para>
 
 <programlisting language="python">
 object_files = []
+saved_object_files = object_files
+
+# Do NOT use += here, there will be a new object_files,
+# but saved_object_files will still refer to the original list
+object_files += Object('bar.c')
 
-# Do NOT use += here:
-#    object_files += Object('bar.c')
-#
-# It will not update the object_files list in place.
-#
 # Instead, use the list extend method:
 object_files.extend(Object('bar.c'))
 </programlisting>
+</note>
 
-<para>The path name for a Node's file may be used
-by passing the Node to &Python;'s built-in
-<function>str</function>
-function:</para>
+<para>
+To access the individual Node that represents the requested target file,
+use a list index
+(e.g. <literal>bar_obj_list[0]</literal>).
+The path name for a Node's file can be obtained
+by using &Python;'s string constructor <function>str</function>
+(e.g. <literal>str(bar_obj_list[0])</literal>).
+</para>
 
 <programlisting language="python">
 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
 print("The path to bar_obj is:", str(bar_obj_list[0]))
 </programlisting>
 
-<para>Note that because the Builder call returns a
-<classname>NodeList</classname>,
-you have to access the first element in the list
-(<literal>bar_obj_list[0]</literal> in the example)
-to get at the Node that actually represents
-the object file.</para>
-
 <para>
-When trying to handle errors that may occur in a builder method,
-consider that the corresponding Action is executed at a different
-time than the &SConscript; file statement calling the builder.
-It is not useful to wrap a builder call in a
-<systemitem>try</systemitem> block,
-since success in the builder call is not the same as
-the builder itself succeeding.
-If necessary, a Builder's Action should be coded to exit with
-a useful exception message indicating the problem in the &SConscript; files -
-programmatically recovering from build errors is rarely useful.
+All targets of builder methods automatically depend on their sources.
+&SCons; automatically scans
+source files for various programming languages,
+eliminating the need for explicit dependency specification.
+By default, &SCons; can scan
+C source files,
+C++ source files,
+Fortran source files with
+<filename>.F</filename>
+(POSIX systems only),
+<filename>.fpp</filename>,
+or
+<filename>.FPP</filename>
+file extensions,
+and assembly language files with
+<filename>.S</filename>
+(POSIX systems only),
+<filename>.spp</filename>,
+or
+<filename>.SPP</filename>
+files extensions
+for C preprocessor dependencies.
+SCons also has default support
+for scanning D source files.
+You can also specify an explicit dependency
+using the &f-link-env-Depends; method
+of a &consenv;.
+</para>
+
+<para>
+Builders are created at runtime for efficiency
+and added to the &consenv; as methods.
+&SCons; provides templates for a large number
+of Builders for known build types,
+and additional Builders can be written to add to a project.
+The templates usually exist in
+<link linkend='tools'>Tool specification modules</link>,
+which, when run, can probe for the presence of required external tools,
+such as a compiler binary,
+and for other necessary conditions,
+before instantiating the Builder.
+The Builders available in a given &consenv; thus vary
+with the type of platform, how the platform is provisioned,
+and the tools selected for loading.
+The available builder methods are registered as
+key-value pairs in the &cv-link-BUILDERS; attribute of the &consenv;.
 </para>
 
 <para>
-The following builder methods are predefined in the
-&SCons; core software distribution.
-Depending on the setup of a particular
-&consenv; and on the type and software
-installation status of the underlying system,
-not all builders may be available in that
-&consenv;.
-Since the function calling signature is the same for all builders:
+Although a Builder is created as a method of a &consenv;,
+many may also be called as if they were a global function.
+These will be indicated in the listing of Builders below
+without a leading <varname>env.</varname>
+A Builder called this way will internally use the
+&DefEnv; to look up &consvars;:
 </para>
+
 <programlisting language="python">
-<function>Buildername</function>(<parameter>target, source, [key=val, ...]</parameter>)
+Program('hello', 'hello.c')
+SharedLibrary('word', 'word.cpp')
 </programlisting>
+
+<para>
+Builders called in the global function style
+are automatically in scope inside &SConscript; files.
+They are not in scope
+in project-specific &Python; modules that you include
+via the &Python; <literal>import</literal> statement
+from an &SConscript; file,
+and you will need to add them to that module’s global scope explicitly.
+You can do that by adding the following import to the &Python; module:
+<userinput>from SCons.Script import *</userinput>.
+</para>
+
 <para>
-it is omitted in this listing for brevity.
+The following builder methods have templates in the
+&SCons; core software distribution.
 </para>
 
+
 <!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
 <!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
 
@@ -3343,62 +3272,13 @@ it is omitted in this listing for brevity.
 <!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
 <!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
 
-
-<para>All
-targets of builder methods automatically depend on their sources.
-An explicit dependency can
-be specified using the
-&f-link-env-Depends;
-method of a &consenv; (see below).</para>
-
-<para>In addition,
-&scons;
-automatically scans
-source files for various programming languages,
-so the dependencies do not need to be specified explicitly.
-By default, SCons can
-C source files,
-C++ source files,
-Fortran source files with
-<filename>.F</filename>
-(POSIX systems only),
-<filename>.fpp</filename>,
-or
-<filename>.FPP</filename>
-file extensions,
-and assembly language files with
-<filename>.S</filename>
-(POSIX systems only),
-<filename>.spp</filename>,
-or
-<filename>.SPP</filename>
-files extensions
-for C preprocessor dependencies.
-SCons also has default support
-for scanning D source files,
-You can also write your own Scanners
-to add support for additional source file types.
-These can be added to the default
-Scanner object used by the
-&b-link-Object;, &b-link-StaticObject; and &b-link-SharedObject;
-Builders by adding them
-to the
-<classname>SourceFileScanner</classname>
-object.
-See <xref linkend="scanner_objects"/>
-for more information about
-defining your own Scanner objects
-and using the
-<classname>SourceFileScanner</classname>
-object.</para>
-
 </refsect2>
 
 <refsect2 id='env_methods'>
 <title>&SCons; Functions and Environment Methods</title>
 
 <para>
-&SCons; provides a variety of  &consenv; methods
+&SCons; provides a variety of &consenv; methods
 and global functions to manipulate the build configuration.
 Often, a &consenv; method and a global function with
 the same name exist for convenience.
@@ -3441,19 +3321,17 @@ with two key differences:
 <orderedlist>
 <listitem>
 <para>
-&Consenv; methods that change the environment
+&Consenv; methods that read from or change the environment
 act on the environment instance from which they are called,
-while the corresponding global function acts on
-a special “hidden” &consenv; called the Default Environment.
-In some cases, the global function may take
-an initial argument giving the object to operate on.
+while the corresponding global function reads from
+a special “hidden” &consenv; called the &DefEnv;
 </para>
 </listitem>
 <listitem>
 <para>
 String-valued arguments
 (including strings in list-valued arguments)
-are subject to construction variable expansion
+are subject to &consvar; expansion
 by the environment method form;
 variable expansion is not immediately performed in the global function.
 For example, <userinput>Default('$MYTARGET')</userinput>
@@ -5844,7 +5722,7 @@ Adding new Tool modules is described in
 <title>Builder Objects</title>
 
 <para>&scons;
-can be extended to build different types of targets
+can be extended to build additional types of targets
 by adding new Builder objects
 to a &consenv;.
 <emphasis>In general</emphasis>,
@@ -5853,7 +5731,7 @@ when you want to build a new type of file or other external target.
 For output file types &scons; already knows about,
 you can usually modify the behavior of premade Builders
 such as &b-link-Program;, &b-link-Object; or &b-link-Library;
-by changing the &consvars; they use
+by changing the &consvars; that control their behavior
 (&cv-link-CC;, &cv-link-LINK;, etc.).
 In this manner you can, for example, change the compiler to use,
 which is simpler and less error-prone than writing a new builder.
@@ -5865,8 +5743,8 @@ The documentation for each Builder lists which
 using the
 &f-link-Builder;
 factory function.
-Once created, a builder is added to an environment
-by entering it in the &cv-link-BUILDERS; dictionary
+Once created, a builder is added to a &consenv;
+by registering it in the &cv-link-BUILDERS; dictionary
 in that environment (some of the examples
 in this section illustrate this).
 Doing so automatically triggers &SCons; to add a method
@@ -6399,16 +6277,14 @@ env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
 
 <warning>
 <para>
-&Python; only keeps one current directory
-location even if there are multiple threads.
+&Python; only tracks one current directory location,
+even if there are multiple executing threads.
 This means that use of the
 <parameter>chdir</parameter>
-argument
-will
+argument will
 <emphasis>not</emphasis>
-work with the SCons
-<option>-j</option>
-option,
+work with &SCons; in multi-threaded mode
+(the <link linkend="opt-jobs"><option>-j</option></link> option),
 because individual worker threads spawned
 by SCons interfere with each other
 when they start changing directory.</para>
@@ -6420,8 +6296,8 @@ when they start changing directory.</para>
 <para>Any additional keyword arguments supplied
 when a Builder object is created
 (that is, when the &f-link-Builder; function is called)
-will be set in the executing construction
-environment when the Builder object is called.
+will be set in the executing &consenv;
+when the Builder object is called.
 The canonical example here would be
 to set a &consvar; to
 the repository of a source code system.</para>
@@ -6440,6 +6316,19 @@ and
 <link linkend='emitter_function'>emitter functions</link>.
 </para>
 
+<para>
+When handling errors in a custom builder method,
+remember that the corresponding Action is executed at a different
+time than the &SConscript; file statement calling the builder.
+Wrapping a builder call in a <systemitem>try</systemitem> block
+is not useful,
+as success of the builder call is not the same as
+the build itself succeeding.
+If necessary, code a Builder's Action to exit with
+a useful exception message indicating the problem in the &SConscript; files.
+Programmatic recovery from build errors is rarely useful.
+</para>
+
 </refsect2>
 
 <refsect2 id='action_objects'>
@@ -6583,7 +6472,7 @@ will expand &consvars; in any argument strings,
 including
 <parameter>action</parameter>,
 at the time it is called,
-using the construction variables in the &consenv; through which
+using the &consvars; in the &consenv; through which
 it was called. The global function form &f-link-Action;
 delays variable expansion until
 the Action object is actually used.