Manpage: note pre/post actions effect on an alias

CHANGES.txt

@@ -26,6 +26,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       are now more clearly distinguished (-live.py suffix and docstring).
     - runtest.py once again finds "external" tests, such as the tests for
       tools in scons-contrib. An earlier rework had broken this.  Fixes #4699.
+    - Clarify how pre/post actions on an alias work.
 
 
 RELEASE 4.9.1 -  Thu, 27 Mar 2025 11:40:20 -0700
@@ -41,6 +42,7 @@ RELEASE 4.9.1 -  Thu, 27 Mar 2025 11:40:20 -0700
   From Mats Wichmann:
     - Fix typos in CCFLAGS test. Didn't affect the test itself, but
       didn't correctly apply the DefaultEnvironment speedup.
+
     - New CacheDir initialization code failed on Python 3.7 for unknown
       reason (worked on 3.8+). Adjusted the approach a bit.  Fixes #4694.
     - Try to fix Windows fails on Docbook tests in case xsltproc is found.

RELEASE.txt

@@ -56,6 +56,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
 -----------
 
@@ -66,4 +68,5 @@ Thanks to the following contributors listed below for their contributions to thi
 ==========================================================================================
 .. code-block:: text
 
+
     git shortlog --no-merges -ns 4.9.1..HEAD

SCons/Environment.xml

@@ -348,7 +348,7 @@ 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
@@ -374,6 +374,12 @@ foo = Program('foo.c')
 AddPostAction(foo, Chmod('$TARGET', "a-x"))
 </example_commands>
 
+<para>
+If a <parameter>target</parameter> is an &f-Alias;,
+<parameter>action</parameter> is associated with the
+action of the alias, if specified.
+</para>
+
 </summary>
 </scons_function>
 
@@ -383,7 +389,7 @@ 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
@@ -406,31 +412,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 &f-Alias;,
+<parameter>action</parameter> is associated with the
+action of the alias, if specified.
 </para>
+
 </summary>
 </scons_function>
 
@@ -440,7 +454,7 @@ file into an object file.
 </arguments>
 <summary>
 <para>
-Creates an <firstterm>alias</firstterm> target that
+Create an <firstterm>Alias</firstterm> node 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