[appveyor skip] fix ulink vs link xml syntax

5 files changed, 180 insertions, 175 deletions

diff --git a/.travis.yml b/.travis.yml
index 48ceca923..5bf578457 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -86,7 +86,7 @@ jobs:
           - python bin/docs-update-generated.py
           - python bin/docs-validate.py
           - python bin/docs-create-example-outputs.py
-          - python script/scons.py
+          - python scripts/scons.py
           - python setup.py bdist_wheel
           - python setup.py sdist --formats=gztar,zip
           - ls -l build/dist
diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
index 77f9bfbe1..94c8eff17 100644
--- a/doc/generated/builders.gen
+++ b/doc/generated/builders.gen
@@ -18,7 +18,7 @@
     <listitem><para>
 Builds a C source file given a lex (<filename>.l</filename>)
 or yacc (<filename>.y</filename>) input file.
-The suffix specified by the &cv-link-CFILESUFFIX; construction variable
+The suffix specified by the &cv-link-CFILESUFFIX; &consvar;
 (<filename>.c</filename> by default)
 is automatically added to the target
 if it is not already present.
@@ -90,7 +90,7 @@ env.CompilationDatabase('my_output.json')
 Builds a C++ source file given a lex (<filename>.ll</filename>)
 or yacc (<filename>.yy</filename>)
 input file.
-The suffix specified by the &cv-link-CXXFILESUFFIX; construction variable
+The suffix specified by the &cv-link-CXXFILESUFFIX; &consvar;
 (<filename>.cc</filename> by default)
 is automatically added to the target
 if it is not already present.
@@ -1737,18 +1737,19 @@ builder method;
 see that builder method's description for
 a list of legal source file suffixes
 and how they are interpreted.
-The target executable file prefix
-(specified by the &cv-link-PROGPREFIX; construction variable; nothing by default)
-and suffix
-(specified by the &cv-link-PROGSUFFIX; construction variable;
-by default, <filename>.exe</filename> on Windows systems,
-nothing on POSIX systems)
+The target executable file prefix,
+specified by the &cv-link-PROGPREFIX; &consvar;
+(nothing by default),
+and suffix,
+specified by the &cv-link-PROGSUFFIX; &consvar;
+(by default, <filename>.exe</filename> on Windows systems,
+nothing on POSIX systems),
 are automatically added to the target if not already present.
 Example:
 </para>
 
 <example_commands>
-env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
+env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
 </example_commands>
 </listitem>
   </varlistentry>
@@ -1925,30 +1926,28 @@ or C, C++, D or Fortran source files.
 If any source files are given,
 then they will be automatically
 compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the &cv-link-SHLIBPREFIX; construction variable;
-by default, <filename>lib</filename> on POSIX systems,
-nothing on Windows systems)
-and suffix
-(specified by the &cv-link-SHLIBSUFFIX; construction variable;
-by default, <filename>.dll</filename> on Windows systems,
-<filename>.so</filename> on POSIX systems)
+The target library file prefix,
+specified by the &cv-link-SHLIBPREFIX; &consvar;
+(by default, <filename>lib</filename> on POSIX systems,
+nothing on Windows systems),
+and suffix,
+specified by the &cv-link-SHLIBSUFFIX; &consvar;
+(by default, <filename>.dll</filename> on Windows systems,
+<filename>.so</filename> on POSIX systems),
 are automatically added to the target if not already present.
 Example:
 </para>
 
 <example_commands>
-env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
+env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
 </example_commands>
 
 <para>
 On Windows systems, the
 &b-SharedLibrary;
-builder method will always build an import
-(<filename>.lib</filename>) library
-in addition to the shared (<filename>.dll</filename>) library,
+builder method will always build an import library
+(<filename>.lib</filename>)
+in addition to the shared library (<filename>.dll</filename>),
 adding a <filename>.lib</filename> library with the same basename
 if there is not already a <filename>.lib</filename> file explicitly
 listed in the targets.
