Tweak pseudo-builder in user guide [skip appveyor]

Minor fiddling - example format, headers, wordings tweaks

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

1 files changed, 29 insertions, 44 deletions

diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml
index 7b5200ede..86297de7a 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,17 @@
          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:
-
-  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.
-
--->
+<title>Extending &SCons;: Pseudo-Builders and the AddMethod function</title>
 
   <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
+  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 Builder's
   or otherwise processes its arguments
-  before calling one or more &Builder;s.
+  before calling one or more Builders.
   In the following example,
   we want to install the program into the standard
   <filename>/usr/bin</filename> directory hierarchy,
@@ -69,10 +49,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 +70,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 provides more flexibility
+  in parsing arguments than you can get with a standard Builder method.
   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
   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()