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.