Builder and Variable Subst doc updates [ci skip]

Work on Builder Methods and Variable Substitution man sections - some
wording tweaks, do some formatting markup a little more consistently,
etc.

Tweak the wording for the Command builder, a description shared
between manpage and userguide.

Closes #3030: Environment.xml had many references to detail sections
elsewhere, like "see XXX section below," which don't work well -
this xml is generated into both the manpage and the user guide,
and the locality of saying "below" is incorrect for the latter since
those sections are only in the manpage. Essentially these are changed
to say "see the manpage section XXX". Adding clickable links is of
course also possible, but I recall there was some objection to
cross-document links, so I didn't do that.

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

1 files changed, 211 insertions, 151 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index faec455..c1773c7 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1921,7 +1921,7 @@ These warnings are enabled by default.</para>
 <option>--debug=object</option>
 feature not working when
 <command>scons</command>
-is run with the python
+is run with the Python
 <option>-O</option>
 option or from optimized Python (.pyo) modules.</para>
 
@@ -2048,7 +2048,7 @@ env['BAR'] = 'bar'
 
 <para>As a convenience,
 construction variables may also be set or modified by the
-<emphasis>parse_flags</emphasis>
+<emphasis role="bold">parse_flags</emphasis>
 keyword argument, which applies the
 &f-link-env-MergeFlags;
 method (described below) to the argument value
@@ -2228,7 +2228,7 @@ def exists(env):
   return True
 
 # in SConstruct:
-env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
+env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})],
                   toolpath=['tools'])
 </programlisting>
 
@@ -2247,7 +2247,7 @@ With a nested tool name the dot represents a directory seperator</para>
 
 <programlisting>
 # namespaced builder
-env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool'])
+env = Environment(ENV=os.environ, tools=['SubDir1.SubDir2.SomeTool'])
 env.SomeTool(targets, sources)
 
 # Search Paths
@@ -2293,75 +2293,104 @@ env.SomeTool(targets, sources)
 
 <refsect2 id='builder_methods'><title>Builder Methods</title>
 
-<para>Build rules are specified by calling a construction
-environment's builder methods.
-The arguments to the builder methods are
-<emphasis role="bold">target</emphasis>
-(a list of targets to be built,
-usually file names)
+<para>You tell <program>scons</program> what to build
+by calling Builders, functions which know to take a
+particular action when given files of a particular type
+to produce a particular result type. <program>scons</program>
+defines a number of builders, and you can also write your own.
+Builders are attached to a &consenv; as methods,
+and the available builder methods are listed as
+key-value pairs in the
+<envar>BUILDERS</envar> attribute of the &consenv;.
+The available builders can be displayed like this
+for debugging purposes:
+</para>
+
+<literallayout class="monospaced">
+print("Builders:", list(env['BUILDERS']))
+</literalllayout>
+
+<para>
+Builder methods always take two arguments:
+<replaceable>target</replaceable>
+(a target or a list of targets to be built)
 and
-<emphasis role="bold">source</emphasis>
-(a list of sources to be built,
-usually file names).</para>
+<replaceable>source</replaceable>
+(a source or list of sources to be used as input
+when building),
+although in some circumstances,
+the target argument can actually be omitted (see below).
+Builder methods also take a variety of
+keyword arguments, described below.
+</para>
 
 <para>Because long lists of file names
 can lead to a lot of quoting,
 <command>scons</command>
-supplies a
-<emphasis role="bold">Split()</emphasis>
+supplies a &Split;
 global function
 and a same-named environment method
 that split a single string
 into a list, separated on
 strings of white-space characters.
