docs: update parseconfig, parseflags, mergeflags

Docstrings Environment (inc. .backtick) also lightly updated.

Functional change: the function to be called by ParseConfig
is now passed the *unique* flag, previously omitted (if the
default MergeFlags was used, it still picked up this flag but
a user-supplied function did not).  Added a unit test for
user-supplied function.

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

3 files changed, 51 insertions, 48 deletions

diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml
index 5a864b1..18c9bb8 100644
--- a/doc/user/mergeflags.xml
+++ b/doc/user/mergeflags.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE sconsdoc [
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
-    
+
     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
     %builders-mod;
     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
@@ -21,7 +21,9 @@
 
 <!--
 
-  __COPYRIGHT__
+  MIT License
+
+  Copyright The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -46,16 +48,16 @@
 
  <para>
 
- &SCons; &consenvs; have an &f-link-env-MergeFlags; method
- that merges values from a passed-in argument into the &consenv;
+ &SCons; &consenvs; have a &f-link-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
+ as a list of options you would 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 it already exists in the &consvar;.
  If the argument is a string, &MergeFlags; calls the
- &f-link-env-ParseFlags; method to burst it out into a 
+ &f-link-ParseFlags; method to burst it out into a
  dictionary first, then acts on the result.
 
  </para>
@@ -82,7 +84,7 @@ env = Environment()
 env.Append(CCFLAGS='-option -O3 -O1')
 flags = {'CCFLAGS': '-whatever -O3'}
 env.MergeFlags(flags)
-print(env['CCFLAGS'])
+print("CCFLAGS:", env['CCFLAGS'])
    </file>
  </scons_example>
 
@@ -99,7 +101,7 @@ print(env['CCFLAGS'])
  -->
  is an internal &SCons; object
  which automatically converts
- the options we specified as a string into a list.
+ the options you specify as a string into a list.
 
  </para>
 
@@ -109,7 +111,7 @@ env = Environment()
 env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include'])
 flags = {'CPPPATH': ['/usr/opt/include', '/usr/local/include']}
 env.MergeFlags(flags)
-print(env['CPPPATH'])
+print("CPPPATH:", env['CPPPATH'])
    </file>
  </scons_example>
 
@@ -124,9 +126,9 @@ print(env['CPPPATH'])
  [TODO: for when we make CLVar public]
  is a Python list, not a <varname>CLVar</varname>,
  -->
- is a normal Python list,
- so we must specify its values as a list
- in the dictionary we pass to the &MergeFlags; function.
+ is a normal &Python; list,
+ so you should give its values as a list
+ in the dictionary you pass to the &MergeFlags; function.
 
  </para>
 
@@ -143,8 +145,8 @@ env = Environment()
 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'])
+print("CCFLAGS:", env['CCFLAGS'])
+print("CPPPATH:", env['CPPPATH'])
    </file>
  </scons_example>
 
@@ -157,8 +159,8 @@ print(env['CPPPATH'])
  In the combined example above,
  &ParseFlags; has sorted the options into their corresponding variables
  and returned a dictionary for &MergeFlags; to apply
- to the construction variables
- in the specified construction environment.
+ to the &consvars;
+ in the specified &consenv;.
 
  </para>
 
diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml
index a07201a..fc9a889 100644
--- a/doc/user/parseconfig.xml
+++ b/doc/user/parseconfig.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE sconsdoc [
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
-    
+
     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
     %builders-mod;
     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
@@ -21,7 +21,9 @@
 
 <!--
 
-  __COPYRIGHT__
+  MIT License
+
+  Copyright The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -48,22 +50,22 @@
 
  Configuring the right options to build programs to work with
  libraries--especially shared libraries--that are available
- on POSIX systems can be very complicated.
+ on POSIX systems can be complex.
  To help this situation,
  various utilies with names that end in <filename>config</filename>
  return the command-line options for the GNU Compiler Collection (GCC)
- that are needed to use these libraries;
+ that are needed to build and link against those libraries;
  for example, the command-line options
  to use a library named <filename>lib</filename>
- would be found by calling a utility named <filename>lib-config</filename>.
+ could be found by calling a utility named <command>lib-config</command>.
 
  </para>
 
  <para>
 
  A more recent convention is that these options
- are available from the generic <filename>pkg-config</filename> program,
- which has common framework, error handling, and the like,
+ are available through the generic <command>pkg-config</command> program,
+ providing a common framework, error handling, and the like,
  so that all the package creator has to do is provide the set of strings
  for his particular package.
 
@@ -71,14 +73,12 @@
 
  <para>
 
- &SCons; construction environments have a &ParseConfig; method
- that executes a <filename>*config</filename> utility
- (either <filename>pkg-config</filename> or a
- more specific utility)
- and configures the appropriate construction variables
- in the environment
- based on the command-line options
- returned by the specified command.
+ &SCons; &consvars; have a &f-link-ParseConfig;
+ method that asks the host system to execute a command
+ and then configures the appropriate &consvars; based on
+ the output of that command.
+ This lets you run a program like <command>pkg-config</command>
+ or a more specific utility to help set up your build.
 
  </para>
 
@@ -87,7 +87,7 @@
 env = Environment()
 env['CPPPATH'] = ['/lib/compat']
 env.ParseConfig("pkg-config x11 --cflags --libs")
-print(env['CPPPATH'])
+print("CPPPATH:", env['CPPPATH'])
    </file>
  </scons_example>
 
@@ -112,14 +112,14 @@ print(env['CPPPATH'])
 
  <screen>
 % <userinput>scons -Q</userinput>
-['/lib/compat', '/usr/X11/include']
+CPPPATH: ['/lib/compat', '/usr/X11/include']
 scons: `.' is up to date.
  </screen>
 
  <para>
 
  In the example above, &SCons; has added the include directory to
- <varname>CPPPATH</varname>.
+ &cv-link-CPPPATH;
  (Depending upon what other flags are emitted by the
  <filename>pkg-config</filename> command,
  other variables may have been extended as well.)
@@ -129,8 +129,8 @@ scons: `.' is up to date.
  <para>
 
  Note that the options are merged with existing options using
- the &MergeFlags; method,
- so that each option only occurs once in the construction variable:
+ the &f-link-MergeFlags; method,
+ so that each option only occurs once in the &consvar;.
 
  </para>
 
@@ -139,7 +139,7 @@ scons: `.' is up to date.
 env = Environment()
 env.ParseConfig("pkg-config x11 --cflags --libs")
 env.ParseConfig("pkg-config x11 --cflags --libs")
-print(env['CPPPATH'])
+print("CPPPATH:", "CPPPATH:", env['CPPPATH'])
    </file>
  </scons_example>
 
@@ -156,7 +156,7 @@ print(env['CPPPATH'])
 
  <screen>
 % <userinput>scons -Q</userinput>
-['/usr/X11/include']
+CPPPATH: ['/usr/X11/include']
 scons: `.' is up to date.
  </screen>
 
diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml
index 1cd0bbf..a1ab7af 100644
--- a/doc/user/parseflags.xml
+++ b/doc/user/parseflags.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE sconsdoc [
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
-    
+
     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
     %builders-mod;
     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
@@ -21,7 +21,9 @@
 
 <!--
 
-  __COPYRIGHT__
+  MIT License
+
+  Copyright The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -55,10 +57,10 @@
 
  <para>
 
- &SCons; &consenvs; have a &f-link-env-ParseFlags; method
+ &SCons; &consenvs; have a &f-link-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 &f-link-env-ParseConfig; method,
+ and distributes them into the appropriate &consvars;
+ Historically, it was created to support the &f-link-ParseConfig; method,
  so it focuses on options used by the GNU Compiler Collection (GCC)
  for the C and C++ toolchains.
 
@@ -67,8 +69,8 @@
  <para>
 
  &ParseFlags; returns a dictionary containing the options
- distributed into their respective construction variables.
- Normally, this dictionary would then be passed to &MergeFlags;
+ distributed into their respective &consvars;.
+ Normally, this dictionary would then be passed to &f-link-MergeFlags;
  to merge the options into a &consenv;,
  but the dictionary can be edited if desired to provide
  additional functionality.
@@ -164,8 +166,7 @@ void main() { return 0; }
 
  <para>
 
- If a string begins with a an exclamation mark (<literal>!</literal>,
- sometimes also called a bang),
+ If a string begins with a an exclamation mark (<literal>!</literal>),
  the string is passed to the shell for execution.
  The output of the command is then parsed: