Set global lxml etree XSLT maximum traversal depth. Update generated documentation artifacts.

4 files changed, 105 insertions, 69 deletions

diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
index a2d9acd..efc4c9e 100644
--- a/doc/generated/functions.gen
+++ b/doc/generated/functions.gen
@@ -1611,45 +1611,49 @@ See the manpage section "Construction Environments" for more details.
 </listitem>
   </varlistentry>
   <varlistentry id="f-Execute">
-    <term><function>Execute</function>(<parameter>action, [strfunction, varlist]</parameter>)</term>
-    <term><replaceable>env</replaceable>.<methodname>Execute</methodname>(<parameter>action, [strfunction, varlist]</parameter>)</term>
+    <term><function>Execute</function>(<parameter>action, [actionargs ...]</parameter>)</term>
+    <term><replaceable>env</replaceable>.<methodname>Execute</methodname>(<parameter>action, [actionargs ...]</parameter>)</term>
     <listitem><para>
-Executes an Action object.
-The specified
+Executes an Action.
 <parameter>action</parameter>
 may be an Action object
-(see manpage section "Action Objects"
-for an explanation of behavior),
 or it may be a command-line string,
 list of commands,
 or executable &Python; function,
-each of which will be converted
+each of which will first be converted
 into an Action object
 and then executed.
 Any additional arguments to &f-Execute;
-(<parameter>strfunction</parameter>, <parameter>varlist</parameter>)
 are passed on to the &f-link-Action; factory function
-which actually creates the Action object.
-The exit value of the command
-or return value of the &Python; function
-will be returned.
+which actually creates the Action object
+(see the manpage section <link linkend="action_objects">Action Objects</link>
+for a description). Example:
+</para>
+
+<example_commands>
+Execute(Copy('file.out', 'file.in'))
+</example_commands>
+
+<para>&f-Execute; performs its action immediately,
+as part of the SConscript-reading phase.
+There are no sources or targets declared in an
+&f-Execute; call, so any objects it manipulates
+will not be tracked as part of the &SCons; dependency graph.
+In the example above, neither
+<filename>file.out</filename> nor
+<filename>file.in</filename> will be tracked objects.
 </para>
 
 <para>
-Note that
+&f-Execute; returns the exit value of the command
+or return value of the &Python; function.
 &scons;
-will print an error message if the executed
+prints an error message if the executed
 <parameter>action</parameter>
-fails--that is,
-exits with or returns a non-zero value.
-&scons;
-will
+fails (exits with or returns a non-zero value),
+however it does
 <emphasis>not</emphasis>,
-however,
-automatically terminate the build
-if the specified
-<parameter>action</parameter>
-fails.
+automatically terminate the build for such a failure.
 If you want the build to stop in response to a failed
 &f-Execute;
 call,
@@ -1657,8 +1661,6 @@ you must explicitly check for a non-zero return value:
 </para>
 
 <example_commands>
-Execute(Copy('file.out', 'file.in'))
-
 if Execute("mkdir sub/dir/ectory"):
     # The mkdir failed, don't try to build.
     Exit(1)
diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen
index ecc301a..35ded17 100644
--- a/doc/generated/tools.gen
+++ b/doc/generated/tools.gen
@@ -389,35 +389,35 @@ Sets construction variables for the dvips utility.
     <listitem><para>
 Set construction variables for generic POSIX Fortran 03 compilers.
 </para>
-<para>Sets: &cv-link-F03;, &cv-link-F03COM;, &cv-link-F03FLAGS;, &cv-link-F03PPCOM;, &cv-link-SHF03;, &cv-link-SHF03COM;, &cv-link-SHF03FLAGS;, &cv-link-SHF03PPCOM;, &cv-link-_F03INCFLAGS;.</para><para>Uses: &cv-link-F03COMSTR;, &cv-link-F03PPCOMSTR;, &cv-link-SHF03COMSTR;, &cv-link-SHF03PPCOMSTR;.</para></listitem>
+<para>Sets: &cv-link-F03;, &cv-link-F03COM;, &cv-link-F03FLAGS;, &cv-link-F03PPCOM;, &cv-link-SHF03;, &cv-link-SHF03COM;, &cv-link-SHF03FLAGS;, &cv-link-SHF03PPCOM;, &cv-link-_F03INCFLAGS;.</para><para>Uses: &cv-link-F03COMSTR;, &cv-link-F03PPCOMSTR;, &cv-link-FORTRANCOMMONFLAGS;, &cv-link-SHF03COMSTR;, &cv-link-SHF03PPCOMSTR;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-f08">
     <term>f08</term>
     <listitem><para>
 Set construction variables for generic POSIX Fortran 08 compilers.
 </para>