@@ -1957,9 +1956,9 @@ listed in the targets.
 <para>
 On Cygwin systems, the
 &b-SharedLibrary;
-builder method will always build an import
-(<filename>.dll.a</filename>) library
-in addition to the shared (<filename>.dll</filename>) library,
+builder method will always build an import library
+(<filename>.dll.a</filename>)
+in addition to the shared library (<filename>.dll</filename>),
 adding a <filename>.dll.a</filename> library with the same basename
 if there is not already a <filename>.dll.a</filename> file explicitly
 listed in the targets.
@@ -1967,7 +1966,7 @@ listed in the targets.
 
 <para>
 Any object files listed in the
-<literal>source</literal>
+<parameter>source</parameter>
 must have been built for a shared library
 (that is, using the
 &b-SharedObject;
@@ -1980,37 +1979,37 @@ will raise an error if there is any mismatch.
 On some platforms, there is a distinction between a shared library
 (loaded automatically by the system to resolve external references)
 and a loadable module (explicitly loaded by user action).
-For maximum portability, use the &b-LoadableModule; builder for the latter.
+For maximum portability, use the &b-link-LoadableModule; builder for the latter.
 </para>
 
 <para>
-When the &cv-link-SHLIBVERSION; construction variable is defined a versioned
-shared library is created. This modifies the &cv-link-SHLINKFLAGS; as required,
-adds the version number to the library name, and creates the symlinks that
-are needed.
+When the &cv-link-SHLIBVERSION; &consvar; is defined, a versioned
+shared library is created. This modifies &cv-link-SHLINKFLAGS; as required,
+adds the version number to the library name, and creates any
+symbolic links that are needed.
 </para>
 
 <example_commands>
-env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
+env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
 </example_commands>
 
 <para>
 On a POSIX system, versions with a single token create exactly one symlink:
-libbar.so.6 would have symlinks libbar.so only.
+<filename>libbar.so.6</filename> would have symlink <filename>libbar.so</filename> only.
 On a POSIX system, versions with two or more
-tokens create exactly two symlinks: libbar.so.2.3.1 would have symlinks
-libbar.so and libbar.so.2; on a Darwin (OSX) system the library would be
-libbar.2.3.1.dylib and the link would be libbar.dylib.
+tokens create exactly two symlinks: <filename>libbar.so.2.3.1</filename> would have symlinks
+<filename>libbar.so</filename> and <filename>libbar.so.2</filename>; on a Darwin (OSX) system the library would be
+<filename>libbar.2.3.1.dylib</filename> and the link would be <filename>libbar.dylib</filename>.
 </para>
 
 <para>
 On Windows systems, specifying
-<literal>register=1</literal>
+<parameter>register=1</parameter>
 will cause the <filename>.dll</filename> to be
-registered after it is built using REGSVR32.
-The command that is run
-("regsvr32" by default) is determined by &cv-link-REGSVR; construction
-variable, and the flags passed are determined by &cv-link-REGSVRFLAGS;.  By
+registered after it is built.
+The command that is run is determined by the &cv-link-REGSVR; &consvar;
+(<command>regsvr32</command> by default),
+and the flags passed are determined by &cv-link-REGSVRFLAGS;.  By
 default, &cv-link-REGSVRFLAGS; includes the <option>/s</option> option,
 to prevent dialogs from popping
 up and requiring user attention when it is run.  If you change
@@ -2019,9 +2018,7 @@ For example,
 </para>
 
 <example_commands>
-env.SharedLibrary(target = 'bar',
-                  source = ['bar.cxx', 'foo.obj'],
-                  register=1)
+env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
 </example_commands>
 
 <para>
@@ -2034,7 +2031,7 @@ when it is done linking it.
     <term><function>SharedObject</function>()</term>
     <term><replaceable>env</replaceable>.<methodname>SharedObject</methodname>()</term>
     <listitem><para>
-Builds an object file for
+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
@@ -2042,7 +2039,7 @@ specified above for the
 builder method.
 On some platforms building a shared object requires additional
 compiler option
-(e.g. <option>-fPIC</option> for gcc)
+(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
@@ -2052,25 +2049,25 @@ 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; construction variable;
-by default, the same as &cv-link-OBJPREFIX;)
-and suffix
-(specified by the &cv-link-SHOBJSUFFIX; construction variable)
+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.
 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(target='ddd', source='ddd.c')
+env.SharedObject(target='eee.o', source='eee.cpp')
+env.SharedObject(target='fff.obj', source='fff.for')
 </example_commands>
 
 <para>
 Note that the source files will be scanned
 according to the suffix mappings in the
-<literal>SourceFileScanner</literal>
+<classname>SourceFileScanner</classname>
 object.
 See the section "Scanner Objects,"
 below, for more information.
@@ -2086,27 +2083,25 @@ or C, C++, D or Fortran source files.
 If any source files are given,
 then they will be automatically
 compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the &cv-link-LIBPREFIX; construction variable;
-by default, <filename>lib</filename> on POSIX systems,
-nothing on Windows systems)
-and suffix
-(specified by the &cv-link-LIBSUFFIX; construction variable;
-by default, <filename>.lib</filename> on Windows systems,
-<filename>.a</filename> on POSIX systems)
+The static library file prefix,
+specified by the &cv-link-LIBPREFIX; &consvar;
+(by default, <filename>lib</filename> on POSIX systems,
+nothing on Windows systems),
+and suffix,
+specified by the &cv-link-LIBSUFFIX; &consvar;
+(by default, <filename>.lib</filename> on Windows systems,
+<filename>.a</filename> on POSIX systems),
 are automatically added to the target if not already present.
 Example:
 </para>
 
 <example_commands>
