Imported Upstream version 2.2.0upstream/2.2.0

1 files changed, 200 insertions, 0 deletions

diff --git a/src/engine/SCons/Tool/gettext.xml b/src/engine/SCons/Tool/gettext.xml
new file mode 100644
index 0000000..bd4dd0f
--- /dev/null
+++ b/src/engine/SCons/Tool/gettext.xml
@@ -0,0 +1,200 @@
+<!--
+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="gettext">
+<summary>
+This is actually a toolset, which supports internationalization and
+localization of sofware being constructed with SCons. The toolset loads
+following tools:
+
+<itemizedlist mark='opencircle'>
+  <listitem><para>
+    &t-link-xgettext; - to extract internationalized messages from source code to 
+    <literal>POT</literal> file(s),
+  </para></listitem>
+  <listitem><para>
+    &t-link-msginit; - may be optionally used to initialize <literal>PO</literal>
+    files,
+  </para></listitem>
+  <listitem><para>
+    &t-link-msgmerge; - to update <literal>PO</literal> files, that already contain
+    translated messages,</para></listitem>
+  <listitem><para>
+    &t-link-msgfmt; - to compile textual <literal>PO</literal> file to binary
+    installable <literal>MO</literal> file.
+  </para></listitem>
+</itemizedlist>
+
+When you enable &t-gettext;, it internally loads all abovementioned tools,
+so you're encouraged to see their individual documentation.
+
+Each of the above tools provides its own builder(s) which may be used to
+perform particular activities related to software internationalization. You
+may be however interested in <emphasis>top-level</emphasis> builder
+&b-Translate; described few paragraphs later.
+
+To use &t-gettext; tools add <literal>'gettext'</literal> tool to your
+environment:
+<example>
+  env = Environment( tools = ['default', 'gettext'] )
+</example>
+</summary>
+<sets>
+</sets>
+<uses>
+<!-- PLATFORM -->
+</uses>
+</tool>
+
+<builder name="Translate">
+<summary>
+This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts
+internationalized messages from source files, updates <literal>POT</literal>
+template (if necessary) and then updates <literal>PO</literal> translations (if
+necessary). If &cv-link-POAUTOINIT; is set, missing <literal>PO</literal> files
+will be automatically created (i.e. without translator person intervention).
+The variables &cv-link-LINGUAS_FILE; and &cv-link-POTDOMAIN; are taken into
+acount too. All other construction variables used by &b-link-POTUpdate;, and
+&b-link-POUpdate; work here too.
+
+<emphasis>Example 1</emphasis>.
+The simplest way is to specify input files and output languages inline in
+a SCons script when invoking &b-Translate;
+<example>
+# SConscript in 'po/' directory
+env = Environment( tools = ["default", "gettext"] )
+env['POAUTOINIT'] = 1
+env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) 
+</example>
+
+<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
+<example>
+# LINGUAS
+en pl 
+#end
+</example>
+
+<example>
+# POTFILES.in
+a.cpp
+b.cpp
+# end
+</example>
+
+<example>
+# SConscript
+env = Environment( tools = ["default", "gettext"] )
+env['POAUTOINIT'] = 1
+env['XGETTEXTPATH'] = ['../']
+env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') 
+</example>
+
+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.
+
+<emphasis>Example 3</emphasis>.
+Let's prepare a development tree as below
+<example>
+ project/
+  + SConstruct
+  + build/        
+  + src/
+      + po/
+          + SConscript
+          + SConscript.i18n
+          + POTFILES.in
+          + LINGUAS
+</example>
+with <filename>build</filename> being variant directory. Write the top-level
+<filename>SConstruct</filename> script as follows
+<example>
+  # 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>
+the <filename>src/po/SConscript.i18n</filename> as
+<example>
+  # src/po/SConscript.i18n
+  Import('env')
+  env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
+</example>
+and the <filename>src/po/SConscript</filename>
+<example>
+  # src/po/SConscript
+  Import('env')
+  env.MOFiles(LINGUAS_FILE = 1)
+</example>
+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).
+
+<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>
+
+</summary>
+</builder>
+
+<cvar name="POTDOMAIN">
+<summary>
+The &cv-POTDOMAIN; defines default domain, used to generate
+<literal>POT</literal> filename as <filename>&cv-POTDOMAIN;.pot</filename> when
+no <literal>POT</literal> file name is provided by the user. This applies to
+&b-link-POTUpdate;, &b-link-POInit; and &b-link-POUpdate; builders (and
+builders, that use them, e.g. &b-Translate;). Normally (if &cv-POTDOMAIN; is
+not defined), the builders use <filename>messages.pot</filename> as default
+<literal>POT</literal> file name.
+</summary>
+</cvar>
+
+<cvar name="POAUTOINIT">
+<summary>
+The &cv-POAUTOINIT; variable, if set to <literal>True</literal> (on non-zero
+numeric value), let the &t-link-msginit; tool to automatically initialize
+<emphasis>missing</emphasis> <literal>PO</literal> files with
+<command>msginit(1)</command>.  This applies to both,
+&b-link-POInit; and &b-link-POUpdate; builders (and others that use any of
+them).
+</summary>
+</cvar>
+
+<cvar name="LINGUAS_FILE">
+<summary>
+The &cv-LINGUAS_FILE; defines file(s) containing list of additional linguas
+to be processed by &b-link-POInit;, &b-link-POUpdate; or &b-link-MOFiles;
+builders. It also affects &b-link-Translate; builder. If the variable contains
+a string, it defines name of the list file. The &cv-LINGUAS_FILE; may be a
+list of file names as well. If &cv-LINGUAS_FILE; is set to
+<literal>True</literal> (or non-zero numeric value), the list will be read from
+default file named
+<filename>LINGUAS</filename>.
+
+</summary>
+</cvar>