Manpage: modify the Builder Methods section

CHANGES.txt

@@ -198,6 +198,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       attribute and to explain what's being done in the example.
     - Test framework reformatted using settings from pyproject.toml.
       Includes code embedded in docstrings.
+    - Improve the Builder Methods intro section in manpage, making sure
+      all prose appears before the listing of methods.
 
     From Adam Scott:
     - Changed Ninja's TEMPLATE rule pool to use `install_pool` instead of

RELEASE.txt

@@ -224,6 +224,9 @@ DOCUMENTATION
   being created from '${SOURCE.base}.out' to use a valid special
   attribute and to explain what's being done in the example.
 
+- Improve the descriptive portion of the Builder Methods section in
+  the manpage: reword, reorganize.
+
 DEVELOPMENT
 -----------
 

SCons/BuilderTests.py

@@ -714,8 +714,8 @@ def func(target, source, env) -> None:
             infiles.append(test.workpath('%d.in' % i))
             outfiles.append(test.workpath('%d.out' % i))
             test.write(infiles[-1], "\n")
-        builder = SCons.Builder.Builder(action=SCons.Action.Action(func,None),
-                                        single_source = 1, suffix='.out')
+        builder = SCons.Builder.Builder(action=SCons.Action.Action(func, None),
+                                        single_source=True, suffix='.out')
         env['CNT'] = [0]
         tgt = builder(env, target=outfiles[0], source=infiles[0])[0]
         s = str(tgt)

SCons/Node/__init__.py

@@ -215,7 +215,7 @@ def get_contents_dir(node):
         contents.append('%s %s\n' % (n.get_csig(), n.name))
     return ''.join(contents)
 
-def get_contents_file(node):
+def get_contents_file(node) -> bytes:
     if not node.rexists():
         return b''
     fname = node.rfile().get_abspath()

SCons/Tool/Tool.xml

@@ -36,13 +36,13 @@ if it is not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 # builds foo.c
 env.CFile(target='foo.c', source='foo.l')
 
 # builds bar.c
 env.CFile(target='bar', source='bar.y')
-</example_commands>
+</programlisting>
 
 <!--para>  ** Left here for reference, does not need to be user-visible. **
 Note that for yacc files,
@@ -67,13 +67,13 @@ if it is not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 # builds foo.cc
 env.CXXFile(target='foo.cc', source='foo.ll')
 
 # builds bar.cc
 env.CXXFile(target='bar', source='bar.yy')
-</example_commands>
+</programlisting>
 
 <!--para>  ** Left here for reference, does not need to be user-visible. **
 Note that for yacc files,
@@ -141,9 +141,9 @@ are automatically added to the target if not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
-</example_commands>
+</programlisting>
 </summary>
 </builder>
 
@@ -187,9 +187,9 @@ it is appended (following a period) to the resulting library name.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
-</example_commands>
+</programlisting>
 
 <para>
 On Windows systems, the
@@ -228,9 +228,9 @@ adds the version number to the library name, and creates any
 symbolic links that are needed.
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
-</example_commands>
+</programlisting>
 
 <para>
 On a POSIX system, supplying a simple version string (no dots)
@@ -264,9 +264,9 @@ up and requiring user attention when it is run.  If you change
 For example,
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
-</example_commands>
+</programlisting>
 
 <para>
 will register <filename>bar.dll</filename> as a COM object
@@ -281,38 +281,41 @@ when it is done linking it.
 Builds an object file intended for
 inclusion in a shared library.
 Source files must have one of the same set of extensions
-specified above for the
-&b-StaticObject;
+specified for the
+&b-link-StaticObject;
 builder method.
