Update docs on argument passing to Environment, etc.

Adds a new uguide Ch 7 section on using the parse_flags method (with Ex.)
Moves the section on overrides in calls to Builders to Chap 7 -
  it was using concepts not introduced yet where it was placed.

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

10 files changed, 238 insertions, 124 deletions

diff --git a/doc/generated/examples/environments_ex6_1.xml b/doc/generated/examples/environments_ex6_1.xml
index 03a5e7c..70fbb03 100644
--- a/doc/generated/examples/environments_ex6_1.xml
+++ b/doc/generated/examples/environments_ex6_1.xml
@@ -1,4 +1,5 @@
 <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 is: cc
+LATEX is: None
 scons: `.' is up to date.
 </screen>
diff --git a/doc/generated/examples/parse_flags_ex1_1.xml b/doc/generated/examples/parse_flags_ex1_1.xml
new file mode 100644
index 0000000..1cead7d
--- /dev/null
+++ b/doc/generated/examples/parse_flags_ex1_1.xml
@@ -0,0 +1,7 @@
+<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>
+CPPPATH: ['/opt/include']
+LIBPATH: ['/opt/lib']
+LIBS: ['foo']
+cc -o f1.o -c -I/opt/include f1.c
+cc -o f1 f1.o -L/opt/lib -lfoo
+</screen>
diff --git a/doc/overview.rst b/doc/overview.rst
index aed27af..9a2558a 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -125,7 +125,7 @@ method form, or both, exist. If all four exist you will get:
 *f-link-foobar*
     which is a link to the description of the global Function
 
-*f-env-link-foobar*
+*f-link-env-foobar*
     which is a link to the description of the environment method
 
 
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 10b79f6..d7237df 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -36,6 +36,7 @@ nodes.xml
 output.xml
 parseconfig.xml
 parseflags.xml
+parse_flags_arg.xml
 preface.xml
 python.xml
 repositories.xml
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 0a5722b..77c6972 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -367,11 +367,11 @@ environment, of directory names, suffixes, etc.
     <listitem>
     <para>
 
-    The <firstterm>external environment</firstterm>
+    The <firstterm>External Environment</firstterm>
     is the set of variables in the user's environment
-    at the time the user runs &SCons;.
-    These variables are available within the &SConscript; files
-    through the Python <literal>os.environ</literal> dictionary.
+    at the time the user runs &SCons;. These variables are not
+    automatically part of an &SCons; build
+    but are available to be examined if needed.
     See <xref linkend="sect-external-environments"></xref>, below.
 
     </para>
@@ -384,7 +384,7 @@ environment, of directory names, suffixes, etc.
     <listitem>
     <para>
 
-    A <firstterm>&consenv;</firstterm>
+    A <firstterm>&ConsEnv;</firstterm>
     is a distinct object created within
     a &SConscript; file and
     which contains values that
@@ -408,7 +408,7 @@ environment, of directory names, suffixes, etc.
     <listitem>
     <para>
 
-    An <firstterm>execution environment</firstterm>
+    An <firstterm>Execution Environment</firstterm>
     is the values that &SCons; sets
     when executing an external
     command (such as a compiler or linker)
@@ -429,7 +429,7 @@ environment, of directory names, suffixes, etc.
   Unlike &Make;,  &SCons; does not automatically
   copy or import values between different environments
   (with the exception of explicit clones of &consenvs;,
-  which inherit values from their parent).
+  which inherit the values from their parent).
   This is a deliberate design choice
   to make sure that builds are,
   by default, repeatable regardless of
@@ -477,8 +477,8 @@ environment, of directory names, suffixes, etc.
   variable settings that
   the user has in force
   when executing &SCons;
-  are available through the normal Python
-  <envar>os.environ</envar>
+  are available in the Python
+  <varname>os.environ</varname>
   dictionary.
   This means that you must add an
   <literal>import os</literal> statement
@@ -491,6 +491,8 @@ environment, of directory names, suffixes, etc.
    <scons_example name="environments_ex1">
      <file name="SConstruct" printme="1">
 import os
+
+print("Shell is", os.environ['SHELL'])
      </file>
      <file name="foo.c">
 int main() { }
@@ -500,7 +502,7 @@ int main() { }
   <para>
 
   More usefully, you can use the
-  <envar>os.environ</envar>
+  <varname>os.environ</varname>
   dictionary in your &SConscript;
   files to initialize &consenvs;
   with values from the user's external environment.
@@ -618,8 +620,9 @@ int main() { }
 
       <para>
 
-      You can fetch individual &consvars;
-      using the normal syntax
+      You can fetch individual values, known as
+      <firstterm>Construction Variables</firstterm>,
+      using the same syntax used
       for accessing individual named items in a Python dictionary:
 
       </para>
@@ -628,14 +631,20 @@ int main() { }
         <file name="SConstruct" printme="1">
 env = Environment()
 print("CC is: %s" % env['CC'])
+print("LATEX is: %s" % env.get('LATEX', None))
         </file>
       </scons_example>
 
       <para>
 
-      This example &SConstruct; file doesn't build anything,
-      but because it's actually a Python script,
-      it will print the value of &cv-link-CC; for us:
+      This example &SConstruct; file doesn't contain instructions
+      for building any targets, but because it's still a valid
+      &SConstruct; it will be evaulated and the Python
+      <function>print</function> calls will output the values
+      of &cv-link-CC; and &cv-link-LATEX; for us (using the
+      <function>.get()</function> method for fetching means
+      we get a default value back, rather than a failure,
+      if the variable is not set):
 
       </para>
 
@@ -650,7 +659,8 @@ print("CC is: %s" % env['CC'])
       attributes.
       If you want to have direct access to only the
       dictionary of &consvars;
-      you can fetch this using the &Dictionary; method:
+      you can fetch this using the &Dictionary; method
+      (although it's rarely necessary to use this method):
 
       </para>
 
@@ -1004,8 +1014,8 @@ env = DefaultEnvironment(tools=['gcc', 'gnulink'],
 
       <scons_example name="environments_ex2">
         <file name="SConstruct" printme="1">
-opt = Environment(CCFLAGS = '-O2')
-dbg = Environment(CCFLAGS = '-g')
+opt = Environment(CCFLAGS='-O2')
+dbg = Environment(CCFLAGS='-g')
 
 opt.Program('foo', 'foo.c')
 
@@ -1035,8 +1045,8 @@ int main() { }
 
       <scons_example name="environments_ex3">
         <file name="SConstruct" printme="1">
-opt = Environment(CCFLAGS = '-O2')
-dbg = Environment(CCFLAGS = '-g')
+opt = Environment(CCFLAGS='-O2')
+dbg = Environment(CCFLAGS='-g')
 
 opt.Program('foo', 'foo.c')
 
@@ -1133,7 +1143,7 @@ int main() { }
       <para>
 
       Like the &Environment; call that creates a construction environment,
-      the &Clone; method takes &consvar; assignments,
+      the &Clone; method takes &consvar; assignment keyword arguments,
       which will override the values in the copied construction environment.
       For example, suppose we want to use &gcc;
       to create three versions of a program,
@@ -1148,9 +1158,9 @@ int main() { }
 
       <scons_example name="environments_ex5">
         <file name="SConstruct" printme="1">
-env = Environment(CC = 'gcc')
-opt = env.Clone(CCFLAGS = '-O2')
-dbg = env.Clone(CCFLAGS = '-g')
+env = Environment(CC='gcc')
+opt = env.Clone(CCFLAGS='-O2')
+dbg = env.Clone(CCFLAGS='-g')
 
 env.Program('foo', 'foo.c')
 
@@ -1189,8 +1199,8 @@ int main() { }
 
       <scons_example name="environments_Replace1">
         <file name="SConstruct" printme="1">
-env = Environment(CCFLAGS = '-DDEFINE1')
-env.Replace(CCFLAGS = '-DDEFINE2')
+env = Environment(CCFLAGS='-DDEFINE1')
+env.Replace(CCFLAGS='-DDEFINE2')
 env.Program('foo.c')
         </file>
         <file name="foo.c">
@@ -1222,8 +1232,8 @@ int main() { }
       <scons_example name="environments_Replace-nonexistent">
         <file name="SConstruct" printme="1">
 env = Environment()
-env.Replace(NEW_VARIABLE = 'xyzzy')
-print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
+env.Replace(NEW_VARIABLE='xyzzy')
+print("NEW_VARIABLE = %s" % env['NEW_VARIABLE'])
         </file>
       </scons_example>
 
@@ -1257,12 +1267,12 @@ print("NEW_VARIABLE = %s"%env['NEW_VARIABLE'])
 
       <scons_example name="environments_Replace2">
         <file name="SConstruct" printme="1">
-env = Environment(CCFLAGS = '-DDEFINE1')
-print("CCFLAGS = %s"%env['CCFLAGS'])
+env = Environment(CCFLAGS='-DDEFINE1')
+print("CCFLAGS = %s" % env['CCFLAGS'])
 env.Program('foo.c')
 
-env.Replace(CCFLAGS = '-DDEFINE2')
-print("CCFLAGS = %s"%env['CCFLAGS'])
+env.Replace(CCFLAGS='-DDEFINE2')
+print("CCFLAGS = %s" % env['CCFLAGS'])
 env.Program('bar.c')
         </file>
         <file name="foo.c">
@@ -1320,7 +1330,7 @@ int main() { }
       </para>
 
       <sconstruct>
-env.SetDefault(SPECIAL_FLAG = '-extra-option')
+env.SetDefault(SPECIAL_FLAG='-extra-option')
       </sconstruct>
 
       <para>
@@ -1538,6 +1548,79 @@ env.PrependUnique(CCFLAGS=['-g'])
 
       </para>
 
+      </section>
+
+      <section>
+      <title>Overriding Construction Variable Settings</title>
+
+      <para>
+
+      Rather than creating a cloned environmant for specific tasks,
+      you can <firstterm>override</firstterm> or add construction variables
+      when calling a builder method by passing them as keyword arguments.
+      The values of these overridden or added variables will only be in
+      effect when building that target, and will not affect other parts
+      of the build.
+      For example, if you want to add additional libraries for just one program:
+
+      </para>
+
+      <programlisting>
+env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
+      </programlisting>
+
+      <para>
+
+      or generate a shared library with a non-standard suffix:
+
+      </para>
+
+      <programlisting>
+env.SharedLibrary(
+    target='word',
+    source='word.cpp',
+    SHLIBSUFFIX='.ocx',
+    LIBSUFFIXES=['.ocx'],
+)
+      </programlisting>
+
+      <para>
+
+      When overriding this way, the Python-style keyword arguments
+      mean "set to this value".  If you want your override to augment
+      an existing value, you have to take some extra steps. XXX
+
+      </para>
+
+      <para>
+
+      It is also possible to use the <parameter>parse_flags</parameter>
+      keyword argument in an override to merge command-line
+      style arguments into the appropriate construction
+      variables. This works like the &f-link-env-MergeFlags; method,
+      which will be described later.
+
+      </para>
+
+      <para>
+
+      This example adds 'include' to &cv-link-CPPPATH;,
+      'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;:
+
+      </para>
+
+      <programlisting>
+env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
+      </programlisting>
+
+      <para>
+
+      Using temporary overrides this way is lighter weight than making
+      a full construction environment, so it can help performance in
+      large projects which have lots of special case values to set.
+
+      </para>
+
     </section>
 
   </section>
@@ -1737,7 +1820,7 @@ env = Environment(ENV = os.environ)
       One of the most common requirements
       for manipulating a variable in the execution environment
       is to add one or more custom directories to a search
-      like the <envar>$PATH</envar> variable on Linux or POSIX systems,
+      like the <envar>PATH</envar> variable on Linux or POSIX systems,
       or the <envar>%PATH%</envar> variable on Windows,
       so that a locally-installed compiler or other utility
       can be found when &SCons; tries to execute it to update a target.
diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml
index 10f0c1a..394a39f 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.xml
@@ -463,30 +463,30 @@ Program('program', src_files)
     &SCons; also allows you to identify
     the output file and input source files
     using Python keyword arguments.
-    The output file is known as the
-    <emphasis>target</emphasis>,
-    and the source file(s) are known (logically enough) as the
-    <emphasis>source</emphasis>.
+    The output file keyword is
+    <parameter>target</parameter>,
+    and the source file(s) keyword is (logically enough)
+    <parameter>source</parameter>.
     The Python syntax for this is:
 
     </para>
 
     <programlisting>
 src_files = Split('main.c file1.c file2.c')
-Program(target = 'program', source = src_files)
+Program(target='program', source=src_files)
     </programlisting>
 
     <para>
 
     Because the keywords explicitly identify
-    what each argument is,
-    you can actually reverse the order if you prefer:
+    what each argument is, the order does
+    not matter and you can reverse it if you prefer:
 
     </para>
 
     <programlisting>
 src_files = Split('main.c file1.c file2.c')
-Program(source = src_files, target = 'program')
+Program(source=src_files, target='program')
     </programlisting>
 
     <para>
@@ -646,63 +646,4 @@ Program('bar', bar_files)
 
   </section>
 
-  <section>
-  <title>Overriding construction variables when calling a Builder</title>
-
-    <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>
-
-    <programlisting>
-env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
-    </programlisting>
-
-    <para>
-
-    or generate a shared library with a non-standard suffix:
-
-    </para>
-
-    <programlisting>
-env.SharedLibrary('word', 'word.cpp',
-                  SHLIBSUFFIX='.ocx',
-                  LIBSUFFIXES=['.ocx'])
-    </programlisting>
-
-    <para>
-
-    It is also possible to use the <literal>parse_flags</literal>
-    keyword argument in an override to merge command-line
-    style arguments into the appropriate construction
-    variables (see &f-link-env-MergeFlags;).
-
-    </para>
-
-    <para>
-
-    This example adds 'include' to &cv-link-CPPPATH;,
-    'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;.
-
-    </para>
-
-    <programlisting>
-env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
-    </programlisting>
-
-    <para>
-
-    Within the call to the builder action the environment is not cloned,
-    instead an OverrideEnvironment() is created which is more
-    light weight than a whole Environment()
-
-    </para>
-
-  </section>
-
 </chapter>
diff --git a/doc/user/main.xml b/doc/user/main.xml
index 49fef75..6f516f9 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -87,14 +87,14 @@
     (brief) overview of *what* these functions do to decide if this
     chapter is where they should read in more detail.  -->
     <para>
-    This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;.
+    This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig;
+    methods of a &consenv;, as well as the <parameter>parse_flags</parameter>
+    keyword argument to methods that construct environments.
     </para>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="mergeflags.xml"/>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="parse_flags_arg.xml"/>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="parseflags.xml"/>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="parseconfig.xml"/>
-    <!--
-    XXX parse_flags= option of Environment()
-    -->
   </chapter>
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="output.xml"/>
diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml
index 879a7b2..5a864b1 100644
--- a/doc/user/mergeflags.xml
+++ b/doc/user/mergeflags.xml
@@ -46,21 +46,26 @@
 
  <para>
 
- &SCons; construction environments have a &MergeFlags; method
- that merges a dictionary of values into the construction environment.
+ &SCons; &consenvs; have an &f-link-env-MergeFlags; method
+ that merges values from a passed-in argument into the &consenv;
+ If the argument is a dictionary,
  &MergeFlags; treats each value in the dictionary
  as a list of options such as one might pass to a command
  (such as a compiler or linker).
  &MergeFlags; will not duplicate an option
  if it already exists in the construction environment variable.
+ If the argument is a string, &MergeFlags; calls the
+ &f-link-env-ParseFlags; method to burst it out into a 
+ dictionary first, then acts on the result.
 
  </para>
 
  <para>
 
- &MergeFlags; tries to be intelligent about merging options.
+ &MergeFlags; tries to be intelligent about merging options,
+ knowing that different &consvars; may have different needs.
  When merging options to any variable
- whose name ends in <varname>PATH</varname>,
+ whose name ends in <literal>PATH</literal>,
  &MergeFlags; keeps the leftmost occurrence of the option,
  because in typical lists of directory paths,
  the first occurrence "wins."
@@ -74,8 +79,8 @@
  <scons_example name="mergeflags_MergeFlags1">
    <file name="SConstruct" printme="1">
 env = Environment()
-env.Append(CCFLAGS = '-option -O3 -O1')
-flags = { 'CCFLAGS' : '-whatever -O3' }
+env.Append(CCFLAGS='-option -O3 -O1')
+flags = {'CCFLAGS': '-whatever -O3'}
 env.MergeFlags(flags)
 print(env['CCFLAGS'])
    </file>
@@ -101,8 +106,8 @@ print(env['CCFLAGS'])
  <scons_example name="mergeflags_MergeFlags2">
    <file name="SConstruct" printme="1">
 env = Environment()
-env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include'])
-flags = { 'CPPPATH' : ['/usr/opt/include', '/usr/local/include'] }
+env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include'])
+flags = {'CPPPATH': ['/usr/opt/include', '/usr/local/include']}
 env.MergeFlags(flags)
 print(env['CPPPATH'])
    </file>
@@ -135,8 +140,8 @@ print(env['CPPPATH'])
  <scons_example name="mergeflags_MergeFlags3">
    <file name="SConstruct" printme="1">
 env = Environment()
-env.Append(CCFLAGS = '-option -O3 -O1')
-env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include'])
+env.Append(CCFLAGS='-option -O3 -O1')
+env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include'])
 env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include')
 print(env['CCFLAGS'])
 print(env['CPPPATH'])
diff --git a/doc/user/parse_flags_arg.xml b/doc/user/parse_flags_arg.xml
new file mode 100644
index 0000000..e7d6c42
--- /dev/null
+++ b/doc/user/parse_flags_arg.xml
@@ -0,0 +1,75 @@
+<?xml version='1.0'?>
+<!DOCTYPE sconsdoc [
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+
+    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
+    %builders-mod;
+    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
+    %functions-mod;
+    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
+    %tools-mod;
+    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
+    %variables-mod;
+]>
+
+<section id="sect-parse_flags_"
+         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">
+<title>Merging Options the Environment: the <parameter>merge_flags</parameter> Parameter</title>
+
+<!--
+
+  __COPYRIGHT__
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ It is also possible to merge &consvar; values from arguments
+ given to the &f-link-Environment; call itself.
+ If the <parameter>parse_flags</parameter> keyword argument
+ is given, its value is distributed to &consvars; in the
+ new environment in the same way as
+ described for the &MergeFlags; method.
+ This also works when calling &f-link-env-Clone;.
+
+ </para>
+
+ <scons_example name="parse_flags_ex1">
+   <file name="SConstruct" printme="1">
+env = Environment(parse_flags="-I/opt/include -L/opt/lib -lfoo")
+for k in ('CPPPATH', 'LIBPATH', 'LIBS'):
+    print("%s:" % k, env.get(k))
+env.Program("f1.c")
+   </file>
+   <file name="f1.c">
+int main() { return 0; }
+   </file>
+ </scons_example>
+
+ <scons_output example="parse_flags_ex1" os="posix" suffix="1">
+    <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
+
+</section>
diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml
index 35c336e..1cd0bbf 100644
--- a/doc/user/parseflags.xml
+++ b/doc/user/parseflags.xml
@@ -46,7 +46,7 @@
 
  <para>
 
- &SCons; has a bewildering array of construction variables
+ &SCons; has a bewildering array of &consvars;
  for different types of options when building programs.
  Sometimes you may not know exactly which variable
  should be used for a particular option.
@@ -55,10 +55,10 @@
 
  <para>
 
- &SCons; construction environments have a &ParseFlags; method
+ &SCons; &consenvs; have a &f-link-env-ParseFlags; method
  that takes a set of typical command-line options
  and distributes them into the appropriate construction variables.
- Historically, it was created to support the &ParseConfig; method,
+ Historically, it was created to support the &f-link-env-ParseConfig; method,
  so it focuses on options used by the GNU Compiler Collection (GCC)
  for the C and C++ toolchains.
 
@@ -68,7 +68,7 @@
 
  &ParseFlags; returns a dictionary containing the options
  distributed into their respective construction variables.
- Normally, this dictionary would be passed to &MergeFlags;
+ Normally, this dictionary would then be passed to &MergeFlags;
  to merge the options into a &consenv;,
  but the dictionary can be edited if desired to provide
  additional functionality.
@@ -128,7 +128,7 @@ env.MergeFlags(d)
 env.Program("f1.c")
    </file>
    <file name="f1.c">
- int main() { return 0; }
+void main() { return 0; }
    </file>
  </scons_example>
 
@@ -154,7 +154,7 @@ env.MergeFlags(d)
 env.Program("f1.c")
    </file>
    <file name="f1.c">
-int main() { return 0; }
+void main() { return 0; }
    </file>
  </scons_example>
 
@@ -164,7 +164,8 @@ int main() { return 0; }
 
  <para>
 
- If a string begins with a "!" (an exclamation mark, often called a bang),
+ If a string begins with a an exclamation mark (<literal>!</literal>,
+ sometimes also called a bang),
  the string is passed to the shell for execution.
  The output of the command is then parsed:
 
@@ -181,7 +182,7 @@ env.MergeFlags(d)
 env.Program("f1.c")
    </file>
    <file name="f1.c">
-int main() { return 0; }
+void main() { return 0; }
    </file>
  </scons_example>