SCons/Tool/msgmerge.xml

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