-env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
+env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
 </example_commands>
 
 <para>
 Any object files listed in the
-<literal>source</literal>
+<parameter>source</parameter>
 must have been built for a static library
 (that is, using the
 &b-StaticObject;
@@ -2157,26 +2152,27 @@ Source files must have one of the following extensions:
 </example_commands>
 
 <para>
-The target object file prefix
-(specified by the &cv-link-OBJPREFIX; construction variable; nothing by default)
-and suffix
-(specified by the &cv-link-OBJSUFFIX; construction variable;
-<filename>.obj</filename> on Windows systems,
-<filename>.o</filename> on POSIX systems)
+The target object file prefix,
+specified by the &cv-link-OBJPREFIX; &consvar;
+(nothing 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.
 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(target='aaa', source='aaa.c')
+env.StaticObject(target='bbb.o', source='bbb.c++')
+env.StaticObject(target='ccc.obj', source='ccc.f')
 </example_commands>
 
 <para>
 Note that the source files will be scanned
-according to the suffix mappings in
-<literal>SourceFileScanner</literal>
+according to the suffix mappings in the
+<classname>SourceFileScanner</classname>
 object.
 See the section "Scanner Objects,"
 below, for more information.
@@ -2187,28 +2183,35 @@ below, for more information.
     <term><function>Substfile</function>()</term>
     <term><replaceable>env</replaceable>.<methodname>Substfile</methodname>()</term>
     <listitem><para>
-The &b-Substfile; builder creates a single text file from another file or set of
-files by concatenating them with &cv-LINESEPARATOR; and replacing text
-using the &cv-SUBST_DICT; construction variable. Nested lists of source files
-are flattened. See also &b-Textfile;.
+The &b-Substfile; builder creates a single text file from
+a template consisting of a file or set of files (or nodes),
+replacing text using the &cv-link-SUBST_DICT; &consvar; (if set).
+If a set, they are concatenated into the target file
+using the value of the
+&cv-link-LINESEPARATOR; &consvar; as a separator between contents;
+the separator is not emitted after the contents of the last  file.
+Nested lists of source files
+are flattened. See also &b-link-Textfile;.
 </para>
 
 <para>
-If a single source file is present with an <filename>.in</filename> suffix,
-the suffix is stripped and the remainder is used as the default target name.
+If a single source file name is specified and has a <filename>.in</filename> suffix,
+the suffix is stripped and the remainder of the name is used as the default target name.
 </para>
 
 <para>
-The prefix and suffix specified by the &cv-SUBSTFILEPREFIX;
-and &cv-SUBSTFILESUFFIX; construction variables
+The prefix and suffix specified by the &cv-link-SUBSTFILEPREFIX;
+and &cv-link-SUBSTFILESUFFIX; &consvars;
 (an empty string by default in both cases)
 are automatically added to the target if they are not already present.
 </para>
 
 <para>
-If a construction variable named &cv-SUBST_DICT; is present,
-it may be either a Python dictionary or a sequence of (key,value) tuples.
-If it is a dictionary it is converted into a list of tuples in an arbitrary order,
+If a construction variable named &cv-link-SUBST_DICT; is present,
+it may be either a Python dictionary or a sequence of
+(<replaceable>key</replaceable>, <replaceable>value</replaceable>) tuples.
+If it is a dictionary it is converted into a list of tuples
+with unspecified order,
 so if one key is a prefix of another key
 or if one substitution could be further expanded by another subsitition,
 it is unpredictable whether the expansion will occur.
@@ -2228,42 +2231,40 @@ env = Environment(tools=['default'])
 
 env['prefix'] = '/usr/bin'
 script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'}
-env.Substfile('script.in', SUBST_DICT = script_dict)
+env.Substfile('script.in', SUBST_DICT=script_dict)
 
 conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
-env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
+env.Substfile('config.h.in', conf_dict, SUBST_DICT=conf_dict)
 
 # UNPREDICTABLE - one key is a prefix of another
 bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
-env.Substfile('foo.in', SUBST_DICT = bad_foo)
+env.Substfile('foo.in', SUBST_DICT=bad_foo)
 
 # PREDICTABLE - keys are applied longest first
 good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
-env.Substfile('foo.in', SUBST_DICT = good_foo)
+env.Substfile('foo.in', SUBST_DICT=good_foo)
 
 # UNPREDICTABLE - one substitution could be futher expanded
 bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
-env.Substfile('bar.in', SUBST_DICT = bad_bar)
+env.Substfile('bar.in', SUBST_DICT=bad_bar)
 
 # PREDICTABLE - substitutions are expanded in order
 good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
-env.Substfile('bar.in', SUBST_DICT = good_bar)
+env.Substfile('bar.in', SUBST_DICT=good_bar)
 
 # the SUBST_DICT may be in common (and not an override)
 substutions = {}
 subst = Environment(tools=['textfile'], SUBST_DICT=substitutions)
 substitutions['@foo@'] = 'foo'
 subst['SUBST_DICT']['@bar@'] = 'bar'
-subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
-                           Value('#include "@bar@.h"'),
-                           "common.in",
-                           "pgm1.in"
-                          ])
-subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
-                           Value('#include "@bar@.h"'),
-                           "common.in",
-                           "pgm2.in"
-                          ])
+subst.Substfile(
+    'pgm1.c',
+    [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm1.in"],
+)
+subst.Substfile(
+    'pgm2.c',
+    [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm2.in"],
+)
 
 </example_commands>
 </listitem>
@@ -2313,66 +2314,70 @@ env.Tar('foo')
     <term><function>Textfile</function>()</term>
     <term><replaceable>env</replaceable>.<methodname>Textfile</methodname>()</term>
     <listitem><para>
-The &b-Textfile; builder generates a single text file.
-The source strings constitute the lines;
-nested lists of sources are flattened.
-&cv-LINESEPARATOR; is used to separate the strings.
-</para>
-
-<para>
-If present, the &cv-SUBST_DICT; construction variable
-is used to modify the strings before they are written;
-see the &b-Substfile; description for details.
-</para>
-
-<para>
-The prefix and suffix specified by the &cv-TEXTFILEPREFIX;
-and &cv-TEXTFILESUFFIX; construction variables
-(an empty string and <filename>.txt</filename> by default, respectively)
+The &b-Textfile; builder generates a single text file from
+a template consisting of a list of strings, replacing text
+using the &cv-link-SUBST_DICT; &consvar; (if set) -
+see &b-link-Substfile; for a description of replacement.
+The strings will be separated in the target file using the
+value of the
+&cv-link-LINESEPARATOR; &consvar;;
+the line separator is not emitted after the last string.
+Nested lists of source strings
+are flattened.
+Source strings need not literally be Python strings:
+they can be Nodes or Python objects that convert cleanly
+to &f-link-Value; nodes
+</para>
+
+<para>
+The prefix and suffix specified by the &cv-link-TEXTFILEPREFIX;
+and &cv-link-TEXTFILESUFFIX; &consvars;
+(by default an empty string and <filename>.txt</filename>, respectively)
 are automatically added to the target if they are not already present.
 Examples:
 </para>
 
 <example_commands>
 # builds/writes foo.txt
-env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
+env.Textfile(target='foo.txt', source=['Goethe', 42, 'Schiller'])
 
 # builds/writes bar.txt
-env.Textfile(target = 'bar',
-             source = ['lalala', 'tanteratei'],
-             LINESEPARATOR='|*')
+env.Textfile(target='bar', source=['lalala', 'tanteratei'], LINESEPARATOR='|*')
 
 # nested lists are flattened automatically
-env.Textfile(target = 'blob',
-             source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
+env.Textfile(target='blob', source=['lalala', ['Goethe', 42, 'Schiller'], 'tanteratei'])
 
 # files may be used as input by wraping them in File()
-env.Textfile(target = 'concat',  # concatenate files with a marker between
-             source = [File('concat1'), File('concat2')],
-             LINESEPARATOR = '====================\n')
+env.Textfile(
+    target='concat',  # concatenate files with a marker between
+    source=[File('concat1'), File('concat2')],
+    LINESEPARATOR='====================\n',
+)
+</example_commands>
 
-Results are:
-foo.txt
-  ....8&lt;----
+<para>Results:</para>
+
+<para><filename>foo.txt</filename></para>
+<screen>
   Goethe
   42
   Schiller
-  ....8&lt;---- (no linefeed at the end)
+</screen>
 
-bar.txt:
-  ....8&lt;----
+<para><filename>bar.txt</filename></para>
+<screen>
   lalala|*tanteratei
-  ....8&lt;---- (no linefeed at the end)
+</screen>
 
-blob.txt
-  ....8&lt;----
+<para><filename>blob.txt</filename></para>
+<screen>
   lalala
   Goethe
   42
   Schiller
   tanteratei
-  ....8&lt;---- (no linefeed at the end)
-</example_commands>
+</screen>
+
 </listitem>
   </varlistentry>
   <varlistentry id="b-Translate">
diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen
index 794b55332..6353c6fb4 100644
--- a/doc/generated/tools.gen
+++ b/doc/generated/tools.gen
@@ -964,7 +964,7 @@ Sets construction variables for the TeX formatter and typesetter.
   <varlistentry id="t-textfile">
     <term>textfile</term>
     <listitem><para>
-Set construction variables for the &b-Textfile; and &b-Substfile; builders.
+Set &consvars; for the &b-Textfile; and &b-Substfile; builders.
 </para>
 <para>Sets: &cv-link-LINESEPARATOR;, &cv-link-SUBSTFILEPREFIX;, &cv-link-SUBSTFILESUFFIX;, &cv-link-TEXTFILEPREFIX;, &cv-link-TEXTFILESUFFIX;.</para><para>Uses: &cv-link-SUBST_DICT;.</para></listitem>
   </varlistentry>
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index 6f23d9861..e100939bc 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -1361,7 +1361,7 @@ PDF renderer <literal>fop</literal> or <literal>xep</literal>.
     <listitem><para>
 The path to the external executable <literal>xmllint</literal>, if it's installed.
 Note, that this is only used as last fallback for resolving
-XIncludes, if no libxml2 or lxml Python binding can be imported
+XIncludes, if no lxml Python binding can be imported
 in the current system.
 </para>
 </listitem>
@@ -1405,7 +1405,7 @@ The path to the external executable <literal>xsltproc</literal>
 (or <literal>saxon</literal>, <literal>xalan</literal>), if one of them
 is installed.
 Note, that this is only used as last fallback for XSL transformations, if
-no libxml2 or lxml Python binding can be imported in the current system.
+no lxml Python binding can be imported in the current system.
 </para>
 </listitem>
   </varlistentry>
@@ -3038,6 +3038,14 @@ is <quote><literal>-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</literal></quote>
       <envar>HOST_ARCH</envar>
     </term>
     <listitem><para>
+        The name of the host hardware architecture used to create the Environment.
+        If a platform is specified when creating the Environment, then
+        that Platform's logic will handle setting this value.
+        This value is immutable, and should not be changed by the user after
+        the Environment is initialized.
+        Currently only set for Win32.
+</para>
+    <para>
 Sets the host architecture for Visual Studio compiler. If not set,
 default to the detected host architecture: note that this may depend
 on the python you are using.
@@ -3053,15 +3061,7 @@ Valid values are the same as for &cv-TARGET_ARCH;.
 This is currently only used on Windows, but in the future it will be
 used on other OSes as well.
 </para>
-<para>
-        The name of the host hardware architecture used to create the Environment.
-        If a platform is specified when creating the Environment, then
-        that Platform's logic will handle setting this value.
-        This value is immutable, and should not be changed by the user after
-        the Environment is initialized.
-        Currently only set for Win32.
-</para>
-    </listitem>
+</listitem>
   </varlistentry>
   <varlistentry id="cv-HOST_OS">
     <term>
@@ -3810,7 +3810,7 @@ the same as $SHLIBSUFFIX.
       <envar>LDMODULEVERSION</envar>
     </term>
     <listitem><para>
-When this construction variable is defined, a versioned loadable module
+When this &consvar; is defined, a versioned loadable module
 is created by &b-link-LoadableModule; builder. This activates the
 &cv-link-_LDMODULEVERSIONFLAGS; and thus modifies the &cv-link-LDMODULECOM; as
 required, adds the version number to the library name, and creates the symlinks
@@ -4165,7 +4165,7 @@ for a list of license names and SPDX codes.
       <envar>LINESEPARATOR</envar>
     </term>
     <listitem><para>
-The separator used by the &b-Substfile; and &b-Textfile; builders.
+The separator used by the &b-link-Substfile; and &b-link-Textfile; builders.
 This value is used between sources when constructing the target.
 It defaults to the current system line separator.
 </para>
@@ -7111,7 +7111,7 @@ The suffix used for shared library file names.
       <envar>SHLIBVERSION</envar>
     </term>
     <listitem><para>
-When this construction variable is defined, a versioned shared library
+When this &consvar; is defined, a versioned shared library
 is created by the &b-link-SharedLibrary; builder. This activates the
 &cv-link-_SHLIBVERSIONFLAGS; and thus modifies the &cv-link-SHLINKCOM; as
 required, adds the version number to the library name, and creates the symlinks
@@ -7320,9 +7320,9 @@ in which the command should be executed.
       <envar>SUBST_DICT</envar>
     </term>
     <listitem><para>
-The dictionary used by the &b-Substfile; or &b-Textfile; builders
+The dictionary used by the &b-link-Substfile; or &b-link-Textfile; builders
 for substitution values.
-It can be anything acceptable to the dict() constructor,
+It can be anything acceptable to the <function>dict()</function> constructor,
 so in addition to a dictionary,
 lists of tuples are also acceptable.
 </para>
@@ -7333,7 +7333,7 @@ lists of tuples are also acceptable.
       <envar>SUBSTFILEPREFIX</envar>
     </term>
     <listitem><para>
-The prefix used for &b-Substfile; file names,
+The prefix used for &b-link-Substfile; file names,
 an empty string by default.
 </para>
 </listitem>
@@ -7343,7 +7343,7 @@ an empty string by default.
       <envar>SUBSTFILESUFFIX</envar>
     </term>
     <listitem><para>
-The suffix used for &b-Substfile; file names,
+The suffix used for &b-link-Substfile; file names,
 an empty string by default.
 </para>
 </listitem>
@@ -7651,6 +7651,12 @@ for more information).
       <envar>TARGET_ARCH</envar>
     </term>
     <listitem><para>
+        The name of the target hardware architecture for the compiled objects
+        created by this Environment.
+        This defaults to the value of HOST_ARCH, and the user can override it.
+        Currently only set for Win32.
+</para>
+    <para>
 Sets the target architecture for Visual Studio compiler (i.e. the arch
 of the binaries generated by the compiler). If not set, default to
 &cv-HOST_ARCH;, or, if that is unset, to the architecture of the
@@ -7681,13 +7687,7 @@ and <literal>ia64</literal> (Itanium).
 For example, if you want to compile 64-bit binaries, you would set
 <literal>TARGET_ARCH='x86_64'</literal> in your SCons environment.
 </para>
-<para>
-        The name of the target hardware architecture for the compiled objects
-        created by this Environment.
-        This defaults to the value of HOST_ARCH, and the user can override it.
-        Currently only set for Win32.
-</para>
-    </listitem>
+</listitem>
   </varlistentry>
   <varlistentry id="cv-TARGET_OS">
     <term>
@@ -7823,7 +7823,7 @@ directories for \include and \import files.
       <envar>TEXTFILEPREFIX</envar>
     </term>
     <listitem><para>
-The prefix used for &b-Textfile; file names,
+The prefix used for &b-link-Textfile; file names,
 an empty string by default.
 </para>
 </listitem>
@@ -7833,7 +7833,7 @@ an empty string by default.
       <envar>TEXTFILESUFFIX</envar>
     </term>
     <listitem><para>
-The suffix used for &b-Textfile; file names;
+The suffix used for &b-link-Textfile; file names;
 <filename>.txt</filename> by default.
 </para>
 </listitem>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 18e432186..70a17315f 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -7447,22 +7447,22 @@ and will silently revert to non-cached behavior in such cases.</para>
   <simplelist type="vert">
   <member>
     The SCons User Guide at
-    <ulink url="https://scons.org/doc/production/HTML/scons-user.html"/>
+    <link xlink:href="https://scons.org/doc/production/HTML/scons-user.html"/>
  </member>
   <member>The SCons Design Document (old)</member>
   <member>
     The SCons Cookbook at
-    <ulink url="https://scons-cookbook.readthedocs.io"/>
+    <link xlink:href="https://scons-cookbook.readthedocs.io"/>
     for examples of how to solve various problems with &SCons;.
   </member>
   <member>
     SCons source code
-    <ulink url="https://github.com/SCons/scons">
+    <link xlink:href="https://github.com/SCons/scons">
     on GitHub</ulink>
   </member>
   <member>
     The SCons API Reference
-    <ulink url="https://scons.org/doc/production/HTML/scons-api/index.html"/>
+    <link xlink:href="https://scons.org/doc/production/HTML/scons-api/index.html"/>
     (for internal details)
    </member>
   </simplelist>