Propagate doc about site_scons to builders-writing.xml. Typographic edits.

2 files changed, 161 insertions, 119 deletions

diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 19c91de..2c5cce2 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -900,11 +900,13 @@ This functionality could be invoked as in the following example:
     <para>
 
     The <filename>site_scons</filename> directory gives you a place to
-    put Python modules you can import into your SConscripts
-    (site_scons), add-on tools that can integrate into &SCons;
-    (site_scons/site_tools), and a site_scons/site_init.py file that
-    gets read before any &SConstruct; or &SConscript;, allowing you to
-    change &SCons;'s default behavior.
+    put Python modules you can import into your &SConscript; files
+    (<filename>site_scons</filename>),
+    add-on tools that can integrate into &SCons;
+    (<filename>site_scons/site_tools</filename>),
+    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.
 
     </para>
 
@@ -914,8 +916,8 @@ This functionality could be invoked as in the following example:
     for instance) and you'd like to use it in your project, the
     <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 file containing two functions, exists()
-    and generate().
+    an &Environment; or a Python file containing two functions,
+    <function>exists()</function> and <function>generate()</function>.
 
     </para>
 
@@ -990,7 +992,9 @@ This functionality could be invoked as in the following example:
       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
       choice.  For instance you can do something like this in
-      <filename>site_scons/my_utils.py</filename> to add build_id and MakeWorkDir functions:
+      <filename>site_scons/my_utils.py</filename> to add
+      <function>build_id</function> and <function>MakeWorkDir</function>
+      functions:
     </para>
       
     <scons_example name="site2">
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 265357d..3932181 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -742,148 +742,186 @@ This functionality could be invoked as in the following example:
 
   </section>
 
+  <!--
+
+  <section>
+  <title>target_factor=, source_factory=</title>
+
+  </section>
+
+  <section>
+  <title>target_scanner=, source_scanner=</title>
+
+  </section>
+
+  <section>
+  <title>multi=</title>
+
+  </section>
+
+  <section>
+  <title>single_source=</title>
+
+  </section>
+
+  <section>
+  <title>src_builder=</title>
+
+  </section>
+
+  <section>
+  <title>ensure_suffix=</title>
+
+  </section>
+
+  -->
+
   <section>
   <title>Where To Put Your Custom Builders and Tools</title>
 
-  <para>
+    <para>
 
-  The <filename>site_scons</filename> directory gives you a place to
-  put Python modules you can import into your SConscripts
-  (site_scons), add-on tools that can integrate into &SCons;
-  (site_scons/site_tools), and a site_scons/site_init.py file that
-  gets read before any &SConstruct; or &SConscript;, allowing you to
-  change &SCons;'s default behavior.
+    The <filename>site_scons</filename> directory gives you a place to
+    put Python modules you can import into your &SConscript; files
+    (<filename>site_scons</filename>),
+    add-on tools that can integrate into &SCons;
+    (<filename>site_scons/site_tools</filename>),
+    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.
 
-  </para>
+    </para>
 
-  <para>
+    <para>
 
-  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, the
-  <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 file containing two functions, exists()
-  and generate().
+    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, the
+    <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 file containing two functions,
+    <function>exists()</function> and <function>generate()</function>.
 
-  </para>
+    </para>
 
-  <para>
+    <para>
 
-  A single-function Tool can just be included in your
-  <filename>site_scons/site_init.py</filename> file where it will be
-  parsed and made available for use.  For instance, you could have a
-  <filename>site_scons/site_init.py</filename> file like this:
+    A single-function Tool can just be included in your
+    <filename>site_scons/site_init.py</filename> file where it will be
+    parsed and made available for use.  For instance, you could have a
+    <filename>site_scons/site_init.py</filename> file like this:
 
-  </para>
+    </para>
 
-  <programlisting>
-      def TOOL_ADD_HEADER(env):
-         """A Tool to add a header from $HEADER to the source file"""
-         add_header = Builder(action=['echo "$HEADER" &gt; $TARGET',
-                                      'cat $SOURCE &gt;&gt; $TARGET'])
-         env.Append(BUILDERS = {'AddHeader' : add_header})
-         env['HEADER'] = '' # set default value
-  </programlisting>
+    <programlisting>
+        def TOOL_ADD_HEADER(env):
+           """A Tool to add a header from $HEADER to the source file"""
+           add_header = Builder(action=['echo "$HEADER" &gt; $TARGET',
+                                        'cat $SOURCE &gt;&gt; $TARGET'])
+           env.Append(BUILDERS = {'AddHeader' : add_header})
+           env['HEADER'] = '' # set default value
+    </programlisting>
 
-  <para>
+    <para>
 
-  and a &SConstruct; like this:
+    and a &SConstruct; like this:
 
-  </para>
+    </para>
 
