Merge branch 'master' into msvc/cachefix

3 files changed, 326 insertions, 268 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index d7fe39d..733db78 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -145,7 +145,7 @@ to support additional input file types.
 
 <para>Information about files involved in the build,
 including a cryptographic hash of the contents,
-is cached for later reuse, 
+is cached for later reuse,
 By default content hashes are used to determine if a file
 has changed since the last build,
 but this can be controlled by selecting an appropriate
@@ -3983,7 +3983,7 @@ actually two bytes.</para>
 <para>Checks whether the C compiler
 (as defined by the &cv-link-CC; &consvar;) works,
 by trying to compile a small source file.
-This provides a more rigorous check: 
+This provides a more rigorous check:
 by default, &SCons; itself only detects if there is a program
 with the correct name, not if it is a functioning compiler.
 Returns a boolean indicating success or failure.</para>
@@ -4003,7 +4003,7 @@ be accepted or rejected by the compiler.
 <para>Checks whether the C++ compiler
 (as defined by the &cv-link-CXX; &consvar;) works,
 by trying to compile a small source file.
-This provides a more rigorous check: 
+This provides a more rigorous check:
 by default, &SCons; itself only detects if there is a program
 with the correct name, not if it is a functioning compiler.
 Returns a boolean indicating success or failure.</para>
@@ -4023,7 +4023,7 @@ be accepted or rejected by the compiler.
 <para>Checks whether the shared-object C compiler (as defined by the
 &cv-link-SHCC; &consvar;) works
 by trying to compile a small source file.
-This provides a more rigorous check: 
+This provides a more rigorous check:
 by default, &SCons; itself only detects if there is a program
 with the correct name, not if it is a functioning compiler.
 Returns a boolean indicating success or failure.</para>
@@ -4045,7 +4045,7 @@ be created.
 <para>Checks whether the shared-object C++ compiler (as defined by the
 &cv-link-SHCXX; &consvar;)
 works by trying to compile a small source file.
-This provides a more rigorous check: 
+This provides a more rigorous check:
 by default, &SCons; itself only detects if there is a program
 with the correct name, not if it is a functioning compiler.
 Returns a boolean indicating success or failure.</para>
@@ -4064,7 +4064,7 @@ be created.
   <varlistentry>
   <term><replaceable>context</replaceable>.<methodname>CheckProg</methodname>(<parameter>prog_name</parameter>)</term>
   <listitem>
-<para>Checks if 
+<para>Checks if
 <parameter>prog_name</parameter>
 exists in the path &SCons; will use at build time.
 (<replaceable>context</replaceable>.<varname>env['ENV']['PATH']</varname>).
@@ -4088,7 +4088,35 @@ Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>
 
-  <varlistentry>
+    <varlistentry>
+        <term><replaceable>context</replaceable>.<methodname>CheckMember</methodname>(<parameter>aggregate_member,
+            [header, language]</parameter>)
+        </term>
+        <listitem>
+            <para>Checks for the existence of a member of the C/C++ struct or class.
+                <parameter>aggregate_member</parameter>
+                specifies the struct/class and member to check for.
+                <parameter>header</parameter>
+                is a string containing one or more
+                <literal>#include</literal>
+                lines that will be inserted into the program
+                that will be run to test for the existence of the member.
+                Example:
+            </para>
+
+            <programlisting language="python">
+sconf.CheckMember('struct tm.tm_sec', '#include &lt;time.h&gt;')
+            </programlisting>
+
+            <para>
+                Returns a boolean indicating success or failure.
+            </para>
+
+        </listitem>
+    </varlistentry>
+
+
+    <varlistentry>
   <term><replaceable>context</replaceable>.<methodname>Define</methodname>(<parameter>symbol, [value, comment]</parameter>)</term>
   <listitem>
 <para>This method does not check for anything, but rather forces
@@ -4100,7 +4128,7 @@ it will be be used as the macro replacement value.
 If <parameter>value</parameter> is a string and needs to
 display with quotes, the quotes need to be included,
 as in <literal>'"string"'</literal>
-If the optional 
+If the optional
 <parameter>comment</parameter> is given,
 it is inserted as a comment above the macro definition
 (suitable comment marks will be added automatically).
@@ -6410,27 +6438,200 @@ env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')])
 <refsect3 id='variable_substitution'>
 <title>Variable Substitution</title>
 
