Merge tag 'upstream/2.2.0'

Upstream version 2.2.0

1 files changed, 288 insertions, 0 deletions

diff --git a/src/engine/SCons/Tool/xgettext.xml b/src/engine/SCons/Tool/xgettext.xml
new file mode 100644
index 0000000..ec37ad1
--- /dev/null
+++ b/src/engine/SCons/Tool/xgettext.xml
@@ -0,0 +1,288 @@
+<!--
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 The SCons Foundation
+
+This file is processed by the bin/SConsDoc.py module.
+See its __doc__ string for a discussion of the format.
+-->
+<tool name="xgettext">
+<summary>
+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. 
+</summary>
+<sets>
+POTSUFFIX
+POTUPDATE_ALIAS
+XGETTEXTCOM
+XGETTEXTCOMSTR
+XGETTEXTFLAGS
+XGETTEXTFROM
+XGETTEXTFROMPREFIX
+XGETTEXTFROMSUFFIX
+XGETTEXTPATH
+XGETTEXTPATHPREFIX
+XGETTEXTPATHSUFFIX
+_XGETTEXTDOMAIN
+_XGETTEXTFROMFLAGS
+_XGETTEXTPATHFLAGS
+</sets>
+<uses>
+POTDOMAIN
+</uses>
+</tool>
+
+<builder name="POTUpdate">
+<summary>
+The builder belongs to &t-link-xgettext; tool. The builder updates target
+<literal>POT</literal> file if exists or creates one if it doesn't. The node is
+not built by default (i.e. it is <literal>Ignore</literal>d from
+<literal>'.'</literal>), but only on demand (i.e.  when given
+<literal>POT</literal> file is required or when special alias is invoked). This
+builder adds its targe node (<filename>messages.pot</filename>, say) to a
+special alias (<literal>pot-update</literal> by default, see
+&cv-link-POTUPDATE_ALIAS;) so you can update/create them easily with
+<command>scons pot-update</command>. The file is not written until there is no
+real change in internationalized messages (or in comments that enter
+<literal>POT</literal> file). 
+
+<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
+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>
+
+<emphasis>Example 1.</emphasis>
+Let's create <filename>po/</filename> directory and place following
+<filename>SConstruct</filename> script there:
+<example>
+  # SConstruct in 'po/' subdir
+  env = Environment( tools = ['default', 'xgettext'] )
+  env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
+  env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
+</example>      
+Then invoke scons few times:
+<example>
+  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>
+the results shall be as the comments above say.
+
+<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>    
+  # 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>
+
+<emphasis>Example 3.</emphasis>
+The sources may be specified within separate file, for example
+<filename>POTFILES.in</filename>:
+<example>      
+  # POTFILES.in in 'po/' subdirectory
+  ../a.cpp
+  ../b.cpp
+  # end of file
+</example>    
+The name of the file (<filename>POTFILES.in</filename>) containing the list of
+sources is provided via &cv-link-XGETTEXTFROM;:
+<example>      
+  # SConstruct file in 'po/' subdirectory
+  env = Environment( tools = ['default', 'xgettext'] )
+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
+</example>    
+
+<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>
+  # POTFILES.in in 'po/' subdirectory
+  a.cpp
+  b.cpp
+  # end of file
+</example>
+
+<example>
+  # SConstruct file in 'po/' subdirectory
+  env = Environment( tools = ['default', 'xgettext'] )
+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
+</example>
+
+<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.
+
+Let's create <filename>0/1/po/SConstruct</filename> script:
+<example>
+  # SConstruct file in '0/1/po/' subdirectory
+  env = Environment( tools = ['default', 'xgettext'] )
+  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
+</example>
+and <filename>0/1/po/POTFILES.in</filename>:
+<example>
+  # POTFILES.in in '0/1/po/' subdirectory
+  a.cpp
+  # end of file
+</example>
+Write two <filename>*.cpp</filename> files, the first one is
+<filename>0/a.cpp</filename>:
+<example>
+  /* 0/a.cpp */
+  gettext("Hello from ../../a.cpp")
+</example>
+and the second is <filename>0/1/a.cpp</filename>:
+<example>
+  /* 0/1/a.cpp */
+  gettext("Hello from ../a.cpp")
+</example>
+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>
+  # 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
+<literal>msgid "Hello from ../../a.cpp"</literal> line and not 
+<literal>msgid "Hello from ../a.cpp"</literal>.
+
+</summary>
+
+</builder>
+
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="POTSUFFIX">
+<summary>
+Suffix used for PO Template files (default: <literal>'.pot'</literal>).
+See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="POTUPDATE_ALIAS">
+<summary>
+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.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXT">
+<summary>
+Path to <command>xgettext(1)</command> program (found via
+<function>Detect()</function>).
+See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTCOM">
+<summary>
+Complete xgettext command line.
+See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTCOMSTR">
+<summary>
+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.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTFLAGS">
+<summary>
+Additional flags to <command>xgettext(1)</command>.
+See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTFROM">
+<summary>
+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.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTPATH">
+<summary>
+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.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTPATHPREFIX">
+<summary>
+This flag is used to add single search path to
+<command>xgettext(1)</command>'s commandline (default:
+<literal>'-D'</literal>).
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTPATHSUFFIX">
+<summary>
+(default: <literal>''</literal>)
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTFROMPREFIX">
+<summary>
+This flag is used to add single &cv-link-XGETTEXTFROM; file to
+<command>xgettext(1)</command>'s commandline (default:
+<literal>'-f'</literal>).
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="XGETTEXTFROMSUFFIX">
+<summary>
+(default: <literal>''</literal>)
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="_XGETTEXTDOMAIN">
+<summary>
+Internal "macro". Generates <command>xgettext</command> domain name
+form source and target (default: <literal>'${TARGET.filebase}'</literal>).
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="_XGETTEXTFROMFLAGS">
+<summary>
+Internal "macro". Genrates list of <literal>-D&lt;dir&gt;</literal> flags
+from the &cv-link-XGETTEXTPATH; list.
+</summary>
+</cvar>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<cvar name="_XGETTEXTPATHFLAGS">
+<summary>
+Internal "macro". Generates list of <literal>-f&lt;file&gt;</literal> flags
+from &cv-link-XGETTEXTFROM;.
+</summary>
+</cvar>
+
+<!--
+
+-->