Merge pull request #4299 from mwichmann/doc/uguide-pseudoHEADmaster

Tweak pseudo-builder in user guide

4 files changed, 81 insertions, 81 deletions

diff --git a/doc/scons.mod b/doc/scons.mod
index ea1deccb6..2d3f5a434 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -92,15 +92,23 @@
 <!ENTITY zip            "<application xmlns='http://www.scons.org/dbxsd/v1.0'>zip</application>">
 
 
+<!-- Concepts: these are key SCons things, which may *also* be classes, etc.
+     but are marked here for inclusion in a glossary
+-->
+<!ENTITY Action "<glossterm linkend='gls-action' xmlns='http://www.scons.org/dbxsd/v1.0'>Action</glossterm>">
+<!ENTITY Builder "<glossterm linkend='gls-builder' xmlns='http://www.scons.org/dbxsd/v1.0'>Builder</glossterm>">
+<!ENTITY Builders "<glossterm linkend='gls-builder' xmlns='http://www.scons.org/dbxsd/v1.0'>Builders</glossterm>">
+<!ENTITY Scanner "<glossterm linkend='gls-scanner' xmlns='http://www.scons.org/dbxsd/v1.0'>Scanner</glossterm>">
+<!ENTITY Scanners "<glossterm linkend='gls-scanner' xmlns='http://www.scons.org/dbxsd/v1.0'>Scanners</glossterm>">
+
+
 <!-- Classes.  -->
 
-<!ENTITY Action "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Action</classname>">
 <!ENTITY ActionBase "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>ActionBase</classname>">
 <!ENTITY BuildInfo "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>BuildInfo</classname>">
 <!ENTITY CommandAction "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>CommandAction</classname>">
 <!ENTITY FunctionAction "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>FunctionAction</classname>">
 <!ENTITY ListAction "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>ListAction</classname>">
-<!ENTITY Builder "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Builder</classname>">
 <!ENTITY BuilderBase "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>BuilderBase</classname>">
 <!ENTITY CompositeBuilder "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>CompositeBuilder</classname>">
 <!ENTITY MultiStepBuilder "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>MultiStepBuilder</classname>">
@@ -110,7 +118,6 @@
 <!ENTITY Parallel "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Parallel</classname>">
 <!ENTITY Node "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Node</classname>">
 <!ENTITY Node_FS "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Node.FS</classname>">
-<!ENTITY Scanner "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Scanner</classname>">
 <!ENTITY Sig "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Sig</classname>">
 <!ENTITY Signature "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Signature</classname>">
 <!ENTITY Taskmaster "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>Taskmaster</classname>">
diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml
index 7b5200ede..179be95fd 100644
--- a/doc/user/add-method.xml
+++ b/doc/user/add-method.xml
@@ -1,4 +1,10 @@
 <?xml version='1.0'?>
