SCons/Tool/msgmerge.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 __COPYRIGHT__
   4
   5 This file is processed by the bin/SConsDoc.py module.
   6 See its __doc__ string for a discussion of the format.
   7 -->
   8
   9 <!DOCTYPE sconsdoc [
  10 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  11 %scons;
  12 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  13 %builders-mod;
  14 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  15 %functions-mod;
  16 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  17 %tools-mod;
  18 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  19 %variables-mod;
  20 ]>
  21
  22 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  23           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  24           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  25
  26 <tool name="msgmerge">
  27 <summary>
  28 <para>
  29 This scons tool is a part of scons &t-link-gettext; toolset. It provides
  30 scons interface to <command>msgmerge(1)</command> command, which merges two
  31 Uniform style <filename>.po</filename> files together.
  32 </para>
  33 </summary>
  34 <sets>
  35 <item>MSGMERGE</item>
  36 <item>MSGMERGECOM </item>
  37 <item>MSGMERGECOMSTR</item>
  38 <item>MSGMERGEFLAGS</item>
  39 <item>POSUFFIX </item>
  40 <item>POTSUFFIX</item>
  41 <item>POUPDATE_ALIAS</item>
  42 </sets>
  43 <uses>
  44 <item>POTDOMAIN</item>
  45 <item>LINGUAS_FILE</item>
  46 <item>POAUTOINIT</item>
  47 </uses>
  48 </tool>
  49
  50 <builder name="POUpdate">
  51 <summary>
  52 <para>
  53 The builder belongs to &t-link-msgmerge; tool. The builder updates
  54 <literal>PO</literal> files with <command>msgmerge(1)</command>, or initializes
  55 missing <literal>PO</literal> files as described in documentation of
  56 &t-link-msginit; tool and &b-link-POInit; builder (see also
  57 &cv-link-POAUTOINIT;). Note, that &b-POUpdate; <emphasis>does not add its
  58 targets to <literal>po-create</literal> alias</emphasis> as &b-link-POInit;
  59 does.
  60 </para>
  61
  62 <para>
  63 Target nodes defined through &b-POUpdate; are not built by default
  64 (they're <literal>Ignore</literal>d from <literal>'.'</literal> node). Instead,
  65 they are added automatically to special <literal>Alias</literal>
  66 (<literal>'po-update'</literal> by default). The alias name may be changed
  67 through the &cv-link-POUPDATE_ALIAS; construction variable.  You can easily
  68 update <literal>PO</literal> files in your project by <command>scons
  69 po-update</command>.
  70 </para>
  71
  72 <para>
  73 <emphasis>Example 1.</emphasis>
  74 Update <filename>en.po</filename> and <filename>pl.po</filename> from
  75 <filename>messages.pot</filename> template (see also &cv-link-POTDOMAIN;),
  76 assuming that the later one exists or there is rule to build it (see
  77 &b-link-POTUpdate;):
  78 </para>
  79 <example_commands>
  80   # ...
  81   env.POUpdate(['en','pl']) # messages.pot --&gt; [en.po, pl.po]
  82 </example_commands>
  83
  84 <para>
  85 <emphasis>Example 2.</emphasis>
  86 Update <filename>en.po</filename> and <filename>pl.po</filename> from
  87 <filename>foo.pot</filename> template:
  88 </para>
  89 <example_commands>
  90   # ...
  91   env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --&gt;  [en.po, pl.pl]
  92 </example_commands>
  93
  94 <para>
  95 <emphasis>Example 3.</emphasis>
  96 Update <filename>en.po</filename> and <filename>pl.po</filename> from
  97 <filename>foo.pot</filename> (another version):
  98 </para>
  99 <example_commands>
 100   # ...
 101   env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- &gt; [en.po, pl.pl]
 102 </example_commands>
 103
 104 <para>
 105 <emphasis>Example 4.</emphasis>
 106 Update files for languages defined in <filename>LINGUAS</filename> file. The
 107 files are updated from <filename>messages.pot</filename> template:
 108 </para>
 109 <example_commands>
 110   # ...
 111   env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
 112 </example_commands>
 113
 114 <para>
 115 <emphasis>Example 5.</emphasis>
 116 Same as above, but update from <filename>foo.pot</filename> template:
 117 </para>
 118 <example_commands>
 119   # ...
 120   env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
 121 </example_commands>
 122
 123 <para>
 124 <emphasis>Example 6.</emphasis>
 125 Update <filename>en.po</filename> and <filename>pl.po</filename> plus files for
 126 languages defined in <filename>LINGUAS</filename> file. The files are updated
 127 from <filename>messages.pot</filename> template:
 128 </para>
 129 <example_commands>
 130   # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
 131   env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
 132 </example_commands>
 133
 134 <para>
 135 <emphasis>Example 7.</emphasis>
 136 Use &cv-link-POAUTOINIT; to automatically initialize <literal>PO</literal> file
 137 if it doesn't exist:
 138 </para>
 139 <example_commands>
 140   # ...
 141   env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
 142 </example_commands>
 143
 144 <para>
 145 <emphasis>Example 8.</emphasis>
 146 Update <literal>PO</literal> files for languages defined in
 147 <filename>LINGUAS</filename> file. The files are updated from
 148 <filename>foo.pot</filename> template. All necessary settings are
 149 pre-configured via environment.
 150 </para>
 151 <example_commands>
 152   # ...
 153   env['POAUTOINIT'] = 1
 154   env['LINGUAS_FILE'] = 1
 155   env['POTDOMAIN'] = 'foo'
 156   env.POUpdate()
 157 </example_commands>
 158
 159 </summary>
 160 </builder>
 161
 162 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 163 <cvar name="POUPDATE_ALIAS">
 164 <summary>
 165 <para>
 166 Common alias for all <literal>PO</literal> files being defined with
 167 &b-link-POUpdate; builder (default: <literal>'po-update'</literal>).
 168 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 169 </para>
 170 </summary>
 171 </cvar>
 172 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 173 <cvar name="MSGMERGE">
 174 <summary>
 175 <para>
 176 Absolute path to <command>msgmerge(1)</command> binary as found by
 177 <function>Detect()</function>.
 178 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 179 </para>
 180 </summary>
 181 </cvar>
 182 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 183 <cvar name="MSGMERGECOM">
 184 <summary>
 185 <para>
 186 Complete command line to run <command>msgmerge(1)</command> command.
 187 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 188 </para>
 189 </summary>
 190 </cvar>
 191 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 192 <cvar name="MSGMERGECOMSTR">
 193 <summary>
 194 <para>
 195 String to be displayed when <command>msgmerge(1)</command> is invoked
 196 (default: <literal>''</literal>, which means ``print &cv-link-MSGMERGECOM;'').
 197 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 198 </para>
 199 </summary>
 200 </cvar>
 201 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 202 <cvar name="MSGMERGEFLAGS">
 203 <summary>
 204 <para>
 205 Additional flags to <command>msgmerge(1)</command> command.
 206 See &t-link-msgmerge; tool and &b-link-POUpdate; builder.
 207 </para>
 208 </summary>
 209 </cvar>
 210
 211 </sconsdoc>