Manpage example tweaks [ci skip]

A set of minor changes to various extra files (i.e. not scons.xml itself).

Mainly this reformats some example code when it looked bad in a
fixed-width version (pdf or Linux-style manpage).

Also: additional wording on default environment (included here because
file was being modified anyway), and define an entity for default env. in
doc/scons.mod.

Commits changes to two generated .mod files to make sure entities
list is correct even if even if a full regen of these files
(bin/docs-update-generated) is not done.

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

11 files changed, 54 insertions, 47 deletions

diff --git a/doc/generated/functions.mod b/doc/generated/functions.mod
index 3d49229..47d2be4 100644
--- a/doc/generated/functions.mod
+++ b/doc/generated/functions.mod
@@ -80,7 +80,6 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-SetDefault "<function xmlns='http://www.scons.org/dbxsd/v1.0'>SetDefault</function>">
 <!ENTITY f-SetOption "<function xmlns='http://www.scons.org/dbxsd/v1.0'>SetOption</function>">
 <!ENTITY f-SideEffect "<function xmlns='http://www.scons.org/dbxsd/v1.0'>SideEffect</function>">
-<!ENTITY f-SourceCode "<function xmlns='http://www.scons.org/dbxsd/v1.0'>SourceCode</function>">
 <!ENTITY f-Split "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Split</function>">
 <!ENTITY f-subst "<function xmlns='http://www.scons.org/dbxsd/v1.0'>subst</function>">
 <!ENTITY f-Tag "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Tag</function>">
@@ -161,7 +160,6 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-env-SetDefault "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.SetDefault</function>">
 <!ENTITY f-env-SetOption "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.SetOption</function>">
 <!ENTITY f-env-SideEffect "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.SideEffect</function>">
-<!ENTITY f-env-SourceCode "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.SourceCode</function>">
 <!ENTITY f-env-Split "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Split</function>">
 <!ENTITY f-env-subst "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.subst</function>">
 <!ENTITY f-env-Tag "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Tag</function>">
@@ -252,7 +250,6 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-link-SetDefault "<link linkend='f-SetDefault' xmlns='http://www.scons.org/dbxsd/v1.0'><function>SetDefault</function></link>">
 <!ENTITY f-link-SetOption "<link linkend='f-SetOption' xmlns='http://www.scons.org/dbxsd/v1.0'><function>SetOption</function></link>">
 <!ENTITY f-link-SideEffect "<link linkend='f-SideEffect' xmlns='http://www.scons.org/dbxsd/v1.0'><function>SideEffect</function></link>">
-<!ENTITY f-link-SourceCode "<link linkend='f-SourceCode' xmlns='http://www.scons.org/dbxsd/v1.0'><function>SourceCode</function></link>">
 <!ENTITY f-link-Split "<link linkend='f-Split' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Split</function></link>">
 <!ENTITY f-link-subst "<link linkend='f-subst' xmlns='http://www.scons.org/dbxsd/v1.0'><function>subst</function></link>">
 <!ENTITY f-link-Tag "<link linkend='f-Tag' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Tag</function></link>">
@@ -333,7 +330,6 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-link-env-SetDefault "<link linkend='f-SetDefault' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.SetDefault</function></link>">
 <!ENTITY f-link-env-SetOption "<link linkend='f-SetOption' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.SetOption</function></link>">
 <!ENTITY f-link-env-SideEffect "<link linkend='f-SideEffect' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.SideEffect</function></link>">
-<!ENTITY f-link-env-SourceCode "<link linkend='f-SourceCode' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.SourceCode</function></link>">
 <!ENTITY f-link-env-Split "<link linkend='f-Split' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Split</function></link>">
 <!ENTITY f-link-env-subst "<link linkend='f-subst' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.subst</function></link>">
 <!ENTITY f-link-env-Tag "<link linkend='f-Tag' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Tag</function></link>">
diff --git a/doc/generated/tools.mod b/doc/generated/tools.mod
index 1209d74..3f8e22a 100644
--- a/doc/generated/tools.mod
+++ b/doc/generated/tools.mod
@@ -78,11 +78,12 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY t-mwcc "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>mwcc</literal>">
 <!ENTITY t-mwld "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>mwld</literal>">
 <!ENTITY t-nasm "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>nasm</literal>">
-<!ENTITY t-Packaging "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>Packaging</literal>">
 <!ENTITY t-packaging "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>packaging</literal>">
+<!ENTITY t-Packaging "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>Packaging</literal>">
 <!ENTITY t-pdf "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>pdf</literal>">
 <!ENTITY t-pdflatex "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>pdflatex</literal>">
 <!ENTITY t-pdftex "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>pdftex</literal>">
+<!ENTITY t-python "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>python</literal>">
 <!ENTITY t-qt "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>qt</literal>">
 <!ENTITY t-rmic "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>rmic</literal>">
 <!ENTITY t-rpcgen "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>rpcgen</literal>">
@@ -186,11 +187,12 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY t-link-mwcc "<link linkend='t-mwcc' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>mwcc</literal></link>">
 <!ENTITY t-link-mwld "<link linkend='t-mwld' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>mwld</literal></link>">
 <!ENTITY t-link-nasm "<link linkend='t-nasm' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>nasm</literal></link>">
