mingw/share/doc/gettext/gettext_5.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.52b
   4      from gettext.texi on 6 June 2010 -->
   5
   6 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
   7 <TITLE>GNU gettext utilities - 5  Making the PO Template File</TITLE>
   8 </HEAD>
   9 <BODY>
  10 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_4.html">previous</A>, <A HREF="gettext_6.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
  11 <P><HR><P>
  12
  13
  14 <H1><A NAME="SEC27" HREF="gettext_toc.html#TOC27">5  Making the PO Template File</A></H1>
  15 <P>
  16 <A NAME="IDX158"></A>
  17
  18 </P>
  19 <P>
  20 After preparing the sources, the programmer creates a PO template file.
  21 This section explains how to use <CODE>xgettext</CODE> for this purpose.
  22
  23 </P>
  24 <P>
  25 <CODE>xgettext</CODE> creates a file named <TT>&lsquo;<VAR>domainname</VAR>.po&rsquo;</TT>.  You
  26 should then rename it to <TT>&lsquo;<VAR>domainname</VAR>.pot&rsquo;</TT>.  (Why doesn't
  27 <CODE>xgettext</CODE> create it under the name <TT>&lsquo;<VAR>domainname</VAR>.pot&rsquo;</TT>
  28 right away?  The answer is: for historical reasons.  When <CODE>xgettext</CODE>
  29 was specified, the distinction between a PO file and PO file template
  30 was fuzzy, and the suffix <SAMP>&lsquo;.pot&rsquo;</SAMP> wasn't in use at that time.)
  31
  32 </P>
  33
  34
  35
  36 <H2><A NAME="SEC28" HREF="gettext_toc.html#TOC28">5.1  Invoking the <CODE>xgettext</CODE> Program</A></H2>
  37
  38 <P>
  39 <A NAME="IDX159"></A>
  40 <A NAME="IDX160"></A>
  41
  42 <PRE>
  43 xgettext [<VAR>option</VAR>] [<VAR>inputfile</VAR>] ...
  44 </PRE>
  45
  46 <P>
  47 The <CODE>xgettext</CODE> program extracts translatable strings from given
  48 input files.
  49
  50 </P>
  51
  52
  53 <H3><A NAME="SEC29" HREF="gettext_toc.html#TOC29">5.1.1  Input file location</A></H3>
  54
  55 <DL COMPACT>
  56
  57 <DT><SAMP>&lsquo;<VAR>inputfile</VAR> ...&rsquo;</SAMP>
  58 <DD>
  59 Input files.
  60
  61 <DT><SAMP>&lsquo;-f <VAR>file</VAR>&rsquo;</SAMP>
  62 <DD>
  63 <DT><SAMP>&lsquo;--files-from=<VAR>file</VAR>&rsquo;</SAMP>
  64 <DD>
  65 <A NAME="IDX161"></A>
  66 <A NAME="IDX162"></A>
  67 Read the names of the input files from <VAR>file</VAR> instead of getting
  68 them from the command line.
  69
  70 <DT><SAMP>&lsquo;-D <VAR>directory</VAR>&rsquo;</SAMP>
  71 <DD>
  72 <DT><SAMP>&lsquo;--directory=<VAR>directory</VAR>&rsquo;</SAMP>
  73 <DD>
  74 <A NAME="IDX163"></A>
  75 <A NAME="IDX164"></A>
  76 Add <VAR>directory</VAR> to the list of directories.  Source files are
  77 searched relative to this list of directories.  The resulting <TT>&lsquo;.po&rsquo;</TT>
  78 file will be written relative to the current directory, though.
  79
  80 </DL>
  81
  82 <P>
  83 If <VAR>inputfile</VAR> is <SAMP>&lsquo;-&rsquo;</SAMP>, standard input is read.
  84
  85 </P>
  86
  87
  88 <H3><A NAME="SEC30" HREF="gettext_toc.html#TOC30">5.1.2  Output file location</A></H3>
  89
  90 <DL COMPACT>
  91
  92 <DT><SAMP>&lsquo;-d <VAR>name</VAR>&rsquo;</SAMP>
  93 <DD>
  94 <DT><SAMP>&lsquo;--default-domain=<VAR>name</VAR>&rsquo;</SAMP>
  95 <DD>
  96 <A NAME="IDX165"></A>
  97 <A NAME="IDX166"></A>
  98 Use <TT>&lsquo;<VAR>name</VAR>.po&rsquo;</TT> for output (instead of <TT>&lsquo;messages.po&rsquo;</TT>).
  99
 100 <DT><SAMP>&lsquo;-o <VAR>file</VAR>&rsquo;</SAMP>
 101 <DD>
 102 <DT><SAMP>&lsquo;--output=<VAR>file</VAR>&rsquo;</SAMP>
 103 <DD>
 104 <A NAME="IDX167"></A>
 105 <A NAME="IDX168"></A>
 106 Write output to specified file (instead of <TT>&lsquo;<VAR>name</VAR>.po&rsquo;</TT> or
 107 <TT>&lsquo;messages.po&rsquo;</TT>).
 108
 109 <DT><SAMP>&lsquo;-p <VAR>dir</VAR>&rsquo;</SAMP>
 110 <DD>
 111 <DT><SAMP>&lsquo;--output-dir=<VAR>dir</VAR>&rsquo;</SAMP>
 112 <DD>
 113 <A NAME="IDX169"></A>
 114 <A NAME="IDX170"></A>
 115 Output files will be placed in directory <VAR>dir</VAR>.
 116
 117 </DL>
 118
 119 <P>
 120 <A NAME="IDX171"></A>
 121 If the output <VAR>file</VAR> is <SAMP>&lsquo;-&rsquo;</SAMP> or <SAMP>&lsquo;/dev/stdout&rsquo;</SAMP>, the output
 122 is written to standard output.
 123
 124 </P>
 125
 126
 127 <H3><A NAME="SEC31" HREF="gettext_toc.html#TOC31">5.1.3  Choice of input file language</A></H3>
 128
 129 <DL COMPACT>
 130
 131 <DT><SAMP>&lsquo;-L <VAR>name</VAR>&rsquo;</SAMP>
 132 <DD>
 133 <DT><SAMP>&lsquo;--language=<VAR>name</VAR>&rsquo;</SAMP>
 134 <DD>
 135 <A NAME="IDX172"></A>
 136 <A NAME="IDX173"></A>
 137 <A NAME="IDX174"></A>
 138 Specifies the language of the input files.  The supported languages
 139 are <CODE>C</CODE>, <CODE>C++</CODE>, <CODE>ObjectiveC</CODE>, <CODE>PO</CODE>, <CODE>Python</CODE>,
 140 <CODE>Lisp</CODE>, <CODE>EmacsLisp</CODE>, <CODE>librep</CODE>, <CODE>Scheme</CODE>, <CODE>Smalltalk</CODE>,
 141 <CODE>Java</CODE>, <CODE>JavaProperties</CODE>, <CODE>C#</CODE>, <CODE>awk</CODE>, <CODE>YCP</CODE>,
 142 <CODE>Tcl</CODE>, <CODE>Perl</CODE>, <CODE>PHP</CODE>, <CODE>GCC-source</CODE>, <CODE>NXStringTable</CODE>,
 143 <CODE>RST</CODE>, <CODE>Glade</CODE>.
 144
 145 <DT><SAMP>&lsquo;-C&rsquo;</SAMP>
 146 <DD>
 147 <DT><SAMP>&lsquo;--c++&rsquo;</SAMP>
 148 <DD>
 149 <A NAME="IDX175"></A>
 150 <A NAME="IDX176"></A>
 151 This is a shorthand for <CODE>--language=C++</CODE>.
 152
 153 </DL>
 154
 155 <P>
 156 By default the language is guessed depending on the input file name
 157 extension.
 158
 159 </P>
 160
 161
 162 <H3><A NAME="SEC32" HREF="gettext_toc.html#TOC32">5.1.4  Input file interpretation</A></H3>
 163
 164 <DL COMPACT>
 165
 166 <DT><SAMP>&lsquo;--from-code=<VAR>name</VAR>&rsquo;</SAMP>
 167 <DD>
 168 <A NAME="IDX177"></A>
 169 Specifies the encoding of the input files.  This option is needed only
 170 if some untranslated message strings or their corresponding comments
 171 contain non-ASCII characters.  Note that Tcl and Glade input files are
 172 always assumed to be in UTF-8, regardless of this option.
 173
 174 </DL>
 175
 176 <P>
 177 By default the input files are assumed to be in ASCII.
 178
 179 </P>
 180
 181
 182 <H3><A NAME="SEC33" HREF="gettext_toc.html#TOC33">5.1.5  Operation mode</A></H3>
 183
 184 <DL COMPACT>
 185
 186 <DT><SAMP>&lsquo;-j&rsquo;</SAMP>
 187 <DD>
 188 <DT><SAMP>&lsquo;--join-existing&rsquo;</SAMP>
 189 <DD>
 190 <A NAME="IDX178"></A>
 191 <A NAME="IDX179"></A>
 192 Join messages with existing file.
 193
 194 <DT><SAMP>&lsquo;-x <VAR>file</VAR>&rsquo;</SAMP>
 195 <DD>
 196 <DT><SAMP>&lsquo;--exclude-file=<VAR>file</VAR>&rsquo;</SAMP>
 197 <DD>
 198 <A NAME="IDX180"></A>
 199 <A NAME="IDX181"></A>
 200 Entries from <VAR>file</VAR> are not extracted.  <VAR>file</VAR> should be a PO or
 201 POT file.
 202
 203 <DT><SAMP>&lsquo;-c[<VAR>tag</VAR>]&rsquo;</SAMP>
 204 <DD>
 205 <DT><SAMP>&lsquo;--add-comments[=<VAR>tag</VAR>]&rsquo;</SAMP>
 206 <DD>
 207 <A NAME="IDX182"></A>
 208 <A NAME="IDX183"></A>
 209 Place comment blocks starting with <VAR>tag</VAR> and preceding keyword lines
 210 in the output file.  Without a <VAR>tag</VAR>, the option means to put <EM>all</EM>
 211 comment blocks preceding keyword lines in the output file.
 212
 213 </DL>
 214
 215
 216
 217 <H3><A NAME="SEC34" HREF="gettext_toc.html#TOC34">5.1.6  Language specific options</A></H3>
 218
 219 <DL COMPACT>
 220
 221 <DT><SAMP>&lsquo;-a&rsquo;</SAMP>
 222 <DD>
 223 <DT><SAMP>&lsquo;--extract-all&rsquo;</SAMP>
 224 <DD>
 225 <A NAME="IDX184"></A>
 226 <A NAME="IDX185"></A>
 227 Extract all strings.
 228
 229 This option has an effect with most languages, namely C, C++, ObjectiveC,
 230 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
 231 GCC-source, Glade.
 232
 233 <DT><SAMP>&lsquo;-k[<VAR>keywordspec</VAR>]&rsquo;</SAMP>
 234 <DD>
 235 <DT><SAMP>&lsquo;--keyword[=<VAR>keywordspec</VAR>]&rsquo;</SAMP>
 236 <DD>
 237 <A NAME="IDX186"></A>
 238 <A NAME="IDX187"></A>
 239 Specify <VAR>keywordspec</VAR> as an additional keyword to be looked for.
 240 Without a <VAR>keywordspec</VAR>, the option means to not use default keywords.
 241
 242 <A NAME="IDX188"></A>
 243 <A NAME="IDX189"></A>
 244 If <VAR>keywordspec</VAR> is a C identifier <VAR>id</VAR>, <CODE>xgettext</CODE> looks
 245 for strings in the first argument of each call to the function or macro
 246 <VAR>id</VAR>.  If <VAR>keywordspec</VAR> is of the form
 247 <SAMP>&lsquo;<VAR>id</VAR>:<VAR>argnum</VAR>&rsquo;</SAMP>, <CODE>xgettext</CODE> looks for strings in the
 248 <VAR>argnum</VAR>th argument of the call.  If <VAR>keywordspec</VAR> is of the form
 249 <SAMP>&lsquo;<VAR>id</VAR>:<VAR>argnum1</VAR>,<VAR>argnum2</VAR>&rsquo;</SAMP>, <CODE>xgettext</CODE> looks for
 250 strings in the <VAR>argnum1</VAR>st argument and in the <VAR>argnum2</VAR>nd argument
 251 of the call, and treats them as singular/plural variants for a message
 252 with plural handling.  Also, if <VAR>keywordspec</VAR> is of the form
 253 <SAMP>&lsquo;<VAR>id</VAR>:<VAR>contextargnum</VAR>c,<VAR>argnum</VAR>&rsquo;</SAMP> or
 254 <SAMP>&lsquo;<VAR>id</VAR>:<VAR>argnum</VAR>,<VAR>contextargnum</VAR>c&rsquo;</SAMP>, <CODE>xgettext</CODE> treats
 255 strings in the <VAR>contextargnum</VAR>th argument as a context specifier.
 256 And, as a special-purpose support for GNOME, if <VAR>keywordspec</VAR> is of the
 257 form <SAMP>&lsquo;<VAR>id</VAR>:<VAR>argnum</VAR>g&rsquo;</SAMP>, <CODE>xgettext</CODE> recognizes the
 258 <VAR>argnum</VAR>th argument as a string with context, using the GNOME <CODE>glib</CODE>
 259 syntax <SAMP>&lsquo;"msgctxt|msgid"&rsquo;</SAMP>.
 260 <BR>
 261 Furthermore, if <VAR>keywordspec</VAR> is of the form
 262 <SAMP>&lsquo;<VAR>id</VAR>:...,<VAR>totalnumargs</VAR>t&rsquo;</SAMP>, <CODE>xgettext</CODE> recognizes this
 263 argument specification only if the number of actual arguments is equal to
 264 <VAR>totalnumargs</VAR>.  This is useful for disambiguating overloaded function
 265 calls in C++.
 266 <BR>
 267 Finally, if <VAR>keywordspec</VAR> is of the form
 268 <SAMP>&lsquo;<VAR>id</VAR>:<VAR>argnum</VAR>...,"<VAR>xcomment</VAR>"&rsquo;</SAMP>, <CODE>xgettext</CODE>, when
 269 extracting a message from the specified argument strings, adds an extracted
 270 comment <VAR>xcomment</VAR> to the message.  Note that when used through a normal
 271 shell command line, the double-quotes around the <VAR>xcomment</VAR> need to be
 272 escaped.
 273
 274 This option has an effect with most languages, namely C, C++, ObjectiveC,
 275 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
 276 GCC-source, Glade.
 277
 278 The default keyword specifications, which are always looked for if not
 279 explicitly disabled, are language dependent.  They are:
 280
 281
 282 <UL>
 283 <LI>
 284
 285 For C, C++, and GCC-source: <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>,
 286 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
 287 <CODE>dcngettext:2,3</CODE>, <CODE>gettext_noop</CODE>, and <CODE>pgettext:1c,2</CODE>,
 288 <CODE>dpgettext:2c,3</CODE>, <CODE>dcpgettext:2c,3</CODE>, <CODE>npgettext:1c,2,3</CODE>,
 289 <CODE>dnpgettext:2c,3,4</CODE>, <CODE>dcnpgettext:2c,3,4</CODE>.
 290
 291 <LI>
 292
 293 For Objective C: Like for C, and also <CODE>NSLocalizedString</CODE>, <CODE>_</CODE>,
 294 <CODE>NSLocalizedStaticString</CODE>, <CODE>__</CODE>.
 295
 296 <LI>
 297
 298 For Shell scripts: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>eval_gettext</CODE>,
 299 <CODE>eval_ngettext:1,2</CODE>.
 300
 301 <LI>
 302
 303 For Python: <CODE>gettext</CODE>, <CODE>ugettext</CODE>, <CODE>dgettext:2</CODE>,
 304 <CODE>ngettext:1,2</CODE>, <CODE>ungettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, <CODE>_</CODE>.
 305
 306 <LI>
 307
 308 For Lisp: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>gettext-noop</CODE>.
 309
 310 <LI>
 311
 312 For EmacsLisp: <CODE>_</CODE>.
 313
 314 <LI>
 315
 316 For librep: <CODE>_</CODE>.
 317
 318 <LI>
 319
 320 For Scheme: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>gettext-noop</CODE>.
 321
 322 <LI>
 323
 324 For Java: <CODE>GettextResource.gettext:2</CODE>,
 325 <CODE>GettextResource.ngettext:2,3</CODE>, <CODE>GettextResource.pgettext:2c,3</CODE>,
 326 <CODE>GettextResource.npgettext:2c,3,4</CODE>, <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>,
 327 <CODE>pgettext:1c,2</CODE>, <CODE>npgettext:1c,2,3</CODE>, <CODE>getString</CODE>.
 328
 329 <LI>
 330
 331 For C#: <CODE>GetString</CODE>, <CODE>GetPluralString:1,2</CODE>,
 332 <CODE>GetParticularString:1c,2</CODE>, <CODE>GetParticularPluralString:1c,2,3</CODE>.
 333
 334 <LI>
 335
 336 For awk: <CODE>dcgettext</CODE>, <CODE>dcngettext:1,2</CODE>.
 337
 338 <LI>
 339
 340 For Tcl: <CODE>::msgcat::mc</CODE>.
 341
 342 <LI>
 343
 344 For Perl: <CODE>gettext</CODE>, <CODE>%gettext</CODE>, <CODE>$gettext</CODE>, <CODE>dgettext:2</CODE>,
 345 <CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>,
 346 <CODE>dcngettext:2,3</CODE>, <CODE>gettext_noop</CODE>.
 347
 348 <LI>
 349
 350 For PHP: <CODE>_</CODE>, <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>, <CODE>dcgettext:2</CODE>,
 351 <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, <CODE>dcngettext:2,3</CODE>.
 352
 353 <LI>
 354
 355 For Glade 1: <CODE>label</CODE>, <CODE>title</CODE>, <CODE>text</CODE>, <CODE>format</CODE>,
 356 <CODE>copyright</CODE>, <CODE>comments</CODE>, <CODE>preview_text</CODE>, <CODE>tooltip</CODE>.
 357 </UL>
 358
 359 To disable the default keyword specifications, the option <SAMP>&lsquo;-k&rsquo;</SAMP> or
 360 <SAMP>&lsquo;--keyword&rsquo;</SAMP> or <SAMP>&lsquo;--keyword=&rsquo;</SAMP>, without a <VAR>keywordspec</VAR>, can be
 361 used.
 362
 363 <DT><SAMP>&lsquo;--flag=<VAR>word</VAR>:<VAR>arg</VAR>:<VAR>flag</VAR>&rsquo;</SAMP>
 364 <DD>
 365 <A NAME="IDX190"></A>
 366 Specifies additional flags for strings occurring as part of the <VAR>arg</VAR>th
 367 argument of the function <VAR>word</VAR>.  The possible flags are the possible
 368 format string indicators, such as <SAMP>&lsquo;c-format&rsquo;</SAMP>, and their negations,
 369 such as <SAMP>&lsquo;no-c-format&rsquo;</SAMP>, possibly prefixed with <SAMP>&lsquo;pass-&rsquo;</SAMP>.
 370 <BR>
 371 <A NAME="IDX191"></A>
 372 The meaning of <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:<VAR>lang</VAR>-format</CODE>
 373 is that in language <VAR>lang</VAR>, the specified <VAR>function</VAR> expects as
 374 <VAR>arg</VAR>th argument a format string.  (For those of you familiar with
 375 GCC function attributes, <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:c-format</CODE> is
 376 roughly equivalent to the declaration
 377 <SAMP>&lsquo;__attribute__ ((__format__ (__printf__, <VAR>arg</VAR>, ...)))&rsquo;</SAMP> attached
 378 to <VAR>function</VAR> in a C source file.)
 379 For example, if you use the <SAMP>&lsquo;error&rsquo;</SAMP> function from GNU libc, you can
 380 specify its behaviour through <CODE>--flag=error:3:c-format</CODE>.  The effect of
 381 this specification is that <CODE>xgettext</CODE> will mark as format strings all
 382 <CODE>gettext</CODE> invocations that occur as <VAR>arg</VAR>th argument of
 383 <VAR>function</VAR>.
 384 This is useful when such strings contain no format string directives:
 385 together with the checks done by <SAMP>&lsquo;msgfmt -c&rsquo;</SAMP> it will ensure that
 386 translators cannot accidentally use format string directives that would
 387 lead to a crash at runtime.
 388 <BR>
 389 <A NAME="IDX192"></A>
 390 The meaning of <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:pass-<VAR>lang</VAR>-format</CODE>
 391 is that in language <VAR>lang</VAR>, if the <VAR>function</VAR> call occurs in a
 392 position that must yield a format string, then its <VAR>arg</VAR>th argument
 393 must yield a format string of the same type as well.  (If you know GCC
 394 function attributes, the <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:pass-c-format</CODE>
 395 option is roughly equivalent to the declaration
 396 <SAMP>&lsquo;__attribute__ ((__format_arg__ (<VAR>arg</VAR>)))&rsquo;</SAMP> attached to <VAR>function</VAR>
 397 in a C source file.)
 398 For example, if you use the <SAMP>&lsquo;_&rsquo;</SAMP> shortcut for the <CODE>gettext</CODE> function,
 399 you should use <CODE>--flag=_:1:pass-c-format</CODE>.  The effect of this
 400 specification is that <CODE>xgettext</CODE> will propagate a format string
 401 requirement for a <CODE>_("string")</CODE> call to its first argument, the literal
 402 <CODE>"string"</CODE>, and thus mark it as a format string.
 403 This is useful when such strings contain no format string directives:
 404 together with the checks done by <SAMP>&lsquo;msgfmt -c&rsquo;</SAMP> it will ensure that
 405 translators cannot accidentally use format string directives that would
 406 lead to a crash at runtime.
 407 <BR>
 408 This option has an effect with most languages, namely C, C++, ObjectiveC,
 409 Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP,
 410 GCC-source.
 411
 412 <DT><SAMP>&lsquo;-T&rsquo;</SAMP>
 413 <DD>
 414 <DT><SAMP>&lsquo;--trigraphs&rsquo;</SAMP>
 415 <DD>
 416 <A NAME="IDX193"></A>
 417 <A NAME="IDX194"></A>
 418 <A NAME="IDX195"></A>
 419 Understand ANSI C trigraphs for input.
 420 <BR>
 421 This option has an effect only with the languages C, C++, ObjectiveC.
 422
 423 <DT><SAMP>&lsquo;--qt&rsquo;</SAMP>
 424 <DD>
 425 <A NAME="IDX196"></A>
 426 <A NAME="IDX197"></A>
 427 Recognize Qt format strings.
 428 <BR>
 429 This option has an effect only with the language C++.
 430
 431 <DT><SAMP>&lsquo;--kde&rsquo;</SAMP>
 432 <DD>
 433 <A NAME="IDX198"></A>
 434 <A NAME="IDX199"></A>
 435 Recognize KDE 4 format strings.
 436 <BR>
 437 This option has an effect only with the language C++.
 438
 439 <DT><SAMP>&lsquo;--boost&rsquo;</SAMP>
 440 <DD>
 441 <A NAME="IDX200"></A>
 442 <A NAME="IDX201"></A>
 443 Recognize Boost format strings.
 444 <BR>
 445 This option has an effect only with the language C++.
 446
 447 <DT><SAMP>&lsquo;--debug&rsquo;</SAMP>
 448 <DD>
 449 <A NAME="IDX202"></A>
 450 <A NAME="IDX203"></A>
 451 Use the flags <CODE>c-format</CODE> and <CODE>possible-c-format</CODE> to show who was
 452 responsible for marking a message as a format string.  The latter form is
 453 used if the <CODE>xgettext</CODE> program decided, the format form is used if
 454 the programmer prescribed it.
 455
 456 By default only the <CODE>c-format</CODE> form is used.  The translator should
 457 not have to care about these details.
 458
 459 </DL>
 460
 461 <P>
 462 This implementation of <CODE>xgettext</CODE> is able to process a few awkward
 463 cases, like strings in preprocessor macros, ANSI concatenation of
 464 adjacent strings, and escaped end of lines for continued strings.
 465
 466 </P>
 467
 468
 469 <H3><A NAME="SEC35" HREF="gettext_toc.html#TOC35">5.1.7  Output details</A></H3>
 470
 471 <DL COMPACT>
 472
 473 <DT><SAMP>&lsquo;--color&rsquo;</SAMP>
 474 <DD>
 475 <DT><SAMP>&lsquo;--color=<VAR>when</VAR>&rsquo;</SAMP>
 476 <DD>
 477 <A NAME="IDX204"></A>
 478 Specify whether or when to use colors and other text attributes.
 479 See section <A HREF="gettext_9.html#SEC150">9.11.1  The <CODE>--color</CODE> option</A> for details.
 480
 481 <DT><SAMP>&lsquo;--style=<VAR>style_file</VAR>&rsquo;</SAMP>
 482 <DD>
 483 <A NAME="IDX205"></A>
 484 Specify the CSS style rule file to use for <CODE>--color</CODE>.
 485 See section <A HREF="gettext_9.html#SEC152">9.11.3  The <CODE>--style</CODE> option</A> for details.
 486
 487 <DT><SAMP>&lsquo;--force-po&rsquo;</SAMP>
 488 <DD>
 489 <A NAME="IDX206"></A>
 490 Always write an output file even if no message is defined.
 491
 492 <DT><SAMP>&lsquo;-i&rsquo;</SAMP>
 493 <DD>
 494 <DT><SAMP>&lsquo;--indent&rsquo;</SAMP>
 495 <DD>
 496 <A NAME="IDX207"></A>
 497 <A NAME="IDX208"></A>
 498 Write the .po file using indented style.
 499
 500 <DT><SAMP>&lsquo;--no-location&rsquo;</SAMP>
 501 <DD>
 502 <A NAME="IDX209"></A>
 503 Do not write <SAMP>&lsquo;#: <VAR>filename</VAR>:<VAR>line</VAR>&rsquo;</SAMP> lines.  Note that using
 504 this option makes it harder for technically skilled translators to understand
 505 each message's context.
 506
 507 <DT><SAMP>&lsquo;-n&rsquo;</SAMP>
 508 <DD>
 509 <DT><SAMP>&lsquo;--add-location&rsquo;</SAMP>
 510 <DD>
 511 <A NAME="IDX210"></A>
 512 <A NAME="IDX211"></A>
 513 Generate <SAMP>&lsquo;#: <VAR>filename</VAR>:<VAR>line</VAR>&rsquo;</SAMP> lines (default).
 514
 515 <DT><SAMP>&lsquo;--strict&rsquo;</SAMP>
 516 <DD>
 517 <A NAME="IDX212"></A>
 518 Write out a strict Uniforum conforming PO file.  Note that this
 519 Uniforum format should be avoided because it doesn't support the
 520 GNU extensions.
 521
 522 <DT><SAMP>&lsquo;--properties-output&rsquo;</SAMP>
 523 <DD>
 524 <A NAME="IDX213"></A>
 525 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
 526 that this file format doesn't support plural forms and silently drops
 527 obsolete messages.
 528
 529 <DT><SAMP>&lsquo;--stringtable-output&rsquo;</SAMP>
 530 <DD>
 531 <A NAME="IDX214"></A>
 532 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
 533 Note that this file format doesn't support plural forms.
 534
 535 <DT><SAMP>&lsquo;-w <VAR>number</VAR>&rsquo;</SAMP>
 536 <DD>
 537 <DT><SAMP>&lsquo;--width=<VAR>number</VAR>&rsquo;</SAMP>
 538 <DD>
 539 <A NAME="IDX215"></A>
 540 <A NAME="IDX216"></A>
 541 Set the output page width.  Long strings in the output files will be
 542 split across multiple lines in order to ensure that each line's width
 543 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
 544
 545 <DT><SAMP>&lsquo;--no-wrap&rsquo;</SAMP>
 546 <DD>
 547 <A NAME="IDX217"></A>
 548 Do not break long message lines.  Message lines whose width exceeds the
 549 output page width will not be split into several lines.  Only file reference
 550 lines which are wider than the output page width will be split.
 551
 552 <DT><SAMP>&lsquo;-s&rsquo;</SAMP>
 553 <DD>
 554 <DT><SAMP>&lsquo;--sort-output&rsquo;</SAMP>
 555 <DD>
 556 <A NAME="IDX218"></A>
 557 <A NAME="IDX219"></A>
 558 <A NAME="IDX220"></A>
 559 Generate sorted output.  Note that using this option makes it much harder
 560 for the translator to understand each message's context.
 561
 562 <DT><SAMP>&lsquo;-F&rsquo;</SAMP>
 563 <DD>
 564 <DT><SAMP>&lsquo;--sort-by-file&rsquo;</SAMP>
 565 <DD>
 566 <A NAME="IDX221"></A>
 567 <A NAME="IDX222"></A>
 568 Sort output by file location.
 569
 570 <DT><SAMP>&lsquo;--omit-header&rsquo;</SAMP>
 571 <DD>
 572 <A NAME="IDX223"></A>
 573 Don't write header with <SAMP>&lsquo;msgid ""&rsquo;</SAMP> entry.
 574
 575 <A NAME="IDX224"></A>
 576 This is useful for testing purposes because it eliminates a source
 577 of variance for generated <CODE>.gmo</CODE> files.  With <CODE>--omit-header</CODE>,
 578 two invocations of <CODE>xgettext</CODE> on the same files with the same
 579 options at different times are guaranteed to produce the same results.
 580
 581 Note that using this option will lead to an error if the resulting file
 582 would not entirely be in ASCII.
 583
 584 <DT><SAMP>&lsquo;--copyright-holder=<VAR>string</VAR>&rsquo;</SAMP>
 585 <DD>
 586 <A NAME="IDX225"></A>
 587 Set the copyright holder in the output.  <VAR>string</VAR> should be the
 588 copyright holder of the surrounding package.  (Note that the msgstr
 589 strings, extracted from the package's sources, belong to the copyright
 590 holder of the package.)  Translators are expected to transfer or disclaim
 591 the copyright for their translations, so that package maintainers can
 592 distribute them without legal risk.  If <VAR>string</VAR> is empty, the output
 593 files are marked as being in the public domain; in this case, the translators
 594 are expected to disclaim their copyright, again so that package maintainers
 595 can distribute them without legal risk.
 596
 597 The default value for <VAR>string</VAR> is the Free Software Foundation, Inc.,
 598 simply because <CODE>xgettext</CODE> was first used in the GNU project.
 599
 600 <DT><SAMP>&lsquo;--foreign-user&rsquo;</SAMP>
 601 <DD>
 602 <A NAME="IDX226"></A>
 603 Omit FSF copyright in output.  This option is equivalent to
 604 <SAMP>&lsquo;--copyright-holder=”&rsquo;</SAMP>.  It can be useful for packages outside the GNU
 605 project that want their translations to be in the public domain.
 606
 607 <DT><SAMP>&lsquo;--package-name=<VAR>package</VAR>&rsquo;</SAMP>
 608 <DD>
 609 <A NAME="IDX227"></A>
 610 Set the package name in the header of the output.
 611
 612 <DT><SAMP>&lsquo;--package-version=<VAR>version</VAR>&rsquo;</SAMP>
 613 <DD>
 614 <A NAME="IDX228"></A>
 615 Set the package version in the header of the output.  This option has an
 616 effect only if the <SAMP>&lsquo;--package-name&rsquo;</SAMP> option is also used.
 617
 618 <DT><SAMP>&lsquo;--msgid-bugs-address=<VAR>email@address</VAR>&rsquo;</SAMP>
 619 <DD>
 620 <A NAME="IDX229"></A>
 621 Set the reporting address for msgid bugs.  This is the email address or URL
 622 to which the translators shall report bugs in the untranslated strings:
 623
 624
 625 <UL>
 626 <LI>Strings which are not entire sentences, see the maintainer guidelines
 627
 628 in section <A HREF="gettext_4.html#SEC19">4.3  Preparing Translatable Strings</A>.
 629 <LI>Strings which use unclear terms or require additional context to be
 630
 631 understood.
 632 <LI>Strings which make invalid assumptions about notation of date, time or
 633
 634 money.
 635 <LI>Pluralisation problems.
 636
 637 <LI>Incorrect English spelling.
 638
 639 <LI>Incorrect formatting.
 640
 641 </UL>
 642
 643 It can be your email address, or a mailing list address where translators
 644 can write to without being subscribed, or the URL of a web page through
 645 which the translators can contact you.
 646
 647 The default value is empty, which means that translators will be clueless!
 648 Don't forget to specify this option.
 649
 650 <DT><SAMP>&lsquo;-m[<VAR>string</VAR>]&rsquo;</SAMP>
 651 <DD>
 652 <DT><SAMP>&lsquo;--msgstr-prefix[=<VAR>string</VAR>]&rsquo;</SAMP>
 653 <DD>
 654 <A NAME="IDX230"></A>
 655 <A NAME="IDX231"></A>
 656 Use <VAR>string</VAR> (or "" if not specified) as prefix for msgstr values.
 657
 658 <DT><SAMP>&lsquo;-M[<VAR>string</VAR>]&rsquo;</SAMP>
 659 <DD>
 660 <DT><SAMP>&lsquo;--msgstr-suffix[=<VAR>string</VAR>]&rsquo;</SAMP>
 661 <DD>
 662 <A NAME="IDX232"></A>
 663 <A NAME="IDX233"></A>
 664 Use <VAR>string</VAR> (or "" if not specified) as suffix for msgstr values.
 665
 666 </DL>
 667
 668
 669
 670 <H3><A NAME="SEC36" HREF="gettext_toc.html#TOC36">5.1.8  Informative output</A></H3>
 671
 672 <DL COMPACT>
 673
 674 <DT><SAMP>&lsquo;-h&rsquo;</SAMP>
 675 <DD>
 676 <DT><SAMP>&lsquo;--help&rsquo;</SAMP>
 677 <DD>
 678 <A NAME="IDX234"></A>
 679 <A NAME="IDX235"></A>
 680 Display this help and exit.
 681
 682 <DT><SAMP>&lsquo;-V&rsquo;</SAMP>
 683 <DD>
 684 <DT><SAMP>&lsquo;--version&rsquo;</SAMP>
 685 <DD>
 686 <A NAME="IDX236"></A>
 687 <A NAME="IDX237"></A>
 688 Output version information and exit.
 689
 690 </DL>
 691
 692 <P><HR><P>
 693 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_4.html">previous</A>, <A HREF="gettext_6.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
 694 </BODY>
 695 </HTML>