-<para>Sets: &cv-link-F08;, &cv-link-F08COM;, &cv-link-F08FLAGS;, &cv-link-F08PPCOM;, &cv-link-SHF08;, &cv-link-SHF08COM;, &cv-link-SHF08FLAGS;, &cv-link-SHF08PPCOM;, &cv-link-_F08INCFLAGS;.</para><para>Uses: &cv-link-F08COMSTR;, &cv-link-F08PPCOMSTR;, &cv-link-SHF08COMSTR;, &cv-link-SHF08PPCOMSTR;.</para></listitem>
+<para>Sets: &cv-link-F08;, &cv-link-F08COM;, &cv-link-F08FLAGS;, &cv-link-F08PPCOM;, &cv-link-SHF08;, &cv-link-SHF08COM;, &cv-link-SHF08FLAGS;, &cv-link-SHF08PPCOM;, &cv-link-_F08INCFLAGS;.</para><para>Uses: &cv-link-F08COMSTR;, &cv-link-F08PPCOMSTR;, &cv-link-FORTRANCOMMONFLAGS;, &cv-link-SHF08COMSTR;, &cv-link-SHF08PPCOMSTR;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-f77">
     <term>f77</term>
     <listitem><para>
 Set construction variables for generic POSIX Fortran 77 compilers.
 </para>
-<para>Sets: &cv-link-F77;, &cv-link-F77COM;, &cv-link-F77FILESUFFIXES;, &cv-link-F77FLAGS;, &cv-link-F77PPCOM;, &cv-link-F77PPFILESUFFIXES;, &cv-link-FORTRAN;, &cv-link-FORTRANCOM;, &cv-link-FORTRANFLAGS;, &cv-link-SHF77;, &cv-link-SHF77COM;, &cv-link-SHF77FLAGS;, &cv-link-SHF77PPCOM;, &cv-link-SHFORTRAN;, &cv-link-SHFORTRANCOM;, &cv-link-SHFORTRANFLAGS;, &cv-link-SHFORTRANPPCOM;, &cv-link-_F77INCFLAGS;.</para><para>Uses: &cv-link-F77COMSTR;, &cv-link-F77PPCOMSTR;, &cv-link-FORTRANCOMSTR;, &cv-link-FORTRANPPCOMSTR;, &cv-link-SHF77COMSTR;, &cv-link-SHF77PPCOMSTR;, &cv-link-SHFORTRANCOMSTR;, &cv-link-SHFORTRANPPCOMSTR;.</para></listitem>
+<para>Sets: &cv-link-F77;, &cv-link-F77COM;, &cv-link-F77FILESUFFIXES;, &cv-link-F77FLAGS;, &cv-link-F77PPCOM;, &cv-link-F77PPFILESUFFIXES;, &cv-link-FORTRAN;, &cv-link-FORTRANCOM;, &cv-link-FORTRANFLAGS;, &cv-link-SHF77;, &cv-link-SHF77COM;, &cv-link-SHF77FLAGS;, &cv-link-SHF77PPCOM;, &cv-link-SHFORTRAN;, &cv-link-SHFORTRANCOM;, &cv-link-SHFORTRANFLAGS;, &cv-link-SHFORTRANPPCOM;, &cv-link-_F77INCFLAGS;.</para><para>Uses: &cv-link-F77COMSTR;, &cv-link-F77PPCOMSTR;, &cv-link-FORTRANCOMMONFLAGS;, &cv-link-FORTRANCOMSTR;, &cv-link-FORTRANFLAGS;, &cv-link-FORTRANPPCOMSTR;, &cv-link-SHF77COMSTR;, &cv-link-SHF77PPCOMSTR;, &cv-link-SHFORTRANCOMSTR;, &cv-link-SHFORTRANFLAGS;, &cv-link-SHFORTRANPPCOMSTR;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-f90">
     <term>f90</term>
     <listitem><para>
 Set construction variables for generic POSIX Fortran 90 compilers.
 </para>
