Minor type and doc tweaks [skip appveyor]

Small changes harvested from abandoned PR SCons#4671 so they're not lost.
These changes omit the large surgery to the Builder Objects section
in doc/man/scons.xml from the PR.  The changes consist of a few doc
formatting changes, entity usage, moving one chunk of text in the
SharedObject entry down ito its own paragraph, noting when a builder is
single source, and, in the code, consistently using the single_source
builder argument as a boolean.

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

Author: mwichmann

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/EnvironmentTests.py

@@ -156,10 +156,10 @@ def TestEnvironment(self, *args, **kw):
             if key not in kw:
                 kw[key] = value
         if 'BUILDERS' not in kw:
-            static_obj = SCons.Builder.Builder(action = {},
-                                               emitter = {},
-                                               suffix = '.o',
-                                               single_source = 1)
+            static_obj = SCons.Builder.Builder(action={},
+                                               emitter={},
+                                               suffix='.o',
+                                               single_source=True)
             kw['BUILDERS'] = {'Object' : static_obj}
             static_obj.add_action('.cpp', 'fake action')
 

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

@@ -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>
 env.SharedObject(target='ddd', source='ddd.c')
 env.SharedObject(target='eee.o', source='eee.cpp')
 env.SharedObject(target='fff.obj', source='fff.for')
+env.SharedObject(source=Glob('*.c'))
 </example_commands>
 
 <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.
@@ -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>
 env.StaticObject(target='aaa', source='aaa.c')
 env.StaticObject(target='bbb.o', source='bbb.c++')
 env.StaticObject(target='ccc.obj', source='ccc.f')
+env.StaticObject(source=Glob('*.c'))
 </example_commands>
 
 <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)

doc/man/scons.xml

@@ -1130,7 +1130,7 @@ when encountering an otherwise unexplained error.</para>
 (When
 &scons;
 is executed without the
-<option>-j</option>
+<link linkend="opt-jobs"><option>-j</option></link>
 option,
 the elapsed wall-clock time will typically
 be slightly longer than the total time spent
@@ -1142,7 +1142,7 @@ When
 is executed
 <emphasis>with</emphasis>
 the
-<option>-j</option>
+<link linkend="opt-jobs"><option>-j</option></link>
 option,
 and your build configuration allows good parallelization,
 the elapsed wall-clock time should
@@ -2289,7 +2289,7 @@ which can yield unpredictable behavior with some compilers.</para>
   <varlistentry>
   <term><emphasis role="bold">future-reserved-variable</emphasis></term>
   <listitem>
-<para>Warnings about construction variables which
+<para>Warnings about &consvars; which
 are currently allowed,
 but will become reserved variables in a future release.
 </para>
@@ -2377,7 +2377,7 @@ Add another "-no" to disable.
   <listitem>
 <para>Warnings about the version of &Python;
 not being able to support parallel builds when the
-<option>-j</option>
+<link linkend="opt-jobs"><option>-j</option></link>
 option is used.
 These warnings are enabled by default.</para>
 <para>
@@ -2619,7 +2619,7 @@ settings. Otherwise, &f-env-Clone; takes the same arguments as
 &SCons; provides a special &consenv; called the
 <firstterm>&DefEnv;</firstterm>.
 The &defenv; is used only for global functions, that is,
-construction activities called without the context of a regular &consenv;.
+build requests called without the context of a regular &consenv;.
 See &f-link-DefaultEnvironment; for more information.
 </para>
 
@@ -5890,7 +5890,7 @@ Adding new Tool modules is described in
 <title>Builder Objects</title>
 
 <para>&scons;
-can be extended to build different types of targets
+can be extended to build additional types of targets
 by adding new Builder objects
 to a &consenv;.
 <emphasis>In general</emphasis>,
@@ -5899,7 +5899,7 @@ when you want to build a new type of file or other external target.
 For output file types &scons; already knows about,
 you can usually modify the behavior of premade Builders
 such as &b-link-Program;, &b-link-Object; or &b-link-Library;
-by changing the &consvars; they use
+by changing the &consvars; that control their behavior
 (&cv-link-CC;, &cv-link-LINK;, etc.).
 In this manner you can, for example, change the compiler to use,
 which is simpler and less error-prone than writing a new builder.
@@ -5911,8 +5911,8 @@ The documentation for each Builder lists which
 using the
 &f-link-Builder;
 factory function.
-Once created, a builder is added to an environment
-by entering it in the &cv-link-BUILDERS; dictionary
+Once created, a builder is added to a &consenv;
+by registering it in the &cv-link-BUILDERS; dictionary
 in that environment (some of the examples
 in this section illustrate this).
 Doing so automatically triggers &SCons; to add a method
@@ -6445,16 +6445,14 @@ env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
 
 <warning>
 <para>
-&Python; only keeps one current directory
-location even if there are multiple threads.
+&Python; only tracks one current directory location,
+even if there are multiple executing threads.
 This means that use of the
 <parameter>chdir</parameter>
-argument
-will
+argument will
 <emphasis>not</emphasis>
-work with the SCons
-<option>-j</option>
-option,
+work with &SCons; in multi-threaded mode
+(the <link linkend="opt-jobs"><option>-j</option></link> option),
 because individual worker threads spawned
 by SCons interfere with each other
 when they start changing directory.</para>
@@ -6466,8 +6464,8 @@ when they start changing directory.</para>
 <para>Any additional keyword arguments supplied
 when a Builder object is created
 (that is, when the &f-link-Builder; function is called)
-will be set in the executing construction
-environment when the Builder object is called.
+will be set in the executing &consenv;
+when the Builder object is called.
 The canonical example here would be
 to set a &consvar; to
 the repository of a source code system.</para>
@@ -6629,7 +6627,7 @@ will expand &consvars; in any argument strings,
 including
 <parameter>action</parameter>,
 at the time it is called,
-using the construction variables in the &consenv; through which
+using the &consvars; in the &consenv; through which
 it was called. The global function form &f-link-Action;
 delays variable expansion until
 the Action object is actually used.