+<!--
+SPDX-License-Identifier: MIT
+
+Copyright The SCons Foundation
+-->
+
 <!DOCTYPE sconsdoc [
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
@@ -18,43 +24,22 @@
          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>Extending &SCons;: Pseudo-Builders and the AddMethod function</title>
 
-<!--
-
-  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
-  "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:
+<title>Extending &SCons;: Pseudo-Builders and the AddMethod function</title>
 
-  The above copyright notice and this permission notice shall be included
-  in all copies or substantial portions of the Software.
+  <para>
 
-  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.
+  The &f-link-AddMethod; function is used to add a method
+  to an environment.  It is typically used to add a "pseudo-builder,"
+  a function that looks like a &Builder; but
+  wraps up calls to multiple other &Builders;
+  or otherwise processes its arguments
+  before calling one or more &Builders;.
 
--->
+  </para>
 
   <para>
 
-  The &AddMethod; function is used to add a method
-  to an environment.  It's typically used to add a "pseudo-builder,"
-  a function that looks like a &Builder; but
-  wraps up calls to multiple other &Builder;s
-  or otherwise processes its arguments
-  before calling one or more &Builder;s.
   In the following example,
   we want to install the program into the standard
   <filename>/usr/bin</filename> directory hierarchy,
@@ -69,10 +54,11 @@ def install_in_bin_dirs(env, source):
     """Install source in both bin dirs"""
     i1 = env.Install("$BIN", source)
     i2 = env.Install("$LOCALBIN", source)
-    return [i1[0], i2[0]] # Return a list, like a normal builder
+    return [i1[0], i2[0]]  # Return a list, like a normal builder
+
 env = Environment(BIN='__ROOT__/usr/bin', LOCALBIN='#install/bin')
 env.AddMethod(install_in_bin_dirs, "InstallInBinDirs")
-env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs     
+env.InstallInBinDirs(Program('hello.c'))  # installs hello in both bin dirs
      </file>
      <file name="hello.c">
 int main() { printf("Hello, world!\n"); }
@@ -89,31 +75,35 @@ int main() { printf("Hello, world!\n"); }
 
   <para>
 
-  As mentioned, a pseudo-builder also provides more flexibility
-  in parsing arguments than you can get with a &Builder;.
+  A pseudo-builder is useful because it gives you more flexibility
+  parsing arguments than you can get with a standard &Builder;.
   The next example shows a pseudo-builder with a
-  named argument that modifies the filename, and a separate argument
-  for the resource file (rather than having the builder figure it out
+  named argument that modifies the filename, and a separate optional
+  argument for a resource file (rather than having the builder figure it out
   by file extension).  This example also demonstrates using the global
   &AddMethod; function to add a method to the global Environment class,
-  so it will be used in all subsequently created environments.
+  so it will be available in all subsequently created environments.
 
   </para>
 
   <scons_example name="addmethod_ex2">
      <file name="SConstruct" printme="1">
-def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
-    """Build the test program;
-    prepends "test_" to src and target,
-    and puts target into testdir."""
-    srcfile = "test_%s.c" % testfile
-    target = "%s/test_%s" % (testdir, testfile)
-    if env['PLATFORM'] == 'win32':
+def BuildTestProg(env, testfile, resourcefile="", testdir="tests"):
+    """Build the test program.
+
+    Prepends "test_" to src and target and puts the target into testdir.
+    If the build is running on Windows, also make use of a resource file,
+    if supplied.
+    """
+    srcfile = f"test_{testfile}.c"
+    target = f"{testdir}/test_{testfile}"
+    if env['PLATFORM'] == 'win32' and resourcefile:
         resfile = env.RES(resourcefile)
         p = env.Program(target, [srcfile, resfile])
     else:
         p = env.Program(target, srcfile)
     return p
+
 AddMethod(Environment, BuildTestProg)
 
 env = Environment()
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index a53e70e07..97ca36f9f 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -222,13 +222,14 @@ 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-link-BUILDERS; variable
-    using the &Append; function:
+    using the &f-link-Append; function:
 
     </para>
 
     <scons_example name="builderswriting_ex3">
        <file name="SConstruct">
 import os
+
 env = Environment()
 env.AppendENVPath('PATH', os.getcwd())
 bld = Builder(action='foobuild &lt; $SOURCE &gt; $TARGET')
diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml
index b9a5084a7..65389879d 100644
--- a/doc/user/scanners.xml
+++ b/doc/user/scanners.xml
@@ -146,15 +146,18 @@ over the file scanning rather than being called for each input line:
 
   <para>
 
-    &SCons; has built-in scanners that know how to look in
+    &SCons; has built-in &Scanners; that know how to look in
     C/C++, Fortran, D, IDL, LaTeX, Python and SWIG source files
     for information about
-    other files that targets built from those files depend on--for example,
-    in the case of files that use the C preprocessor,
-    the <filename>.h</filename> files that are specified
-    using <literal>#include</literal> lines in the source.
+    other files that targets built from those files depend on.
+
+    For example, if you have a file format which uses <literal>#include</literal>
+    to specify files which should be included into the source file
+    when it is processed, you can use an existing scanner already 
+    included in &SCons;.
+
     You can use the same mechanisms that &SCons; uses to create
-    its built-in scanners to write scanners of your own for file types
+    its built-in Scanners to write Scanners of your own for file types
     that &SCons; does not know how to scan "out of the box."
 
   </para>
@@ -164,7 +167,7 @@ over the file scanning rather than being called for each input line:
 
     <para>
 
-      Suppose, for example, that we want to create a simple scanner
+      Suppose, for example, that we want to create a simple &Scanner;
       for <filename>.foo</filename> files.
       A <filename>.foo</filename> file contains some text that
       will be processed,
@@ -183,7 +186,7 @@ include filename.foo
       Scanning a file will be handled by a Python function
       that you must supply.
       Here is a function that will use the Python
-      <filename>re</filename> module
+      <systemitem>re</systemitem> module
       to scan for the <literal>include</literal> lines in our example:
 
     </para>
@@ -203,7 +206,7 @@ def kfile_scan(node, env, path, arg):
       It is important to note that you
       have to return a list of File nodes from the scanner function, simple
       strings for the file names won't do. As in the examples we are showing here,
-      you can use the &File;
+      you can use the &f-link-File;
       function of your current &consenv;  in order to create nodes
       on the fly from a sequence of file names with relative paths.
       
@@ -225,7 +228,7 @@ def kfile_scan(node, env, path, arg):
     <variablelist>
 
       <varlistentry>
-      <term>node</term>
+      <term><parameter>node</parameter></term>
 
       <listitem>
       <para>
@@ -233,8 +236,8 @@ def kfile_scan(node, env, path, arg):
       An &SCons; node object representing the file being scanned.
       The path name to the file can be
       used by converting the node to a string
-      using the <literal>str()</literal> function,
-      or an internal &SCons; <literal>get_text_contents()</literal>
+      using the <function>str</function> function,
+      or an internal &SCons; <methodname>get_text_contents</methodname>
       object method can be used to fetch the contents.
 
       </para>
@@ -242,7 +245,7 @@ def kfile_scan(node, env, path, arg):
       </varlistentry>
 
       <varlistentry>
-      <term>env</term>
+      <term><parameter>env</parameter></term>
 
       <listitem>
       <para>
@@ -256,13 +259,13 @@ def kfile_scan(node, env, path, arg):
       </varlistentry>
 
       <varlistentry>
-      <term>path</term>
+      <term><parameter>path</parameter></term>
 
       <listitem>
       <para>
 
       A list of directories that form the search path for included files
-      for this scanner.
+      for this Scanner.
       This is how &SCons; handles the &cv-link-CPPPATH; and &cv-link-LIBPATH;
       variables.
 
@@ -271,7 +274,7 @@ def kfile_scan(node, env, path, arg):
       </varlistentry>
 
       <varlistentry>
-      <term>arg</term>
+      <term><parameter>arg</parameter></term>
 
       <listitem>
       <para>
@@ -288,10 +291,10 @@ def kfile_scan(node, env, path, arg):
 
     <para>
 
-    A Scanner object is created using the &f-link-Scanner; function,
+    A scanner object is created using the &f-link-Scanner; function,
     which typically takes an <parameter>skeys</parameter> argument
-    to associate a file suffix with this scanner.
-    The Scanner object must then be associated with the
+    to associate a file suffix with this Scanner.
+    The scanner object must then be associated with the
     &cv-link-SCANNERS; &consvar; in the current &consenv;,
     typically by using the &f-link-Append; method:
 
@@ -320,7 +323,6 @@ def kfile_scan(node, env, path):
     return env.File(includes)
 
 kscan = Scanner(function=kfile_scan, skeys=['.k'])
-
 env = Environment(ENV={'PATH': '__ROOT__/usr/local/bin'})
 env.Append(SCANNERS=kscan)
 
@@ -364,21 +366,21 @@ cat
   </section>
 
   <section>
-  <title>Adding a search path to a scanner: &FindPathDirs;</title>
+  <title>Adding a search path to a Scanner: &FindPathDirs;</title>
 
     <para>
 
     If the build tool in question will use a path variable to search
-    for included files or other dependencies, then the Scanner will
+    for included files or other dependencies, then the &Scanner; will
     need to take that path variable into account as well -
     &cv-link-CPPPATH; and &cv-link-LIBPATH; are used this way,
     for example.  The path to search is passed to your
-    scanner as the <parameter>path</parameter> argument.  Path variables
+    Scanner as the <parameter>path</parameter> argument.  Path variables
     may be lists of nodes, semicolon-separated strings, or even
     contain &consvars; which need to be expanded.  
     &SCons; provides the &f-link-FindPathDirs; function which returns
     a callable to expand a given path (given as a SCons &consvar;
-    name) to a list of paths at the time the scanner is called.
+    name) to a list of paths at the time the Scanner is called.
     Deferring evaluation until that point allows, for instance,
     the path to contain &cv-link-TARGET; references which differ for
     each file scanned.
@@ -390,7 +392,7 @@ cat
     Using &FindPathDirs; is quite easy.  Continuing the above example,
     using <varname>KPATH</varname> as the &consvar; with the search path
     (analogous to &cv-link-CPPPATH;), we just modify the call to
-    the &Scanner; factory function to include a path keyword arg:
+    the &f-link-Scanner; factory function to include a path keyword arg:
 
     </para>
     
@@ -404,7 +406,7 @@ kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('K
     
     &FindPathDirs; returns a callable object that, when called, will
     essentially expand the elements in <literal>env['KPATH']</literal>
-    and tell the scanner to search in those dirs.  It will also properly
+    and tell the Scanner to search in those dirs.  It will also properly
     add related repository and variant dirs to the search list.  As a side
     note, the returned method stores the path in an efficient way so
     lookups are fast even when variable substitutions may be needed.
@@ -418,9 +420,9 @@ kscan = Scanner(function=kfile_scan, skeys=['.k'], path_function=FindPathDirs('K
 
     <para>
 
-    One approach for introducing scanners into the build is in
-    conjunction with a Builder.  There are two relvant optional
-    parameters we can use when creating a builder:
+    One approach for introducing a &Scanner; into the build is in
+    conjunction with a &Builder;.  There are two relvant optional
+    parameters we can use when creating a Builder:
     <parameter>source_scanner</parameter> and
     <parameter>target_scanner</parameter>.
     <parameter>source_scanner</parameter> is used for scanning
@@ -459,16 +461,16 @@ env.Foo('file')
     <para>
 
     An emitter function can modify the list of sources or targets
-    passed to the action function when the builder is triggered.
+    passed to the action function when the Builder is triggered.
 
     </para>
 
     <para>
 
     A scanner function will not affect the list of sources or targets
-    seen by the builder during the build action. The scanner function
-    will however affect if the builder should rebuild (if any of
-    the files sourced by the scanner have changed for example).
+    seen by the Builder during the build action. The scanner function
+    will however affect if the Builder should rebuild (if any of
+    the files sourced by the Scanner have changed for example).
 
     </para>
   </section>