Imported Upstream version 2.3.1upstream/2.3.1

1 files changed, 126 insertions, 41 deletions

diff --git a/src/engine/SCons/Tool/xgettext.xml b/src/engine/SCons/Tool/xgettext.xml
index 4e652c3..8f64a7c 100644
--- a/src/engine/SCons/Tool/xgettext.xml
+++ b/src/engine/SCons/Tool/xgettext.xml
@@ -1,40 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <!--
-Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
 
 This file is processed by the bin/SConsDoc.py module.
 See its __doc__ string for a discussion of the format.
 -->
+
+<!DOCTYPE sconsdoc [
+<!ENTITY % scons SYSTEM '../../../../doc/scons.mod'>
+%scons;
+<!ENTITY % builders-mod SYSTEM '../../../../doc/generated/builders.mod'>
+%builders-mod;
+<!ENTITY % functions-mod SYSTEM '../../../../doc/generated/functions.mod'>
+%functions-mod;
+<!ENTITY % tools-mod SYSTEM '../../../../doc/generated/tools.mod'>
+%tools-mod;
+<!ENTITY % variables-mod SYSTEM '../../../../doc/generated/variables.mod'>
+%variables-mod;
+]>
+
+<sconsdoc 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">
+
 <tool name="xgettext">
 <summary>
+<para>
 This scons tool is a part of scons &t-link-gettext; toolset. It provides
 scons interface to <command>xgettext(1)</command>
 program, which extracts internationalized messages from source code. The tool
 provides &b-POTUpdate; builder to make  <literal>PO</literal>
 <emphasis>Template</emphasis> files. 
+</para>
 </summary>
 <sets>
-POTSUFFIX
-POTUPDATE_ALIAS
-XGETTEXTCOM
-XGETTEXTCOMSTR
-XGETTEXTFLAGS
-XGETTEXTFROM
-XGETTEXTFROMPREFIX
-XGETTEXTFROMSUFFIX
-XGETTEXTPATH
-XGETTEXTPATHPREFIX
-XGETTEXTPATHSUFFIX
-_XGETTEXTDOMAIN
-_XGETTEXTFROMFLAGS
-_XGETTEXTPATHFLAGS
+<item>POTSUFFIX</item>
+<item>POTUPDATE_ALIAS</item>
+<item>XGETTEXTCOM</item>
+<item>XGETTEXTCOMSTR</item>
+<item>XGETTEXTFLAGS</item>
+<item>XGETTEXTFROM</item>
+<item>XGETTEXTFROMPREFIX</item>
+<item>XGETTEXTFROMSUFFIX</item>
+<item>XGETTEXTPATH</item>
+<item>XGETTEXTPATHPREFIX</item>
+<item>XGETTEXTPATHSUFFIX</item>
+<item>_XGETTEXTDOMAIN</item>
+<item>_XGETTEXTFROMFLAGS</item>
+<item>_XGETTEXTPATHFLAGS</item>
 </sets>
 <uses>
-POTDOMAIN
+<item>POTDOMAIN</item>
 </uses>
 </tool>
 
 <builder name="POTUpdate">
 <summary>