-<para>Sets: &cv-link-F90;, &cv-link-F90COM;, &cv-link-F90FLAGS;, &cv-link-F90PPCOM;, &cv-link-SHF90;, &cv-link-SHF90COM;, &cv-link-SHF90FLAGS;, &cv-link-SHF90PPCOM;, &cv-link-_F90INCFLAGS;.</para><para>Uses: &cv-link-F90COMSTR;, &cv-link-F90PPCOMSTR;, &cv-link-SHF90COMSTR;, &cv-link-SHF90PPCOMSTR;.</para></listitem>
+<para>Sets: &cv-link-F90;, &cv-link-F90COM;, &cv-link-F90FLAGS;, &cv-link-F90PPCOM;, &cv-link-SHF90;, &cv-link-SHF90COM;, &cv-link-SHF90FLAGS;, &cv-link-SHF90PPCOM;, &cv-link-_F90INCFLAGS;.</para><para>Uses: &cv-link-F90COMSTR;, &cv-link-F90PPCOMSTR;, &cv-link-FORTRANCOMMONFLAGS;, &cv-link-SHF90COMSTR;, &cv-link-SHF90PPCOMSTR;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-f95">
     <term>f95</term>
     <listitem><para>
 Set construction variables for generic POSIX Fortran 95 compilers.
 </para>
-<para>Sets: &cv-link-F95;, &cv-link-F95COM;, &cv-link-F95FLAGS;, &cv-link-F95PPCOM;, &cv-link-SHF95;, &cv-link-SHF95COM;, &cv-link-SHF95FLAGS;, &cv-link-SHF95PPCOM;, &cv-link-_F95INCFLAGS;.</para><para>Uses: &cv-link-F95COMSTR;, &cv-link-F95PPCOMSTR;, &cv-link-SHF95COMSTR;, &cv-link-SHF95PPCOMSTR;.</para></listitem>
+<para>Sets: &cv-link-F95;, &cv-link-F95COM;, &cv-link-F95FLAGS;, &cv-link-F95PPCOM;, &cv-link-SHF95;, &cv-link-SHF95COM;, &cv-link-SHF95FLAGS;, &cv-link-SHF95PPCOM;, &cv-link-_F95INCFLAGS;.</para><para>Uses: &cv-link-F95COMSTR;, &cv-link-F95PPCOMSTR;, &cv-link-FORTRANCOMMONFLAGS;, &cv-link-SHF95COMSTR;, &cv-link-SHF95PPCOMSTR;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-fortran">
     <term>fortran</term>
@@ -437,10 +437,8 @@ Set construction variables for the &gXX; C++ compiler.
     <term>g77</term>
     <listitem><para>
 Set construction variables for the &g77; Fortran compiler.
-Calls the &t-f77; Tool module
-to set variables.
 </para>
-</listitem>
+<para>Sets: &cv-link-F77;, &cv-link-F77COM;, &cv-link-F77FILESUFFIXES;, &cv-link-F77PPCOM;, &cv-link-F77PPFILESUFFIXES;, &cv-link-FORTRAN;, &cv-link-FORTRANCOM;, &cv-link-FORTRANPPCOM;, &cv-link-SHF77;, &cv-link-SHF77COM;, &cv-link-SHF77FLAGS;, &cv-link-SHF77PPCOM;, &cv-link-SHFORTRAN;, &cv-link-SHFORTRANCOM;, &cv-link-SHFORTRANFLAGS;, &cv-link-SHFORTRANPPCOM;.</para><para>Uses: &cv-link-F77FLAGS;, &cv-link-FORTRANCOMMONFLAGS;, &cv-link-FORTRANFLAGS;.</para></listitem>
   </varlistentry>
   <varlistentry id="t-gas">
     <term>gas</term>
@@ -516,7 +514,8 @@ environment:
   <varlistentry id="t-gfortran">
     <term>gfortran</term>
     <listitem><para>
-Sets construction variables for the GNU F95/F2003 GNU compiler.
+Sets construction variables for the GNU Fortran compiler.
+Calls the &t-link-fortran; Tool module to set variables.
 </para>
 <para>Sets: &cv-link-F77;, &cv-link-F90;, &cv-link-F95;, &cv-link-FORTRAN;, &cv-link-SHF77;, &cv-link-SHF77FLAGS;, &cv-link-SHF90;, &cv-link-SHF90FLAGS;, &cv-link-SHF95;, &cv-link-SHF95FLAGS;, &cv-link-SHFORTRAN;, &cv-link-SHFORTRANFLAGS;.</para></listitem>
   </varlistentry>
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index c34b70c..32db05e 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -2682,6 +2682,17 @@ in the &cv-link-FORTRANFLAGS;,
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-FORTRANCOMMONFLAGS">
+    <term>
+      <envar>FORTRANCOMMONFLAGS</envar>
+    </term>
+    <listitem><para>
+General user-specified options that are passed to the Fortran compiler.
+Similar to &cv-link-FORTRANFLAGS;,
+but this variable is applied to all dialects.
+</para>
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-FORTRANCOMSTR">
     <term>
       <envar>FORTRANCOMSTR</envar>