-On some platforms building a shared object requires additional
-compiler option
-(e.g. <option>-fPIC</option> for <command>gcc</command>)
-in addition to those needed to build a
-normal (static) object, but on some platforms there is no difference between a
-shared object and a normal (static) one. When there is a difference, SCons
-will only allow shared objects to be linked into a shared library, and will
-use a different suffix for shared objects. On platforms where there is no
-difference, SCons will allow both normal (static)
-and shared objects to be linked into a
-shared library, and will use the same suffix for shared and normal
-(static) objects.
 The target object file prefix,
 specified by the &cv-link-SHOBJPREFIX; &consvar;
 (by default, the same as &cv-link-OBJPREFIX;),
 and suffix,
 specified by the &cv-link-SHOBJSUFFIX; &consvar;,
 are automatically added to the target if not already present.
+&b-SharedObject; is a single-source builder.
 Examples:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedObject(target='ddd', source='ddd.c')
 env.SharedObject(target='eee.o', source='eee.cpp')
 env.SharedObject(target='fff.obj', source='fff.for')
-</example_commands>
+env.SharedObject(source=Glob('*.c'))
+</programlisting>
 
 <para>
-Note that the source files will be scanned
+On some platforms building a shared object requires additional
+compiler option(s)
+(e.g. <option>-fPIC</option> for <command>gcc</command>)
+in addition to those needed to build a
+normal (static) object.
+If shared and static objects differ,
+&SCons; will allow only shared objects
+to be linked into a shared library,
+and will use a different suffix for shared objects
+to help indicate and track the difference.
+</para>
+
+<para>
+Source files will be scanned
 according to the suffix mappings in the
 <classname>SourceFileScanner</classname>
 object.
@@ -342,9 +345,9 @@ are automatically added to the target if not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
-</example_commands>
+</programlisting>
 
 <para>
 Any object files listed in the
@@ -364,10 +367,10 @@ will raise an error if there is any mismatch.
 <para>
 Builds a static object file
 from one or more C, C++, D, or Fortran source files.
-Source files must have one of the following extensions:
+The file extension mapping is shown in the table:
 </para>
 
-<example_commands>
+<literallayout><literal>
   .asm    assembly language file
   .ASM    assembly language file
   .c      C file
@@ -396,28 +399,30 @@ Source files must have one of the following extensions:
           POSIX:  assembly language file + C pre-processor
   .spp    assembly language file + C pre-processor
   .SPP    assembly language file + C pre-processor
-</example_commands>
+</literal></literallayout>
 
 <para>
 The target object file prefix,
 specified by the &cv-link-OBJPREFIX; &consvar;
-(nothing by default),
+(empty string by default),
 and suffix,
 specified by the &cv-link-OBJSUFFIX; &consvar;
 (<filename>.obj</filename> on Windows systems,
 <filename>.o</filename> on POSIX systems),
 are automatically added to the target if not already present.
+&b-StaticObject; is a single-source builder.
 Examples:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.StaticObject(target='aaa', source='aaa.c')
 env.StaticObject(target='bbb.o', source='bbb.c++')
 env.StaticObject(target='ccc.obj', source='ccc.f')
-</example_commands>
+env.StaticObject(source=Glob('*.c'))
+</programlisting>
 
 <para>
-Note that the source files will be scanned
+Source files will be scanned
 according to the suffix mappings in the
 <classname>SourceFileScanner</classname>
 object.

SCons/Tool/__init__.py

@@ -408,7 +408,7 @@ def createObjBuilders(env):
                                            suffix='$OBJSUFFIX',
                                            src_builder=['CFile', 'CXXFile'],
                                            source_scanner=SourceFileScanner,
-                                           single_source=1)
+                                           single_source=True)
         env['BUILDERS']['StaticObject'] = static_obj
         env['BUILDERS']['Object'] = static_obj
 
@@ -421,7 +421,7 @@ def createObjBuilders(env):
                                            suffix='$SHOBJSUFFIX',
                                            src_builder=['CFile', 'CXXFile'],
                                            source_scanner=SourceFileScanner,
-                                           single_source=1)
+                                           single_source=True)
         env['BUILDERS']['SharedObject'] = shared_obj
 
     return (static_obj, shared_obj)