Manpage: note pre/post actions effect on an alias

CHANGES.txt

@@ -18,6 +18,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
   From Mats Wichmann:
     - Fix typos in CCFLAGS test. Didn't affect the test itself, but
       didn't correctly apply the DefaultEnvironment speedup.
+    - Clarify how pre/post actions on an alias work.
 
 
 RELEASE 4.9.0 -  Sun, 02 Mar 2025 17:22:20 -0700

RELEASE.txt

@@ -53,6 +53,8 @@ DOCUMENTATION
   typo fixes, even if they're mentioned in src/CHANGES.txt to give
   the contributor credit)
 
+- Clarify how pre/post actions on an alias work.
+
 DEVELOPMENT
 -----------
 
@@ -62,4 +64,4 @@ Thanks to the following contributors listed below for their contributions to thi
 ==========================================================================================
 .. code-block:: text
 
-    git shortlog --no-merges -ns 4.0.1..HEAD
+    git shortlog --no-merges -ns 4.9.0..HEAD

SCons/Environment.xml

@@ -348,12 +348,15 @@ env.other_method_name('another arg')
 </arguments>
 <summary>
 <para>
-Arranges for the specified
+Arrange for the specified
 <parameter>action</parameter>
 to be performed
 after the specified
 <parameter>target</parameter>
 has been built.
+<parameter>target</parameter>
+may be a string or Node object,
+or a list of strings or Node objects.
 <parameter>action</parameter> may be
 an Action object, or anything that
 can be converted into an Action object.
@@ -374,6 +377,12 @@ foo = Program('foo.c')
 AddPostAction(foo, Chmod('$TARGET', "a-x"))
 </example_commands>
 
+<para>
+If a <parameter>target</parameter> is an Alias target,
+<parameter>action</parameter> is associated with the
+action of the alias, if specified.
+</para>
+
 </summary>
 </scons_function>
 
@@ -383,12 +392,15 @@ AddPostAction(foo, Chmod('$TARGET', "a-x"))
 </arguments>
 <summary>
 <para>
-Arranges for the specified
+Arrange for the specified
 <parameter>action</parameter>
 to be performed
 before the specified
 <parameter>target</parameter>
 is built.
+<parameter>target</parameter>
+may be a string or Node object,
+or a list of strings or Node objects.
 <parameter>action</parameter> may be
 an Action object, or anything that
 can be converted into an Action object.
@@ -406,31 +418,39 @@ one or more targets in the list.
 <para>
 Note that if any of the targets are built in multiple steps,
 the action will be invoked just
-before the "final" action that specifically
+before the action step that specifically
 generates the specified target(s).
-For example, when building an executable program
-from a specified source
-<filename>.c</filename>
-file via an intermediate object file:
+It may not always be obvious
+if the process is multi-step - for example,
+if you use the &Program; builder to
+construct an executable program from a
+<filename>.c</filename> source file,
+&scons; builds an intermediate object file first;
+the pre-action is invoked after this step
+and just before the link command to
+generate the executable program binary.
+Example:
 </para>
 
 <example_commands>
 foo = Program('foo.c')
-AddPreAction(foo, 'pre_action')
+AddPreAction(foo, 'echo "Running pre-action"')
 </example_commands>
 
+<screen>
+$ scons -Q
+gcc -o foo.o -c foo.c
+echo "Running pre-action"
+Running pre-action
+gcc -o foo foo.o
+</screen>
+
 <para>
-The specified
-<literal>pre_action</literal>
-would be executed before
-&scons;
-calls the link command that actually
-generates the executable program binary
-<filename>foo</filename>,
-not before compiling the
-<filename>foo.c</filename>
-file into an object file.
+If a <parameter>target</parameter> is an Alias target,
+<parameter>action</parameter> is associated with the
+action of the alias, if specified.
 </para>
+
 </summary>
 </scons_function>
 
@@ -440,7 +460,7 @@ file into an object file.
 </arguments>
 <summary>
 <para>
-Creates an <firstterm>alias</firstterm> target that
+Create an <firstterm>Alias</firstterm> target that
 can be used as a reference to zero or more other targets,
 specified by the optional <parameter>source</parameter> parameter.
 Aliases provide a way to give a shorter or more descriptive