@@ -2709,7 +2720,8 @@ default, this is <literal>['.f', '.for', '.ftn']</literal>
       <envar>FORTRANFLAGS</envar>
     </term>
     <listitem><para>
-General user-specified options that are passed to the Fortran compiler.
+General user-specified options for the FORTRAN dialect
+that are passed to the Fortran compiler.
 Note that this variable does
 <emphasis>not</emphasis>
 contain
@@ -6578,44 +6590,65 @@ A Python function used to print the command lines as they are executed
 or
 <option>-s</option>
 options or their equivalents).
-The function should take four arguments:
+The function must accept four arguments:
 <varname>s</varname>,
-the command being executed (a string),
 <varname>target</varname>,
-the target being built (file node, list, or string name(s)),
+<varname>source</varname> and
+<varname>env</varname>.
+<varname>s</varname>
+is a string showing the command being executed,
+<varname>target</varname>,
+is the target being built (file node, list, or string name(s)),
 <varname>source</varname>,
-the source(s) used (file node, list, or string name(s)), and
-<varname>env</varname>,
-the environment being used.
+is the source(s) used (file node, list, or string name(s)),
+and <varname>env</varname>
+is the environment being used.
 </para>
 
 <para>
-The function must do the printing itself.  The default implementation,
-used if this variable is not set or is None, is:
+The function must do the printing itself.
+The default implementation,
+used if this variable is not set or is <constant>None</constant>,
+is to just print the string, as in:
 </para>
 <example_commands>
 def print_cmd_line(s, target, source, env):
-  sys.stdout.write(s + "\n")
+    sys.stdout.write(s + "\n")
 </example_commands>
 
 <para>
-Here's an example of a more interesting function:
+Here is an example of a more interesting function:
 </para>
 
 <example_commands>
 def print_cmd_line(s, target, source, env):
-   sys.stdout.write("Building %s -&gt; %s...\n" %
-    (' and '.join([str(x) for x in source]),
-     ' and '.join([str(x) for x in target])))
-env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
-env.Program('foo', 'foo.c')
+    sys.stdout.write(
+        "Building %s -&gt; %s...\n"
+        % (
+            ' and '.join([str(x) for x in source]),
+            ' and '.join([str(x) for x in target]),
+        )
+    )
+
+env = Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
+env.Program('foo', ['foo.c', 'bar.c'])
 </example_commands>
 
 <para>
-This just prints "Building <varname>targetname</varname> from <varname>sourcename</varname>..." instead
-of the actual commands.
-Such a function could also log the actual commands to a log file,
-for example.
+This prints:
+</para>
+
+<screen>
+...
+scons: Building targets ...
+Building bar.c -&gt; bar.o...
+Building foo.c -&gt; foo.o...
+Building foo.o and bar.o -&gt; foo...
+scons: done building targets.
+</screen>
+
+<para>
+Another example could be a function that logs the actual commands to a file.
 </para>
 </listitem>
   </varlistentry>
@@ -7587,9 +7620,9 @@ targets.
 def custom_shell_env(env, target, source, shell_env):
     """customize shell_env if desired"""
     if str(target[0]) == 'special_target':
-      shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=target, source=source)
+        shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=target, source=source)
     return shell_env
-  
+
 env["SHELL_ENV_GENERATORS"] = [custom_shell_env]
     </example_commands>
 
@@ -7663,7 +7696,7 @@ Options that are passed to the Fortran 03 compiler
 to generated shared-library objects.
 You only need to set &cv-link-SHF03FLAGS; if you need to define specific
 user options for Fortran 03 files.
-You should normally set the &cv-link-SHFORTRANFLAGS; variable,
+You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
 which specifies the user-specified options
 passed to the default Fortran compiler
 for all Fortran versions.
