Merge branch 'master' into AddOption-shortopts

11 files changed, 367 insertions, 345 deletions

diff --git a/SCons/EnvironmentTests.py b/SCons/EnvironmentTests.py
index 6a69e3c..361dda9 100644
--- a/SCons/EnvironmentTests.py
+++ b/SCons/EnvironmentTests.py
@@ -1037,7 +1037,8 @@ class BaseTestCase(unittest.TestCase,TestEnvironmentFixture):
     # underlying method it tests (Environment.BuilderWrapper.execute())
     # is necessary, but we're leaving the code here for now in case
     # that's mistaken.
-    def _DO_NOT_test_Builder_execs(self) -> None:
+    @unittest.skip("BuilderWrapper.execute method not needed")
+    def test_Builder_execs(self) -> None:
         """Test Builder execution through different environments
 
         One environment is initialized with a single
@@ -1291,10 +1292,14 @@ env4.builder1.env, env3)
         ]
         assert flags == expect, flags
 
-        env.Replace(F77PATH = [ 'foo', '$FOO/bar', blat ],
-                    INCPREFIX = 'foo ',
-                    INCSUFFIX = 'bar',
-                    FOO = 'baz')
+        # do a Replace using the dict form
+        newvalues = {
+            "F77PATH": ['foo', '$FOO/bar', blat],
+            "INCPREFIX": 'foo ',
+            "INCSUFFIX": 'bar',
+            "FOO": 'baz',
+        }
+        env.Replace(**newvalues)
         flags = env.subst_list('$_F77INCFLAGS', 1)[0]
         expect = [ '$(',
                    normalize_path('foo'),
diff --git a/SCons/Subst.xml b/SCons/Subst.xml
index 00ed135..4ac4f7d 100644
--- a/SCons/Subst.xml
+++ b/SCons/Subst.xml
@@ -31,16 +31,16 @@ This file is processed by the bin/SConsDoc.py module.
 </arguments>
 <summary>
 <para>
-Specifies the exceptions that will be allowed
-when expanding construction variables.
+Specifies the exceptions that will be ignored
+when expanding &consvars;.
 By default,
-any construction variable expansions that generate a
-<literal>NameError</literal>
+any &consvar; expansions that generate a
+&NameError;
 or
-<literal>IndexError</literal>
+&IndexError;
 exception will expand to a
 <literal>''</literal>
-(an empty string) and not cause scons to fail.
+(an empty string) and not cause &scons; to fail.
 All exceptions not in the specified list
 will generate an error message
 and terminate processing.
@@ -51,7 +51,8 @@ If
 &f-AllowSubstExceptions;
 is called multiple times,
 each call completely overwrites the previous list
-of allowed exceptions.
+of ignored exceptions.
+Calling it with no arguments means no exceptions will be ignored.
 </para>
 
 <para>
diff --git a/SCons/Tool/__init__.py b/SCons/Tool/__init__.py
index 474414e..faa92a7 100644
--- a/SCons/Tool/__init__.py
+++ b/SCons/Tool/__init__.py
@@ -691,8 +691,8 @@ def tool_list(platform, env):
     if str(platform) == 'win32':
         "prefer Microsoft tools on Windows"
         linkers = ['mslink', 'gnulink', 'ilink', 'linkloc', 'ilink32']
-        c_compilers = ['msvc', 'mingw', 'gcc', 'intelc', 'icl', 'icc', 'cc', 'bcc32']
-        cxx_compilers = ['msvc', 'intelc', 'icc', 'g++', 'cxx', 'bcc32']
+        c_compilers = ['msvc', 'mingw', 'gcc', 'clang', 'intelc', 'icl', 'icc', 'cc', 'bcc32']
+        cxx_compilers = ['msvc', 'intelc', 'icc', 'g++', 'clang++', 'cxx', 'bcc32']
         assemblers = ['masm', 'nasm', 'gas', '386asm']
         fortran_compilers = ['gfortran', 'g77', 'ifl', 'cvf', 'f95', 'f90', 'fortran']
         ars = ['mslib', 'ar', 'tlib']
@@ -757,8 +757,8 @@ def tool_list(platform, env):
     else:
         "prefer GNU tools on all other platforms"
         linkers = ['gnulink', 'ilink']
-        c_compilers = ['gcc', 'intelc', 'icc', 'cc']
-        cxx_compilers = ['g++', 'intelc', 'icc', 'cxx']
+        c_compilers = ['gcc', 'clang', 'intelc', 'icc', 'cc']
+        cxx_compilers = ['g++', 'clang++', 'intelc', 'icc', 'cxx']
         assemblers = ['gas', 'nasm', 'masm']
         fortran_compilers = ['gfortran', 'g77', 'ifort', 'ifl', 'f95', 'f90', 'f77']
         ars = ['ar', ]
diff --git a/SCons/Tool/compilation_db.py b/SCons/Tool/compilation_db.py
index e17b5dc..2b1bfb5 100644
--- a/SCons/Tool/compilation_db.py
+++ b/SCons/Tool/compilation_db.py
@@ -43,6 +43,8 @@ from .cxx import CXXSuffixes
 from .cc import CSuffixes
 from .asm import ASSuffixes, ASPPSuffixes
 
+DEFAULT_DB_NAME = 'compile_commands.json'
+
 # TODO: Is there a better way to do this than this global? Right now this exists so that the
 # emitter we add can record all of the things it emits, so that the scanner for the top level
 # compilation database can access the complete list, and also so that the writer has easy
@@ -189,9 +191,8 @@ def compilation_db_emitter(target, source, env):
     if not target and len(source) == 1:
         target = source
 
-    # Default target name is compilation_db.json
     if not target:
-        target = ['compile_commands.json', ]
+        target = [DEFAULT_DB_NAME]
 
     # No source should have been passed. Drop it.
     if source:
@@ -224,13 +225,17 @@ def generate(env, **kwargs) -> None:
         ),
         itertools.product(
             ASSuffixes,
-            [(static_obj, SCons.Defaults.StaticObjectEmitter, "$ASCOM")],
-            [(shared_obj, SCons.Defaults.SharedObjectEmitter, "$ASCOM")],
+            [
+                (static_obj, SCons.Defaults.StaticObjectEmitter, "$ASCOM"),
+                (shared_obj, SCons.Defaults.SharedObjectEmitter, "$ASCOM")
+            ],
         ),
         itertools.product(
             ASPPSuffixes,
-            [(static_obj, SCons.Defaults.StaticObjectEmitter, "$ASPPCOM")],
-            [(shared_obj, SCons.Defaults.SharedObjectEmitter, "$ASPPCOM")],
+            [
+                (static_obj, SCons.Defaults.StaticObjectEmitter, "$ASPPCOM"),
+                (shared_obj, SCons.Defaults.SharedObjectEmitter, "$ASPPCOM")
+            ],
         ),
     )
 
diff --git a/SCons/Tool/dvips.xml b/SCons/Tool/dvips.xml
index 4df22ef..d8a69e8 100644
--- a/SCons/Tool/dvips.xml
+++ b/SCons/Tool/dvips.xml
@@ -54,15 +54,17 @@ or
 The suffix specified by the &cv-link-PSSUFFIX; construction variable
 (<filename>.ps</filename> by default)
 is added automatically to the target
-if it is not already present.  Example:
+if it is not already present.
+&b-PostScript; is a single-source builder.
+Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 # builds from aaa.tex
 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
 # builds bbb.ps from bbb.dvi
 env.PostScript(target = 'bbb', source = 'bbb.dvi')
-</example_commands>
+</programlisting>
 </summary>
 </builder>
 
diff --git a/SCons/Tool/gettext.xml b/SCons/Tool/gettext.xml
index 1606129..4b3eb12 100644
--- a/SCons/Tool/gettext.xml
+++ b/SCons/Tool/gettext.xml
@@ -27,33 +27,33 @@ This file is processed by the bin/SConsDoc.py module.
 <tool name="gettext">
 <summary>
 <para>
-This is actually a toolset, which supports internationalization and
-localization of software being constructed with SCons. The toolset loads
-following tools:
+A toolset supporting internationalization and
+localization of software being constructed with &SCons;.
+The toolset loads the following tools:
 </para>
 
 <para>
 <itemizedlist mark='opencircle'>
   <listitem><para>
-    &t-link-xgettext; - to extract internationalized messages from source code to
-    <literal>POT</literal> file(s),
+    &t-link-xgettext; - extract internationalized messages from source code to
+    <literal>POT</literal> file(s).
   </para></listitem>
   <listitem><para>
-    &t-link-msginit; - may be optionally used to initialize <literal>PO</literal>
-    files,
+    &t-link-msginit; - initialize <literal>PO</literal>
+    files during initial translation of a project.
   </para></listitem>
   <listitem><para>
-    &t-link-msgmerge; - to update <literal>PO</literal> files, that already contain
+    &t-link-msgmerge; - update <literal>PO</literal> files that already contain
     translated messages,</para></listitem>
   <listitem><para>
-    &t-link-msgfmt; - to compile textual <literal>PO</literal> file to binary
-    installable <literal>MO</literal> file.
+    &t-link-msgfmt; - compile textual <literal>PO</literal> files to binary
+    installable <literal>MO</literal> files.
   </para></listitem>
 </itemizedlist>
 </para>
 
 <para>
-When you enable &t-gettext;, it internally loads all abovementioned tools,
+When you enable &t-gettext;, it internally loads all the above-mentioned tools,
 so you're encouraged to see their individual documentation.
 </para>
 
@@ -65,12 +65,12 @@ may be however interested in <emphasis>top-level</emphasis>
 </para>
 
 <para>
-To use &t-gettext; tools add <literal>'gettext'</literal> tool to your
-environment:
+To use the &t-gettext; tools, add the <literal>'gettext'</literal> tool to your
+&consenv;:
 </para>
-<example_commands>
-  env = Environment( tools = ['default', 'gettext'] )
-</example_commands>
+<programlisting language="python">
+env = Environment(tools=['default', 'gettext'])
+</programlisting>
 </summary>
 <sets>
 </sets>
@@ -82,54 +82,56 @@ environment:
 <builder name="Translate">
 <summary>
 <para>
-This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts
-internationalized messages from source files, updates <literal>POT</literal>
-template (if necessary) and then updates <literal>PO</literal> translations (if
-necessary). If &cv-link-POAUTOINIT; is set, missing <literal>PO</literal> files
+This pseudo-Builder is part of the &t-link-gettext; toolset.
+The builder extracts internationalized messages from source files,
+updates the <literal>POT</literal> template (if necessary)
+and then updates <literal>PO</literal> translations (if necessary).
+If &cv-link-POAUTOINIT; is set, missing <literal>PO</literal> files
 will be automatically created (i.e. without translator person intervention).
 The variables &cv-link-LINGUAS_FILE; and &cv-link-POTDOMAIN; are taken into
-acount too. All other construction variables used by &b-link-POTUpdate;, and
+account too. All other construction variables used by &b-link-POTUpdate;, and
 &b-link-POUpdate; work here too.
 </para>
 
 <para>
 <emphasis>Example 1</emphasis>.
 The simplest way is to specify input files and output languages inline in
-a SCons script when invoking &b-Translate;
+a SCons script when invoking &b-Translate;:
 </para>
-<example_commands>
+<programlisting language="python">
 # SConscript in 'po/' directory
-env = Environment( tools = ["default", "gettext"] )
-env['POAUTOINIT'] = 1
-env.Translate(['en','pl'], ['../a.cpp','../b.cpp'])
-</example_commands>
+env = Environment(tools=["default", "gettext"])
+env['POAUTOINIT'] = True
+env.Translate(['en', 'pl'], ['../a.cpp', '../b.cpp'])
+</programlisting>
 
 <para>
 <emphasis>Example 2</emphasis>.
-If you wish, you may also stick to conventional style known from
+If you wish, you may also stick to the conventional style known from
 <productname>autotools</productname>, i.e. using
 <filename>POTFILES.in</filename> and <filename>LINGUAS</filename> files
+to specify the targets and sources:
 </para>
-<example_commands>
+<programlisting language="python">
 # LINGUAS
 en pl
-#end
-</example_commands>
+# end
+</programlisting>
 
-<example_commands>
+<programlisting>
 # POTFILES.in
 a.cpp
 b.cpp
 # end
-</example_commands>
+</programlisting>
 
-<example_commands>
+<programlisting language="python">
 # SConscript
-env = Environment( tools = ["default", "gettext"] )
-env['POAUTOINIT'] = 1
+env = Environment(tools=["default", "gettext"])
+env['POAUTOINIT'] = True
 env['XGETTEXTPATH'] = ['../']
-env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
-</example_commands>
+env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in')
+</programlisting>
 
 <para>
 The last approach is perhaps the recommended one. It allows easily split
@@ -142,7 +144,7 @@ factor" synchronizing these two scripts is then the content of
 <filename>LINGUAS</filename> file.  Note, that the updated
 <literal>POT</literal> and <literal>PO</literal> files are usually going to be
 committed back to the repository, so they must be updated within the source
-directory (and not in variant directories). Additionaly, the file listing of
+directory (and not in variant directories). Additionally, the file listing of
 <filename>po/</filename> directory contains <filename>LINGUAS</filename> file,
 so the source tree looks familiar to translators, and they may work with the
 project in their usual way.
@@ -152,7 +154,7 @@ project in their usual way.
 <emphasis>Example 3</emphasis>.
 Let's prepare a development tree as below
 </para>
-<example_commands>
+<programlisting>
  project/
   + SConstruct
   + build/
@@ -162,52 +164,55 @@ Let's prepare a development tree as below
           + SConscript.i18n
           + POTFILES.in
           + LINGUAS
-</example_commands>
+</programlisting>
 <para>
-with <filename>build</filename> being variant directory. Write the top-level
+with <filename>build</filename> being the variant directory.
+Write the top-level
 <filename>SConstruct</filename> script as follows
 </para>
-<example_commands>
-  # SConstruct
-  env = Environment( tools = ["default", "gettext"] )
-  VariantDir('build', 'src', duplicate = 0)
-  env['POAUTOINIT'] = 1
-  SConscript('src/po/SConscript.i18n', exports = 'env')
-  SConscript('build/po/SConscript', exports = 'env')
-</example_commands>
+<programlisting language="python">
+# SConstruct
+env = Environment(tools=["default", "gettext"])
+VariantDir('build', 'src', duplicate=False)
+env['POAUTOINIT'] = True
+SConscript('src/po/SConscript.i18n', exports='env')
+SConscript('build/po/SConscript', exports='env')
+</programlisting>
 <para>
 the <filename>src/po/SConscript.i18n</filename> as
 </para>
-<example_commands>
-  # src/po/SConscript.i18n
-  Import('env')
-  env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
-</example_commands>
+<programlisting language="python">
+# src/po/SConscript.i18n
+Import('env')
+env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
+</programlisting>
 <para>
 and the <filename>src/po/SConscript</filename>
 </para>
-<example_commands>
-  # src/po/SConscript
-  Import('env')
-  env.MOFiles(LINGUAS_FILE = 1)
-</example_commands>
+<programlisting language="python">
+# src/po/SConscript
+Import('env')
+env.MOFiles(LINGUAS_FILE=True)
+</programlisting>
 <para>
-Such setup produces <literal>POT</literal> and <literal>PO</literal> files
-under source tree in <filename>src/po/</filename> and binary
-<literal>MO</literal> files under variant tree in
+Such a setup produces <literal>POT</literal> and <literal>PO</literal> files
+under the source tree in <filename>src/po/</filename> and binary
+<literal>MO</literal> files under the variant tree in
 <filename>build/po/</filename>. This way the <literal>POT</literal> and
 <literal>PO</literal> files are separated from other output files, which must
 not be committed back to source repositories (e.g. <literal>MO</literal>
 files).
 </para>
 
-<para>
-<note><para>In above example, the <literal>PO</literal> files are not updated,
-nor created automatically when you issue <command>scons '.'</command> command.
-The files must be updated (created) by hand via <command>scons
-po-update</command> and then <literal>MO</literal> files can be compiled by
-running <command>scons '.'</command>.</para></note>
-</para>
+<note><para>In the above example,
+the <literal>PO</literal> files are not updated,
+nor created automatically when you issue the command
+<userinput>scons .</userinput>.
+The files must be updated (created) by hand via
+<userinput>scons po-update</userinput>
+and then <literal>MO</literal> files can be compiled by
+running <userinput>scons .</userinput>.
+</para></note>
 
 </summary>
 </builder>
@@ -245,10 +250,10 @@ them).
 The &cv-LINGUAS_FILE; defines file(s) containing list of additional linguas
 to be processed by &b-link-POInit;, &b-link-POUpdate; or &b-link-MOFiles;
 builders. It also affects &b-link-Translate; builder. If the variable contains
-a string, it defines name of the list file. The &cv-LINGUAS_FILE; may be a
+a string, it defines the name of the list file. The &cv-LINGUAS_FILE; may be a
 list of file names as well. If &cv-LINGUAS_FILE; is set to
-<literal>True</literal> (or non-zero numeric value), the list will be read from
-default file named
+a non-string truthy value, the list will be read from
+the file named
 <filename>LINGUAS</filename>.
 </para>
 
diff --git a/SCons/Tool/msgfmt.xml b/SCons/Tool/msgfmt.xml
index e56c12c..f92830f 100644
--- a/SCons/Tool/msgfmt.xml
+++ b/SCons/Tool/msgfmt.xml
@@ -27,10 +27,13 @@ This file is processed by the bin/SConsDoc.py module.
 <tool name="msgfmt">
 <summary>
 <para>
-This scons tool is a part of scons &t-link-gettext; toolset. It provides scons
-interface to <command>msgfmt(1)</command> command, which generates binary
-message catalog (<literal>MO</literal>) from a textual translation description
-(<literal>PO</literal>).
+This tool is a part of the &t-link-gettext; toolset.
+It provides &SCons;
+an interface to the <command>msgfmt(1)</command> command
+by setting up the &b-link-MOFiles; builder,
+which generates binary message catalog (<literal>MO</literal>) files
+from a textual translation description
+(<literal>PO</literal> files).
 </para>
 </summary>
 <sets>
@@ -49,8 +52,12 @@ message catalog (<literal>MO</literal>) from a textual translation description
 <builder name="MOFiles">
 <summary>
 <para>
-This builder belongs to &t-link-msgfmt; tool. The builder compiles
+This builder is set up by the &t-link-msgfmt; tool.
+The builder compiles
 <literal>PO</literal> files to <literal>MO</literal> files.
+&b-MOFiles; is a single-source builder.
+The <parameter>source</parameter> parameter
+can also be omitted if &cv-link-LINGUAS_FILE; is set.
 </para>
 
 <para>
@@ -58,19 +65,17 @@ This builder belongs to &t-link-msgfmt; tool. The builder compiles
 Create <filename>pl.mo</filename> and <filename>en.mo</filename> by compiling
 <filename>pl.po</filename> and <filename>en.po</filename>:
 </para>
-<example_commands>
-  # ...
-  env.MOFiles(['pl', 'en'])
-</example_commands>
+<programlisting language="python">
+env.MOFiles(['pl', 'en'])
+</programlisting>
 
 <para>
 <emphasis>Example 2</emphasis>.
 Compile files for languages defined in <filename>LINGUAS</filename> file:
 </para>
-<example_commands>
-  # ...
-  env.MOFiles(LINGUAS_FILE = 1)
-</example_commands>
+<programlisting language="python">
+env.MOFiles(LINGUAS_FILE=True)
+</programlisting>
 
 <para>
 <emphasis>Example 3</emphasis>.
@@ -78,24 +83,22 @@ Create <filename>pl.mo</filename> and <filename>en.mo</filename> by compiling
 <filename>pl.po</filename> and <filename>en.po</filename> plus files for
 languages defined in <filename>LINGUAS</filename> file:
 </para>
-<example_commands>
-  # ...
-  env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
-</example_commands>
+<programlisting language="python">
+env.MOFiles(['pl', 'en'], LINGUAS_FILE=True)
+</programlisting>
 
 <para>
 <emphasis>Example 4</emphasis>.
 Compile files for languages defined in <filename>LINGUAS</filename> file
 (another version):
 </para>
-<example_commands>
-  # ...
-  env['LINGUAS_FILE'] = 1
-  env.MOFiles()
-</example_commands>
+<programlisting language="python">
+env['LINGUAS_FILE'] = True
+env.MOFiles()
+</programlisting>
 </summary>
 </builder>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MOSUFFIX">
 <summary>
 <para>
@@ -104,7 +107,7 @@ See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGFMT">
 <summary>
 <para>
@@ -114,7 +117,7 @@ See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGFMTCOM">
 <summary>
 <para>
@@ -123,7 +126,7 @@ See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGFMTCOMSTR">
 <summary>
 <para>
@@ -133,7 +136,7 @@ See &t-link-msgfmt; tool and &b-link-MOFiles; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGFMTFLAGS">
 <summary>
 <para>
diff --git a/SCons/Tool/msginit.xml b/SCons/Tool/msginit.xml
index 667ed54..225074d 100644
--- a/SCons/Tool/msginit.xml
+++ b/SCons/Tool/msginit.xml
@@ -27,10 +27,12 @@ This file is processed by the bin/SConsDoc.py module.
 <tool name="msginit">
 <summary>
 <para>
-This scons tool is a part of scons &t-link-gettext; toolset. It provides
-scons interface to <command>msginit(1)</command> program, which creates new
+This tool is a part of scons &t-link-gettext; toolset. It provides
+&SCons; an interface to the <command>msginit(1)</command> program,
+by setting up the &b-link-POInit; builder,
+which creates a new
 <literal>PO</literal> file, initializing the meta information with values from
-user's environment (or options).
+the &consenv; (or options).
 </para>
 </summary>
 <sets>
@@ -54,26 +56,31 @@ user's environment (or options).
 <builder name="POInit">
 <summary>
 <para>
-This builder belongs to &t-link-msginit; tool. The builder initializes missing
-<literal>PO</literal> file(s) if &cv-link-POAUTOINIT; is set.  If
-&cv-link-POAUTOINIT; is not set (default), &b-POInit; prints instruction for
-user (that is supposed to be a translator), telling how the
-<literal>PO</literal> file should be initialized. In normal projects
+This builder is set up by the &t-link-msginit; tool.
+The builder initializes missing
+<literal>PO</literal> file(s) if &cv-link-POAUTOINIT; is set.
+If &cv-link-POAUTOINIT; is not set (the default),
+&b-POInit; prints instruction for the user (such as a translator),
+telling how the <literal>PO</literal> file should be initialized.
+In normal projects
 <emphasis>you should not use &b-POInit; and use &b-link-POUpdate;
 instead</emphasis>. &b-link-POUpdate; chooses intelligently between
 <command>msgmerge(1)</command> and <command>msginit(1)</command>. &b-POInit;
 always uses <command>msginit(1)</command> and should be regarded as builder for
 special purposes or for temporary use (e.g. for quick, one time initialization
 of a bunch of <literal>PO</literal> files) or for tests.
+&b-POInit; is a single-source builder.
+The <parameter>source</parameter> parameter
+can also be omitted if &cv-link-LINGUAS_FILE; is set.
 </para>
 
 <para>
 Target nodes defined through &b-POInit; are not built by default (they're
 <literal>Ignore</literal>d from <literal>'.'</literal> node) but are added to
-special <literal>Alias</literal> (<literal>'po-create'</literal> by default).
+special &f-link-Alias; (<literal>'po-create'</literal> by default).
 The alias name may be changed through the &cv-link-POCREATE_ALIAS;
-construction variable. All <literal>PO</literal> files defined through
-&b-POInit; may be easily initialized by <command>scons po-create</command>.
+&consvar;. All <literal>PO</literal> files defined through
+&b-POInit; may be easily initialized by <userinput>scons po-create</userinput>.
 </para>
 
 <para>
@@ -81,31 +88,27 @@ construction variable. All <literal>PO</literal> files defined through
 Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
 <filename>messages.pot</filename>:
 </para>
-<example_commands>
-  # ...
-  env.POInit(['en', 'pl']) # messages.pot --&gt; [en.po, pl.po]
-</example_commands>
+<programlisting language="python">
+env.POInit(['en', 'pl']) # messages.pot --&gt; [en.po, pl.po]
+</programlisting>
 
 <para>
 <emphasis>Example 2</emphasis>.
 Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
 <filename>foo.pot</filename>:
 </para>
-<example_commands>
-  # ...
-  env.POInit(['en', 'pl'], ['foo']) # foo.pot --&gt; [en.po, pl.po]
-</example_commands>
+<programlisting language="python">
+env.POInit(['en', 'pl'], ['foo']) # foo.pot --&gt; [en.po, pl.po]
+</programlisting>
 
 <para>
 <emphasis>Example 3</emphasis>.
 Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
-<filename>foo.pot</filename> but using &cv-link-POTDOMAIN; construction
-variable:
+<filename>foo.pot</filename> but using the &cv-link-POTDOMAIN; &consvar;:
 </para>
-<example_commands>
-  # ...
-  env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --&gt; [en.po, pl.po]
-</example_commands>
+<programlisting language="python">
+env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --&gt; [en.po, pl.po]
+</programlisting>
 
 <para>
 <emphasis>Example 4</emphasis>.
@@ -113,10 +116,9 @@ Initialize <literal>PO</literal> files for languages defined in
 <filename>LINGUAS</filename> file. The files will be initialized from template
 <filename>messages.pot</filename>:
 </para>
-<example_commands>
-  # ...
-  env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
-</example_commands>
+<programlisting language="python">
+env.POInit(LINGUAS_FILE=True)  # needs 'LINGUAS' file
+</programlisting>
 
 <para>
 <emphasis>Example 5</emphasis>.
@@ -125,34 +127,30 @@ Initialize <filename>en.po</filename> and <filename>pl.pl</filename>
 <filename>LINGUAS</filename> file. The files will be initialized from template
 <filename>messages.pot</filename>:
 </para>
-<example_commands>
-  # ...
-  env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
-</example_commands>
+<programlisting language="python">
+env.POInit(['en', 'pl'], LINGUAS_FILE=True)
+</programlisting>
 
 <para>
 <emphasis>Example 6</emphasis>.
 You may preconfigure your environment first, and then initialize
 <literal>PO</literal> files:
 </para>
-<example_commands>
-  # ...
-  env['POAUTOINIT'] = 1
-  env['LINGUAS_FILE'] = 1
-  env['POTDOMAIN'] = 'foo'
-  env.POInit()
-</example_commands>
+<programlisting language="python">
+env['POAUTOINIT'] = True
+env['LINGUAS_FILE'] = True
+env['POTDOMAIN'] = 'foo'
+env.POInit()
+</programlisting>
 <para>
 which has same efect as:
 </para>
-<example_commands>
-  # ...
-  env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
-</example_commands>
+<programlisting language="python">
+env.POInit(POAUTOINIT=True, LINGUAS_FILE=True, POTDOMAIN='foo')
+</programlisting>
 </summary>
 </builder>
 
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="POCREATE_ALIAS">
 <summary>
 <para>
@@ -162,7 +160,7 @@ See &t-link-msginit; tool and &b-link-POInit; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="POSUFFIX">
 <summary>
 <para>
@@ -171,17 +169,17 @@ See &t-link-msginit; tool and &b-link-POInit; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGINIT">
 <summary>
 <para>
 Path to <command>msginit(1)</command> program (found via
-<literal>Detect()</literal>).
+&f-link-Detect;).
 See &t-link-msginit; tool and &b-link-POInit; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGINITCOM">
 <summary>
 <para>
@@ -190,17 +188,18 @@ See &t-link-msginit; tool and &b-link-POInit; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGINITCOMSTR">
 <summary>
 <para>
-String to display when <command>msginit(1)</command> is invoked
-(default: <literal>''</literal>, which means ``print &cv-link-MSGINITCOM;'').
+String to display when <command>msginit(1)</command> is invoked.
+The default is an empty string,
+which will print the command line (&cv-link-MSGINITCOM;).
 See &t-link-msginit; tool and &b-link-POInit; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGINITFLAGS">
 <summary>
 <para>
@@ -210,7 +209,7 @@ See &t-link-msginit; tool and &b-link-POInit; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="_MSGINITLOCALE">
 <summary>
 <para>
diff --git a/SCons/Tool/msgmerge.xml b/SCons/Tool/msgmerge.xml
index 1f0437c..f318d47 100644
--- a/SCons/Tool/msgmerge.xml
+++ b/SCons/Tool/msgmerge.xml
@@ -27,8 +27,10 @@ This file is processed by the bin/SConsDoc.py module.
 <tool name="msgmerge">
 <summary>
 <para>
-This scons tool is a part of scons &t-link-gettext; toolset. It provides
-scons interface to <command>msgmerge(1)</command> command, which merges two
+This tool is a part of scons &t-link-gettext; toolset. It provides
+&SCons; an interface to the <command>msgmerge(1)</command> command,
+by setting up the &b-link-POUpdate; builder,
+which merges two
 Uniform style <filename>.po</filename> files together.
 </para>
 </summary>
@@ -51,23 +53,29 @@ Uniform style <filename>.po</filename> files together.
 <builder name="POUpdate">
 <summary>
 <para>
-The builder belongs to &t-link-msgmerge; tool. The builder updates
+The builder is set up by the &t-link-msgmerge; tool.
+part of the &t-link-gettext; toolset.
+The builder updates
 <literal>PO</literal> files with <command>msgmerge(1)</command>, or initializes
-missing <literal>PO</literal> files as described in documentation of
-&t-link-msginit; tool and &b-link-POInit; builder (see also
-&cv-link-POAUTOINIT;). Note, that &b-POUpdate; <emphasis>does not add its
-targets to <literal>po-create</literal> alias</emphasis> as &b-link-POInit;
-does.
+missing <literal>PO</literal> files as described in the documentation of the
+&t-link-msginit; tool and the &b-link-POInit; builder (see also
+&cv-link-POAUTOINIT;).
+&b-POUpdate; is a single-source builder.
+The <parameter>source</parameter> parameter
+can also be omitted if &cv-link-LINGUAS_FILE; is set.
 </para>
 
 <para>
-Target nodes defined through &b-POUpdate; are not built by default
-(they're <literal>Ignore</literal>d from <literal>'.'</literal> node). Instead,
-they are added automatically to special <literal>Alias</literal>
+The target nodes are <emphasis>not</emphasis>
+selected for building by default (e.g. <userinput>scons .</userinput>).
+Instead, they are added automatically to special &f-link-Alias;
 (<literal>'po-update'</literal> by default). The alias name may be changed
-through the &cv-link-POUPDATE_ALIAS; construction variable.  You can easily
-update <literal>PO</literal> files in your project by <command>scons
-po-update</command>.
+through the &cv-link-POUPDATE_ALIAS; &consvar;.  You can easily
+update <literal>PO</literal> files in your project by
+<userinput>scons po-update</userinput>.
+Note that &b-POUpdate; does not add its
+targets to the <literal>po-create</literal> alias as &b-link-POInit;
+does.
 </para>
 
 <para>
@@ -77,49 +85,44 @@ Update <filename>en.po</filename> and <filename>pl.po</filename> from
 assuming that the later one exists or there is rule to build it (see
 &b-link-POTUpdate;):
 </para>
-<example_commands>
-  # ...
-  env.POUpdate(['en','pl']) # messages.pot --&gt; [en.po, pl.po]
-</example_commands>
+<programlisting language="python">
+env.POUpdate(['en','pl'])  # messages.pot --&gt; [en.po, pl.po]
+</programlisting>
 
 <para>
 <emphasis>Example 2.</emphasis>
 Update <filename>en.po</filename> and <filename>pl.po</filename> from
 <filename>foo.pot</filename> template:
 </para>
-<example_commands>
-  # ...
-  env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --&gt;  [en.po, pl.pl]
-</example_commands>
+<programlisting language="python">
+env.POUpdate(['en', 'pl'], ['foo'])  # foo.pot --&gt;  [en.po, pl.pl]
+</programlisting>
 
 <para>
 <emphasis>Example 3.</emphasis>
 Update <filename>en.po</filename> and <filename>pl.po</filename> from
 <filename>foo.pot</filename> (another version):
 </para>
-<example_commands>
-  # ...
-  env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- &gt; [en.po, pl.pl]
-</example_commands>
+<programlisting language="python">
+env.POUpdate(['en', 'pl'], POTDOMAIN='foo')  # foo.pot -- &gt; [en.po, pl.pl]
+</programlisting>
 
 <para>
 <emphasis>Example 4.</emphasis>
 Update files for languages defined in <filename>LINGUAS</filename> file. The
 files are updated from <filename>messages.pot</filename> template:
 </para>
-<example_commands>
-  # ...
-  env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
-</example_commands>
+<programlisting language="python">
+env.POUpdate(LINGUAS_FILE=True)  # needs 'LINGUAS' file
+</programlisting>
 
 <para>
 <emphasis>Example 5.</emphasis>
 Same as above, but update from <filename>foo.pot</filename> template:
 </para>
-<example_commands>
-  # ...
-  env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
-</example_commands>
+<programlisting language="python">
+env.POUpdate(LINGUAS_FILE=True, source=['foo'])
+</programlisting>
 
 <para>
 <emphasis>Example 6.</emphasis>
@@ -127,20 +130,19 @@ Update <filename>en.po</filename> and <filename>pl.po</filename> plus files for
 languages defined in <filename>LINGUAS</filename> file. The files are updated
 from <filename>messages.pot</filename> template:
 </para>
-<example_commands>
-  # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
-  env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
-</example_commands>
+<programlisting language="python">
+# produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
+env.POUpdate(['en', 'pl' ], LINGUAS_FILE=True)
+</programlisting>
 
 <para>
 <emphasis>Example 7.</emphasis>
 Use &cv-link-POAUTOINIT; to automatically initialize <literal>PO</literal> file
 if it doesn't exist:
 </para>
-<example_commands>
-  # ...
-  env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
-</example_commands>
+<programlisting language="python">
+env.POUpdate(LINGUAS_FILE=True, POAUTOINIT=True)
+</programlisting>
 
 <para>
 <emphasis>Example 8.</emphasis>
@@ -149,18 +151,16 @@ Update <literal>PO</literal> files for languages defined in
 <filename>foo.pot</filename> template. All necessary settings are
 pre-configured via environment.
 </para>
-<example_commands>
-  # ...
-  env['POAUTOINIT'] = 1
-  env['LINGUAS_FILE'] = 1
-  env['POTDOMAIN'] = 'foo'
-  env.POUpdate()
-</example_commands>
+<programlisting language="python">
+env['POAUTOINIT'] = True
+env['LINGUAS_FILE'] = True
+env['POTDOMAIN'] = 'foo'
+env.POUpdate()
+</programlisting>
 
 </summary>
 </builder>
 
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="POUPDATE_ALIAS">
 <summary>
 <para>
@@ -170,7 +170,7 @@ See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGMERGE">
 <summary>
 <para>
@@ -180,7 +180,7 @@ See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGMERGECOM">
 <summary>
 <para>
@@ -189,17 +189,18 @@ See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGMERGECOMSTR">
 <summary>
 <para>
-String to be displayed when <command>msgmerge(1)</command> is invoked
-(default: <literal>''</literal>, which means ``print &cv-link-MSGMERGECOM;'').
+String to be displayed when <command>msgmerge(1)</command> is invoked.
+The default is an empty string,
+which will print the command line (&cv-link-MSGMERGECOM;).
 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="MSGMERGEFLAGS">
 <summary>
 <para>
diff --git a/SCons/Tool/pdf.xml b/SCons/Tool/pdf.xml
index 95c5ac3..71dbdda 100644
--- a/SCons/Tool/pdf.xml
+++ b/SCons/Tool/pdf.xml
@@ -48,15 +48,17 @@ or
 The suffix specified by the &cv-link-PDFSUFFIX; construction variable
 (<filename>.pdf</filename> by default)
 is added automatically to the target
-if it is not already present.  Example:
+if it is not already present.
+&b-PDF; is a single-source builder.
+Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 # builds from aaa.tex
 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
 # builds bbb.pdf from bbb.dvi
 env.PDF(target = 'bbb', source = 'bbb.dvi')
-</example_commands>
+</programlisting>
 </summary>
 </builder>
 
diff --git a/SCons/Tool/xgettext.xml b/SCons/Tool/xgettext.xml
index f8b8bb8..10bec3a 100644
--- a/SCons/Tool/xgettext.xml
+++ b/SCons/Tool/xgettext.xml
@@ -27,10 +27,10 @@ This file is processed by the bin/SConsDoc.py module.
 <tool name="xgettext">
 <summary>
 <para>
-This scons tool is a part of scons &t-link-gettext; toolset. It provides
-scons interface to <command>xgettext(1)</command>
-program, which extracts internationalized messages from source code. The tool
-provides &b-POTUpdate; builder to make  <literal>PO</literal>
+This tool is a part of the &t-link-gettext; toolset. It provides
+&SCons; an interface to the <command>xgettext(1)</command>
+program, which extracts internationalized messages from source code.
+The tool sets up the &b-POTUpdate; builder to make  <literal>PO</literal>
 <emphasis>Template</emphasis> files.
 </para>
 </summary>
@@ -58,15 +58,18 @@ provides &b-POTUpdate; builder to make  <literal>PO</literal>
 <builder name="POTUpdate">
 <summary>
 <para>
-The builder belongs to &t-link-xgettext; tool. The builder updates target
-<literal>POT</literal> file if exists or creates one if it doesn't. The node is
-not built by default (i.e. it is <literal>Ignore</literal>d from
-<literal>'.'</literal>), but only on demand (i.e.  when given
-<literal>POT</literal> file is required or when special alias is invoked). This
-builder adds its targe node (<filename>messages.pot</filename>, say) to a
+The builder is set up by the &t-link-xgettext; tool,
+part of the &t-link-gettext; toolset.
+The builder updates the target
+<literal>POT</literal> file if exists or creates it if it doesn't.
+The target node is <emphasis>not</emphasis>
+selected for building by default (e.g. <userinput>scons .</userinput>),
+but only on demand (i.e.  when the given
+<literal>POT</literal> file is required or when special alias is invoked).
+This builder adds its target node (<filename>messages.pot</filename>, say) to a
 special alias (<literal>pot-update</literal> by default, see
 &cv-link-POTUPDATE_ALIAS;) so you can update/create them easily with
-<command>scons pot-update</command>. The file is not written until there is no
+<userinput>scons pot-update</userinput>. The file is not written until there is no
 real change in internationalized messages (or in comments that enter
 <literal>POT</literal> file).
 </para>
@@ -86,86 +89,87 @@ not.</para></note>
 Let's create <filename>po/</filename> directory and place following
 <filename>SConstruct</filename> script there:
 </para>
-<example_commands>
-  # SConstruct in 'po/' subdir
-  env = Environment( tools = ['default', 'xgettext'] )
-  env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
-  env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
-</example_commands>
+<programlisting language="python">
+# SConstruct in 'po/' subdir
+env = Environment(tools=['default', 'xgettext'])
+env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
+env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
+</programlisting>
 <para>
 Then invoke scons few times:
 </para>
-<example_commands>
-  user@host:$ scons             # Does not create foo.pot nor bar.pot
-  user@host:$ scons foo.pot     # Updates or creates foo.pot
-  user@host:$ scons pot-update  # Updates or creates foo.pot and bar.pot
-  user@host:$ scons -c          # Does not clean foo.pot nor bar.pot.
-</example_commands>
+<screen>
+$ scons             # Does not create foo.pot nor bar.pot
+$ scons foo.pot     # Updates or creates foo.pot
+$ scons pot-update  # Updates or creates foo.pot and bar.pot
+$ scons -c          # Does not clean foo.pot nor bar.pot.
+</screen>
 <para>
 the results shall be as the comments above say.
 </para>
 
 <para>
 <emphasis>Example 2.</emphasis>
-The &b-POTUpdate; builder may be used with no target specified, in which
-case default target <filename>messages.pot</filename> will be used. The
-default target may also be overridden by setting &cv-link-POTDOMAIN; construction
-variable or providing it as an override to &b-POTUpdate; builder:
-</para>
-<example_commands>
-  # SConstruct script
-  env = Environment( tools = ['default', 'xgettext'] )
-  env['POTDOMAIN'] = "foo"
-  env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
-  env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
-</example_commands>
+The <parameter>target</parameter> argument can be omitted, in which
+case the default target name <filename>messages.pot</filename> is used.
+The target may also be overridden by setting the &cv-link-POTDOMAIN;
+&consvar; or providing it as an override to the &b-POTUpdate; builder:
+</para>
+<programlisting language="python">
+# SConstruct script
+env = Environment(tools=['default', 'xgettext'])
+env['POTDOMAIN'] = "foo"
+env.POTUpdate(source=["a.cpp", "b.cpp"])  # Creates foo.pot ...
+env.POTUpdate(POTDOMAIN="bar", source=["c.cpp", "d.cpp"])  # and bar.pot
+</programlisting>
 
 <para>
 <emphasis>Example 3.</emphasis>
-The sources may be specified within separate file, for example
+The <parameter>source</parameter> parameter may also be omitted,
+if it is specified in a separate file, for example
 <filename>POTFILES.in</filename>:
 </para>
-<example_commands>
-  # POTFILES.in in 'po/' subdirectory
-  ../a.cpp
-  ../b.cpp
-  # end of file
-</example_commands>
+<programlisting>
+# POTFILES.in in 'po/' subdirectory
+../a.cpp
+../b.cpp
+# end of file
+</programlisting>
 <para>
 The name of the file (<filename>POTFILES.in</filename>) containing the list of
 sources is provided via &cv-link-XGETTEXTFROM;:
 </para>
-<example_commands>
-  # SConstruct file in 'po/' subdirectory
-  env = Environment( tools = ['default', 'xgettext'] )
-  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
-</example_commands>
+<programlisting language="python">
+# SConstruct file in 'po/' subdirectory
+env = Environment(tools=['default', 'xgettext'])
+env.POTUpdate(XGETTEXTFROM='POTFILES.in')
+</programlisting>
 
 <para>
 <emphasis>Example 4.</emphasis>
-You may use &cv-link-XGETTEXTPATH; to define source search path. Assume, for
-example, that you have files <filename>a.cpp</filename>,
+You can use &cv-link-XGETTEXTPATH; to define the source search path.
+Assume, for example, that you have files <filename>a.cpp</filename>,
 <filename>b.cpp</filename>, <filename>po/SConstruct</filename>,
-<filename>po/POTFILES.in</filename>. Then your <literal>POT</literal>-related
-files could look as below:
-</para>
-<example_commands>
-  # POTFILES.in in 'po/' subdirectory
-  a.cpp
-  b.cpp
-  # end of file
-</example_commands>
+<filename>po/POTFILES.in</filename>.
+Then your <literal>POT</literal>-related files could look like this:
+</para>
+<programlisting>
+# POTFILES.in in 'po/' subdirectory
+a.cpp
+b.cpp
+# end of file
+</programlisting>
 
-<example_commands>
-  # SConstruct file in 'po/' subdirectory
-  env = Environment( tools = ['default', 'xgettext'] )
-  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
-</example_commands>
+<programlisting language="python">
+# SConstruct file in 'po/' subdirectory
+env = Environment(tools=['default', 'xgettext'])
+env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH='../')
+</programlisting>
 
 <para>
 <emphasis>Example 5.</emphasis>
-Multiple search directories may be defined within a list, i.e.
-<literal>XGETTEXTPATH = ['dir1', 'dir2', ...]</literal>. The order in the list
+Multiple search directories may be defined as a list, i.e.
+<literal>XGETTEXTPATH=['dir1', 'dir2', ...]</literal>. The order in the list
 determines the search order of source files. The path to the first file found
 is used.
 </para>
@@ -173,44 +177,44 @@ is used.
 <para>
 Let's create <filename>0/1/po/SConstruct</filename> script:
 </para>
-<example_commands>
-  # SConstruct file in '0/1/po/' subdirectory
-  env = Environment( tools = ['default', 'xgettext'] )
-  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
-</example_commands>
+<programlisting language="python">
+# SConstruct file in '0/1/po/' subdirectory
+env = Environment(tools=['default', 'xgettext'])
+env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../', '../../'])
+</programlisting>
 <para>
 and <filename>0/1/po/POTFILES.in</filename>:
 </para>
-<example_commands>
-  # POTFILES.in in '0/1/po/' subdirectory
-  a.cpp
-  # end of file
-</example_commands>
+<programlisting>
+# POTFILES.in in '0/1/po/' subdirectory
+a.cpp
+# end of file
+</programlisting>
 <para>
 Write two <filename>*.cpp</filename> files, the first one is
 <filename>0/a.cpp</filename>:
 </para>
-<example_commands>
-  /* 0/a.cpp */
-  gettext("Hello from ../../a.cpp")
-</example_commands>
+<programlisting language="c++">
+/* 0/a.cpp */
+gettext("Hello from ../../a.cpp")
+</programlisting>
 <para>
 and the second is <filename>0/1/a.cpp</filename>:
 </para>
-<example_commands>
-  /* 0/1/a.cpp */
-  gettext("Hello from ../a.cpp")
-</example_commands>
+<programlisting language="c++">
+/* 0/1/a.cpp */
+gettext("Hello from ../a.cpp")
+</programlisting>
 <para>
 then run scons. You'll obtain <literal>0/1/po/messages.pot</literal> with the
 message <literal>"Hello from ../a.cpp"</literal>. When you reverse order in
 <varname>$XGETTEXTFOM</varname>, i.e. when you write SConscript as
 </para>
-<example_commands>
-  # SConstruct file in '0/1/po/' subdirectory
-  env = Environment( tools = ['default', 'xgettext'] )
-  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
-</example_commands>
+<programlisting language="python">
+# SConstruct file in '0/1/po/' subdirectory
+env = Environment(tools=['default', 'xgettext'])
+env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../../', '../'])
+</programlisting>
 <para>
 then the <filename>messages.pot</filename> will contain
 <literal>msgid "Hello from ../../a.cpp"</literal> line and not
@@ -220,7 +224,6 @@ then the <filename>messages.pot</filename> will contain
 </summary>
 </builder>
 
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="POTSUFFIX">
 <summary>
 <para>
@@ -229,7 +232,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="POTUPDATE_ALIAS">
 <summary>
 <para>
@@ -239,7 +242,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXT">
 <summary>
 <para>
@@ -249,7 +252,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTCOM">
 <summary>
 <para>
@@ -258,7 +261,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTCOMSTR">
 <summary>
 <para>
@@ -268,7 +271,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTFLAGS">
 <summary>
 <para>
@@ -277,7 +280,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTFROM">
 <summary>
 <para>
@@ -290,7 +293,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTPATH">
 <summary>
 <para>
@@ -303,7 +306,7 @@ See also &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTPATHPREFIX">
 <summary>
 <para>
@@ -313,7 +316,7 @@ This flag is used to add single search path to
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTPATHSUFFIX">
 <summary>
 <para>
@@ -321,7 +324,7 @@ This flag is used to add single search path to
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTFROMPREFIX">
 <summary>
 <para>
@@ -331,7 +334,7 @@ This flag is used to add single &cv-link-XGETTEXTFROM; file to
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="XGETTEXTFROMSUFFIX">
 <summary>
 <para>
@@ -339,7 +342,7 @@ This flag is used to add single &cv-link-XGETTEXTFROM; file to
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="_XGETTEXTDOMAIN">
 <summary>
 <para>
@@ -348,7 +351,7 @@ form source and target (default: <literal>'${TARGET.filebase}'</literal>).
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="_XGETTEXTFROMFLAGS">
 <summary>
 <para>
@@ -357,7 +360,7 @@ from the &cv-link-XGETTEXTPATH; list.
 </para>
 </summary>
 </cvar>
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+
 <cvar name="_XGETTEXTPATHFLAGS">
 <summary>
 <para>
@@ -367,8 +370,4 @@ from &cv-link-XGETTEXTFROM;.
 </summary>
 </cvar>
 
-<!--
-
--->
-
 </sconsdoc>