Merge tag 'upstream/2.3.1'

Upstream version 2.3.1

1 files changed, 2577 insertions, 0 deletions

diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
new file mode 100644
index 0000000..41239d4
--- /dev/null
+++ b/doc/generated/builders.gen
@@ -0,0 +1,2577 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sconsdoc [
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+    <!ENTITY % builders-mod SYSTEM "builders.mod">
+    %builders-mod;
+    <!ENTITY % functions-mod SYSTEM "functions.mod">
+    %functions-mod;
+    <!ENTITY % tools-mod SYSTEM "tools.mod">
+    %tools-mod;
+    <!ENTITY % variables-mod SYSTEM "variables.mod">
+    %variables-mod;
+]>
+
+<variablelist xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd">
+  <varlistentry id="b-CFile">
+    <term>
+      <function>CFile()</function>
+    </term>
+    <term>
+      <function>env.CFile()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a C source file given a lex (<filename>.l</filename>)
+or yacc (<filename>.y</filename>) input file.
+The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CFILESUFFIX"><envar>$CFILESUFFIX</envar></link> construction variable
+(<filename>.c</filename> by default)
+is automatically added to the target
+if it is not already present.
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# builds foo.c
+env.CFile(target = 'foo.c', source = 'foo.l')
+# builds bar.c
+env.CFile(target = 'bar', source = 'bar.y')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Command">
+    <term>
+      <function>Command()</function>
+    </term>
+    <term>
+      <function>env.Command()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The <function xmlns="http://www.scons.org/dbxsd/v1.0">Command</function> "Builder" is actually implemented
+as a function that looks like a Builder,
+but actually takes an additional argument of the action
+from which the Builder should be made.
+See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Command"><function>Command</function></link> function description
+for the calling syntax and details.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-CXXFile">
+    <term>
+      <function>CXXFile()</function>
+    </term>
+    <term>
+      <function>env.CXXFile()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a C++ source file given a lex (<filename>.ll</filename>)
+or yacc (<filename>.yy</filename>)
+input file.
+The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CXXFILESUFFIX"><envar>$CXXFILESUFFIX</envar></link> construction variable
+(<filename>.cc</filename> by default)
+is automatically added to the target
+if it is not already present.
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# builds foo.cc
+env.CXXFile(target = 'foo.cc', source = 'foo.ll')
+# builds bar.cc
+env.CXXFile(target = 'bar', source = 'bar.yy')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookEpub">
+    <term>
+      <function>DocbookEpub()</function>
+    </term>
+    <term>
+      <function>env.DocbookEpub()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, providing a Docbook toolchain for EPUB output.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookEpub('manual.epub', 'manual.xml')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+or simply
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookEpub('manual')
+</example_commands>
+
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookHtml">
+    <term>
+      <function>DocbookHtml()</function>
+    </term>
+    <term>
+      <function>env.DocbookHtml()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, providing a Docbook toolchain for HTML output.
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookHtml('manual.html', 'manual.xml')
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+or simply
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookHtml('manual')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookHtmlChunked">
+    <term>
+      <function>DocbookHtmlChunked()</function>
+    </term>
+    <term>
+      <function>env.DocbookHtmlChunked()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, providing a Docbook toolchain for chunked HTML output.
+It supports the <literal>base.dir</literal> parameter. The 
+<filename>chunkfast.xsl</filename> file (requires "EXSLT") is used as the
+default stylesheet. Basic syntax:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookHtmlChunked('manual')
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+where <filename>manual.xml</filename> is the input file.
+</para>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">If you use the <literal>root.filename</literal> 
+parameter in your own stylesheets you have to specify the new target name.
+This ensures that the dependencies get correct, especially for the cleanup via <quote><literal>scons -c</literal></quote>:
+</para>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
+</screen>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">Some basic support for the <literal>base.dir</literal> is provided. You
+can add the <literal>base_dir</literal> keyword to your Builder
+call, and the given prefix gets prepended to all the created filenames:
+</para>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
+</screen>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">Make sure that you don't forget the trailing slash for the base folder, else
+your files get renamed only! 
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookHtmlhelp">
+    <term>
+      <function>DocbookHtmlhelp()</function>
+    </term>
+    <term>
+      <function>env.DocbookHtmlhelp()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, providing a Docbook toolchain for HTMLHELP output.
+Its basic syntax is:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookHtmlhelp('manual')
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+where <filename>manual.xml</filename> is the input file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">If you use the <literal>root.filename</literal> 
+parameter in your own stylesheets you have to specify the new target name.
+This ensures that the dependencies get correct, especially for the cleanup via <quote><literal>scons -c</literal></quote>:
+</para>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
+</screen>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">Some basic support for the <literal>base.dir</literal> parameter
+is provided. You can add the <literal>base_dir</literal> keyword to
+your Builder call, and the given prefix gets prepended to all the
+created filenames:
+</para>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
+</screen>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">Make sure that you don't forget the trailing slash for the base folder, else
+your files get renamed only! 
+</para>
+
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookMan">
+    <term>
+      <function>DocbookMan()</function>
+    </term>
+    <term>
+      <function>env.DocbookMan()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, providing a Docbook toolchain for Man page output.
+Its basic syntax is:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookMan('manual')
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+where <filename>manual.xml</filename> is the input file. Note, that 
+you can specify a target name, but the actual output names are automatically
+set from the <literal>refname</literal> entries in your XML source.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookPdf">
+    <term>
+      <function>DocbookPdf()</function>
+    </term>
+    <term>
+      <function>env.DocbookPdf()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, providing a Docbook toolchain for PDF output.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookPdf('manual.pdf', 'manual.xml')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+or simply
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookPdf('manual')
+</example_commands>
+
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookSlidesHtml">
+    <term>
+      <function>DocbookSlidesHtml()</function>
+    </term>
+    <term>
+      <function>env.DocbookSlidesHtml()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, providing a Docbook toolchain for HTML slides output.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookSlidesHtml('manual')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">If you use the <literal>titlefoil.html</literal> parameter in
+your own stylesheets you have to give the new target name. This ensures
+that the dependencies get correct, especially for the cleanup via 
+<quote><literal>scons -c</literal></quote>:
+</para>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
+</screen>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">Some basic support for the <literal>base.dir</literal> parameter 
+is provided. You
+can add the <literal>base_dir</literal> keyword to your Builder
+call, and the given prefix gets prepended to all the created filenames:
+</para>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
+</screen>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">Make sure that you don't forget the trailing slash for the base folder, else
+your files get renamed only! 
+</para>
+
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookSlidesPdf">
+    <term>
+      <function>DocbookSlidesPdf()</function>
+    </term>
+    <term>
+      <function>env.DocbookSlidesPdf()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, providing a Docbook toolchain for PDF slides output.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+or simply
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookSlidesPdf('manual')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookXInclude">
+    <term>
+      <function>DocbookXInclude()</function>
+    </term>
+    <term>
+      <function>env.DocbookXInclude()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, for resolving XIncludes in a separate processing step.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DocbookXslt">
+    <term>
+      <function>DocbookXslt()</function>
+    </term>
+    <term>
+      <function>env.DocbookXslt()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A pseudo-Builder, applying a given XSL transformation to the input file.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['docbook'])
+env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">Note, that this builder requires the <literal>xsl</literal> parameter
+to be set.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-DVI">
+    <term>
+      <function>DVI()</function>
+    </term>
+    <term>
+      <function>env.DVI()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a <filename>.dvi</filename> file
+from a <filename>.tex</filename>,
+<filename>.ltx</filename> or <filename>.latex</filename> input file.
+If the source file suffix is <filename>.tex</filename>,
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will examine the contents of the file;
+if the string
+<literal>\documentclass</literal>
+or
+<literal>\documentstyle</literal>
+is found, the file is assumed to be a LaTeX file and
+the target is built by invoking the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LATEXCOM"><envar>$LATEXCOM</envar></link> command line;
+otherwise, the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-TEXCOM"><envar>$TEXCOM</envar></link> command line is used.
+If the file is a LaTeX file,
+the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">DVI</function>
+builder method will also examine the contents
+of the
+<filename>.aux</filename>
+file and invoke the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-BIBTEX"><envar>$BIBTEX</envar></link> command line
+if the string
+<literal>bibdata</literal>
+is found,
+start <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MAKEINDEX"><envar>$MAKEINDEX</envar></link> to generate an index if a
+<filename>.ind</filename>
+file is found
+and will examine the contents
+<filename>.log</filename>
+file and re-run the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LATEXCOM"><envar>$LATEXCOM</envar></link> command
+if the log file says it is necessary.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The suffix <filename>.dvi</filename>
+(hard-coded within TeX itself)
+is automatically added to the target
+if it is not already present.
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# builds from aaa.tex
+env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
+# builds bbb.dvi
+env.DVI(target = 'bbb', source = 'bbb.ltx')
+# builds from ccc.latex
+env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Gs">
+    <term>
+      <function>Gs()</function>
+    </term>
+    <term>
+      <function>env.Gs()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A Builder for explicitly calling the <literal>gs</literal> executable.
+Depending on the underlying OS, the different names <literal>gs</literal>,
+<literal>gsos2</literal> and <literal>gswin32c</literal>
+are tried.
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">env = Environment(tools=['gs'])
+env.Gs('cover.jpg','scons-scons.pdf',
+       GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q') 
+       )
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Install">
+    <term>
+      <function>Install()</function>
+    </term>
+    <term>
+      <function>env.Install()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Installs one or more source files or directories
+in the specified target,
+which must be a directory.
+The names of the specified source files or directories
+remain the same within the destination directory. The
+sources may be given as a string or as a node returned by
+a builder.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Install('/usr/local/bin', source = ['foo', 'bar'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-InstallAs">
+    <term>
+      <function>InstallAs()</function>
+    </term>
+    <term>
+      <function>env.InstallAs()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Installs one or more source files or directories
+to specific names,
+allowing changing a file or directory name
+as part of the installation.
+It is an error if the
+target
+and
+source
+arguments list different numbers of files or directories.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-InstallVersionedLib">
+    <term>
+      <function>InstallVersionedLib()</function>
+    </term>
+    <term>
+      <function>env.InstallVersionedLib()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Installs a versioned shared library. The <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link>
+construction variable should be defined in the environment
+to confirm the version number in the library name.
+The symlinks appropriate to the architecture will be generated.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.InstallAs(target = '/usr/local/bin/foo',
+              source = 'foo_debug')
+env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
+              source = ['libFOO.a', 'libBAR.a'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Jar">
+    <term>
+      <function>Jar()</function>
+    </term>
+    <term>
+      <function>env.Jar()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a Java archive (<filename>.jar</filename>) file
+from the specified list of sources.
+Any directories in the source list
+will be searched for <filename>.class</filename> files).
+Any <filename>.java</filename> files in the source list
+will be compiled  to <filename>.class</filename> files
+by calling the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> Builder.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCHDIR"><envar>$JARCHDIR</envar></link> value is set, the
+<application xmlns="http://www.scons.org/dbxsd/v1.0">jar</application>
+command will change to the specified directory using the
+<option>-C</option>
+option.
+If <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCHDIR</envar> is not set explicitly,
+<application xmlns="http://www.scons.org/dbxsd/v1.0">SCons</application> will use the top of any subdirectory tree
+in which Java <filename>.class</filename>
+were built by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> Builder.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the contents any of the source files begin with the string
+<literal>Manifest-Version</literal>,
+the file is assumed to be a manifest
+and is passed to the
+<application xmlns="http://www.scons.org/dbxsd/v1.0">jar</application>
+command with the
+<option>m</option>
+option set.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Jar(target = 'foo.jar', source = 'classes')
+
+env.Jar(target = 'bar.jar',
+        source = ['bar1.java', 'bar2.java'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Java">
+    <term>
+      <function>Java()</function>
+    </term>
+    <term>
+      <function>env.Java()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds one or more Java class files.
+The sources may be any combination of explicit
+<filename>.java</filename> files,
+or directory trees which will be scanned
+for <filename>.java</filename> files.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+SCons will parse each source <filename>.java</filename> file
+to find the classes
+(including inner classes)
+defined within that file,
+and from that figure out the
+target <filename>.class</filename> files that will be created.
+The class files will be placed underneath
+the specified target directory.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+SCons will also search each Java file
+for the Java package name,
+which it assumes can be found on a line
+beginning with the string
+<literal>package</literal>
+in the first column;
+the resulting <filename>.class</filename> files
+will be placed in a directory reflecting
+the specified package name.
+For example,
+the file
+<filename>Foo.java</filename>
+defining a single public
+<classname>Foo</classname>
+class and
+containing a package name of
+<classname>sub.dir</classname>
+will generate a corresponding
+<filename>sub/dir/Foo.class</filename>
+class file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Java(target = 'classes', source = 'src')
+env.Java(target = 'classes', source = ['src1', 'src2'])
+env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Java source files can use the native encoding for the underlying OS.
+Since SCons compiles in simple ASCII mode by default,
+the compiler will generate warnings about unmappable characters,
+which may lead to errors as the file is processed further.
+In this case, the user must specify the <literal>LANG</literal>
+environment variable to tell the compiler what encoding is used.
+For portibility, it's best if the encoding is hard-coded
+so that the compile will work if it is done on a system
+with a different encoding.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env = Environment()
+env['ENV']['LANG'] = 'en_GB.UTF-8'
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-JavaH">
+    <term>
+      <function>JavaH()</function>
+    </term>
+    <term>
+      <function>env.JavaH()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds C header and source files for
+implementing Java native methods.
+The target can be either a directory
+in which the header files will be written,
+or a header file name which
+will contain all of the definitions.
+The source can be the names of <filename>.class</filename> files,
+the names of <filename>.java</filename> files
+to be compiled into <filename>.class</filename> files
+by calling the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Java"><function>Java</function></link> builder method,
+or the objects returned from the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Java</function>
+builder method.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the construction variable
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JAVACLASSDIR"><envar>$JAVACLASSDIR</envar></link>
+is set, either in the environment
+or in the call to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">JavaH</function>
+builder method itself,
+then the value of the variable
+will be stripped from the
+beginning of any <filename>.class</filename> file names.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# builds java_native.h
+classes = env.Java(target = 'classdir', source = 'src')
+env.JavaH(target = 'java_native.h', source = classes)
+
+# builds include/package_foo.h and include/package_bar.h
+env.JavaH(target = 'include',
+          source = ['package/foo.class', 'package/bar.class'])
+
+# builds export/foo.h and export/bar.h
+env.JavaH(target = 'export',
+          source = ['classes/foo.class', 'classes/bar.class'],
+          JAVACLASSDIR = 'classes')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Library">
+    <term>
+      <function>Library()</function>
+    </term>
+    <term>
+      <function>env.Library()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A synonym for the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticLibrary</function>
+builder method.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-LoadableModule">
+    <term>
+      <function>LoadableModule()</function>
+    </term>
+    <term>
+      <function>env.LoadableModule()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+On most systems,
+this is the same as
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>.
+On Mac OS X (Darwin) platforms,
+this creates a loadable module bundle.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-M4">
+    <term>
+      <function>M4()</function>
+    </term>
+    <term>
+      <function>env.M4()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds an output file from an M4 input file.
+This uses a default <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-M4FLAGS"><envar>$M4FLAGS</envar></link> value of
+<option>-E</option>,
+which considers all warnings to be fatal
+and stops on the first warning
+when using the GNU version of m4.
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.M4(target = 'foo.c', source = 'foo.c.m4')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Moc">
+    <term>
+      <function>Moc()</function>
+    </term>
+    <term>
+      <function>env.Moc()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds an output file from a moc input file. Moc input files are either
+header files or cxx files. This builder is only available after using the
+tool 'qt'. See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-QTDIR"><envar>$QTDIR</envar></link> variable for more information.
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Moc('foo.h') # generates moc_foo.cc
+env.Moc('foo.cpp') # generates foo.moc
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-MOFiles">
+    <term>
+      <function>MOFiles()</function>
+    </term>
+    <term>
+      <function>env.MOFiles()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msgfmt"><literal>msgfmt</literal></link> tool. The builder compiles
+<literal>PO</literal> files to <literal>MO</literal> files.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 1</emphasis>.
+Create <filename>pl.mo</filename> and <filename>en.mo</filename> by compiling
+<filename>pl.po</filename> and <filename>en.po</filename>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.MOFiles(['pl', 'en'])
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 2</emphasis>.
+Compile files for languages defined in <filename>LINGUAS</filename> file:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.MOFiles(LINGUAS_FILE = 1)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 3</emphasis>.
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 4</emphasis>.
+Compile files for languages defined in <filename>LINGUAS</filename> file 
+(another version):
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env['LINGUAS_FILE'] = 1
+  env.MOFiles()
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-MSVSProject">
+    <term>
+      <function>MSVSProject()</function>
+    </term>
+    <term>
+      <function>env.MSVSProject()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a Microsoft Visual Studio project file,
+and by default builds a solution file as well.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This builds a Visual Studio project file, based on the version of
+Visual Studio that is configured (either the latest installed version,
+or the version specified by
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVS_VERSION"><envar>$MSVS_VERSION</envar></link>
+in the Environment constructor).
+For Visual Studio 6, it will generate a
+<filename>.dsp</filename>
+file.
+For Visual Studio 7 (.NET) and later versions, it will generate a
+<filename>.vcproj</filename>
+file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+By default,
+this also generates a solution file
+for the specified project,
+a
+<filename>.dsw</filename>
+file for Visual Studio 6
+or a
+<filename>.sln</filename>
+file for Visual Studio 7 (.NET).
+This behavior may be disabled by specifying
+<literal>auto_build_solution=0</literal>
+when you call
+<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function>,
+in which case you presumably want to
+build the solution file(s)
+by calling the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSSolution</function>
+Builder (see below).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The <function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function> builder
+takes several lists of filenames
+to be placed into the project file.
+These are currently limited to
+<literal>srcs</literal>,
+<literal>incs</literal>,
+<literal>localincs</literal>,
+<literal>resources</literal>,
+and
+<literal>misc</literal>.
+These are pretty self-explanatory, but it should be noted that these
+lists are added to the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SOURCES"><envar>$SOURCES</envar></link> construction variable as strings,
+NOT as SCons File Nodes.  This is because they represent file
+names to be added to the project file, not the source files used to
+build the project file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The above filename lists are all optional,
+although at least one must be specified
+for the resulting project file to be non-empty.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+In addition to the above lists of values,
+the following values may be specified:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>target</literal>:
+The name of the target
+<filename>.dsp</filename>
+or
+<filename>.vcproj</filename>
+file.
+The correct
+suffix for the version of Visual Studio must be used,
+but the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVSPROJECTSUFFIX"><envar>$MSVSPROJECTSUFFIX</envar></link>
+construction variable
+will be defined to the correct value (see example below).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>variant</literal>:
+The name of this particular variant.
+For Visual Studio 7 projects,
+this can also be a list of variant names.
+These are typically things like "Debug" or "Release", but really
+can be anything you want.
+For Visual Studio 7 projects,
+they may also specify a target platform
+separated from the variant name by a
+<literal>|</literal>
+(vertical pipe)
+character:
+<literal>Debug|Xbox</literal>.
+The default target platform is Win32.
+Multiple calls to
+<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function>
+with different variants are allowed;
+all variants will be added to the project file with their appropriate
+build targets and sources.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>buildtarget</literal>:
+An optional string, node, or list of strings or nodes
+(one per build variant), to tell the Visual Studio debugger
+what output target to use in what build variant.
+The number of
+<literal>buildtarget</literal>
+entries must match the number of
+<literal>variant</literal>
+entries.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>runfile</literal>:
+The name of the file that Visual Studio 7 and later
+will run and debug.
+This appears as the value of the
+<literal>Output</literal>
+field in the resutling Visual Studio project file.
+If this is not specified,
+the default is the same as the specified
+<literal>buildtarget</literal>
+value.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that because <application xmlns="http://www.scons.org/dbxsd/v1.0">SCons</application> always executes its build commands
+from the directory in which the <filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename> file is located,
+if you generate a project file in a different directory
+than the <filename xmlns="http://www.scons.org/dbxsd/v1.0">SConstruct</filename> directory,
+users will not be able to double-click
+on the file name in compilation error messages
+displayed in the Visual Studio console output window.
+This can be remedied by adding the
+Visual C/C++
+<literal>/FC</literal>
+compiler option to the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-CCFLAGS"><envar>$CCFLAGS</envar></link>  variable
+so that the compiler will print
+the full path name of any
+files that cause compilation errors.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example usage:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+barsrcs = ['bar.cpp'],
+barincs = ['bar.h'],
+barlocalincs = ['StdAfx.h']
+barresources = ['bar.rc','resource.h']
+barmisc = ['bar_readme.txt']
+
+dll = env.SharedLibrary(target = 'bar.dll',
+                        source = barsrcs)
+
+env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
+                srcs = barsrcs,
+                incs = barincs,
+                localincs = barlocalincs,
+                resources = barresources,
+                misc = barmisc,
+                buildtarget = dll,
+                variant = 'Release')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-MSVSSolution">
+    <term>
+      <function>MSVSSolution()</function>
+    </term>
+    <term>
+      <function>env.MSVSSolution()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a Microsoft Visual Studio solution file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This builds a Visual Studio solution file,
+based on the version of Visual Studio that is configured
+(either the latest installed version,
+or the version specified by
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVS_VERSION"><envar>$MSVS_VERSION</envar></link>
+in the construction environment).
+For Visual Studio 6, it will generate a
+<filename>.dsw</filename>
+file.
+For Visual Studio 7 (.NET), it will
+generate a
+<filename>.sln</filename>
+file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The following values must be specified:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>target</literal>:
+The name of the target .dsw or .sln file.  The correct
+suffix for the version of Visual Studio must be used, but the value
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MSVSSOLUTIONSUFFIX"><envar>$MSVSSOLUTIONSUFFIX</envar></link>
+will be defined to the correct value (see example below).
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>variant</literal>:
+The name of this particular variant, or a list of variant
+names (the latter is only supported for MSVS 7 solutions). These are
+typically things like "Debug" or "Release", but really can be anything
+you want. For MSVS 7 they may also specify target platform, like this
+"Debug|Xbox". Default platform is Win32.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<literal>projects</literal>:
+A list of project file names, or Project nodes returned by calls to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">MSVSProject</function>
+Builder,
+to be placed into the solution file.
+It should be noted that these file names are NOT added to the $SOURCES
+environment variable in form of files, but rather as strings.   This
+is because they represent file names to be added to the solution file,
+not the source files used to build the solution file.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Example Usage:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
+                 projects = ['bar' + env['MSVSPROJECTSUFFIX']],
+                 variant = 'Release')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Object">
+    <term>
+      <function>Object()</function>
+    </term>
+    <term>
+      <function>env.Object()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+A synonym for the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function>
+builder method.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Package">
+    <term>
+      <function>Package()</function>
+    </term>
+    <term>
+      <function>env.Package()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a Binary Package of the given source files. 
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Package(source = FindInstalledFiles())
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds software distribution packages.
+Packages consist of files to install and packaging information.
+The former may be specified with the <varname xmlns="http://www.scons.org/dbxsd/v1.0">source</varname> parameter and may be left out,
+in which case the <function xmlns="http://www.scons.org/dbxsd/v1.0">FindInstalledFiles</function> function will collect
+all files that have an <function xmlns="http://www.scons.org/dbxsd/v1.0">Install</function> or <function xmlns="http://www.scons.org/dbxsd/v1.0">InstallAs</function> Builder attached.
+If the <varname xmlns="http://www.scons.org/dbxsd/v1.0">target</varname> is not specified
+it will be deduced from additional information given to this Builder.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The packaging information is specified
+with the help of construction variables documented below.
+This information is called a tag to stress that
+some of them can also be attached to files with the <function xmlns="http://www.scons.org/dbxsd/v1.0">Tag</function> function.
+The mandatory ones will complain if they were not specified.
+They vary depending on chosen target packager.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The target packager may be selected with the "PACKAGETYPE" command line
+option or with the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$PACKAGETYPE</envar> construction variable. Currently
+the following packagers available:
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+ * msi - Microsoft Installer
+ * rpm - Redhat Package Manger
+ * ipkg - Itsy Package Management System
+ * tarbz2 - compressed tar
+ * targz - compressed tar
+ * zip - zip file
+ * src_tarbz2 - compressed tar source
+ * src_targz - compressed tar source
+ * src_zip - zip file source
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+An updated list is always available under the "package_type" option when
+running "scons --help" on a project that has packaging activated.
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env = Environment(tools=['default', 'packaging'])
+env.Install('/bin/', 'my_program')
+env.Package( NAME           = 'foo',
+             VERSION        = '1.2.3',
+             PACKAGEVERSION = 0,
+             PACKAGETYPE    = 'rpm',
+             LICENSE        = 'gpl',
+             SUMMARY        = 'balalalalal',
+             DESCRIPTION    = 'this should be really really long',
+             X_RPM_GROUP    = 'Application/fu',
+             SOURCE_URL     = 'http://foo.org/foo-1.2.3.tar.gz'
+        )
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-PCH">
+    <term>
+      <function>PCH()</function>
+    </term>
+    <term>
+      <function>env.PCH()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a Microsoft Visual C++ precompiled header.
+Calling this builder method
+returns a list of two targets: the PCH as the first element, and the object
+file as the second element. Normally the object file is ignored.
+This builder method is only
+provided when Microsoft Visual C++ is being used as the compiler.
+The PCH builder method is generally used in
+conjuction with the PCH construction variable to force object files to use
+the precompiled header:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env['PCH'] = env.PCH('StdAfx.cpp')[0]
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-PDF">
+    <term>
+      <function>PDF()</function>
+    </term>
+    <term>
+      <function>env.PDF()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a <filename>.pdf</filename> file
+from a <filename>.dvi</filename> input file
+(or, by extension, a <filename>.tex</filename>,
+<filename>.ltx</filename>,
+or
+<filename>.latex</filename> input file).
+The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PDFSUFFIX"><envar>$PDFSUFFIX</envar></link> construction variable
+(<filename>.pdf</filename> by default)
+is added automatically to the target
+if it is not already present.  Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# 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>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-POInit">
+    <term>
+      <function>POInit()</function>
+    </term>
+    <term>
+      <function>env.POInit()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msginit"><literal>msginit</literal></link> tool. The builder initializes missing
+<literal>PO</literal> file(s) if <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is set.  If
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is not set (default), <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> prints instruction for
+user (that is supposed to be a translator), telling how the
+<literal>PO</literal> file should be initialized. In normal projects
+<emphasis>you should not use <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> and use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link>
+instead</emphasis>. <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link> chooses intelligently between
+<command>msgmerge(1)</command> and <command>msginit(1)</command>. <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function>
+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.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Target nodes defined through <function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> 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).
+The alias name may be changed through the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POCREATE_ALIAS"><envar>$POCREATE_ALIAS</envar></link>
+construction variable. All <literal>PO</literal> files defined through
+<function xmlns="http://www.scons.org/dbxsd/v1.0">POInit</function> may be easily initialized by <command>scons po-create</command>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 1</emphasis>.
+Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
+<filename>messages.pot</filename>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POInit(['en', 'pl']) # messages.pot --&gt; [en.po, pl.po] 
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 2</emphasis>.
+Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
+<filename>foo.pot</filename>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POInit(['en', 'pl'], ['foo']) # foo.pot --&gt; [en.po, pl.po] 
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 3</emphasis>.
+Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
+<filename>foo.pot</filename> but using <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> construction
+variable:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --&gt; [en.po, pl.po] 
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 4</emphasis>.
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 5</emphasis>.
+Initialize <filename>en.po</filename> and <filename>pl.pl</filename>
+<literal>PO</literal> files plus files for languages defined in
+<filename>LINGUAS</filename> file. The files will be initialized from template
+<filename>messages.pot</filename>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 6</emphasis>.
+You may preconfigure your environment first, and then initialize
+<literal>PO</literal> files:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env['POAUTOINIT'] = 1
+  env['LINGUAS_FILE'] = 1
+  env['POTDOMAIN'] = 'foo'
+  env.POInit()
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+which has same efect as:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-PostScript">
+    <term>
+      <function>PostScript()</function>
+    </term>
+    <term>
+      <function>env.PostScript()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a <filename>.ps</filename> file
+from a <filename>.dvi</filename> input file
+(or, by extension, a <filename>.tex</filename>,
+<filename>.ltx</filename>,
+or
+<filename>.latex</filename> input file).
+The suffix specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PSSUFFIX"><envar>$PSSUFFIX</envar></link> construction variable
+(<filename>.ps</filename> by default)
+is added automatically to the target
+if it is not already present.  Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# 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>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-POTUpdate">
+    <term>
+      <function>POTUpdate()</function>
+    </term>
+    <term>
+      <function>env.POTUpdate()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-xgettext"><literal>xgettext</literal></link> 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
+special alias (<literal>pot-update</literal> by default, see
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTUPDATE_ALIAS"><envar>$POTUPDATE_ALIAS</envar></link>) so you can update/create them easily with
+<command>scons pot-update</command>. The file is not written until there is no
+real change in internationalized messages (or in comments that enter
+<literal>POT</literal> file). 
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<note> <para>You may see <command>xgettext(1)</command> being invoked by the
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-xgettext"><literal>xgettext</literal></link> tool even if there is no real change in internationalized
+messages (so the <literal>POT</literal> file is not being updated).  This
+happens every time  a source file has changed. In such case we invoke
+<command>xgettext(1)</command> and compare its output with the content of
+<literal>POT</literal> file to decide whether the file should be updated or
+not.</para></note>
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 1.</emphasis>
+Let's create <filename>po/</filename> directory and place following
+<filename>SConstruct</filename> script there:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # 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>      
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Then invoke scons few times:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  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>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+the results shall be as the comments above say.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 2.</emphasis>
+The <function xmlns="http://www.scons.org/dbxsd/v1.0">POTUpdate</function> 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 overriden by setting <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> construction
+variable or providing it as an override to <function xmlns="http://www.scons.org/dbxsd/v1.0">POTUpdate</function> builder:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">    
+  # 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>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 3.</emphasis>
+The sources may be specified within separate file, for example
+<filename>POTFILES.in</filename>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">      
+  # POTFILES.in in 'po/' subdirectory
+  ../a.cpp
+  ../b.cpp
+  # end of file
+</example_commands>    
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The name of the file (<filename>POTFILES.in</filename>) containing the list of
+sources is provided via <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-XGETTEXTFROM"><envar>$XGETTEXTFROM</envar></link>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">      
+  # SConstruct file in 'po/' subdirectory
+  env = Environment( tools = ['default', 'xgettext'] )
+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
+</example_commands>    
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 4.</emphasis>
+You may use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-XGETTEXTPATH"><envar>$XGETTEXTPATH</envar></link> to define 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 xmlns="http://www.scons.org/dbxsd/v1.0">
+  # POTFILES.in in 'po/' subdirectory
+  a.cpp
+  b.cpp
+  # end of file
+</example_commands>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # SConstruct file in 'po/' subdirectory
+  env = Environment( tools = ['default', 'xgettext'] )
+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<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
+determines the search order of source files. The path to the first file found
+is used.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Let's create <filename>0/1/po/SConstruct</filename> script:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # SConstruct file in '0/1/po/' subdirectory
+  env = Environment( tools = ['default', 'xgettext'] )
+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+and <filename>0/1/po/POTFILES.in</filename>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # POTFILES.in in '0/1/po/' subdirectory
+  a.cpp
+  # end of file
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Write two <filename>*.cpp</filename> files, the first one is
+<filename>0/a.cpp</filename>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  /* 0/a.cpp */
+  gettext("Hello from ../../a.cpp")
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+and the second is <filename>0/1/a.cpp</filename>:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  /* 0/1/a.cpp */
+  gettext("Hello from ../a.cpp")
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+  # SConstruct file in '0/1/po/' subdirectory
+  env = Environment( tools = ['default', 'xgettext'] )
+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
+</example_commands> 
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+then the <filename>messages.pot</filename> will contain
+<literal>msgid "Hello from ../../a.cpp"</literal> line and not 
+<literal>msgid "Hello from ../a.cpp"</literal>.
+</para>
+
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-POUpdate">
+    <term>
+      <function>POUpdate()</function>
+    </term>
+    <term>
+      <function>env.POUpdate()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msgmerge"><literal>msgmerge</literal></link> tool. The builder updates
+<literal>PO</literal> files with <command>msgmerge(1)</command>, or initializes
+missing <literal>PO</literal> files as described in documentation of
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-msginit"><literal>msginit</literal></link> tool and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POInit"><function>POInit</function></link> builder (see also
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link>). Note, that <function xmlns="http://www.scons.org/dbxsd/v1.0">POUpdate</function> <emphasis>does not add its
+targets to <literal>po-create</literal> alias</emphasis> as <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POInit"><function>POInit</function></link>
+does.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Target nodes defined through <function xmlns="http://www.scons.org/dbxsd/v1.0">POUpdate</function> 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> 
+(<literal>'po-update'</literal> by default). The alias name may be changed
+through the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POUPDATE_ALIAS"><envar>$POUPDATE_ALIAS</envar></link> construction variable.  You can easilly 
+update <literal>PO</literal> files in your project by <command>scons
+po-update</command>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 1.</emphasis>
+Update <filename>en.po</filename> and <filename>pl.po</filename> from
+<filename>messages.pot</filename> template (see also <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link>),
+assuming that the later one exists or there is rule to build it (see
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POTUpdate"><function>POTUpdate</function></link>):
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POUpdate(['en','pl']) # messages.pot --&gt; [en.po, pl.po]
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 2.</emphasis>
+Update <filename>en.po</filename> and <filename>pl.po</filename> from
+<filename>foo.pot</filename> template:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --&gt;  [en.po, pl.pl]
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 3.</emphasis>
+Update <filename>en.po</filename> and <filename>pl.po</filename> from
+<filename>foo.pot</filename> (another version):
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- &gt; [en.po, pl.pl]
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<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 xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 5.</emphasis>
+Same as above, but update from <filename>foo.pot</filename> template:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 6.</emphasis>
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+  # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
+  env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1) 
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 7.</emphasis>
+Use <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> to automatically initialize <literal>PO</literal> file
+if it doesn't exist:
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 8.</emphasis>
+Update <literal>PO</literal> files for languages defined in
+<filename>LINGUAS</filename> file. The files are updated from
+<filename>foo.pot</filename> template. All necessary settings are
+pre-configured via environment.
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # ...
+  env['POAUTOINIT'] = 1
+  env['LINGUAS_FILE'] = 1
+  env['POTDOMAIN'] = 'foo'
+  env.POUpdate()
+</example_commands>
+
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Program">
+    <term>
+      <function>Program()</function>
+    </term>
+    <term>
+      <function>env.Program()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds an executable given one or more object files
+or C, C++, D, or Fortran source files.
+If any C, C++, D or Fortran source files are specified,
+then they will be automatically
+compiled to object files using the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Object</function>
+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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PROGPREFIX"><envar>$PROGPREFIX</envar></link> construction variable; nothing by default)
+and suffix
+(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-PROGSUFFIX"><envar>$PROGSUFFIX</envar></link> construction variable;
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-RES">
+    <term>
+      <function>RES()</function>
+    </term>
+    <term>
+      <function>env.RES()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a Microsoft Visual C++ resource file.
+This builder method is only provided
+when Microsoft Visual C++ or MinGW is being used as the compiler. The
+<filename>.res</filename>
+(or
+<filename>.o</filename>
+for MinGW) suffix is added to the target name if no other suffix is given.
+The source
+file is scanned for implicit dependencies as though it were a C file.
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.RES('resource.rc')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-RMIC">
+    <term>
+      <function>RMIC()</function>
+    </term>
+    <term>
+      <function>env.RMIC()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds stub and skeleton class files
+for remote objects
+from Java <filename>.class</filename> files.
+The target is a directory
+relative to which the stub
+and skeleton class files will be written.
+The source can be the names of <filename>.class</filename> files,
+or the objects return from the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Java</function>
+builder method.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If the construction variable
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JAVACLASSDIR"><envar>$JAVACLASSDIR</envar></link>
+is set, either in the environment
+or in the call to the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">RMIC</function>
+builder method itself,
+then the value of the variable
+will be stripped from the
+beginning of any <filename>.class </filename>
+file names.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+classes = env.Java(target = 'classdir', source = 'src')
+env.RMIC(target = 'outdir1', source = classes)
+
+env.RMIC(target = 'outdir2',
+         source = ['package/foo.class', 'package/bar.class'])
+
+env.RMIC(target = 'outdir3',
+         source = ['classes/foo.class', 'classes/bar.class'],
+         JAVACLASSDIR = 'classes')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-RPCGenClient">
+    <term>
+      <function>RPCGenClient()</function>
+    </term>
+    <term>
+      <function>env.RPCGenClient()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Generates an RPC client stub (<filename>_clnt.c</filename>) file
+from a specified RPC (<filename>.x</filename>) source file.
+Because rpcgen only builds output files
+in the local directory,
+the command will be executed
+in the source file's directory by default.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Builds src/rpcif_clnt.c
+env.RPCGenClient('src/rpcif.x')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-RPCGenHeader">
+    <term>
+      <function>RPCGenHeader()</function>
+    </term>
+    <term>
+      <function>env.RPCGenHeader()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Generates an RPC header (<filename>.h</filename>) file
+from a specified RPC (<filename>.x</filename>) source file.
+Because rpcgen only builds output files
+in the local directory,
+the command will be executed
+in the source file's directory by default.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Builds src/rpcif.h
+env.RPCGenHeader('src/rpcif.x')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-RPCGenService">
+    <term>
+      <function>RPCGenService()</function>
+    </term>
+    <term>
+      <function>env.RPCGenService()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Generates an RPC server-skeleton (<filename>_svc.c</filename>) file
+from a specified RPC (<filename>.x</filename>) source file.
+Because rpcgen only builds output files
+in the local directory,
+the command will be executed
+in the source file's directory by default.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Builds src/rpcif_svc.c
+env.RPCGenClient('src/rpcif.x')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-RPCGenXDR">
+    <term>
+      <function>RPCGenXDR()</function>
+    </term>
+    <term>
+      <function>env.RPCGenXDR()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Generates an RPC XDR routine (<filename>_xdr.c</filename>) file
+from a specified RPC (<filename>.x</filename>) source file.
+Because rpcgen only builds output files
+in the local directory,
+the command will be executed
+in the source file's directory by default.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# Builds src/rpcif_xdr.c
+env.RPCGenClient('src/rpcif.x')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-SharedLibrary">
+    <term>
+      <function>SharedLibrary()</function>
+    </term>
+    <term>
+      <function>env.SharedLibrary()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a shared library
+(<filename>.so</filename> on a POSIX system,
+<filename>.dll</filename> on Windows)
+given one or more object files
+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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBPREFIX"><envar>$SHLIBPREFIX</envar></link> construction variable;
+by default, <filename>lib</filename> on POSIX systems,
+nothing on Windows systems)
+and suffix
+(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBSUFFIX"><envar>$SHLIBSUFFIX</envar></link> construction variable;
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+On Windows systems, the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>
+builder method will always build an import
+(<filename>.lib</filename>) library
+in addition to the shared (<filename>.dll</filename>) library,
+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.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+On Cygwin systems, the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function>
+builder method will always build an import
+(<filename>.dll.a</filename>) library
+in addition to the shared (<filename>.dll</filename>) library,
+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.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Any object files listed in the
+<literal>source</literal>
+must have been built for a shared library
+(that is, using the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">SharedObject</function>
+builder method).
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will raise an error if there is any mismatch.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+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 <function xmlns="http://www.scons.org/dbxsd/v1.0">LoadableModule</function> builder for the latter.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+When the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> construction variable is defined a versioned
+shared library is created. This modifies the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLINKFLAGS"><envar>$SHLINKFLAGS</envar></link> as required,
+adds the version number to the library name, and creates the symlinks that
+are needed. <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> needs to be of the form X.Y.Z, where X
+and Y are numbers, and Z is a number but can also contain letters to designate
+alpha, beta, or release candidate patch levels.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This builder may create multiple links to the library. On a POSIX system,
+for the shared library libbar.so.2.3.1, the links created would be
+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.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+On Windows systems, specifying
+<literal>register=1</literal>
+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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVR"><envar>$REGSVR</envar></link> construction
+variable, and the flags passed are determined by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link>.  By
+default, <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link> includes the <option>/s</option> option,
+to prevent dialogs from popping
+up and requiring user attention when it is run.  If you change
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-REGSVRFLAGS"><envar>$REGSVRFLAGS</envar></link>, be sure to include the <option>/s</option> option.
+For example,
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.SharedLibrary(target = 'bar',
+                  source = ['bar.cxx', 'foo.obj'],
+                  register=1)
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+will register <filename>bar.dll</filename> as a COM object
+when it is done linking it.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-SharedObject">
+    <term>
+      <function>SharedObject()</function>
+    </term>
+    <term>
+      <function>env.SharedObject()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds an object file for
+inclusion in a shared library.
+Source files must have one of the same set of extensions
+specified above for the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function>
+builder method.
+On some platforms building a shared object requires additional
+compiler option
+(e.g. <option>-fPIC</option> for gcc)
+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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHOBJPREFIX"><envar>$SHOBJPREFIX</envar></link> construction variable;
+by default, the same as <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJPREFIX"><envar>$OBJPREFIX</envar></link>)
+and suffix
+(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHOBJSUFFIX"><envar>$SHOBJSUFFIX</envar></link> construction variable)
+are automatically added to the target if not already present.
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the source files will be scanned
+according to the suffix mappings in the
+<literal>SourceFileScanner</literal>
+object.
+See the section "Scanner Objects,"
+below, for more information.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-StaticLibrary">
+    <term>
+      <function>StaticLibrary()</function>
+    </term>
+    <term>
+      <function>env.StaticLibrary()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a static library given one or more object files
+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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LIBPREFIX"><envar>$LIBPREFIX</envar></link> construction variable;
+by default, <filename>lib</filename> on POSIX systems,
+nothing on Windows systems)
+and suffix
+(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LIBSUFFIX"><envar>$LIBSUFFIX</envar></link> construction variable;
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Any object files listed in the
+<literal>source</literal>
+must have been built for a static library
+(that is, using the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">StaticObject</function>
+builder method).
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+will raise an error if there is any mismatch.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-StaticObject">
+    <term>
+      <function>StaticObject()</function>
+    </term>
+    <term>
+      <function>env.StaticObject()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+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:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  .asm    assembly language file
+  .ASM    assembly language file
+  .c      C file
+  .C      Windows:  C file
+          POSIX:  C++ file
+  .cc     C++ file
+  .cpp    C++ file
+  .cxx    C++ file
+  .cxx    C++ file
+  .c++    C++ file
+  .C++    C++ file
+  .d      D file
+  .f      Fortran file
+  .F      Windows:  Fortran file
+          POSIX:  Fortran file + C pre-processor
+  .for    Fortran file
+  .FOR    Fortran file
+  .fpp    Fortran file + C pre-processor
+  .FPP    Fortran file + C pre-processor
+  .m      Object C file
+  .mm     Object C++ file
+  .s      assembly language file
+  .S      Windows:  assembly language file
+          ARM: CodeSourcery Sourcery Lite
+  .sx     assembly language file + C pre-processor
+          POSIX:  assembly language file + C pre-processor
+  .spp    assembly language file + C pre-processor
+  .SPP    assembly language file + C pre-processor
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The target object file prefix
+(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJPREFIX"><envar>$OBJPREFIX</envar></link> construction variable; nothing by default)
+and suffix
+(specified by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-OBJSUFFIX"><envar>$OBJSUFFIX</envar></link> construction variable;
+<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 xmlns="http://www.scons.org/dbxsd/v1.0">
+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 xmlns="http://www.scons.org/dbxsd/v1.0">
+Note that the source files will be scanned
+according to the suffix mappings in
+<literal>SourceFileScanner</literal>
+object.
+See the section "Scanner Objects,"
+below, for more information.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Substfile">
+    <term>
+      <function>Substfile()</function>
+    </term>
+    <term>
+      <function>env.Substfile()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The <function xmlns="http://www.scons.org/dbxsd/v1.0">Substfile</function> builder generates a single text file
+by concatenating the source files.
+Nested lists of sources are flattened. 
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$LINESEPARATOR</envar> is used to separate the source files;
+see the description of <function xmlns="http://www.scons.org/dbxsd/v1.0">Textfile</function> for details.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+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.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The prefix and suffix specified by the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBSTFILEPREFIX</envar>
+and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBSTFILESUFFIX</envar> construction variables
+(the null string by default in both cases)
+are automatically added to the target if they are not already present.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If a construction variable named <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBST_DICT</envar> is present,
+it may be either a Python dictionary or a sequence of (key,value) tuples.
+If the former,
+the dictionary is converted into a list of tuples in an arbitrary order,
+so if one key is a prefix of another key
+or if one substitution could be further expanded by another subsitition,
+it is unpredictible whether the expansion will occur.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Any occurences in the source of a key
+are replaced by the corresponding value,
+which may be a Python callable function or a string.
+If a value is a function,
+it is first called (with no arguments) to produce a string.
+The string is <emphasis>subst</emphasis>-expanded
+and the result replaces the key.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env = Environment(tools = ['default', 'textfile'])
+
+env['prefix'] = '/usr/bin'
+script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'}
+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)
+
+# UNPREDICTABLE - one key is a prefix of another
+bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
+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)
+
+# UNPREDICTABLE - one substitution could be futher expanded
+bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
+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)
+
+# 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"
+                          ])
+
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Tar">
+    <term>
+      <function>Tar()</function>
+    </term>
+    <term>
+      <function>env.Tar()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a tar archive of the specified files
+and/or directories.
+Unlike most builder methods,
+the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Tar</function>
+builder method may be called multiple times
+for a given target;
+each additional call
+adds to the list of entries
+that will be built into the archive.
+Any source directories will
+be scanned for changes to
+any on-disk files,
+regardless of whether or not
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+knows about them from other Builder or function calls.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Tar('src.tar', 'src')
+
+# Create the stuff.tar file.
+env.Tar('stuff', ['subdir1', 'subdir2'])
+# Also add "another" to the stuff.tar file.
+env.Tar('stuff', 'another')
+
+# Set TARFLAGS to create a gzip-filtered archive.
+env = Environment(TARFLAGS = '-c -z')
+env.Tar('foo.tar.gz', 'foo')
+
+# Also set the suffix to .tgz.
+env = Environment(TARFLAGS = '-c -z',
+                  TARSUFFIX = '.tgz')
+env.Tar('foo')
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Textfile">
+    <term>
+      <function>Textfile()</function>
+    </term>
+    <term>
+      <function>env.Textfile()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The <function xmlns="http://www.scons.org/dbxsd/v1.0">Textfile</function> builder generates a single text file.
+The source strings constitute the lines;
+nested lists of sources are flattened. 
+<envar xmlns="http://www.scons.org/dbxsd/v1.0">$LINESEPARATOR</envar> is used to separate the strings.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If present, the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$SUBST_DICT</envar> construction variable
+is used to modify the strings before they are written;
+see the <function xmlns="http://www.scons.org/dbxsd/v1.0">Substfile</function> description for details.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The prefix and suffix specified by the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$TEXTFILEPREFIX</envar>
+and <envar xmlns="http://www.scons.org/dbxsd/v1.0">$TEXTFILESUFFIX</envar> construction variables
+(the null string and <filename>.txt</filename> by default, respectively)
+are automatically added to the target if they are not already present.
+Examples:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# builds/writes foo.txt
+env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
+
+# builds/writes bar.txt
+env.Textfile(target = 'bar',
+             source = ['lalala', 'tanteratei'],
+             LINESEPARATOR='|*')
+
+# nested lists are flattened automatically
+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')
+
+Results are:
+foo.txt
+  ....8&lt;----
+  Goethe
+  42
+  Schiller
+  ....8&lt;---- (no linefeed at the end)
+
+bar.txt:
+  ....8&lt;----
+  lalala|*tanteratei
+  ....8&lt;---- (no linefeed at the end)
+
+blob.txt
+  ....8&lt;----
+  lalala
+  Goethe
+  42
+  Schiller
+  tanteratei
+  ....8&lt;---- (no linefeed at the end)
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Translate">
+    <term>
+      <function>Translate()</function>
+    </term>
+    <term>
+      <function>env.Translate()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This pseudo-builder belongs to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="t-gettext"><literal>gettext</literal></link> 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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POAUTOINIT"><envar>$POAUTOINIT</envar></link> is set, missing <literal>PO</literal> files
+will be automatically created (i.e. without translator person intervention).
+The variables <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LINGUAS_FILE"><envar>$LINGUAS_FILE</envar></link> and <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-POTDOMAIN"><envar>$POTDOMAIN</envar></link> are taken into
+acount too. All other construction variables used by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POTUpdate"><function>POTUpdate</function></link>, and
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-POUpdate"><function>POUpdate</function></link> work here too.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 1</emphasis>.
+The simplest way is to specify input files and output languages inline in
+a SCons script when invoking <function xmlns="http://www.scons.org/dbxsd/v1.0">Translate</function>
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# SConscript in 'po/' directory
+env = Environment( tools = ["default", "gettext"] )
+env['POAUTOINIT'] = 1
+env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) 
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 2</emphasis>.
+If you wish, you may also stick to conventional style known from
+<productname>autotools</productname>, i.e. using
+<filename>POTFILES.in</filename> and <filename>LINGUAS</filename> files
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# LINGUAS
+en pl 
+#end
+</example_commands>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# POTFILES.in
+a.cpp
+b.cpp
+# end
+</example_commands>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+# SConscript
+env = Environment( tools = ["default", "gettext"] )
+env['POAUTOINIT'] = 1
+env['XGETTEXTPATH'] = ['../']
+env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') 
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The last approach is perhaps the recommended one. It allows easily split
+internationalization/localization onto separate SCons scripts, where a script
+in source tree is responsible for translations (from sources to
+<literal>PO</literal> files) and script(s) under variant directories are
+responsible for compilation of <literal>PO</literal> to <literal>MO</literal>
+files to and for installation of <literal>MO</literal> files. The "gluing
+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
+<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.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+<emphasis>Example 3</emphasis>.
+Let's prepare a development tree as below
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+ project/
+  + SConstruct
+  + build/        
+  + src/
+      + po/
+          + SConscript
+          + SConscript.i18n
+          + POTFILES.in
+          + LINGUAS
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+with <filename>build</filename> being variant directory. Write the top-level
+<filename>SConstruct</filename> script as follows
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # 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>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+the <filename>src/po/SConscript.i18n</filename> as
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # src/po/SConscript.i18n
+  Import('env')
+  env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+and the <filename>src/po/SConscript</filename>
+</para>
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+  # src/po/SConscript
+  Import('env')
+  env.MOFiles(LINGUAS_FILE = 1)
+</example_commands>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+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
+<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 xmlns="http://www.scons.org/dbxsd/v1.0">
+<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>
+
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-TypeLibrary">
+    <term>
+      <function>TypeLibrary()</function>
+    </term>
+    <term>
+      <function>env.TypeLibrary()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a Windows type library (<filename>.tlb</filename>)
+file from an input IDL file (<filename>.idl</filename>).
+In addition, it will build the associated inteface stub and
+proxy source files,
+naming them according to the base name of the <filename>.idl</filename> file.
+For example,
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.TypeLibrary(source="foo.idl")
+</example_commands>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Will create <filename>foo.tlb</filename>,
+<filename>foo.h</filename>,
+<filename>foo_i.c</filename>,
+<filename>foo_p.c</filename>
+and
+<filename>foo_data.c</filename>
+files.
+</para>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Uic">
+    <term>
+      <function>Uic()</function>
+    </term>
+    <term>
+      <function>env.Uic()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a header file, an implementation file and a moc file from an ui file.
+and returns the corresponding nodes in the above order.
+This builder is only available after using the tool 'qt'. Note: you can
+specify <filename>.ui</filename> files directly as source
+files to the <function xmlns="http://www.scons.org/dbxsd/v1.0">Program</function>,
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Library</function> and <function xmlns="http://www.scons.org/dbxsd/v1.0">SharedLibrary</function> builders
+without using this builder. Using this builder lets you override the standard
+naming conventions (be careful: prefixes are always prepended to names of
+built files; if you don't want prefixes, you may set them to ``).
+See the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-QTDIR"><envar>$QTDIR</envar></link> variable for more information.
+Example:
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Uic('foo.ui') # -&gt; ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
+env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
+        source = 'foo.ui') # -&gt; ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
+</example_commands>
+</listitem>
+  </varlistentry>
+  <varlistentry id="b-Zip">
+    <term>
+      <function>Zip()</function>
+    </term>
+    <term>
+      <function>env.Zip()</function>
+    </term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Builds a zip archive of the specified files
+and/or directories.
+Unlike most builder methods,
+the
+<function xmlns="http://www.scons.org/dbxsd/v1.0">Zip</function>
+builder method may be called multiple times
+for a given target;
+each additional call
+adds to the list of entries
+that will be built into the archive.
+Any source directories will
+be scanned for changes to
+any on-disk files,
+regardless of whether or not
+<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+knows about them from other Builder or function calls.
+</para>
+
+<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
+env.Zip('src.zip', 'src')
+
+# Create the stuff.zip file.
+env.Zip('stuff', ['subdir1', 'subdir2'])
+# Also add "another" to the stuff.tar file.
+env.Zip('stuff', 'another')
+</example_commands>
+</listitem>
+  </varlistentry>
+</variablelist>