@@ -7751,7 +7784,7 @@ Options that are passed to the Fortran 08 compiler
 to generated shared-library objects.
 You only need to set &cv-link-SHF08FLAGS; if you need to define specific
 user options for Fortran 08 files.
-You should normally set the &cv-link-SHFORTRANFLAGS; variable,
+You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
 which specifies the user-specified options
 passed to the default Fortran compiler
 for all Fortran versions.
@@ -7839,7 +7872,7 @@ Options that are passed to the Fortran 77 compiler
 to generated shared-library objects.
 You only need to set &cv-link-SHF77FLAGS; if you need to define specific
 user options for Fortran 77 files.
-You should normally set the &cv-link-SHFORTRANFLAGS; variable,
+You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
 which specifies the user-specified options
 passed to the default Fortran compiler
 for all Fortran versions.
@@ -7927,7 +7960,7 @@ Options that are passed to the Fortran 90 compiler
 to generated shared-library objects.
 You only need to set &cv-link-SHF90FLAGS; if you need to define specific
 user options for Fortran 90 files.
-You should normally set the &cv-link-SHFORTRANFLAGS; variable,
+You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
 which specifies the user-specified options
 passed to the default Fortran compiler
 for all Fortran versions.
@@ -8015,7 +8048,7 @@ Options that are passed to the Fortran 95 compiler
 to generated shared-library objects.
 You only need to set &cv-link-SHF95FLAGS; if you need to define specific
 user options for Fortran 95 files.
-You should normally set the &cv-link-SHFORTRANFLAGS; variable,
+You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable,
 which specifies the user-specified options
 passed to the default Fortran compiler
 for all Fortran versions.
@@ -8389,7 +8422,7 @@ which would be a symlink and point to <filename>libtest.so.0.1.2</filename>
     </term>
     <listitem><para>
 A command interpreter function that will be called to execute command line
-strings. The function must expect the following arguments:
+strings. The function must accept five arguments:
 </para>
 
 <example_commands>
@@ -8397,18 +8430,18 @@ def spawn(shell, escape, cmd, args, env):
 </example_commands>
 
 <para>
-<varname>sh</varname>
-is a string naming the shell program to use.
+<varname>shell</varname>
+is a string naming the shell program to use,
 <varname>escape</varname>
 is a function that can be called to escape shell special characters in
-the command line.
+the command line,
 <varname>cmd</varname>
-is the path to the command to be executed.
+is the path to the command to be executed,
 <varname>args</varname>
-is the arguments to the command.
+holds the arguments to the command and
 <varname>env</varname>
-is a dictionary of the environment variables
-in which the command should be executed.
+is a dictionary of environment variables
+defining the execution environment in which the command should be executed.
 </para>
 </listitem>
   </varlistentry>
diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod
index d3d29f2..cc51043 100644
--- a/doc/generated/variables.mod
+++ b/doc/generated/variables.mod
@@ -186,6 +186,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-File "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$File</envar>">
 <!ENTITY cv-FORTRAN "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRAN</envar>">
 <!ENTITY cv-FORTRANCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRANCOM</envar>">
+<!ENTITY cv-FORTRANCOMMONFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRANCOMMONFLAGS</envar>">
 <!ENTITY cv-FORTRANCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRANCOMSTR</envar>">
 <!ENTITY cv-FORTRANFILESUFFIXES "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRANFILESUFFIXES</envar>">
 <!ENTITY cv-FORTRANFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRANFLAGS</envar>">
@@ -854,6 +855,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-link-File "<link linkend='cv-File' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$File</envar></link>">
 <!ENTITY cv-link-FORTRAN "<link linkend='cv-FORTRAN' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRAN</envar></link>">
 <!ENTITY cv-link-FORTRANCOM "<link linkend='cv-FORTRANCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRANCOM</envar></link>">
+<!ENTITY cv-link-FORTRANCOMMONFLAGS "<link linkend='cv-FORTRANCOMMONFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRANCOMMONFLAGS</envar></link>">
 <!ENTITY cv-link-FORTRANCOMSTR "<link linkend='cv-FORTRANCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRANCOMSTR</envar></link>">
 <!ENTITY cv-link-FORTRANFILESUFFIXES "<link linkend='cv-FORTRANFILESUFFIXES' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRANFILESUFFIXES</envar></link>">
 <!ENTITY cv-link-FORTRANFLAGS "<link linkend='cv-FORTRANFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRANFLAGS</envar></link>">