Update markup on TARGETS, SOURCES, ARGUMENTS [ci skip]

Use <varname> to mark up variables in these three areas,
also a few other variables that were marked up differently.
Sometimes that markup comes in the form of using an existing
entity (&BUILD_TARGETS; for example), which is already
suitably marked up in the entity definition.

Use <parameter> to mark up when they're in the context of
function params.

The parse_flags kwarg now includes a link to the env.ParseFlags
method, since the latter describes how the args are distributed.

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

1 files changed, 55 insertions, 51 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 5630e93..6c46462 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1185,11 +1185,11 @@ and re-initialize the dependency graph from scratch.</para>
       <term><emphasis role="bold">build</emphasis><emphasis>[OPTIONS] [TARGETS] ...</emphasis></term>
       <listitem>
 <para>Builds the specified
-<emphasis>TARGETS</emphasis>
+<parameter>TARGETS</parameter>
 (and their dependencies)
 with the specified
 SCons command-line
-<emphasis>OPTIONS</emphasis>.
+<parameter>OPTIONS</parameter>.
 <emphasis role="bold">b</emphasis>
 and
 <emphasis role="bold">scons</emphasis>
@@ -1232,9 +1232,10 @@ which only happens once at the beginning of interactive mode).</para>
       <term><emphasis role="bold">clean</emphasis><emphasis>[OPTIONS] [TARGETS] ...</emphasis></term>
       <listitem>
 <para>Cleans the specified
-<emphasis>TARGETS</emphasis>
+<parameter>TARGETS</parameter>
 (and their dependencies)
-with the specified options.
+with the specified
+<parameter>OPTIONS</parameter>.
 <emphasis role="bold">c</emphasis>
 is a synonym.
 This command is itself a synonym for
@@ -2000,15 +2001,15 @@ These warnings are enabled by default.</para>
   <listitem>
 <para>Warnings about attempts to set the
 reserved &consvar; names
-<envar>CHANGED_SOURCES</envar>,
-<envar>CHANGED_TARGETS</envar>,
-<envar>TARGET</envar>,
-<envar>TARGETS</envar>,
-<envar>SOURCE</envar>,
-<envar>SOURCES</envar>,
-<envar>UNCHANGED_SOURCES</envar>
+<varname>CHANGED_SOURCES</varname>,
+<varname>CHANGED_TARGETS</varname>,
+<varname>TARGET</varname>,
+<varname>TARGETS</varname>,
+<varname>SOURCE</varname>,
+<varname>SOURCES</varname>,
+<varname>UNCHANGED_SOURCES</varname>
 or
-<envar>UNCHANGED_TARGETS</envar>.
+<varname>UNCHANGED_TARGETS</varname>.
 These warnings are disabled by default.</para>
   </listitem>
   </varlistentry>
@@ -2105,7 +2106,7 @@ env['BAR'] = 'bar'
 
 <para>As a convenience,
 &consvars; may also be set or modified by the
-<parameter class="function">parse_flags</parameter>
+<parameter>parse_flags</parameter>
 keyword argument, which applies the
 &f-link-env-MergeFlags;
 method (described below) to the argument value
@@ -2119,11 +2120,15 @@ env = Environment(parse_flags='-Iinclude -DEBUG -lm')
 </programlisting>
 
 <para>This example adds 'include' to
-<envar>CPPPATH</envar>,
+the <varname>CPPPATH</varname> &consvar;
 'EBUG' to
-<envar>CPPDEFINES</envar>,
+<varname>CPPDEFINES</varname>,
 and 'm' to
-<envar>LIBS</envar>.</para>
+<varname>LIBS</varname>.
+&f-link-env-ParseFlags; describes how these arguments
+are distributed to &consvars;.
+</para>
+
 
 <para>By default, a new &consenv; is
 initialized with a set of builder methods
@@ -2148,21 +2153,21 @@ and suffixes appropriate for that platform.</para>
 <para>Note that the
 <emphasis role="bold">win32</emphasis>
 platform adds the
-<emphasis role="bold">SystemDrive</emphasis>
+<varname>SystemDrive</varname>
 and
-<emphasis role="bold">SystemRoot</emphasis>
+<varname>SystemRoot</varname>
 variables from the user's external environment
 to the &consenv;'s