-<!ENTITY t-link-Packaging "<link linkend='t-Packaging' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>Packaging</literal></link>">
 <!ENTITY t-link-packaging "<link linkend='t-packaging' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>packaging</literal></link>">
+<!ENTITY t-link-Packaging "<link linkend='t-Packaging' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>Packaging</literal></link>">
 <!ENTITY t-link-pdf "<link linkend='t-pdf' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>pdf</literal></link>">
 <!ENTITY t-link-pdflatex "<link linkend='t-pdflatex' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>pdflatex</literal></link>">
 <!ENTITY t-link-pdftex "<link linkend='t-pdftex' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>pdftex</literal></link>">
+<!ENTITY t-link-python "<link linkend='t-python' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>python</literal></link>">
 <!ENTITY t-link-qt "<link linkend='t-qt' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>qt</literal></link>">
 <!ENTITY t-link-rmic "<link linkend='t-rmic' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>rmic</literal></link>">
 <!ENTITY t-link-rpcgen "<link linkend='t-rpcgen' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>rpcgen</literal></link>">
diff --git a/doc/scons.mod b/doc/scons.mod
index bc63a42..006107e 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -447,6 +447,8 @@
 <!ENTITY Consenvs "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>Construction environments</phrase>">
 <!ENTITY consenv "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>construction environment</phrase>">
 <!ENTITY consenvs "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>construction environments</phrase>">
+<!ENTITY DefEnv "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>Default Environment</phrase>">
+<!ENTITY defenv "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>default environment</phrase>">
 
 <!ENTITY ConsVar "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>Construction Variable</phrase>">
 <!ENTITY ConsVars "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>Construction Variables</phrase>">
diff --git a/src/engine/SCons/Defaults.xml b/src/engine/SCons/Defaults.xml
index 22f46fe..06fad1c 100644
--- a/src/engine/SCons/Defaults.xml
+++ b/src/engine/SCons/Defaults.xml
@@ -268,12 +268,8 @@ into a list of Dir instances relative to the target being built.
 <para>
 The list of suffixes of files that will be scanned
 for imported D package files.
-The default list is:
+The default list is <literal>['.d']</literal>.
 </para>
-
-<example_commands>
-['.d']
-</example_commands>
 </summary>
 </cvar>
 
@@ -584,9 +580,12 @@ in order to execute many of the global functions in this list
 from source code management systems.
 The default environment is a singleton, so the keyword
 arguments affect it only on the first call, on subsequent
-calls the already-constructed object is returned.
+calls the already-constructed object is returned and
+any arguments are ignored.
 The default environment can be modified in the same way
 as any &consenv;.
+Modifying the &defenv; has no effect on the environment
+constructed by a subsequent &f-Environment; call.
 </para>
 </summary>
 </scons_function>
diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml
index a171f38..48980e2 100644
--- a/src/engine/SCons/Environment.xml
+++ b/src/engine/SCons/Environment.xml
@@ -1836,9 +1836,10 @@ Examples:
 </para>
 
 <example_commands>
-Program('foo', Glob('*.c'))
-Zip('/tmp/everything', Glob('.??*') + Glob('*'))
-sources = Glob('*.cpp', exclude=['os_*_specific_*.cpp']) + Glob('os_%s_specific_*.cpp'%currentOS)
+Program("foo", Glob("*.c"))
+Zip("/tmp/everything", Glob(".??*") + Glob("*"))
+sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \
+          Glob( "os_%s_specific_*.cpp" % currentOS)
 </example_commands>
 </summary>
 </scons_function>
diff --git a/src/engine/SCons/Tool/applelink.xml b/src/engine/SCons/Tool/applelink.xml
index fc0cf63..977f2ce 100644
--- a/src/engine/SCons/Tool/applelink.xml
+++ b/src/engine/SCons/Tool/applelink.xml
@@ -171,7 +171,7 @@ See its __doc__ string for a discussion of the format.
             </para>
 
             <example_commands>
-                env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
+env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
             </example_commands>
 
         </summary>
@@ -213,7 +213,7 @@ See its __doc__ string for a discussion of the format.
             </para>
 
             <example_commands>
-                env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
+env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
             </example_commands>
 
             <para>
@@ -221,7 +221,7 @@ See its __doc__ string for a discussion of the format.
             </para>
 
             <example_commands>
-                ... -Fmyframeworkdir
+... -Fmyframeworkdir
             </example_commands>
 
             <para>
diff --git a/src/engine/SCons/Tool/jar.xml b/src/engine/SCons/Tool/jar.xml
index 30c51f8..151dda1 100644
--- a/src/engine/SCons/Tool/jar.xml
+++ b/src/engine/SCons/Tool/jar.xml
@@ -120,7 +120,7 @@ If this is not set, then &cv-link-JARCOM; (the command line) is displayed.
 </para>
 
 <example_commands>
-env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
+env = Environment(JARCOMSTR="JARchiving $SOURCES into $TARGET")
 </example_commands>
 </summary>
 </cvar>
