Move some pieces around in builder docs

This is part of unmerged PR SCons#4671. This change moves two short
sections around:

* The note on builders and dependencies is moved to before the listing
  of methods be consistent with the other three sections of this type:
  all "descriptive text" followed by included generated listing, with
  no text following that.

* The note on debugging user-written builders moves from the
  Builder Methods section to the Builder Objects section, where it
  seems more natural: the need to debug a builder seems a lot less
  likely with the pre-built Builders. Some rewording, as well.

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

Author: mwichmann

CHANGES.txt

@@ -182,6 +182,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       support batch mode (currently: Windows).  Change the way the changed
       and unchanged target and source lists are accounted for to resolve.
       Fixes #3029.
+    - Improve documentation of builder methods and builder objects.
 
 
 RELEASE 4.9.1 -  Thu, 27 Mar 2025 11:40:20 -0700

RELEASE.txt

@@ -154,6 +154,8 @@ DOCUMENTATION
 
 - Improve the wording of AppendENVPath and PrependENVPath in manpage.
 
+- Improve documentation of builder methods and builder objects.
+
 DEVELOPMENT
 -----------
 

doc/man/scons.xml

@@ -3281,64 +3281,6 @@ 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.
-</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:
-</para>
-<programlisting language="python">
-<function>Buildername</function>(<parameter>target, source, [key=val, ...]</parameter>)
-</programlisting>
-<para>
-it is omitted in this listing for brevity.
-</para>
-
-<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
-<!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
-
-<!-- '\" The descriptions below of the various SCons Builders are generated -->
-<!-- '\" from the .xml files located together with the various Python -->
-<!-- '\" builder modules in the build engine directory -->
-
-<!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
-<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
-<xsi:include xmlns:xsi="http://www.w3.org/2001/XInclude" href="../generated/builders.gen"/>
-<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
-<!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
-
-<!-- '\" The descriptions abocve of the various SCons Builders are generated -->
-<!-- '\" from the .xml files located together with the various Python -->
-<!-- '\" builder modules in the build engine directory -->
-
-<!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
-<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
-
-
 <para>All
 targets of builder methods automatically depend on their sources.
 An explicit dependency can
@@ -3387,13 +3329,58 @@ and using the
 <classname>SourceFileScanner</classname>
 object.</para>
 
+
+<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>
+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:
+</para>
+<programlisting language="python">
+<function>Buildername</function>(<parameter>target, source, [key=val, ...]</parameter>)
+</programlisting>
+<para>
+it is omitted in this listing for brevity.
+</para>
+
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
+
+<!-- '\" The descriptions below of the various SCons Builders are generated -->
+<!-- '\" from the .xml files located together with the various Python -->
+<!-- '\" builder modules in the build engine directory -->
+
+<!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<xsi:include xmlns:xsi="http://www.w3.org/2001/XInclude" href="../generated/builders.gen"/>
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+<!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
+
+<!-- '\" The descriptions abocve of the various SCons Builders are generated -->
+<!-- '\" from the .xml files located together with the various Python -->
+<!-- '\" builder modules in the build engine directory -->
+
+<!-- '\" END GENERATED BUILDER DESCRIPTIONS -->
+<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
+
 </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.
@@ -6484,6 +6471,21 @@ and
 <link linkend='emitter_function'>emitter functions</link>.
 </para>
 
+<para>
+When debugging errors in a custom builder method,
+remember that the builder's Action is executed asynchronously -
+the builder call in the &SConscript; only instructs
+&SCons; what you want built, while the actual building is
+scheduled later (if necessary) by the taskmaster.
+As a result, wrapping a builder call in a
+<systemitem>try</systemitem> block is not useful,
+as success in the builder call is not the same as
+the build itself succeeding.
+If necessary, code a builder's Action to exit with
+a useful error message indicating the problem in the &SConscript; file.
+Attempting programmatic recovery from build errors is rarely useful.
+</para>
+
 </refsect2>
 
 <refsect2 id='action_objects'>