-  <programlisting>
-      # Use TOOL_ADD_HEADER from site_scons/site_init.py
-      env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====")
-      env.AddHeader('tgt', 'src')
-  </programlisting>
+    <programlisting>
+        # Use TOOL_ADD_HEADER from site_scons/site_init.py
+        env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====")
+        env.AddHeader('tgt', 'src')
+    </programlisting>
 
-  <para>
+    <para>
 
-    The <function>TOOL_ADD_HEADER</function> tool method will be
-    called to add the <function>AddHeader</function> tool to the
-    environment.
+      The <function>TOOL_ADD_HEADER</function> tool method will be
+      called to add the <function>AddHeader</function> tool to the
+      environment.
 
-  </para>
+    </para>
 
-  <!-- 
-  <scons_output example="site1" os="posix">
-     <scons_output_command>scons -Q</scons_output_command>
-  </scons_output>
-  -->
+    <!-- 
+    <scons_output example="site1" os="posix">
+       <scons_output_command>scons -Q</scons_output_command>
+    </scons_output>
+    -->
 
-  <para>
-    Similarly, a more full-fledged tool with
-    <function>exists()</function> and <function>generate()</function>
-    methods can be installed in
-    <filename>site_scons/site_tools/toolname.py</filename>.  Since
-    <filename>site_scons/site_tools</filename> is automatically added
-    to the head of the tool search path, any tool found there will be
-    available to all environments.  Furthermore, a tool found there
-    will override a built-in tool of the same name, so if you need to
-    change the behavior of a built-in tool, site_scons gives you the
-    hook you need.
-  </para>
+    <para>
+      Similarly, a more full-fledged tool with
+      <function>exists()</function> and <function>generate()</function>
+      methods can be installed in
+      <filename>site_scons/site_tools/toolname.py</filename>.  Since
+      <filename>site_scons/site_tools</filename> is automatically added
+      to the head of the tool search path, any tool found there will be
+      available to all environments.  Furthermore, a tool found there
+      will override a built-in tool of the same name, so if you need to
+      change the behavior of a built-in tool, site_scons gives you the
+      hook you need.
+    </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
-    choice.  For instance you can do something like this in
-    <filename>site_scons/my_utils.py</filename> to add build_id and MakeWorkDir functions:
-  </para>
-    
-  <programlisting>
-      from SCons.Script import *   # for Execute and Mkdir
-      def build_id():
-         """Return a build ID (stub version)"""
-         return "100"
-      def MakeWorkDir(workdir):
-         """Create the specified dir immediately"""
-         Execute(Mkdir(workdir))
-  </programlisting>
+    <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
+      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>
+      
+    <programlisting>
+        from SCons.Script import *   # for Execute and Mkdir
+        def build_id():
+           """Return a build ID (stub version)"""
+           return "100"
+        def MakeWorkDir(workdir):
+           """Create the specified dir immediately"""
+           Execute(Mkdir(workdir))
+    </programlisting>
 
-  <para>
+    <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>
+    </para>
 
-  <programlisting>
-      import my_utils
-      print "build_id=" + my_utils.build_id()
-      my_utils.MakeWorkDir('/tmp/work')
-  </programlisting>
+    <programlisting>
+        import my_utils
+        print "build_id=" + my_utils.build_id()
+        my_utils.MakeWorkDir('/tmp/work')
+    </programlisting>
 
-  <para>
-    Note that although you can put this library 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
-    such as &Environment; or &Mkdir; or &Execute; in any file other
-    than a &SConstruct; or &SConscript; you always need to do
-  </para>
-  <programlisting>
-      from SCons.Script import *
-  </programlisting>
+    <para>
+      Note that although you can put this library 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
+      such as &Environment; or &Mkdir; or &Execute; in any file other
+      than a &SConstruct; or &SConscript; you always need to do
+    </para>
+    <programlisting>
+        from SCons.Script import *
+    </programlisting>
 
-  <para>
-    This is true in modules in <filename>site_scons</filename> such as
-    <filename>site_scons/site_init.py</filename> as well.
-  </para>
+    <para>
+      This is true in modules in <filename>site_scons</filename> such as
+      <filename>site_scons/site_init.py</filename> as well.
+    </para>
 
-  <para>
+    <para>
 
-    If you have a machine-wide site dir you'd like to use instead of
-    <filename>./site_scons</filename>, use the
-    <literal>--site-dir</literal> option to point to your dir.
-    <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, even
-    if it exists, use the <literal>--no-site-dir</literal> option.
+      If you have a machine-wide site dir you'd like to use instead of
+      <filename>./site_scons</filename>, use the
+      <literal>--site-dir</literal> option to point to your dir.
+      <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, even
+      if it exists, use the <literal>--no-site-dir</literal> option.
 
-  </para>
+    </para>
 
   </section>