Merge pull request #4665 from mwichmann/doc/source-subst-special

Update docs on special method evaluation

6 files changed, 58 insertions, 31 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 01bb5c6..3082252 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -193,6 +193,9 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       and other attributes rather than indexing into stat return.
     - The update-release-info test is adapted to accept changed help output
       introduced in Python 3.12.8/3.13.1.
+    - Update the User Guide Command() example which now shows a target name
+      being created from '${SOURCE.base}.out' to use a valid special
+      attribute and to explain what's being done in the example.
 
     From Adam Scott:
     - Changed Ninja's TEMPLATE rule pool to use `install_pool` instead of
diff --git a/RELEASE.txt b/RELEASE.txt
index 5fbf662..19927a3 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -220,6 +220,10 @@ DOCUMENTATION
 
 - Improved Variables documentation.
 
+- Update the User Guide Command() example which now shows a target name
+  being created from '${SOURCE.base}.out' to use a valid special
+  attribute and to explain what's being done in the example.
+
 DEVELOPMENT
 -----------
 
diff --git a/doc/generated/examples/builderscommands_ex5_1.xml b/doc/generated/examples/builderscommands_ex3_1.xml
index 67659c1..67659c1 100644
--- a/doc/generated/examples/builderscommands_ex5_1.xml
+++ b/doc/generated/examples/builderscommands_ex3_1.xml
diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml
index d7e8c34..ff6611c 100644
--- a/doc/user/builders-commands.xml
+++ b/doc/user/builders-commands.xml
@@ -142,37 +142,53 @@ foo.in
 
   <para>
 
-  Note that &cv-link-SOURCE; and &cv-link-TARGET; are expanded
-  in the source and target as well, so you can write:
+  &cv-link-SOURCE; and &cv-link-TARGET; are expanded
+  in the source and target as well:
 
   </para>
 
