Resync generated docs

There have been a few doc changes since 3.0.1, this commit
resyncs the generated docs to pick up fixes and wording.
No code or test effect.

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

9 files changed, 93 insertions, 59 deletions

diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
index d851c93..ada4e43 100644
--- a/doc/generated/builders.gen
+++ b/doc/generated/builders.gen
@@ -1206,13 +1206,15 @@ the following packagers available:
 
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
  * msi - Microsoft Installer
- * rpm - Redhat Package Manger
+ * rpm - RPM Package Manger
  * ipkg - Itsy Package Management System
- * tarbz2 - compressed tar
- * targz - compressed tar
+ * tarbz2 - bzip2 compressed tar
+ * targz - gzip compressed tar
+ * tarxz - xz compressed tar
  * zip - zip file
- * src_tarbz2 - compressed tar source
- * src_targz - compressed tar source
+ * src_tarbz2 - bzip2 compressed tar source
+ * src_targz - gzip compressed tar source
+ * src_tarxz - xz compressed tar source
  * src_zip - zip file source
 </para>
 
diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml
index 19b02f5..18b04eb 100644
--- a/doc/generated/examples/caching_ex-random_1.xml
+++ b/doc/generated/examples/caching_ex-random_1.xml
@@ -2,8 +2,8 @@
 <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
 cc -o f3.o -c f3.c
 cc -o f5.o -c f5.c
-cc -o f2.o -c f2.c
 cc -o f4.o -c f4.c
+cc -o f2.o -c f2.c
 cc -o f1.o -c f1.c
 cc -o prog f1.o f2.o f3.o f4.o f5.o
 </screen>
diff --git a/doc/generated/examples/environments_ex3_1.xml b/doc/generated/examples/environments_ex3_1.xml
index 12b6ae0..3262302 100644
--- a/doc/generated/examples/environments_ex3_1.xml
+++ b/doc/generated/examples/environments_ex3_1.xml
@@ -1,22 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
-UnicodeDecodeError: 'utf8' codec can't decode byte 0xc2 in position 547: invalid continuation byte:
-  File "/home/my/project/SConstruct", line 6:
-    dbg.Program('foo', 'foo.c')
-  File "bootstrap/src/engine/SCons/Environment.py", line 260:
-    return MethodWrapper.__call__(self, target, source, *args, **kw)
-  File "bootstrap/src/engine/SCons/Environment.py", line 224:
-    return self.method(*nargs, **kwargs)
-  File "bootstrap/src/engine/SCons/Builder.py", line 635:
-    return self._execute(env, target, source, OverrideWarner(kw), ekw)
-  File "bootstrap/src/engine/SCons/Builder.py", line 541:
-    source = self.src_builder_sources(env, source, overwarn)
-  File "bootstrap/src/engine/SCons/Builder.py", line 748:
-    tlist = bld._execute(env, None, [s], overwarn)
-  File "bootstrap/src/engine/SCons/Builder.py", line 557:
-    _node_errors(self, env, tlist, slist)
-  File "bootstrap/src/engine/SCons/Builder.py", line 303:
-    msg = "Two environments with different actions were specified for the same target: %s\n(action 1: %s)\n(action 2: %s)" % (t,t_contents.decode('utf-8'),contents.decode('utf-8'))
-  File "/home/bdbaddog/tools/python-2.7.13/lib/python2.7/encodings/utf_8.py", line 16:
-    return codecs.utf_8_decode(input, errors, True)
+
+scons: *** Two environments with different actions were specified for the same target: foo.o
+File "/home/my/project/SConstruct", line 6, in &lt;module&gt;
 </screen>
diff --git a/doc/generated/examples/java_jar1_1.xml b/doc/generated/examples/java_jar1_1.xml
index daa3d1a..de93227 100644
--- a/doc/generated/examples/java_jar1_1.xml
+++ b/doc/generated/examples/java_jar1_1.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
 javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
-scons: *** [test.jar] Source `classes.class' not found, needed by target `test.jar'.
+jar cf test.jar classes
 </screen>
diff --git a/doc/generated/examples/troubleshoot_stacktrace_2.xml b/doc/generated/examples/troubleshoot_stacktrace_2.xml
index 4b55f0d..52bfa43 100644
--- a/doc/generated/examples/troubleshoot_stacktrace_2.xml
+++ b/doc/generated/examples/troubleshoot_stacktrace_2.xml
@@ -4,7 +4,7 @@ scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'.
 scons: internal stack trace:
   File "bootstrap/src/engine/SCons/Job.py", line 199, in start
     task.prepare()
-  File "bootstrap/src/engine/SCons/Script/Main.py", line 175, in prepare
+  File "bootstrap/src/engine/SCons/Script/Main.py", line 176, in prepare
     return SCons.Taskmaster.OutOfDateTask.prepare(self)
   File "bootstrap/src/engine/SCons/Taskmaster.py", line 198, in prepare
     executor.prepare()
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
index 79a83c6..617a0a4 100644
--- a/doc/generated/functions.gen
+++ b/doc/generated/functions.gen
@@ -3523,16 +3523,16 @@ below, for a complete explanation of the arguments and behavior.
   </varlistentry>
   <varlistentry id="f-SConscript">
     <term>