-(These are similar to the split() member function of Python strings
-but work even if the input isn't a string.)</para>
+(These are similar to the Python string <function>split</function>
+method, but work even if the input isn't a string.)</para>
 
-<para>Like all Python arguments,
-the target and source arguments to a builder method
-can be specified either with or without
-the "target" and "source" keywords.
-When the keywords are omitted,
-the target is first,
-followed by the source.
-The following are equivalent examples of calling the Program builder method:</para>
+<para>
+The target and source arguments to a builder method
+can be specified either as positional arguments,
+in which case the target comes first, or as
+keyword arguments, using <parameter>target=</parameter>
+and <parameter>source=</parameter>.
+The following are equivalent examples of calling the
+&Program; builder method:
+</para>
 
 <literallayout class="monospaced">
 env.Program('bar', ['bar.c', 'foo.c'])
 env.Program('bar', Split('bar.c foo.c'))
 env.Program('bar', env.Split('bar.c foo.c'))
-env.Program(source =  ['bar.c', 'foo.c'], target = 'bar')
-env.Program(target = 'bar', Split('bar.c foo.c'))
-env.Program(target = 'bar', env.Split('bar.c foo.c'))
-env.Program('bar', source = 'bar.c foo.c'.split())
+env.Program(source=['bar.c', 'foo.c'], target='bar')
+env.Program(target='bar', source=Split('bar.c foo.c'))
+env.Program(target='bar', source=env.Split('bar.c foo.c'))
+env.Program('bar', source='bar.c foo.c'.split())
 </literallayout>
 
-<para>Target and source file names
-that are not absolute path names
-(that is, do not begin with
-<emphasis role="bold">/</emphasis>
-on POSIX systems
-or
-<emphasis role="bold">\</emphasis>
-on Windows systems,
-with or without
-an optional drive letter)
-are interpreted relative to the directory containing the
-<emphasis role="bold">SConscript</emphasis>
-file being read.
-An initial
-<emphasis role="bold">#</emphasis>
-(hash mark)
-on a path name means that the rest of the file name
-is interpreted relative to
-the directory containing
-the top-level
-<emphasis role="bold">SConstruct</emphasis>
-file,
-even if the
-<emphasis role="bold">#</emphasis>
-is followed by a directory separator character
-(slash or backslash).</para>
+<para>
+Python follows the POSIX pathname convention for path
+strings: if a string begins with the operating system pathname separator
+(on Windows both the slash and backslash separator work,
+and any leading drive specifier is ignored for
+the determination) it is considered an absolute path,
+otherwise it is a relative path.
+If the path string contains no separator characters,
+it is searched for as a file in the current directory. If it
+contains separator characters, the search follows down
+from the starting point, which is the top of the directory tree for
+an absolute path and the current directory for a relative path.
+</para>
+<para>
+<command>scons</command> recognizes a third way to specify
+path strings: if the string begins with
+the <emphasis role="bold">#</emphasis> character it is
+top-relative - it works like a relative path but the
+search follows down from the directory containing the top-level
+<emphasis role="bold">SConstruct</emphasis> rather than
+from the current directory (the # is allowed
+to be followed by a pathname separator, which is ignored if
+found in that position).
+Top-relative paths only work in places where &scons; will
+interpret the path (see some examples below).  To be
+used in other contexts the string will need to be converted
+to a relative or absolute path first.
+</para>
+
+<para>
+Target and source pathnames can be absolute, relative, or
+top-relative. Relative pathnames are searched considering the
+directory of the <emphasis role="bold">SConscript</emphasis>
+file currently being processed as the "current directory".
+</para>
 
 <para>Examples:</para>
 
@@ -2403,12 +2432,12 @@ executable program
 or
 <emphasis role="bold">bar.exe</emphasis>
 (on Windows systems)
-from the bar.c source file:</para>
+from the <filename>bar.c</filename> source file:</para>
 
 <literallayout class="monospaced">
-env.Program(target = 'bar', source = 'bar.c')
-env.Program('bar', source = 'bar.c')
-env.Program(source = 'bar.c')
+env.Program(target='bar', source='bar.c')
+env.Program('bar', source='bar.c')
+env.Program(source='bar.c')
 env.Program('bar.c')
 </literallayout>
 
@@ -2418,28 +2447,31 @@ keyword argument may be specified
 when calling a Builder.
 When specified,
 all source file strings that are not absolute paths
+or top-relative paths
 will be interpreted relative to the specified
 <emphasis role="bold">srcdir</emphasis>.
 The following example will build the
-<emphasis role="bold">build/prog</emphasis>
+<filename>build/prog</filename>
 (or
-<emphasis role="bold">build/prog.exe</emphasis>
+<filename>build/prog.exe</filename>
 on Windows)
 program from the files
-<emphasis role="bold">src/f1.c</emphasis>
+<filename>src/f1.c</filename>
 and
-<emphasis role="bold">src/f2.c</emphasis>:</para>
+<filename>src/f2.c</filename>:
+</para>
 
 <literallayout class="monospaced">
 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
 </literallayout>
 
-<para>It is possible to override or add construction variables when calling a
-builder method by passing additional keyword arguments.
-These overridden or added
-variables will only be in effect when building the target, so they will not
-affect other parts of the build. For example, if you want to add additional
-libraries for just one program:</para>
+<para>It is possible to <emphasis>override</emphasis> (replace or add)
+construction variables when calling a
+builder method by passing them as keyword arguments.
+These overrides
+will only be in effect when building that target, and will not
+affect other parts of the build. For example, if you want to specify
+some libraries needed by just one program:</para>
 
 <literallayout class="monospaced">
 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
@@ -2459,7 +2491,7 @@ for dependencies on the non-standard library names;
 see the descriptions of these variables, below, for more information.)</para>
 
 <para>It is also possible to use the
-<emphasis>parse_flags</emphasis>
+<emphasis role="bold">parse_flags</emphasis>
 keyword argument in an override,
 to merge command-line style arguments
 into the appropriate construction variables
@@ -2504,8 +2536,7 @@ from SCons.Script import *
 </literallayout>
 
 <para>All builder methods return a list-like object
-containing Nodes that
-represent the target or targets that will be built.
+containing Nodes that will be built.
 A
 <emphasis>Node</emphasis>
 is an internal SCons object
@@ -2517,9 +2548,8 @@ can be passed to other builder methods as source(s)
 or passed to any SCons function or method
 where a filename would normally be accepted.
 For example, if it were necessary
-to add a specific
-<option>-D</option>
-flag when compiling one specific object file:</para>
+to add a specific preprocessor define
+when compiling one specific object file:</para>
 
 <literallayout class="monospaced">
 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
@@ -2530,14 +2560,14 @@ env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
 makes for a more portable build
 by avoiding having to specify
 a platform-specific object suffix
-when calling the Program() builder method.</para>
+when calling the &Program; builder method.</para>
 
-<para>Note that Builder calls will automatically "flatten"
+<para>Note that builder calls will automatically "flatten"
 the source and target file lists,
-so it's all right to have the bar_obj list
-return by the StaticObject() call
+so it's all right to have the <literal>bar_obj_list</literal>
+returned by the &StaticObject; call
 in the middle of the source file list.
-If you need to manipulate a list of lists returned by Builders
+If you need to manipulate a list of lists returned by builders
 directly using Python,
 you can either build the list by hand:</para>
 
@@ -2549,8 +2579,7 @@ for object in objects:
     print(str(object))
 </literallayout>
 
-<para>Or you can use the
-<emphasis role="bold">Flatten</emphasis>()
+<para>Or you can use the &Flatten;
 function supplied by scons
 to create a list containing just the Nodes,
 which may be more convenient:</para>
@@ -2563,23 +2592,23 @@ for object in objects:
     print(str(object))
 </literallayout>
 
-<para>Note also that because Builder calls return
+<para>Note also that because builder calls return
 a list-like object, not an actual Python list,
 you should
 <emphasis>not</emphasis>
-use the Python
-<emphasis role="bold">+=</emphasis>
-operator to append Builder results to a Python list.
+use the Python add
+operator (<literal>+</literal> or <literal>+=</literal>)
+to append builder results to a Python list.
 Because the list and the object are different types,
 Python will not update the original list in place,
 but will instead create a new Node-list object
 containing the concatenation of the list
-elements and the Builder results.
+elements and the builder results.
 This will cause problems for any other Python variables
 in your SCons configuration
 that still hold on to a reference to the original list.
-Instead, use the Python
-<markup>.extend()</markup>
+Instead, use the Python list
+<function>extend</function>
 method to make sure the list is updated in-place.
 Example:</para>
 
@@ -2592,7 +2621,7 @@ object_files = []
 #
 # It will not update the object_files list in place.
 #
-# Instead, use the .extend() method:
+# Instead, use the list extend method:
 object_files.extend(Object('bar.c'))
 
 </literallayout>
@@ -2609,7 +2638,7 @@ print("The path to bar_obj is:", str(bar_obj_list[0]))
 
 <para>Note again that because the Builder call returns a list,
 we have to access the first element in the list
-<emphasis role="bold">(bar_obj_list[0])</emphasis>
+(<literal>(bar_obj_list[0])</literal>)
 to get at the Node that actually represents
 the object file.</para>
 
@@ -2672,7 +2701,12 @@ to use just the filename portion of the
 targets and source.</para>
 
 <para><command>scons</command>
-provides the following builder methods:</para>
+predefined the following builder methods.
+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 to that
+&consenv;.</para>
 
 <!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
 <!-- '\" BEGIN GENERATED BUILDER DESCRIPTIONS -->
@@ -4409,7 +4443,7 @@ functions return
 and
 <emphasis>Dir</emphasis>
 Nodes, respectively.
-python objects, respectively.
+Python objects, respectively.
 Those objects have several user-visible attributes
 and methods that are often useful:</para>
 
@@ -5426,17 +5460,15 @@ a = Action(build_it, varlist=['XXX'])
 </programlisting>
 
 <para>The
-<emphasis role="bold">Action</emphasis>()
+&Action;
 global function
 can be passed the following
 optional keyword arguments
 to modify the Action object's behavior:</para>
 
-
-<para><emphasis role="bold">chdir</emphasis>
-The
-<emphasis role="bold">chdir</emphasis>
-keyword argument specifies that
+<para>
+<replaceable>chdir</replaceable>
+specifies that
 scons will execute the action
 after changing to the specified directory.
 If the
@@ -5481,15 +5513,9 @@ a = Action("build &lt; ${SOURCE.file} &gt; ${TARGET.file}",
            chdir=1)
 </literallayout>
 
-
-<para><emphasis role="bold">exitstatfunc</emphasis>
-The
-<emphasis role="bold">Action</emphasis>()
-global function
-also takes an
-<emphasis role="bold">exitstatfunc</emphasis>
-keyword argument
-which specifies a function
+<para>
+<replaceable>exitstatfunc</replaceable>
+specifies a function
 that is passed the exit status
 (or return value)
 from the specified action
@@ -5511,11 +5537,9 @@ a = Action("build &lt; ${SOURCE.file} &gt; ${TARGET.file}",
 </programlisting>
 
 
-<para><emphasis role="bold">batch_key</emphasis>
-The
-<emphasis role="bold">batch_key</emphasis>
-keyword argument can be used
-to specify that the Action can create multiple target files
+<para>
+<replaceable>batch_key</replaceable>
+specifies that the Action can create multiple target files
 by processing multiple independent source files simultaneously.
 (The canonical example is "batch compilation"
 of multiple object files
@@ -5524,7 +5548,7 @@ to a single invocation of a compiler
 such as Microsoft's Visual C / C++ compiler.)
 If the
 <emphasis role="bold">batch_key</emphasis>
-argument is any non-False, non-callable Python value,
+argument evaluates True and is not a callable object,
 the configured Action object will cause
 <command>scons</command>
 to collect all targets built with the Action object
@@ -5556,7 +5580,7 @@ will be used to identify different
 for batch building.
 A
 <emphasis role="bold">batch_key</emphasis>
-function must take the following arguments:</para>
+function must accept the following arguments:</para>
 
 <variablelist>
   <varlistentry>
@@ -5688,7 +5712,7 @@ sequences of file manipulation
 without relying
 on platform-specific
 external commands:
-that</para>
+</para>
 <literallayout class="monospaced">
 env = Environment(TMPBUILD = '/tmp/builddir')
 env.Command('foo.out', 'foo.in',
@@ -5848,13 +5872,13 @@ env.Command('marker', 'input_file',
 
 <para>Before executing a command,
 <command>scons</command>
-performs construction variable interpolation on the strings that make up
-the command line of builders.
-Variables are introduced by a
-<emphasis role="bold">$</emphasis>
+performs construction variable interpolation on the string that makes up
+the command line of the builder.
+Variables are introduced in such strings by a
+<literal>$</literal>
 prefix.
-Besides construction variables, scons provides the following
-variables for each command execution:</para>
+Besides regular construction variables, scons provides the following
+special variables for each command execution:</para>
 
 <variablelist>
   <varlistentry>
@@ -5923,15 +5947,19 @@ from sources that have
 <emphasis>not</emphasis>
 changed since the target was last built.</para>
 
-<para>(Note that the above variables are reserved
-and may not be set in a construction environment.)</para>
-
   </listitem>
   </varlistentry>
 </variablelist>
 
-<para>For example, given the construction variable CC='cc', targets=['foo'], and
-sources=['foo.c', 'bar.c']:</para>
+<para>Note that the above variables are reserved
+and may not be set in a construction environment.</para>
+
+<para>For example, given the construction variables
+<literal>CC='cc'</literal>,
+<literal>targets=['foo']</literal>
+and
+<literal>sources=['foo.c', 'bar.c']</literal>:
+</para>
 
 <literallayout class="monospaced">
 action='$CC -c -o $TARGET $SOURCES'
@@ -5944,7 +5972,8 @@ cc -c -o foo foo.c bar.c
 </literallayout>
 
 <para>Variable names may be surrounded by curly braces ({})
-to separate the name from the trailing characters.
+to separate the name from surrounding characters which
+are not part of the name.
 Within the curly braces, a variable name may have
 a Python slice subscript appended to select one
 or more items from a list.
@@ -6107,20 +6136,42 @@ may be a callable Python function
 associated with a
 construction variable in the environment.
 The function should
-take four arguments:
-<emphasis>target</emphasis>
-- a list of target nodes,
-<emphasis>source</emphasis>
-- a list of source nodes,
-<emphasis>env</emphasis>
-- the construction environment,
-<emphasis>for_signature</emphasis>
-- a Boolean value that specifies
+accept four arguments:
+</para>
+<variablelist>
+  <varlistentry>
+  <term><replaceable>target</replaceable></term>
+  <listitem>
+<para>a list of target nodes</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><replaceable>source</replaceable></term>
+  <listitem>
+<para>a list of source nodes</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><replaceable>env</replaceable></term>
+  <listitem>
+<para>the construction environment</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><replaceable>for_signature</replaceable></term>
+  <listitem>
+<para>a Boolean value that specifies
 whether the function is being called
-for generating a build signature.
+for generating a build signature. </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
 SCons will insert whatever
 the called function returns
-into the expanded string:</para>
+into the expanded string:
+</para>
 
 <programlisting>
 def foo(target, source, env, for_signature):
@@ -6201,9 +6252,10 @@ echo Last build occurred  . &gt; $TARGET
 
 <refsect2 id='python_code_substitution'><title>Python Code Substitution</title>
 
-<para>Any python code within
-<emphasis role="bold">${</emphasis>-<emphasis role="bold">}</emphasis>
-pairs gets evaluated by python 'eval', with the python globals set to
+<para>Any Python code within
+curly braces (and introduced by the variable prefix <literal>$</literal>)
+gets evaluated by the Python <function>eval</function> statement,
+with the Python globals set to
 the current environment's set of construction variables.
 So in the following case:</para>
 <literallayout class="monospaced">
@@ -6219,14 +6271,20 @@ echo FOO &gt; foo.out
 <literallayout class="monospaced">
 echo BAR &gt; foo.out
 </literallayout>
-<para>according to the current value of env['COND'] when the command is
-executed.  The evaluation occurs when the target is being
-built, not when the SConscript is being read.  So if env['COND'] is changed
+<para>according to the current value of <literal>env['COND']</literal>
+when the command is executed.
+The evaluation takes place when the target is being
+built, not when the SConscript is being read.  So if
+<literal>env['COND']</literal> is changed
 later in the SConscript, the final value will be used.</para>
 
-<para>Here's a more interesting example.  Note that all of COND, FOO, and
-BAR are environment variables, and their values are substituted into
-the final command.  FOO is a list, so its elements are interpolated
+<para>Here's a more interesting example.  Note that all of
+<envar>COND</envar>,
+<envar>FOO</envar>,
+and
+<envar>BAR</envar> are construction variables,
+and their values are substituted into the final command.
+<envar>FOO</envar> is a list, so its elements are interpolated
 separated by spaces.</para>
 
 <literallayout class="monospaced">
@@ -6574,9 +6632,10 @@ do this, in part,
 by sharing an ability to interpret UNIX-like path names.
 For example, the Cygwin tools
 will internally translate a Cygwin path name
-like /cygdrive/c/mydir
+like <filename>/cygdrive/c/mydir</filename>
 to an equivalent Windows pathname
-of C:/mydir (equivalent to C:\mydir).</para>
+of <filename>C:/mydir</filename> (equivalent to <filename>C:\mydir</filename>).
+</para>
 
 <para>Versions of Python
 that are built for native Windows execution,
@@ -6584,7 +6643,8 @@ such as the python.org and ActiveState versions,
 do not have the Cygwin path name semantics.
 This means that using a native Windows version of Python
 to build compiled programs using Cygwin tools
-(such as gcc, bison, and flex)
+(such as <command>gcc</command>, <command>bison</command>,
+and <command>flex</command>)
 may yield unpredictable results.
 "Mixing and matching" in this way
 can be made to work,