New manpage section on emitters

AGENTS.md

@@ -79,6 +79,13 @@ from `doc` and `doc/generated`), the SCons schema extension
 (`doc/xsd`), and the framework from `bin/SConsDoc.py`,
 which also contains information on some of the extensions.
 
+The generated files can be built on demand
+(`python bin/docs-update-generated.py`),
+and should never be directly edited.
+It is project convention *not* to commit the changes to generated
+files as they happen, but rather to commit the accumulated changes
+during the release process.
+
 ## Lint & Type
 
 ```bash

CHANGES.txt

@@ -47,6 +47,11 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Fix the ninja ctrl-c test, which was failing on some platforms.
     - Reference manual improvements:
       * Additional clarification for SideEffect()
+      * Split out a new section on Emitters with additional prose and
+        examples, since the information does not exclusively apply to
+        the emitter argument to Builder(). The Builder Objects "emitter"
+        argument section still has some wording, plus a link to the
+        new section.
     - User Guide improvements:
       * Removed the out-of-date table of option names for SetOption and
         GetOption and instead point to the maintained tables in Appendix D.

RELEASE.txt

@@ -87,6 +87,11 @@ DOCUMENTATION
   generated from the checked-in documentation sources by bin/scons-man-to-ai.py,
   and can be built with the "ai-manpage" target.
 
+* Split out a new section on Emitters with additional prose and examples,
+  since the information does not exclusively apply to the emitter argument
+  to Builder(). The Builder Objects "emitter" argument section still
+  has some wording, plus a link to the new section.
+
 DEVELOPMENT
 -----------
 

SCons/Environment.xml

@@ -888,19 +888,17 @@ for a complete explanation of the arguments and behavior.
 
 <para>
 Note that the
-<function>env.Builder</function>()
+&f-env-Builder;
 form of the invocation will expand
-&consvars; in any arguments strings,
+&consvars; in any argument strings,
 including the
 <parameter>action</parameter>
 argument,
-at the time it is called
-using the &consvars; in the
-<varname>env</varname>
-&consenv; through which
-&f-env-Builder; was called.
+at the time it is called,
+using the values from
+<varname>env</varname>.
 The
-&f-Builder;
+&f-Builder; (global fuction)
 form delays all variable expansion
 until after the Builder object is actually called.
 </para>

SCons/Tool/Tool.xml

@@ -511,10 +511,10 @@ determine the version of versioned import library.
 <cvar name="LIBEMITTER">
 <summary>
 <para>
-Contains the emitter specification for the
+A callable or list of callables used as the emitter for the
 &b-link-StaticLibrary; builder.
-The manpage section "Builder Objects" contains
-general information on specifying emitters.
+See the manpage section "Emitter Functions"
+for general emitter behavior.
 </para>
 </summary>
 </cvar>
@@ -535,32 +535,32 @@ specified in the same format as &cv-link-SHLIBVERSION;.
 <cvar name="LDMODULEEMITTER">
 <summary>
 <para>
-Contains the emitter specification for the
+A callable or list of callables used as the emitter for the
 &b-link-LoadableModule; builder.
-The manpage section "Builder Objects" contains
-general information on specifying emitters.
+See the manpage section "Emitter Functions"
+for general emitter behavior.
 </para>
 </summary>
 </cvar>
 
 <cvar name="SHLIBEMITTER">
 <summary>
 <para>
-Contains the emitter specification for the
+A callable or list of callables used as the emitter for the
 &b-link-SharedLibrary; builder.
-The manpage section "Builder Objects" contains
-general information on specifying emitters.
+See the manpage section "Emitter Functions"
+for general emitter behavior.
 </para>
 </summary>
 </cvar>
 
 <cvar name="PROGEMITTER">
 <summary>
 <para>
-Contains the emitter specification for the
+A callable or list of callables used as the emitter for the
 &b-link-Program; builder.
-The manpage section "Builder Objects" contains
-general information on specifying emitters.
+See the manpage section "Emitter Functions"
+for general emitter behavior.
 </para>
 </summary>
 </cvar>