-      <literal>SConscript(scripts, [exports, variant_dir, duplicate])</literal>
+      <literal>SConscript(scripts, [exports, variant_dir, duplicate, must_exist])</literal>
     </term>
     <term>
-      <literal>env.SConscript(scripts, [exports, variant_dir, duplicate])</literal>
+      <literal>env.SConscript(scripts, [exports, variant_dir, duplicate, must_exist])</literal>
     </term>
     <term>
-      <literal>SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate])</literal>
+      <literal>SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist])</literal>
     </term>
     <term>
-      <literal>env.SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate])</literal>
+      <literal>env.SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist])</literal>
     </term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -3734,6 +3734,17 @@ TODO??? SConscript('build/SConscript', src_dir='src')
 </para>
 
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
+The optional
+<varname>must_exist</varname>
+argument, if true, causes an exception to be raised if a requested
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">SConscript</filename> file is not found. The current default is false,
+causing only a warning to be omitted, but this behavior is deprecated.
+For scripts which truly intend to be optional, transition to
+explicty supplying
+<literal>must_exist=False</literal> to the call.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
 Here are some composite examples:
 </para>
 
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index a756d35..9246249 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -51,7 +51,9 @@ This is used to fill in the
 <literal>Architecture:</literal>
 field in an Ipkg
 <filename>control</filename> file,
-and as part of the name of a generated RPM file.
+and the <literal>BuildArch:</literal> field
+in the RPM <filename>.spec</filename> file,
+as well as forming part of the name of a generated RPM package file.
 </para>
 </listitem>
   </varlistentry>
@@ -240,7 +242,7 @@ or this:
 
 <example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
 env = Environment()
-env['BUILDERS]['NewBuilder'] = foo
+env['BUILDERS']['NewBuilder'] = foo
 </example_commands>
 </listitem>
   </varlistentry>
@@ -389,7 +391,6 @@ the <filename>control</filename> for Ipkg,
 the <filename>.wxs</filename> for MSI).
 If set, the function will be called
 after the SCons template for the file has been written.
-XXX
 </para>
 </listitem>
   </varlistentry>
@@ -2943,15 +2944,6 @@ is <quote><literal>-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</literal></quote>
     <term>HOST_ARCH</term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
-        The name of the host hardware architecture used to create the Environment.
-        If a platform is specified when creating the Environment, then
-        that Platform's logic will handle setting this value.
-        This value is immutable, and should not be changed by the user after
-        the Environment is initialized.
-        Currently only set for Win32.
-</para>
-    
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
 Sets the host architecture for Visual Studio compiler. If not set,
 default to the detected host architecture: note that this may depend
 on the python you are using.
@@ -2967,7 +2959,16 @@ Valid values are the same as for <envar xmlns="http://www.scons.org/dbxsd/v1.0">
 This is currently only used on Windows, but in the future it will be
 used on other OSes as well.
 </para>
-</listitem>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+        The name of the host hardware architecture used to create the Environment.
+        If a platform is specified when creating the Environment, then
+        that Platform's logic will handle setting this value.
+        This value is immutable, and should not be changed by the user after
+        the Environment is initialized.
+        Currently only set for Win32.
+</para>
+    </listitem>
   </varlistentry>
   <varlistentry id="cv-HOST_OS">
     <term>HOST_OS</term>
@@ -3209,7 +3210,7 @@ The command line used to call the Java archive tool.
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The string displayed when the Java archive tool
 is called
-If this is not set, then <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCOM</envar> (the command line) is displayed.
+If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCOM"><envar>$JARCOM</envar></link> (the command line) is displayed.
 </para>
 
 <example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -3219,7 +3220,7 @@ env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The string displayed when the Java archive tool
 is called
-If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCOM"><envar>$JARCOM</envar></link> (the command line) is displayed.
+If this is not set, then <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCOM</envar> (the command line) is displayed.
 </para>
 
 <example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -3933,10 +3934,10 @@ and these suffixes.
     <term>LICENSE</term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
-The abbreviated name of the license under which
-this project is released (gpl, lpgl, bsd etc.).
+The abbreviated name, preferably the SPDX code, of the license under which
+this project is released (GPL-3.0, LGPL-2.1, BSD-2-Clause etc.).
 See http://www.opensource.org/licenses/alphabetical
-for a list of license names.
+for a list of license names and SPDX codes.
 </para>
 </listitem>
   </varlistentry>
@@ -7100,13 +7101,6 @@ that may not be set or used in a construction environment.
     <term>TARGET_ARCH</term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
-        The name of the target hardware architecture for the compiled objects
-        created by this Environment.
-        This defaults to the value of HOST_ARCH, and the user can override it.
-        Currently only set for Win32.
-</para>
-    
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
 Sets the target architecture for Visual Studio compiler (i.e. the arch
 of the binaries generated by the compiler). If not set, default to
 <envar xmlns="http://www.scons.org/dbxsd/v1.0">$HOST_ARCH</envar>, or, if that is unset, to the architecture of the