-<para>Before executing a command,
-&scons;
-performs variable substitution on the string that makes up
-the action part of the builder.
-Variables to be interpolated are indicated in the
-string with a leading
-<literal>$</literal>, to distinguish them from plain text
-which is not to be substituted.
-The name may be surrounded by curly braces
-(<literal>${}</literal>)
-to separate the name from surrounding characters if necessary.
-Curly braces are required when you use
-Python list subscripting/slicing notation on a variable
-to select one or more items from a list,
-or access a variable's special attributes,
-or use Python expression substitution.
+<para>
+Before executing a command, &scons;
+performs parameter expansion (<firstterm>substitution</firstterm>)
+on the string that makes up the action part of the builder.
+The format of a substitutable parameter is
+<literal>${<replaceable>expression</replaceable>}</literal>.
+If <replaceable>expression</replaceable> refers to a variable,
+the braces in <literal>${<replaceable>expression</replaceable>}</literal>
+can be omitted <emphasis>unless</emphasis> the variable name is
+immediately followed by a character that could either be interpreted
+as part of the name, or is &Python; syntax such as
+<emphasis role="bold">[</emphasis> (for indexing/slicing)
+or <emphasis role="bold">.</emphasis> (for attribute access -
+see <link linkend="special_attributes">Special Attributes</link> below).
 </para>
 
 <para>
+If <replaceable>expression</replaceable> refers to a &consvar;,
+it is replaced with the value of that variable in the
+&consenv; at the time of execution.
+If <replaceable>expression</replaceable> looks like
+a variable name but is not defined in the &consenv;
+it is replaced with an empty string.
+If <replaceable>expression</replaceable> refers to one of the
+<link linkend="special_variables">Special Variables</link>
+(see below) the corresponding value of the variable is substituted.
+<replaceable>expression</replaceable> may also be
+a &Python; expression to be evaluated.
+See <link linkend='python_code_substitution'>Python Code Substitution</link>
+below for a description.
+</para>
+
+<para>&SCons; uses the following rules when converting &consvars; into
+command line strings:</para>
+
+<itemizedlist>
+  <listitem>
+  <para>If the value is a string it is interpreted as space delimited
+  command line arguments.</para>
+  </listitem>
+
+  <listitem>
+  <para>If the value is a list it is interpreted as a list of command
+  line arguments. Each element of the list is converted to a string.</para>
+  </listitem>
+
+  <listitem>
+  <para>Anything that is not a list or string is converted to a string and
+  interpreted as a single command line argument.</para>
+  </listitem>
+
+  <listitem>
+  <para>Newline characters (<literal>\n</literal>) delimit lines.
+  The newline parsing is done after
+  all other parsing, so it is not possible for arguments (e.g. file names) to
+  contain embedded newline characters.</para>
+  </listitem>
+
+  <listitem>
+  <para>For a literal <emphasis role="bold">$</emphasis>
+  use <emphasis role="bold">$$</emphasis>.
+  For example, <literal>$$FOO</literal> will be left in the
+  final string as <literal>$FOO</literal>.</para>
+  </listitem>
+</itemizedlist>
+
+<para>
+When a build action is executed, a hash of the command line is
+saved, together with other information about the target(s) built
+by the action, for future use in rebuild determination.
+This is called the <firstterm>&buildsig;</firstterm>
+(or <firstterm>&build_action; signature</firstterm>).
+The escape sequence
+<emphasis role="bold">$(</emphasis>
+<replaceable>subexpression</replaceable>
+<emphasis role="bold">$)</emphasis>
+may be used to indicate parts of a command line
+that may change without
+causing a rebuild--that is,
+which are not to be included when calculating the &buildsig;.
+All text from
+<emphasis role="bold">$(</emphasis>
+up to and including the matching
+<emphasis role="bold">$)</emphasis>
+will be removed from the command line
+before it is added to the &buildsig;
+while only the
+<emphasis role="bold">$(</emphasis>
+and
+<emphasis role="bold">$)</emphasis>
+will be removed before the command is executed.
+For example, the command line string:</para>
+
+<programlisting language="python">
+"echo Last build occurred $( $TODAY $). &gt; $TARGET"
+</programlisting>
+
+<para>would execute the command:</para>
+
+<screen>
+echo Last build occurred $TODAY. &gt; $TARGET
+</screen>
+
+<para>but the build signature added to any target files would be computed from:</para>
+
+<screen>
+echo Last build occurred  . &gt; $TARGET
+</screen>
+
+<para>While &consvars; are normally directly substituted,
+if a &consvar; has a value which
+is a callable &Python; object
+(a function, or a class with a <literal>__call__</literal> method),
+that object is called during substitution.
+The callable must accept four arguments:
+<parameter>target</parameter>,
+<parameter>source</parameter>,
+<parameter>env</parameter> and
+<parameter>for_signature</parameter>.
+<parameter>source</parameter> is a list of source nodes,
+<parameter>target</parameter> is a list of target nodes,
+<parameter>env</parameter> is the &consenv; to use for context,
+and <parameter>for_signature</parameter> is
+a boolean value that tells the callable
+if it is being called for the purpose of generating a build signature.
+Since the build signature is used for rebuild determination,
+variable elements that do not affect whether
+a rebuild should be triggered
+should be omitted from the returned string
+if <parameter>for_signature</parameter> is true.
+See <emphasis role="bold">$(</emphasis>
+and <emphasis role="bold">$)</emphasis> above
+for the syntax.
+</para>
+
+<para>
+&SCons; will insert whatever
+the callable returns
+into the expanded string:
+</para>
+
+<programlisting language="python">
+def foo(target, source, env, for_signature):
+    return "bar"
+
+# Will expand $BAR to "bar baz"
+env = Environment(FOO=foo, BAR="$FOO baz")
+</programlisting>
+
+<para>As a reminder, substitution happens when
+<literal>$BAR</literal> is actually used in a
+builder action.  The value of <literal>env['BAR']</literal>
+will be exactly as it was set: <literal>"$FOO baz"</literal>.
+This can make debugging tricky,
+as the substituted result is not available at the time
+the SConscript files are being interpreted and
+thus not available to <systemitem>print()</systemitem>.
+However, you can perform the substitution on demand
+by calling the &f-link-env-subst; method for this purpose.
+</para>
+
+<para>You can use this feature to pass arguments to a
+callable variable by creating a callable class
+that stores passed arguments in the instance,
+and then uses them
+(in the <methodname>__call__</methodname> method)
+when the instance is called.
+Note that in this case,
+the entire variable expansion must
+be enclosed by curly braces
+so that the arguments will
+be associated with the
+instantiation of the class:</para>
+
+<programlisting language="python">
+class foo:
+    def __init__(self, arg):
+        self.arg = arg
+
+    def __call__(self, target, source, env, for_signature):
+        return self.arg + " bar"
+
+# Will expand $BAR to "my argument bar baz"
+env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
+</programlisting>
+
+</refsect3>
+
+<refsect3 id='special_variables'>
+<title>Substitution: Special Variables</title>
+
+<para>
 Besides regular &consvars;, scons provides the following
-special variables for use in expanding commands:</para>
+<firstterm>Special Variables</firstterm> for use in expanding commands:</para>
 
 <variablelist>
   <varlistentry>
@@ -6502,8 +6703,12 @@ changed since the target was last built.</para>
   </varlistentry>
 </variablelist>
 
-<para>These names are reserved
-and may not be assigned to or used as &consvars;.</para>
+<para>
+These names are reserved
+and may not be assigned to or used as &consvars;.
+&SCons; computes them in a context-dependent manner
+and they and are not retrieved from a &consenv;.
+</para>
 
 <para>For example, the following builder call:
 </para>
@@ -6529,6 +6734,11 @@ In the previous example, a string
 would expand to: <computeroutput>bar.c</computeroutput>.
 </para>
 
+</refsect3>
+
+<refsect3 id='special_attributes'>
+<title>Substitution: Special Attributes
+</title>
 <para>A variable name may
 have the following
 modifiers appended within the enclosing curly braces
@@ -6624,119 +6834,6 @@ Some modifiers can be combined, like
 <literal>${TARGET.file.suffix}</literal>, etc.
 </para>
 
-<para>The curly brace notation may also be used
-to enclose a Python expression to be evaluated.
-See <xref linkend='python_code_substitution'/> below
-for a description.</para>
-
-<para>The special escape sequences
-<emphasis role="bold">$(</emphasis>
-and
-<emphasis role="bold">$)</emphasis>
-may be used to surround parts of a command line
-that may change
-<emphasis>without</emphasis>
-causing a rebuild--that is,
-which are not included in the &buildsig;
-of target files built with this command.
-All text between
-<emphasis role="bold">$(</emphasis>
-and
-<emphasis role="bold">$)</emphasis>
-will be removed from the command line
-before it is added to the &buildsig;
-and the
-<emphasis role="bold">$(</emphasis>
-and
-<emphasis role="bold">$)</emphasis>
-will be removed before the command is executed.
-For example, the command line:</para>
-
-<programlisting language="python">
-echo Last build occurred $( $TODAY $). &gt; $TARGET
-</programlisting>
-
-<para>would execute the command:</para>
-
-<screen>
-echo Last build occurred $TODAY. &gt; $TARGET
-</screen>
-
-<para>but the command portion of the
-the &buildsig; computed for any target files built
-by this action would be:</para>
-
-<screen>
-echo Last build occurred  . &gt; $TARGET
-</screen>
-
-<para>While &consvars; are normally directly substituted,
-if a variable refers to a &consvar;
-whose value is a &Python; function,
-that function is called during substitution.
-Such a function must accept four arguments:
-<parameter>target</parameter>,
-<parameter>source</parameter>,
-<parameter>env</parameter> and
-<parameter>for_signature</parameter>.
-<parameter>source</parameter> is a list of source nodes,
-<parameter>target</parameter> is a list of target nodes,
-<parameter>env</parameter> is the &consenv; to use for context,
-and <parameter>for_signature</parameter> is
-a Boolean value that tells the function
-if it is being called for the purpose of generating a &buildsig;.
-Since the &buildsig; is used for rebuild determination,
-the function should omit variable elements
-that do not affect whether a rebuild should be triggered
-(see <emphasis role="bold">$(</emphasis>
-and <emphasis role="bold">$)</emphasis>
-above) if <parameter>for_signature</parameter> is true.
-</para>
-
-<para>
-&SCons; will insert whatever
-the called function returns
-into the expanded string:
-</para>
-
-<programlisting language="python">
-def foo(target, source, env, for_signature):
-    return "bar"
-
-# Will expand $BAR to "bar baz"
-env = Environment(FOO=foo, BAR="$FOO baz")
-</programlisting>
-
-<para>As a reminder, substitution happens when
-<literal>$BAR</literal> is actually used in a
-builder action.  The value of <literal>env['BAR']</literal>
-will be exactly as it was set: <literal>"$FOO baz"</literal>.
-</para>
-
-<para>You can use this feature to pass arguments to a
-Python function by creating a callable class
-that stores one or more arguments in an object,
-and then uses them when the
-<methodname>__call__()</methodname>
-method is called.
-Note that in this case,
-the entire variable expansion must
-be enclosed by curly braces
-so that the arguments will
-be associated with the
-instantiation of the class:</para>
-
-<programlisting language="python">
-class foo:
-    def __init__(self, arg):
-        self.arg = arg
-
-    def __call__(self, target, source, env, for_signature):
-        return self.arg + " bar"
-
-# Will expand $BAR to "my argument bar baz"
-env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
-</programlisting>
 </refsect3>
 
 <refsect3 id='python_code_substitution'>
@@ -6744,8 +6841,8 @@ env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
 
 <para>
 If a substitutable expression using the notation
-<literal>${something}</literal> does not appear to match one of
-the other substitution patterns,
+<literal>${<replaceable>expression</replaceable>}</literal>
+does not appear to match one of the other substitution patterns,
 it is evaluated as a Python expression.
 This uses Python's <function>eval</function> function,
 with the <parameter>globals</parameter> parameter set to
@@ -6811,45 +6908,6 @@ which &SCons; passes to <function>eval</function> which
 returns the value.
 </para>
 
-<para>&SCons; uses the following rules when converting &consvars; into
-command lines:</para>
-
-<variablelist>
-  <varlistentry>
-  <term>string</term>
-  <listitem>
-<para>When the value is a string it is interpreted as a space delimited list of
-command line arguments.</para>
-  </listitem>
-  </varlistentry>
-
-  <varlistentry>
-  <term>list</term>
-  <listitem>
-<para>When the value is a list it is interpreted as a list of command line
-arguments. Each element of the list is converted to a string.</para>
-  </listitem>
-  </varlistentry>
-
-  <varlistentry>
-  <term>other</term>
-  <listitem>
-<para>Anything that is not a list or string is converted to a string and
-interpreted as a single command line argument.</para>
-  </listitem>
-  </varlistentry>
-
-  <varlistentry>
-  <term>newline</term>
-  <listitem>
-<para>Newline characters (<literal>\n</literal>) delimit lines.
-The newline parsing is done after
-all other parsing, so it is not possible for arguments (e.g. file names) to
-contain embedded newline characters.</para>
-  </listitem>
-  </varlistentry>
-</variablelist>
-
 <note><para>
 Use of the Python <function>eval</function> function
 is considered to have security implications, since,
@@ -6909,7 +6967,7 @@ is optional, the default is no <parameter>arg</parameter>.
 <para>
 The function can use use
 <function>str</function>(<parameter>node</parameter>)
-to fetch the name of the file, 
+to fetch the name of the file,
 <replaceable>node</replaceable>.<function>dir</function>
 to fetch the directory the file is in,
 <replaceable>node</replaceable>.<function>get_contents</function>()
@@ -6930,7 +6988,7 @@ in order to build Nodes with correct paths.
 Using &f-link-FindPathDirs; with an argument of <literal>CPPPATH</literal>
 as the <parameter>path_function</parameter> in the &f-Scanner; call
 means the scanner function will be called with the paths extracted
-from &cv-CPPPATH; in the environment <parameter>env</parameter> 
+from &cv-CPPPATH; in the environment <parameter>env</parameter>
 passed as the <parameter>paths</parameter> parameter.
 </para>
 <para>
diff --git a/doc/scons.mod b/doc/scons.mod
index 5579d4d..8a6df17 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -440,15 +440,15 @@
 
 <!ENTITY Dictionary "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>Dictionary</literal>">
 
-<!ENTITY Emitter "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>Emitter</literal>">
-<!ENTITY emitter "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>emitter</literal>">
+<!ENTITY Emitter "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>Emitter</phrase>">
+<!ENTITY emitter "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>emitter</phrase>">
 
-<!ENTITY factory "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>factory</literal>">
+<!ENTITY factory "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>factory</phrase>">
 
-<!ENTITY Generator "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>Generator</literal>">
-<!ENTITY generator "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>generator</literal>">
+<!ENTITY Generator "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>Generator</phrase>">
+<!ENTITY generator "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>generator</phrase>">
 
-<!ENTITY Nodes "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>Nodes</literal>">
+<!ENTITY Nodes "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>Nodes</phrase>">
 
 <!ENTITY contentsig "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>content signature</phrase>">
 <!ENTITY contentsigs "<phrase xmlns='http://www.scons.org/dbxsd/v1.0'>content signatures</phrase>">
@@ -462,12 +462,12 @@
 
 <!-- Python keyword arguments -->
 
-<!ENTITY action "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>action=</literal>">
-<!ENTITY batch_key "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>batch_key=</literal>">
-<!ENTITY cmdstr "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>cmdstr=</literal>">
-<!ENTITY exitstatfunc "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>exitstatfunc=</literal>">
-<!ENTITY strfunction "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>strfunction=</literal>">
-<!ENTITY varlist "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>varlist=</literal>">
+<!ENTITY action "<parameter xmlns='http://www.scons.org/dbxsd/v1.0'>action=</parameter>">
+<!ENTITY batch_key "<parameter xmlns='http://www.scons.org/dbxsd/v1.0'>batch_key=</parameter>">
+<!ENTITY cmdstr "<parameter xmlns='http://www.scons.org/dbxsd/v1.0'>cmdstr=</parameter>">
+<!ENTITY exitstatfunc "<parameter xmlns='http://www.scons.org/dbxsd/v1.0'>exitstatfunc=</parameter>">
+<!ENTITY strfunction "<parameter xmlns='http://www.scons.org/dbxsd/v1.0'>strfunction=</parameter>">
+<!ENTITY varlist "<parameter xmlns='http://www.scons.org/dbxsd/v1.0'>varlist=</parameter>">
 
 
 <!-- File and program names used in examples.  -->
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 5a8851d..a53e70e 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.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">
@@ -81,14 +81,14 @@
     </para>
 
     <programlisting>
-bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
+bld = Builder(action='foobuild &lt; $SOURCE &gt; $TARGET')
     </programlisting>
 
     <para>
 
     All the above line does is create a free-standing
     &Builder; object.
-    The next section will show us how to actually use it.
+    The next section will show how to actually use it.
 
     </para>
 
@@ -105,7 +105,7 @@ bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
     for files to be built.
     This is done through the &cv-link-BUILDERS;
     &consvar; in an environment.
-    The &cv-BUILDERS; variable is a Python dictionary
+    The &cv-link-BUILDERS; variable is a &Python; dictionary
     that maps the names by which you want to call
     various &Builder; objects to the objects themselves.
     For example, if we want to call the
@@ -221,7 +221,7 @@ hello.c
 
     To be able to use both our own defined &Builder; objects
     and the default &Builder; objects in the same &consenv;,
-    you can either add to the &cv-BUILDERS; variable
+    you can either add to the &cv-link-BUILDERS; variable
     using the &Append; function:
 
     </para>
@@ -296,8 +296,8 @@ env.Program('hello.c')
     suffixes to the target and/or the source file.
     For example, rather than having to specify
     explicitly that you want the <literal>Foo</literal>
-    &Builder; to build the <literal>file.foo</literal>
-    target file from the <literal>file.input</literal> source file,
+    &Builder; to build the <filename>file.foo</filename>
+    target file from the <filename>file.input</filename> source file,
     you can give the <literal>.foo</literal>
     and <literal>.input</literal> suffixes to the &Builder;,
     making for more compact and readable calls to
@@ -361,7 +361,7 @@ env.Foo('file2')
 
     In &SCons;, you don't have to call an external command
     to build a file.
-    You can, instead, define a Python function
+    You can, instead, define a &Python; function
     that a &Builder; object can invoke
     to build your target file (or files).
     Such a &buildfunc; definition looks like:
@@ -383,7 +383,7 @@ def build_function(target, source, env):
     <variablelist>
 
       <varlistentry>
-      <term>target</term>
+      <term><parameter>target</parameter></term>
 
       <listitem>
       <para>
@@ -392,14 +392,14 @@ def build_function(target, source, env):
       the target or targets to be
       built by this function.
       The file names of these target(s)
-      may be extracted using the Python &str; function.
+      may be extracted using the &Python; &str; function.
 
       </para>
       </listitem>
       </varlistentry>
 
       <varlistentry>
-      <term>source</term>
+      <term><parameter>source</parameter></term>
 
       <listitem>
       <para>
@@ -408,21 +408,21 @@ def build_function(target, source, env):
       the sources to be
       used by this function to build the targets.
       The file names of these source(s)
-      may be extracted using the Python &str; function.
+      may be extracted using the &Python; &str; function.
 
       </para>
       </listitem>
       </varlistentry>
 
       <varlistentry>
-      <term>env</term>
+      <term><parameter>env</parameter></term>
 
       <listitem>
       <para>
 
       The &consenv; used for building the target(s).
       The function may use any of the
-      environment's construction variables
+      environment's &consvars;
       in any way to affect how it builds the targets.
 
       </para>
@@ -446,7 +446,7 @@ def build_function(target, source, env):
 
     <para>
 
-    Once you've defined the Python function
+    Once you've defined the &Python; function
     that will build your target file,
     defining a &Builder; object for it is as
     simple as specifying the name of the function,
@@ -479,7 +479,7 @@ file.input
     <para>
 
     And notice that the output changes slightly,
-    reflecting the fact that a Python function,
+    reflecting the fact that a &Python; function,
     not an external command,
     is now called to build the target file:
 
@@ -497,8 +497,8 @@ file.input
     <para>
 
     &SCons; Builder objects can create an action "on the fly"
-    by using a function called a &generator;.
-    (Note: this is not the same thing as a Python generator function
+    by using a function called a <firstterm>&Generator;</firstterm>.
+    (Note: this is not the same thing as a &Python; generator function
     described in <ulink url="https://www.python.org/dev/peps/pep-0255/">PEP 255</ulink>)
     This provides a great deal of flexibility to
     construct just the right list of commands
@@ -521,7 +521,7 @@ def generate_actions(source, target, env, for_signature):
     <variablelist>
 
       <varlistentry>
-      <term>source</term>
+      <term><parameter>source</parameter></term>
 
       <listitem>
       <para>
@@ -531,7 +531,7 @@ def generate_actions(source, target, env, for_signature):
       by the command or other action
       generated by this function.
       The file names of these source(s)
-      may be extracted using the Python &str; function.
+      may be extracted using the &Python; &str; function.
 
       </para>
       </listitem>
@@ -539,7 +539,7 @@ def generate_actions(source, target, env, for_signature):
       </varlistentry>
 
       <varlistentry>
-      <term>target</term>
+      <term><parameter>target</parameter></term>
 
       <listitem>
       <para>
@@ -549,7 +549,7 @@ def generate_actions(source, target, env, for_signature):
       by the command or other action
       generated by this function.
       The file names of these target(s)
-      may be extracted using the Python &str; function.
+      may be extracted using the &Python; &str; function.
 
       </para>
       </listitem>
@@ -557,14 +557,14 @@ def generate_actions(source, target, env, for_signature):
       </varlistentry>
 
       <varlistentry>
-      <term>env</term>
+      <term><parameter>env</parameter></term>
 
       <listitem>
       <para>
 
       The &consenv; used for building the target(s).
-      The generator may use any of the
-      environment's construction variables
+      The &generator; may use any of the
+      environment's &consvars;
       in any way to determine what command
       or other action to return.
 
@@ -574,13 +574,13 @@ def generate_actions(source, target, env, for_signature):
       </varlistentry>
 
       <varlistentry>
-      <term>for_signature</term>
+      <term><parameter>for_signature</parameter></term>
 
       <listitem>
       <para>
 
       A flag that specifies whether the
-      generator is being called to contribute to a build signature,
+      &generator; is being called to contribute to a &buildsig;,
       as opposed to actually executing the command.
 
       <!-- XXX NEED MORE HERE, describe generators use in signatures -->
@@ -604,8 +604,8 @@ def generate_actions(source, target, env, for_signature):
 
     Once you've defined a &generator;,
     you create a &Builder; to use it
-    by specifying the generator keyword argument
-    instead of <literal>action</literal>.
+    by specifying the <parameter>generator</parameter> keyword argument
+    instead of <parameter>action</parameter>.
 
     </para>
 
@@ -652,9 +652,9 @@ env.Foo('file')
     <para>
 
     Note that it's illegal to specify both an
-    <literal>action</literal>
+    <parameter>action</parameter>
     and a
-    <literal>generator</literal>
+    <parameter>generator</parameter>
     for a &Builder;.
 
     </para>
@@ -672,7 +672,7 @@ env.Foo('file')
     that takes as its arguments
     the list of the targets passed to the builder,
     the list of the sources passed to the builder,
-    and the construction environment.
+    and the &consenv;.
     The emitter function should return the modified
     lists of targets that should be built
     and sources from which the targets will be built.
@@ -739,7 +739,7 @@ env.Foo('file')
     </sconstruct>
 
     <para>
-    
+
     And would yield the following output:
 
     </para>
@@ -751,16 +751,15 @@ env.Foo('file')
     <para>
 
     One very flexible thing that you can do is
-    use a construction variable to specify
-    different emitter functions for different
-    construction variable.
+    use a &consvar; to specify
+    different emitter functions for different &consenvs;.
     To do this, specify a string
-    containing a construction variable
+    containing a &consvar;
     expansion as the emitter when you call
     the &f-link-Builder; function,
-    and set that construction variable to
+    and set that &consvar; to
     the desired emitter function
-    in different construction environments:
+    in different &consenvs;:
 
     </para>
 
@@ -827,9 +826,9 @@ cat
     is a powerful concept, but sometimes all you really want
     is to be able to use an existing builder but change its
     concept of what targets are created.
-    In this case, 
+    In this case,
     trying to recreate the logic of an existing Builder to
-    supply a special emitter can be a lot of work. 
+    supply a special emitter can be a lot of work.
     The typical case for this is when you want to use a compiler flag
     that causes additional files to be generated.
     For example the GNU linker accepts an option
@@ -844,12 +843,12 @@ cat
     <para>
 
     To help with this, &SCons; provides &consvars; which correspond
-    to a few standard builders: 
-    &cv-link-PROGEMITTER; for &b-link-Program;; 
-    &cv-link-LIBEMITTER; for &b-link-Library;; 
-    &cv-link-SHLIBEMITTER; for &b-link-SharedLibrary; and 
+    to a few standard builders:
+    &cv-link-PROGEMITTER; for &b-link-Program;;
+    &cv-link-LIBEMITTER; for &b-link-Library;;
+    &cv-link-SHLIBEMITTER; for &b-link-SharedLibrary; and
     &cv-link-LDMODULEEMITTER; for &b-link-LoadableModule;;.
-    Adding an emitter to one of these will cause it to be 
+    Adding an emitter to one of these will cause it to be
     invoked in addition to any existing emitter for the
     corresponding builder.
 
@@ -944,10 +943,10 @@ main()
     <para>
 
     The <filename>site_scons</filename> directories give you a place to
-    put Python modules and packages that you can import into your &SConscript; files
-    (<filename>site_scons</filename>),
+    put &Python; modules and packages that you can import into your
+    &SConscript; files (at the top level)
     add-on tools that can integrate into &SCons;
-    (<filename>site_scons/site_tools</filename>),
+    (in a <filename>site_tools</filename> subdirectory),
     and a <filename>site_scons/site_init.py</filename> file that
     gets read before any &SConstruct; or &SConscript; file,
     allowing you to change &SCons;'s default behavior.
@@ -957,8 +956,10 @@ main()
     <para>
 
     Each system type (Windows, Mac, Linux, etc.) searches a canonical
-    set of directories for <filename>site_scons</filename>; see the man page for details.
-    The top-level SConstruct's <filename>site_scons</filename> dir is always searched last,
+    set of directories for <filename>site_scons</filename>;
+    see the man page for details.
+    The top-level SConstruct's <filename>site_scons</filename> dir
+    (that is, the one in the project) is always searched last,
     and its dir is placed first in the tool path so it overrides all
     others.
 
@@ -969,8 +970,8 @@ main()
     If you get a tool from somewhere (the &SCons; wiki or a third party,
     for instance) and you'd like to use it in your project, a
     <filename>site_scons</filename> dir is the simplest place to put it.
-    Tools come in two flavors; either a Python function that operates on
-    an &Environment; or a Python module or package  containing two functions,
+    Tools come in two flavors; either a &Python; function that operates on
+    an &Environment; or a &Python; module or package  containing two functions,
     <function>exists()</function> and <function>generate()</function>.
 
     </para>
@@ -1023,7 +1024,7 @@ env.AddHeader('tgt', 'src')
 
     </para>
 
-    <!-- 
+    <!--
     <scons_output example="builderswriting_site1" os="posix" suffix="1">
        <scons_output_command>scons -Q</scons_output_command>
     </scons_output>
@@ -1050,15 +1051,16 @@ env.AddHeader('tgt', 'src')
     </para>
 
     <para>
-      Many people have a library of utility Python functions they'd like
-      to include in &SConscript;s; just put that module in
-      <filename>site_scons/my_utils.py</filename> or any valid Python module name of your
+      Many people have a collection of utility &Python; functions they'd like
+      to include in their &SConscript; files: just put them in
+      <filename>site_scons/my_utils.py</filename>
+      or any valid &Python; module name of your
       choice.  For instance you can do something like this in
       <filename>site_scons/my_utils.py</filename> to add
       <function>build_id</function> and <function>MakeWorkDir</function>
       functions:
     </para>
-      
+
     <scons_example name="builderswriting_site2">
       <file name="site_scons/my_utils.py" printme="1">
 from SCons.Script import *  # for Execute and Mkdir
@@ -1073,16 +1075,15 @@ def MakeWorkDir(workdir):
       </file>
       <file name="SConscript">
 import my_utils
+
 MakeWorkDir('/tmp/work')
 print("build_id=" + my_utils.build_id())
       </file>
     </scons_example>
 
     <para>
-
-    And then in your &SConscript; or any sub-&SConscript; anywhere in
-    your build, you can import <filename>my_utils</filename> and use it:
-
+      And then in your &SConscript; or any sub-&SConscript; anywhere in
+      your build, you can import <filename>my_utils</filename> and use it:
     </para>
 
     <sconstruct>
@@ -1092,11 +1093,12 @@ my_utils.MakeWorkDir('/tmp/work')
     </sconstruct>
 
     <para>
-      Note that although you can put this library in
+      You can put this collection in its own module in a
+      <filename>site_scons</filename> and import it as in the example,
+      or you can include it in
       <filename>site_scons/site_init.py</filename>,
-      it is no better there than <filename>site_scons/my_utils.py</filename>
-      since you still have to import that module into your &SConscript;.
-      Also note that in order to refer to objects in the SCons namespace
+      which is automatically imported (unless you disable site directories).
+      Note that in order to refer to objects in the SCons namespace
       such as &Environment; or &Mkdir; or &Execute; in any file other
       than a &SConstruct; or &SConscript; you always need to do
     </para>
@@ -1105,22 +1107,20 @@ from SCons.Script import *
     </sconstruct>
 
     <para>
-      This is true in modules in <filename>site_scons</filename> such as
+      This is true of modules in <filename>site_scons</filename> such as
       <filename>site_scons/site_init.py</filename> as well.
     </para>
 
     <para>
-
-      You can use any of the user- or machine-wide site dirs such as
+      You can use any of the user- or machine-wide site directories such as
       <filename>~/.scons/site_scons</filename> instead of
       <filename>./site_scons</filename>, or use the
-      <option>--site-dir</option> option to point to your own dir.
+      <option>--site-dir</option> option to point to your own directory.
       <filename>site_init.py</filename> and
-      <filename>site_tools</filename> will be located under that dir.
-      To avoid using a <filename>site_scons</filename> dir at all,
+      <filename>site_tools</filename> will be located under that directory.
+      To avoid using a <filename>site_scons</filename> directory at all,
       even if it exists, use the <option>--no-site-dir</option>
       option.
-
     </para>
 
   </section>