+<para>
 The builder belongs to &t-link-xgettext; tool. The builder updates target
 <literal>POT</literal> file if exists or creates one if it doesn't. The node is
 not built by default (i.e. it is <literal>Ignore</literal>d from
@@ -46,7 +68,9 @@ special alias (<literal>pot-update</literal> by default, see
 <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>
 <note> <para>You may see <command>xgettext(1)</command> being invoked by the
 &t-link-xgettext; tool even if there is no real change in internationalized
 messages (so the <literal>POT</literal> file is not being updated).  This
@@ -54,235 +78,296 @@ 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>
 <emphasis>Example 1.</emphasis>
 Let's create <filename>po/</filename> directory and place following
 <filename>SConstruct</filename> script there:
-<example>
+</para>
+<example_commands>
   # SConstruct in 'po/' subdir
   env = Environment( tools = ['default', 'xgettext'] )
   env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
   env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
-</example>      
+</example_commands>      
+<para>
 Then invoke scons few times:
-<example>
+</para>
+<example_commands>
   user@host:$ scons             # Does not create foo.pot nor bar.pot
   user@host:$ scons foo.pot     # Updates or creates foo.pot
   user@host:$ scons pot-update  # Updates or creates foo.pot and bar.pot
   user@host:$ scons -c          # Does not clean foo.pot nor bar.pot.
-</example>
+</example_commands>
+<para>
 the results shall be as the comments above say.
+</para>
 
+<para>
 <emphasis>Example 2.</emphasis>
 The &b-POTUpdate; builder may be used with no target specified, in which
 case default target <filename>messages.pot</filename> will be used. The
 default target may also be overriden by setting &cv-link-POTDOMAIN; construction
 variable or providing it as an override to &b-POTUpdate; builder:
-<example>    
+</para>
+<example_commands>    
   # SConstruct script
   env = Environment( tools = ['default', 'xgettext'] )
   env['POTDOMAIN'] = "foo"
   env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
   env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
-</example>
+</example_commands>
 
+<para>
 <emphasis>Example 3.</emphasis>
 The sources may be specified within separate file, for example
 <filename>POTFILES.in</filename>:
-<example>      
+</para>
+<example_commands>      
   # POTFILES.in in 'po/' subdirectory
   ../a.cpp
   ../b.cpp
   # end of file
-</example>    
+</example_commands>    
+<para>
 The name of the file (<filename>POTFILES.in</filename>) containing the list of
 sources is provided via &cv-link-XGETTEXTFROM;:
-<example>      
+</para>
+<example_commands>      
   # SConstruct file in 'po/' subdirectory
   env = Environment( tools = ['default', 'xgettext'] )
   env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
-</example>    
+</example_commands>    
 
+<para>
 <emphasis>Example 4.</emphasis>
 You may use &cv-link-XGETTEXTPATH; to define source search path. Assume, for
 example, that you have files <filename>a.cpp</filename>,
 <filename>b.cpp</filename>, <filename>po/SConstruct</filename>,
 <filename>po/POTFILES.in</filename>. Then your <literal>POT</literal>-related
 files could look as below:
-<example>
+</para>
+<example_commands>
   # POTFILES.in in 'po/' subdirectory
   a.cpp
   b.cpp
   # end of file
-</example>
+</example_commands>
 
-<example>
+<example_commands>
   # SConstruct file in 'po/' subdirectory
   env = Environment( tools = ['default', 'xgettext'] )
   env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
-</example>
+</example_commands>
 
+<para>
 <emphasis>Example 5.</emphasis>
 Multiple search directories may be defined within a list, i.e.
 <literal>XGETTEXTPATH = ['dir1', 'dir2', ...]</literal>. The order in the list
 determines the search order of source files. The path to the first file found
 is used.
+</para>
 
+<para>
 Let's create <filename>0/1/po/SConstruct</filename> script:
-<example>
+</para>
+<example_commands>
   # SConstruct file in '0/1/po/' subdirectory
   env = Environment( tools = ['default', 'xgettext'] )
   env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
-</example>
+</example_commands>
+<para>
 and <filename>0/1/po/POTFILES.in</filename>:
-<example>
+</para>
+<example_commands>
   # POTFILES.in in '0/1/po/' subdirectory
   a.cpp
   # end of file
-</example>
+</example_commands>
+<para>
 Write two <filename>*.cpp</filename> files, the first one is
 <filename>0/a.cpp</filename>:
-<example>
+</para>
+<example_commands>
   /* 0/a.cpp */
   gettext("Hello from ../../a.cpp")
-</example>
+</example_commands>
+<para>
 and the second is <filename>0/1/a.cpp</filename>:
-<example>
+</para>
+<example_commands>
   /* 0/1/a.cpp */
   gettext("Hello from ../a.cpp")
-</example>
+</example_commands>
+<para>
 then run scons. You'll obtain <literal>0/1/po/messages.pot</literal> with the
 message <literal>"Hello from ../a.cpp"</literal>. When you reverse order in
 <varname>$XGETTEXTFOM</varname>, i.e. when you write SConscript as
-<example>
+</para>
+<example_commands>
   # SConstruct file in '0/1/po/' subdirectory
   env = Environment( tools = ['default', 'xgettext'] )
   env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
-</example> then the <filename>messages.pot</filename> will contain
+</example_commands> 
+<para>
+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>
 
 </summary>
-
 </builder>
 
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="POTSUFFIX">
 <summary>
+<para>
 Suffix used for PO Template files (default: <literal>'.pot'</literal>).
 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="POTUPDATE_ALIAS">
 <summary>
+<para>
 Name of the common phony target for all PO Templates created with
 &b-link-POUpdate; (default: <literal>'pot-update'</literal>).
 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXT">
 <summary>
+<para>
 Path to <command>xgettext(1)</command> program (found via
 <function>Detect()</function>).
 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTCOM">
 <summary>
+<para>
 Complete xgettext command line.
 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTCOMSTR">
 <summary>
+<para>
 A string that is shown when <command>xgettext(1)</command> command is invoked
 (default: <literal>''</literal>, which means "print &cv-link-XGETTEXTCOM;").
 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTFLAGS">
 <summary>
+<para>
 Additional flags to <command>xgettext(1)</command>.
 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTFROM">
 <summary>
+<para>
 Name of file containing list of <command>xgettext(1)</command>'s source
 files. Autotools' users know this as <filename>POTFILES.in</filename> so they
 will in most cases set <literal>XGETTEXTFROM="POTFILES.in"</literal> here.
 The &cv-XGETTEXTFROM; files have same syntax and semantics as the well known
 GNU <filename>POTFILES.in</filename>.
 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTPATH">
 <summary>
+<para>
 List of directories, there <command>xgettext(1)</command> will look for
 source files (default: <literal>[]</literal>).
 <note><para>
 This variable works only together with &cv-link-XGETTEXTFROM;
 </para></note>
 See also &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTPATHPREFIX">
 <summary>
+<para>
 This flag is used to add single search path to
 <command>xgettext(1)</command>'s commandline (default:
 <literal>'-D'</literal>).
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTPATHSUFFIX">
 <summary>
+<para>
 (default: <literal>''</literal>)
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTFROMPREFIX">
 <summary>
+<para>
 This flag is used to add single &cv-link-XGETTEXTFROM; file to
 <command>xgettext(1)</command>'s commandline (default:
 <literal>'-f'</literal>).
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="XGETTEXTFROMSUFFIX">
 <summary>
+<para>
 (default: <literal>''</literal>)
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="_XGETTEXTDOMAIN">
 <summary>
+<para>
 Internal "macro". Generates <command>xgettext</command> domain name
 form source and target (default: <literal>'${TARGET.filebase}'</literal>).
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="_XGETTEXTFROMFLAGS">
 <summary>
+<para>
 Internal "macro". Genrates list of <literal>-D&lt;dir&gt;</literal> flags
 from the &cv-link-XGETTEXTPATH; list.
+</para>
 </summary>
 </cvar>
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <cvar name="_XGETTEXTPATHFLAGS">
 <summary>
+<para>
 Internal "macro". Generates list of <literal>-f&lt;file&gt;</literal> flags
 from &cv-link-XGETTEXTFROM;.
+</para>
 </summary>
 </cvar>
 
 <!--
 
 -->
+
+</sconsdoc>
\ No newline at end of file