@@ -7131,7 +7125,14 @@ and <literal>ia64</literal> (Itanium).
 For example, if you want to compile 64-bit binaries, you would set
 <literal>TARGET_ARCH='x86_64'</literal> in your SCons environment.
 </para>
-</listitem>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+        The name of the target hardware architecture for the compiled objects
+        created by this Environment.
+        This defaults to the value of HOST_ARCH, and the user can override it.
+        Currently only set for Win32.
+</para>
+    </listitem>
   </varlistentry>
   <varlistentry id="cv-TARGET_OS">
     <term>TARGET_OS</term>
@@ -7547,6 +7548,7 @@ This is used to fill in the
 <literal>BuildRequires:</literal>
 field in the RPM
 <filename>.spec</filename> file.
+Note this should only be used on a host managed by rpm as the dependencies will not be resolvable at build time otherwise.
 </para>
 </listitem>
   </varlistentry>
@@ -7605,7 +7607,8 @@ field in the RPM
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 This is used to fill in the
 <literal>Epoch:</literal>
-field in the controlling information for RPM packages.
+field in the RPM
+<filename>.spec</filename> file.
 </para>
 </listitem>
   </varlistentry>
@@ -7631,6 +7634,38 @@ field in the RPM
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-X_RPM_EXTRADEFS">
+    <term>X_RPM_EXTRADEFS</term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A list used to supply extra defintions or flags
+to be added to the RPM <filename>.spec</filename> file.
+Each item is added as-is with a carriage return appended.
+This is useful if some specific RPM feature not otherwise
+anticipated by SCons needs to be turned on or off.
+Note if this variable is omitted, SCons will by
+default supply the value
+<literal>'%global debug_package %{nil}'</literal>
+to disable debug package generation.
+To enable debug package generation, include this
+variable set either to None, or to a custom
+list that does not include the default line.
+Added in version 3.1.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Package(
+    NAME             = 'foo',
+...
+    X_RPM_EXTRADEFS = [
+        '%define _unpackaged_files_terminate_build 0'
+        '%define _missing_doc_files_terminate_build 0'
+    ],
+... )
+</example_commands>
+
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-X_RPM_GROUP">
     <term>X_RPM_GROUP</term>
     <listitem>
diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod
index 6ecf6c9..52ee4e1 100644
--- a/doc/generated/variables.mod
+++ b/doc/generated/variables.mod
@@ -584,6 +584,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-X_RPM_EPOCH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$X_RPM_EPOCH</envar>">
 <!ENTITY cv-X_RPM_EXCLUDEARCH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$X_RPM_EXCLUDEARCH</envar>">
 <!ENTITY cv-X_RPM_EXLUSIVEARCH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$X_RPM_EXLUSIVEARCH</envar>">
+<!ENTITY cv-X_RPM_EXTRADEFS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$X_RPM_EXTRADEFS</envar>">
 <!ENTITY cv-X_RPM_GROUP "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$X_RPM_GROUP</envar>">
 <!ENTITY cv-X_RPM_GROUP_lang "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$X_RPM_GROUP_lang</envar>">
 <!ENTITY cv-X_RPM_ICON "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$X_RPM_ICON</envar>">
@@ -1213,6 +1214,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY cv-link-X_RPM_EPOCH "<link linkend='cv-X_RPM_EPOCH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$X_RPM_EPOCH</envar></link>">
 <!ENTITY cv-link-X_RPM_EXCLUDEARCH "<link linkend='cv-X_RPM_EXCLUDEARCH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$X_RPM_EXCLUDEARCH</envar></link>">
 <!ENTITY cv-link-X_RPM_EXLUSIVEARCH "<link linkend='cv-X_RPM_EXLUSIVEARCH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$X_RPM_EXLUSIVEARCH</envar></link>">
+<!ENTITY cv-link-X_RPM_EXTRADEFS "<link linkend='cv-X_RPM_EXTRADEFS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$X_RPM_EXTRADEFS</envar></link>">
 <!ENTITY cv-link-X_RPM_GROUP "<link linkend='cv-X_RPM_GROUP' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$X_RPM_GROUP</envar></link>">
 <!ENTITY cv-link-X_RPM_GROUP_lang "<link linkend='cv-X_RPM_GROUP_lang' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$X_RPM_GROUP_lang</envar></link>">
 <!ENTITY cv-link-X_RPM_ICON "<link linkend='cv-X_RPM_ICON' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$X_RPM_ICON</envar></link>">
diff --git a/src/engine/SCons/Tool/packaging/__init__.xml b/src/engine/SCons/Tool/packaging/__init__.xml
index 9b8eecf..41a3f11 100644
--- a/src/engine/SCons/Tool/packaging/__init__.xml
+++ b/src/engine/SCons/Tool/packaging/__init__.xml
@@ -477,7 +477,7 @@ field in the RPM
 <summary>
 <para>
 A list used to supply extra defintions or flags
-to be added to the RPM <filename>.spec<filename> file.
+to be added to the RPM <filename>.spec</filename> file.
 Each item is added as-is with a carriage return appended.
 This is useful if some specific RPM feature not otherwise
 anticipated by SCons needs to be turned on or off.