diff --git a/src/engine/SCons/Tool/javac.xml b/src/engine/SCons/Tool/javac.xml
index 893130b..b1548c7 100644
--- a/src/engine/SCons/Tool/javac.xml
+++ b/src/engine/SCons/Tool/javac.xml
@@ -174,7 +174,7 @@ env['ENV']['LANG'] = 'en_GB.UTF-8'
             </para>
 
             <example_commands>
-env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
+env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
             </example_commands>
         </summary>
     </cvar>
diff --git a/src/engine/SCons/Tool/javah.xml b/src/engine/SCons/Tool/javah.xml
index 4d436b1..5a2840f 100644
--- a/src/engine/SCons/Tool/javah.xml
+++ b/src/engine/SCons/Tool/javah.xml
@@ -77,17 +77,18 @@ Examples:
 
 <example_commands>
 # builds java_native.h
-classes = env.Java(target = 'classdir', source = 'src')
-env.JavaH(target = 'java_native.h', source = classes)
+classes = env.Java(target="classdir", source="src")
+env.JavaH(target="java_native.h", source=classes)
 
 # builds include/package_foo.h and include/package_bar.h
-env.JavaH(target = 'include',
-          source = ['package/foo.class', 'package/bar.class'])
+env.JavaH(target="include", source=["package/foo.class", "package/bar.class"])
 
 # builds export/foo.h and export/bar.h
-env.JavaH(target = 'export',
-          source = ['classes/foo.class', 'classes/bar.class'],
-          JAVACLASSDIR = 'classes')
+env.JavaH(
+    target="export",
+    source=["classes/foo.class", "classes/bar.class"],
+    JAVACLASSDIR="classes",
+)
 </example_commands>
 </summary>
 </builder>
@@ -120,7 +121,7 @@ If this is not set, then &cv-link-JAVAHCOM; (the command line) is displayed.
 </para>
 
 <example_commands>
-env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
+env = Environment(JAVAHCOMSTR="Generating header/stub file(s) $TARGETS from $SOURCES")
 </example_commands>
 </summary>
 </cvar>
diff --git a/src/engine/SCons/Tool/msvs.xml b/src/engine/SCons/Tool/msvs.xml
index b1f79b2..f6c9a39 100644
--- a/src/engine/SCons/Tool/msvs.xml
+++ b/src/engine/SCons/Tool/msvs.xml
@@ -422,7 +422,11 @@ env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'],
       </variablelist>
       <para>Example Usage:</para>
       <example_commands>
-env.MSVSSolution(target='Bar' + env['MSVSSOLUTIONSUFFIX'], projects=['bar' + env['MSVSPROJECTSUFFIX']], variant='Release')
+env.MSVSSolution(
+    target="Bar" + env["MSVSSOLUTIONSUFFIX"],
+    projects=["bar" + env["MSVSPROJECTSUFFIX"]],
+    variant="Release",
+)
       </example_commands>
     </summary>
   </builder> <cvar name="MSVS">
diff --git a/src/engine/SCons/Tool/packaging/__init__.xml b/src/engine/SCons/Tool/packaging/__init__.xml
index 2b3c4fd..37e97ff 100644
--- a/src/engine/SCons/Tool/packaging/__init__.xml
+++ b/src/engine/SCons/Tool/packaging/__init__.xml
@@ -86,18 +86,19 @@ on a project that has packaging activated.
 </para>
 
 <example_commands>
-env = Environment(tools=['default', 'packaging'])
-env.Install('/bin/', 'my_program')
-env.Package( NAME           = 'foo',
-             VERSION        = '1.2.3',
-             PACKAGEVERSION = 0,
-             PACKAGETYPE    = 'rpm',
-             LICENSE        = 'gpl',
-             SUMMARY        = 'balalalalal',
-             DESCRIPTION    = 'this should be really really long',
-             X_RPM_GROUP    = 'Application/fu',
-             SOURCE_URL     = 'http://foo.org/foo-1.2.3.tar.gz'
-        )
+env = Environment(tools=["default", "packaging"])
+env.Install("/bin/", "my_program")
+env.Package(
+    NAME="foo",
+    VERSION="1.2.3",
+    PACKAGEVERSION=0,
+    PACKAGETYPE="rpm",
+    LICENSE="gpl",
+    SUMMARY="balalalalal",
+    DESCRIPTION="this should be really really long",
+    X_RPM_GROUP="Application/fu",
+    SOURCE_URL="http://foo.org/foo-1.2.3.tar.gz",
+)
 </example_commands>
 </summary>
 </builder>
@@ -503,13 +504,14 @@ Added in version 3.1.
 
 <example_commands>
 env.Package(
-    NAME             = 'foo',
-...
-    X_RPM_EXTRADEFS = [
-        '%define _unpackaged_files_terminate_build 0'
-        '%define _missing_doc_files_terminate_build 0'
+    NAME="foo",
+    ...
+    X_RPM_EXTRADEFS=[
+        "%define _unpackaged_files_terminate_build 0"
+        "%define _missing_doc_files_terminate_build 0"
     ],
-... )
+    ...
+)
 </example_commands>
 
 </summary>