-<emphasis role="bold">ENV</emphasis>
+<varname>ENV</varname>
 dictionary.
 This is so that any executed commands
 that use sockets to connect with other systems
 (such as fetching source files from
 external CVS repository specifications like
-<emphasis role="bold">:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</emphasis>)
+<literal>:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</literal>)
 will work on Windows systems.</para>
 
-<para>The platform argument may be a function or callable object.
+<para>The <parameter>platform</parameter> argument may be a function or callable object,
 in which case the &Environment; method
 will call it to update
 the new &consenv;:</para>
@@ -2259,15 +2264,15 @@ env = Environment(tools=[my_tool])
 may also themselves be two-element lists of the form
 (<emphasis>toolname</emphasis>, <emphasis>kw_dict</emphasis>).
 SCons searches for the
-<emphasis>toolname</emphasis>
+<parameter>toolname</parameter>
 specification file as described above, and
 passes
-<emphasis>kw_dict</emphasis>,
+<parameter>kw_dict</parameter>,
 which must be a dictionary, as keyword arguments to the tool's
-<emphasis role="bold">generate</emphasis>
+<function>generate</function>
 function.
 The
-<emphasis role="bold">generate</emphasis>
+<function>generate</function>
 function can use the arguments to modify the tool's behavior
 by setting up the environment in different ways
 or otherwise changing its initialization.</para>
@@ -2535,7 +2540,7 @@ env.SharedLibrary('word', 'word.cpp',
                   LIBSUFFIXES=['.ocx'])
 </programlisting>
 
-<para>Note that both the <envar>$SHLIBSUFFIX</envar> and <envar>$LIBSUFFIXES</envar>
+<para>Note that both the <varname>$SHLIBSUFFIX</varname> and <varname>$LIBSUFFIXES</varname>
 variables must be set if you want SCons to search automatically
 for dependencies on the non-standard library names;
 see the descriptions of these variables, below, for more information.</para>
@@ -2553,11 +2558,11 @@ env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
 </programlisting>
 
 <para>This example adds 'include' to
-<emphasis role="bold">CPPPATH</emphasis>,
+<varname>CPPPATH</varname>,
 'EBUG' to
-<emphasis role="bold">CPPDEFINES</emphasis>,
+<varname>CPPDEFINES</varname>,
 and 'm' to
-<emphasis role="bold">LIBS</emphasis>.</para>
+<varname>LIBS</varname>.</para>
 
 <para>Although the builder methods defined by
 &scons;
@@ -2938,7 +2943,7 @@ to affect how you want the build to be performed.</para>
 
 <variablelist>
   <varlistentry>
-  <term>ARGLIST</term>
+  <term>&ARGLIST;</term>
   <listitem>
 <para>A list of the
 <emphasis>keyword</emphasis>=<emphasis>value</emphasis>
@@ -2971,7 +2976,7 @@ for key, value in ARGLIST:
   </varlistentry>
 
   <varlistentry>
-  <term>ARGUMENTS</term>
+  <term>&ARGUMENTS;</term>
   <listitem>
 <para>A dictionary of all the
 <emphasis>keyword</emphasis>=<emphasis>value</emphasis>
@@ -2981,8 +2986,7 @@ and if a given keyword has
 more than one value assigned to it
 on the command line,
 the last (right-most) value is
-the one in the
-<emphasis role="bold">ARGUMENTS</emphasis>
+the one in the &ARGUMENTS;
 dictionary.</para>
 
 <para>Example:</para>
@@ -2997,7 +3001,7 @@ else:
   </varlistentry>
 
   <varlistentry>
-  <term>BUILD_TARGETS</term>
+  <term>&BUILD_TARGETS;</term>
   <listitem>
 <para>A list of the targets which
 &scons;
@@ -3043,7 +3047,7 @@ if 'special/program' in BUILD_TARGETS:
   </varlistentry>
 
   <varlistentry>
-  <term>COMMAND_LINE_TARGETS</term>
+  <term>&COMMAND_LINE_TARGETS;</term>
   <listitem>
 <para>A list of the targets explicitly specified on
 the command line. If there are command line targets,
@@ -3066,7 +3070,7 @@ if 'special/program' in COMMAND_LINE_TARGETS:
   </varlistentry>
 
   <varlistentry>