-  <scons_example name="builderscommands_ex3">
-     <file name="SConstruct" printme="1">
-env.Command('${SOURCE.basename}.out', 'foo.in', build)
-     </file>
-  </scons_example>
+  <!-- NOTE: this used to be an scons_example, but was not complete and
+       didn't have a matching scons_output, which meant problems were not
+       detected. The style of this line is now reused in the last example
+       of the section to make sure it's actually tested
+       (see issue #2905 - which was closed prematurely).
+  -->
+  <sconstruct>
+env.Command('${SOURCE.base}.out', File('foo.in'), build)
+  </sconstruct>
 
   <para>
 
-  which does the same thing as the previous example, but allows you
-  to avoid repeating yourself.
+  Which does the same thing as the previous example, but allows you
+  to write a more generic rule for transforming the source filename
+  to the target filename, since unlike regular Builders,
+  &Command; does not have any built-in rules for that.
 
   </para>
 
+  <tip>
+    <title>Sidebar: Node Special Attributes</title>
+
   <para>
 
-  It may be helpful to use the <parameter>action</parameter>
-  keyword to specify the action, is this makes things more clear
-  to the reader:
+  The example uses a <firstterm>Node special attribute</firstterm>
+  (<literal>.base</literal>, the file without its suffix),
+  a concept which has not been introduced yet,
+  but will appear in several subsequent examples
+  (see details in the Reference Manual section
+  <emphasis>Substitution: Special Attributes</emphasis>).
+  Due to the quirks of &SCons;' deferred evaluation scheme,
+  node special attribues do not currently work
+  in source and target arguments <emphasis>if</emphasis> the
+  replacement is a string (like <literal>'foo.in'</literal>).
+  They do work fine in strings describing actions.
+  You can give &SCons; a little help by
+  manually converting the filename string to a Node
+  (see <xref linkend="sect-creating-nodes"/>),
+  which is the approach used in the example.
 
   </para>
-
-  <scons_example name="builderscommands_ex4">
-     <file name="SConstruct" printme="1">
-env.Command('${SOURCE.basename}.out', 'foo.in', action=build)
-     </file>
-  </scons_example>
+  </tip>
 
   <para>
 
@@ -187,11 +203,13 @@ env.Command('${SOURCE.basename}.out', 'foo.in', action=build)
   which include a message based on the type of action.
   However, you can also construct the &Action; object yourself
   to pass to &f-Command;, which gives you much more control.
+  Using the <parameter>action</parameter> keyword can also help
+  make such lines easier to read.
   Here's an evolution of the example from above showing this approach:
 
   </para>
 
-  <scons_example name="builderscommands_ex5">
+  <scons_example name="builderscommands_ex3">
      <file name="SConstruct" printme="1">
 env = Environment()
 
@@ -200,7 +218,7 @@ def build(target, source, env):
     return None
 
 act = Action(build, cmdstr="Building ${TARGET}")
-env.Command('foo.out', 'foo.in', action=act)
+env.Command('${SOURCE.base}.out', File('foo.in'), action=act)
      </file>
      <file name="foo.in">
 foo.in
@@ -213,7 +231,7 @@ foo.in
 
   </para>
 
-  <scons_output example="builderscommands_ex5" suffix="1">
+  <scons_output example="builderscommands_ex3" suffix="1">
     <scons_output_command>scons -Q</scons_output_command>
   </scons_output>
 
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 6807694..75d8ddd 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -1877,8 +1877,10 @@ env.Command('foo', [], '__ROOT__/usr/bin/printenv.py')
       </file>
       <file name="__ROOT__/usr/bin/printenv.py" chmod="0o755">
 #!/usr/bin/env python
+
 import os
 import sys
+
 if len(sys.argv) &gt; 1:
     keys = sys.argv[1:]
 else:
@@ -2133,7 +2135,7 @@ env.SomeTool(targets, sources)
       </para>
 
 <sconstruct>
-# For Windows based on the python version and install directory, this may be something like
+# For Windows based on the Python version and install directory, this may be something like
 C:\Python35\Lib\site-packages\someinstalledpackage\SomeTool.py
 C:\Python35\Lib\site-packages\someinstalledpackage\SomeTool\__init__.py
 
@@ -2172,10 +2174,10 @@ env.SomeTool(targets, sources)
       To avoid the use of a prefix within the name of the tool or filtering
       <varname>sys.path</varname> for directories,
       we can use &f-link-PyPackageDir; function to locate the directory of
-      the python package.
+      the &Python; package.
       &f-PyPackageDir; returns a Dir object which represents the path of the
       directory
-      for the python package / module specified as a parameter.
+      for the &Python; package / module specified as a parameter.
       </para>
 
       <sconstruct>
diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml
index a652e79..eba6014 100644
--- a/doc/user/nodes.xml
+++ b/doc/user/nodes.xml
@@ -40,7 +40,7 @@ This file is processed by the bin/SConsDoc.py module.
 
   </para>
 
-  <section>
+  <section id="sect-builder-nodelists">
   <title>Builder Methods Return Lists of Target Nodes</title>
 
     <para>
@@ -150,7 +150,7 @@ int main() { printf("Goodbye, world!\n"); }
 
   </section>
 
-  <section>
+  <section id="sect-creating-nodes">
   <title>Explicitly Creating File and Directory Nodes</title>
 
     <para>
@@ -228,7 +228,7 @@ xyzzy = Entry('xyzzy')
 
   </section>
 
-  <section>
+  <section id="sect-printing-nodes">
   <title>Printing &Node; File Names</title>
 
     <para>
@@ -290,7 +290,7 @@ int main() { printf("Hello, world!\n"); }
 
   </section>
 
-  <section>
+  <section id="sect-node-names">
   <title>Using a &Node;'s File Name as a String</title>
 
     <para>
@@ -337,7 +337,7 @@ int main() { printf("Hello, world!\n"); }
 
   </section>
 
-  <section>
+  <section id="sect-node-paths">
   <title>&GetBuildPath;: Getting the Path From a &Node; or String</title>
 
     <para>
@@ -384,7 +384,7 @@ print(env.GetBuildPath([n, "sub/dir/$VAR"]))
 
   <!--
 
-  <section>
+  <section id="sect-node-contents">
   <title>Fetching the Contents of a &Node;</title>
 
     <para>
@@ -422,7 +422,7 @@ int main() { printf("Hello, world!\n"); }
 
   <!--
 
-  <section>
+  <section id="sect-value-nodes">
   <title>Python Value &Node;</title>
 
     <para>