SCons/Tool/xgettext.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="xgettext">
  27 <summary>
  28 <para>
  29 This scons tool is a part of scons &t-link-gettext; toolset. It provides
  30 scons interface to <command>xgettext(1)</command>
  31 program, which extracts internationalized messages from source code. The tool
  32 provides &b-POTUpdate; builder to make  <literal>PO</literal>
  33 <emphasis>Template</emphasis> files.
  34 </para>
  35 </summary>
  36 <sets>
  37 <item>POTSUFFIX</item>
  38 <item>POTUPDATE_ALIAS</item>
  39 <item>XGETTEXTCOM</item>
  40 <item>XGETTEXTCOMSTR</item>
  41 <item>XGETTEXTFLAGS</item>
  42 <item>XGETTEXTFROM</item>
  43 <item>XGETTEXTFROMPREFIX</item>
  44 <item>XGETTEXTFROMSUFFIX</item>
  45 <item>XGETTEXTPATH</item>
  46 <item>XGETTEXTPATHPREFIX</item>
  47 <item>XGETTEXTPATHSUFFIX</item>
  48 <item>_XGETTEXTDOMAIN</item>
  49 <item>_XGETTEXTFROMFLAGS</item>
  50 <item>_XGETTEXTPATHFLAGS</item>
  51 </sets>
  52 <uses>
  53 <item>POTDOMAIN</item>
  54 </uses>
  55 </tool>
  56
  57 <builder name="POTUpdate">
  58 <summary>
  59 <para>
  60 The builder belongs to &t-link-xgettext; tool. The builder updates target
  61 <literal>POT</literal> file if exists or creates one if it doesn't. The node is
  62 not built by default (i.e. it is <literal>Ignore</literal>d from
  63 <literal>'.'</literal>), but only on demand (i.e.  when given
  64 <literal>POT</literal> file is required or when special alias is invoked). This
  65 builder adds its targe node (<filename>messages.pot</filename>, say) to a
  66 special alias (<literal>pot-update</literal> by default, see
  67 &cv-link-POTUPDATE_ALIAS;) so you can update/create them easily with
  68 <command>scons pot-update</command>. The file is not written until there is no
  69 real change in internationalized messages (or in comments that enter
  70 <literal>POT</literal> file).
  71 </para>
  72
  73 <para>
  74 <note> <para>You may see <command>xgettext(1)</command> being invoked by the
  75 &t-link-xgettext; tool even if there is no real change in internationalized
  76 messages (so the <literal>POT</literal> file is not being updated).  This
  77 happens every time  a source file has changed. In such case we invoke
  78 <command>xgettext(1)</command> and compare its output with the content of
  79 <literal>POT</literal> file to decide whether the file should be updated or
  80 not.</para></note>
  81 </para>
  82
  83 <para>
  84 <emphasis>Example 1.</emphasis>
  85 Let's create <filename>po/</filename> directory and place following
  86 <filename>SConstruct</filename> script there:
  87 </para>
  88 <example_commands>
  89   # SConstruct in 'po/' subdir
  90   env = Environment( tools = ['default', 'xgettext'] )
  91   env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
  92   env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
  93 </example_commands>
  94 <para>
  95 Then invoke scons few times:
  96 </para>
  97 <example_commands>
  98   user@host:$ scons             # Does not create foo.pot nor bar.pot
  99   user@host:$ scons foo.pot     # Updates or creates foo.pot
 100   user@host:$ scons pot-update  # Updates or creates foo.pot and bar.pot
 101   user@host:$ scons -c          # Does not clean foo.pot nor bar.pot.
 102 </example_commands>
 103 <para>
 104 the results shall be as the comments above say.
 105 </para>
 106
 107 <para>
 108 <emphasis>Example 2.</emphasis>
 109 The &b-POTUpdate; builder may be used with no target specified, in which
 110 case default target <filename>messages.pot</filename> will be used. The
 111 default target may also be overridden by setting &cv-link-POTDOMAIN; construction
 112 variable or providing it as an override to &b-POTUpdate; builder:
 113 </para>
 114 <example_commands>
 115   # SConstruct script
 116   env = Environment( tools = ['default', 'xgettext'] )
 117   env['POTDOMAIN'] = "foo"
 118   env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
 119   env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
 120 </example_commands>
 121
 122 <para>
 123 <emphasis>Example 3.</emphasis>
 124 The sources may be specified within separate file, for example
 125 <filename>POTFILES.in</filename>:
 126 </para>
 127 <example_commands>
 128   # POTFILES.in in 'po/' subdirectory
 129   ../a.cpp
 130   ../b.cpp
 131   # end of file
 132 </example_commands>
 133 <para>
 134 The name of the file (<filename>POTFILES.in</filename>) containing the list of
 135 sources is provided via &cv-link-XGETTEXTFROM;:
 136 </para>
 137 <example_commands>
 138   # SConstruct file in 'po/' subdirectory
 139   env = Environment( tools = ['default', 'xgettext'] )
 140   env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
 141 </example_commands>
 142
 143 <para>
 144 <emphasis>Example 4.</emphasis>
 145 You may use &cv-link-XGETTEXTPATH; to define source search path. Assume, for
 146 example, that you have files <filename>a.cpp</filename>,
 147 <filename>b.cpp</filename>, <filename>po/SConstruct</filename>,
 148 <filename>po/POTFILES.in</filename>. Then your <literal>POT</literal>-related
 149 files could look as below:
 150 </para>
 151 <example_commands>
 152   # POTFILES.in in 'po/' subdirectory
 153   a.cpp
 154   b.cpp
 155   # end of file
 156 </example_commands>
 157
 158 <example_commands>
 159   # SConstruct file in 'po/' subdirectory
 160   env = Environment( tools = ['default', 'xgettext'] )
 161   env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
 162 </example_commands>
 163
 164 <para>
 165 <emphasis>Example 5.</emphasis>
 166 Multiple search directories may be defined within a list, i.e.
 167 <literal>XGETTEXTPATH = ['dir1', 'dir2', ...]</literal>. The order in the list
 168 determines the search order of source files. The path to the first file found
 169 is used.
 170 </para>
 171
 172 <para>
 173 Let's create <filename>0/1/po/SConstruct</filename> script:
 174 </para>
 175 <example_commands>
 176   # SConstruct file in '0/1/po/' subdirectory
 177   env = Environment( tools = ['default', 'xgettext'] )
 178   env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
 179 </example_commands>
 180 <para>
 181 and <filename>0/1/po/POTFILES.in</filename>:
 182 </para>
 183 <example_commands>
 184   # POTFILES.in in '0/1/po/' subdirectory
 185   a.cpp
 186   # end of file
 187 </example_commands>
 188 <para>
 189 Write two <filename>*.cpp</filename> files, the first one is
 190 <filename>0/a.cpp</filename>:
 191 </para>
 192 <example_commands>
 193   /* 0/a.cpp */
 194   gettext("Hello from ../../a.cpp")
 195 </example_commands>
 196 <para>
 197 and the second is <filename>0/1/a.cpp</filename>:
 198 </para>
 199 <example_commands>
 200   /* 0/1/a.cpp */
 201   gettext("Hello from ../a.cpp")
 202 </example_commands>
 203 <para>
 204 then run scons. You'll obtain <literal>0/1/po/messages.pot</literal> with the
 205 message <literal>"Hello from ../a.cpp"</literal>. When you reverse order in
 206 <varname>$XGETTEXTFOM</varname>, i.e. when you write SConscript as
 207 </para>
 208 <example_commands>
 209   # SConstruct file in '0/1/po/' subdirectory
 210   env = Environment( tools = ['default', 'xgettext'] )
 211   env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
 212 </example_commands>
 213 <para>
 214 then the <filename>messages.pot</filename> will contain
 215 <literal>msgid "Hello from ../../a.cpp"</literal> line and not
 216 <literal>msgid "Hello from ../a.cpp"</literal>.
 217 </para>
 218
 219 </summary>
 220 </builder>
 221
 222 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 223 <cvar name="POTSUFFIX">
 224 <summary>
 225 <para>
 226 Suffix used for PO Template files (default: <literal>'.pot'</literal>).
 227 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 228 </para>
 229 </summary>
 230 </cvar>
 231 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 232 <cvar name="POTUPDATE_ALIAS">
 233 <summary>
 234 <para>
 235 Name of the common phony target for all PO Templates created with
 236 &b-link-POUpdate; (default: <literal>'pot-update'</literal>).
 237 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 238 </para>
 239 </summary>
 240 </cvar>
 241 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 242 <cvar name="XGETTEXT">
 243 <summary>
 244 <para>
 245 Path to <command>xgettext(1)</command> program (found via
 246 <function>Detect()</function>).
 247 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 248 </para>
 249 </summary>
 250 </cvar>
 251 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 252 <cvar name="XGETTEXTCOM">
 253 <summary>
 254 <para>
 255 Complete xgettext command line.
 256 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 257 </para>
 258 </summary>
 259 </cvar>
 260 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 261 <cvar name="XGETTEXTCOMSTR">
 262 <summary>
 263 <para>
 264 A string that is shown when <command>xgettext(1)</command> command is invoked
 265 (default: <literal>''</literal>, which means "print &cv-link-XGETTEXTCOM;").
 266 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 267 </para>
 268 </summary>
 269 </cvar>
 270 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 271 <cvar name="XGETTEXTFLAGS">
 272 <summary>
 273 <para>
 274 Additional flags to <command>xgettext(1)</command>.
 275 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 276 </para>
 277 </summary>
 278 </cvar>
 279 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 280 <cvar name="XGETTEXTFROM">
 281 <summary>
 282 <para>
 283 Name of file containing list of <command>xgettext(1)</command>'s source
 284 files. Autotools' users know this as <filename>POTFILES.in</filename> so they
 285 will in most cases set <literal>XGETTEXTFROM="POTFILES.in"</literal> here.
 286 The &cv-XGETTEXTFROM; files have same syntax and semantics as the well known
 287 GNU <filename>POTFILES.in</filename>.
 288 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 289 </para>
 290 </summary>
 291 </cvar>
 292 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 293 <cvar name="XGETTEXTPATH">
 294 <summary>
 295 <para>
 296 List of directories, there <command>xgettext(1)</command> will look for
 297 source files (default: <literal>[]</literal>).
 298 <note><para>
 299 This variable works only together with &cv-link-XGETTEXTFROM;
 300 </para></note>
 301 See also &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 302 </para>
 303 </summary>
 304 </cvar>
 305 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 306 <cvar name="XGETTEXTPATHPREFIX">
 307 <summary>
 308 <para>
 309 This flag is used to add single search path to
 310 <command>xgettext(1)</command>'s commandline (default:
 311 <literal>'-D'</literal>).
 312 </para>
 313 </summary>
 314 </cvar>
 315 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 316 <cvar name="XGETTEXTPATHSUFFIX">
 317 <summary>
 318 <para>
 319 (default: <literal>''</literal>)
 320 </para>
 321 </summary>
 322 </cvar>
 323 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 324 <cvar name="XGETTEXTFROMPREFIX">
 325 <summary>
 326 <para>
 327 This flag is used to add single &cv-link-XGETTEXTFROM; file to
 328 <command>xgettext(1)</command>'s commandline (default:
 329 <literal>'-f'</literal>).
 330 </para>
 331 </summary>
 332 </cvar>
 333 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 334 <cvar name="XGETTEXTFROMSUFFIX">
 335 <summary>
 336 <para>
 337 (default: <literal>''</literal>)
 338 </para>
 339 </summary>
 340 </cvar>
 341 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 342 <cvar name="_XGETTEXTDOMAIN">
 343 <summary>
 344 <para>
 345 Internal "macro". Generates <command>xgettext</command> domain name
 346 form source and target (default: <literal>'${TARGET.filebase}'</literal>).
 347 </para>
 348 </summary>
 349 </cvar>
 350 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 351 <cvar name="_XGETTEXTFROMFLAGS">
 352 <summary>
 353 <para>
 354 Internal "macro". Genrates list of <literal>-D&lt;dir&gt;</literal> flags
 355 from the &cv-link-XGETTEXTPATH; list.
 356 </para>
 357 </summary>
 358 </cvar>
 359 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 360 <cvar name="_XGETTEXTPATHFLAGS">
 361 <summary>
 362 <para>
 363 Internal "macro". Generates list of <literal>-f&lt;file&gt;</literal> flags
 364 from &cv-link-XGETTEXTFROM;.
 365 </para>
 366 </summary>
 367 </cvar>
 368
 369 <!--
 370
 371 -->
 372
 373 </sconsdoc>