-  <term>DEFAULT_TARGETS</term>
+  <term>&DEFAULT_TARGETS;</term>
   <listitem>
 <para>A list of the target
 <emphasis>nodes</emphasis>
@@ -5610,10 +5614,10 @@ and configured with the same &consenv;
 into single invocations of the Action object's
 command line or function.
 Command lines will typically want to use the
-<emphasis role="bold">CHANGED_SOURCES</emphasis>
+<varname>cHANGED_SOURCES</varname>
 &consvar;
 (and possibly
-<emphasis role="bold">CHANGED_TARGETS</emphasis>
+<varname>CHANGED_TARGETS</varname>
 as well)
 to only pass to the command line those sources that
 have actually changed since their targets were built.</para>
@@ -5944,7 +5948,7 @@ special variables for each command execution:</para>
 
 <variablelist>
   <varlistentry>
-  <term>CHANGED_SOURCES</term>
+  <term><varname>CHANGED_SOURCES</varname></term>
   <listitem>
 <para>The file names of all sources of the build command
 that have changed since the target was last built.</para>
@@ -5952,7 +5956,7 @@ that have changed since the target was last built.</para>
   </varlistentry>
 
   <varlistentry>
-  <term>CHANGED_TARGETS</term>
+  <term><varname>CHANGED_TARGETS</varname></term>
   <listitem>
 <para>The file names of all targets that would be built
 from sources that have changed since the target was last built.</para>
@@ -5960,7 +5964,7 @@ from sources that have changed since the target was last built.</para>
   </varlistentry>
 
   <varlistentry>
-  <term>SOURCE</term>
+  <term><varname>SOURCE</varname></term>
   <listitem>
 <para>The file name of the source of the build command,
 or the file name of the first source
@@ -5969,14 +5973,14 @@ if multiple sources are being built.</para>
   </varlistentry>
 
   <varlistentry>
-  <term>SOURCES</term>
+  <term><varname>SOURCES</varname></term>
   <listitem>
 <para>The file names of the sources of the build command.</para>
   </listitem>
   </varlistentry>
 
   <varlistentry>
-  <term>TARGET</term>
+  <term><varname>TARGET</varname></term>
   <listitem>
 <para>The file name of the target being built,
 or the file name of the first target
@@ -5985,14 +5989,14 @@ if multiple targets are being built.</para>
   </varlistentry>
 
   <varlistentry>
-  <term>TARGETS</term>
+  <term><varname>TARGETS</varname></term>
   <listitem>
 <para>The file names of all targets being built.</para>
   </listitem>
   </varlistentry>
 
   <varlistentry>
-  <term>UNCHANGED_SOURCES</term>
+  <term><varname>UNCHANGED_SOURCES</varname></term>
   <listitem>
 <para>The file names of all sources of the build command
 that have
@@ -6245,7 +6249,7 @@ env=Environment(FOO=foo, BAR="$FOO baz")
 Python function by creating a callable class
 that stores one or more arguments in an object,
 and then uses them when the
-<function>__call__()</function>
+<methodname>__call__()</methodname>
 method is called.
 Note that in this case,
 the entire variable expansion must
@@ -6347,12 +6351,12 @@ built, not when the SConscript is being read.  So if
 later in the SConscript, the final value will be used.</para>
 
 <para>Here's a more interesting example.  Note that all of
-<envar>COND</envar>,
-<envar>FOO</envar>,
+<varname>COND</varname>,
+<varname>FOO</varname>,
 and
-<envar>BAR</envar> are &consvars;,
+<varname>BAR</varname> are &consvars;,
 and their values are substituted into the final command.
-<envar>FOO</envar> is a list, so its elements are interpolated
+<varname>FOO</varname> is a list, so its elements are interpolated
 separated by spaces.</para>
 
 <programlisting language="python">
@@ -6929,7 +6933,7 @@ env.Program(target = 'bar', source = 'bar.c')
 </programlisting>
 
 <para>You also can use other Pythonic techniques to add
-to the <envar>BUILDERS</envar> &consvar;, such as:</para>
+to the <varname>BUILDERS</varname> &consvar;, such as:</para>
 
 <programlisting language="python">
 env = Environment()