gettext-tools/doc/xgettext.texi

   1 @pindex xgettext
   2 @cindex @code{xgettext} program, usage
   3 @example
   4 xgettext [@var{option}] [@var{inputfile}] @dots{}
   5 @end example
   6
   7 The @code{xgettext} program extracts translatable strings from given
   8 input files.
   9
  10 @subsection Input file location
  11
  12 @table @samp
  13 @item @var{inputfile} @dots{}
  14 Input files.
  15
  16 @item -f @var{file}
  17 @itemx --files-from=@var{file}
  18 @opindex -f@r{, @code{xgettext} option}
  19 @opindex --files-from@r{, @code{xgettext} option}
  20 Read the names of the input files from @var{file} instead of getting
  21 them from the command line.
  22
  23 @item -D @var{directory}
  24 @itemx --directory=@var{directory}
  25 @opindex -D@r{, @code{xgettext} option}
  26 @opindex --directory@r{, @code{xgettext} option}
  27 Add @var{directory} to the list of directories.  Source files are
  28 searched relative to this list of directories.  The resulting @file{.po}
  29 file will be written relative to the current directory, though.
  30
  31 @end table
  32
  33 If @var{inputfile} is @samp{-}, standard input is read.
  34
  35 @subsection Output file location
  36
  37 @table @samp
  38 @item -d @var{name}
  39 @itemx --default-domain=@var{name}
  40 @opindex -d@r{, @code{xgettext} option}
  41 @opindex --default-domain@r{, @code{xgettext} option}
  42 Use @file{@var{name}.po} for output (instead of @file{messages.po}).
  43
  44 @item -o @var{file}
  45 @itemx --output=@var{file}
  46 @opindex -o@r{, @code{xgettext} option}
  47 @opindex --output@r{, @code{xgettext} option}
  48 Write output to specified file (instead of @file{@var{name}.po} or
  49 @file{messages.po}).
  50
  51 @item -p @var{dir}
  52 @itemx --output-dir=@var{dir}
  53 @opindex -p@r{, @code{xgettext} option}
  54 @opindex --output-dir@r{, @code{xgettext} option}
  55 Output files will be placed in directory @var{dir}.
  56
  57 @end table
  58
  59 @cindex output to stdout, @code{xgettext}
  60 If the output @var{file} is @samp{-} or @samp{/dev/stdout}, the output
  61 is written to standard output.
  62
  63 @subsection Choice of input file language
  64
  65 @table @samp
  66 @item -L @var{name}
  67 @itemx --language=@var{name}
  68 @opindex -L@r{, @code{xgettext} option}
  69 @opindex --language@r{, @code{xgettext} option}
  70 @cindex supported languages, @code{xgettext}
  71 Specifies the language of the input files.  The supported languages
  72 are @code{C}, @code{C++}, @code{ObjectiveC}, @code{PO}, @code{Shell},
  73 @code{Python}, @code{Lisp}, @code{EmacsLisp}, @code{librep}, @code{Scheme},
  74 @code{Smalltalk}, @code{Java}, @code{JavaProperties}, @code{C#}, @code{awk},
  75 @code{YCP}, @code{Tcl}, @code{Perl}, @code{PHP}, @code{GCC-source},
  76 @code{NXStringTable}, @code{RST}, @code{Glade}, @code{Lua}, @code{JavaScript},
  77 @code{Vala}, @code{GSettings}, @code{Desktop}.
  78
  79 @item -C
  80 @itemx --c++
  81 @opindex -C@r{, @code{xgettext} option}
  82 @opindex --c++@r{, @code{xgettext} option}
  83 This is a shorthand for @code{--language=C++}.
  84
  85 @end table
  86
  87 By default the language is guessed depending on the input file name
  88 extension.
  89
  90 @subsection Input file interpretation
  91
  92 @table @samp
  93 @item --from-code=@var{name}
  94 @opindex --from-code@r{, @code{xgettext} option}
  95 Specifies the encoding of the input files.  This option is needed only
  96 if some untranslated message strings or their corresponding comments
  97 contain non-ASCII characters.  Note that Tcl and Glade input files are
  98 always assumed to be in UTF-8, regardless of this option.
  99
 100 @end table
 101
 102 By default the input files are assumed to be in ASCII.
 103
 104 @subsection Operation mode
 105
 106 @table @samp
 107 @item -j
 108 @itemx --join-existing
 109 @opindex -j@r{, @code{xgettext} option}
 110 @opindex --join-existing@r{, @code{xgettext} option}
 111 Join messages with existing file.
 112
 113 @item -x @var{file}
 114 @itemx --exclude-file=@var{file}
 115 @opindex -x@r{, @code{xgettext} option}
 116 @opindex --exclude-file@r{, @code{xgettext} option}
 117 Entries from @var{file} are not extracted.  @var{file} should be a PO or
 118 POT file.
 119
 120 @item -c[@var{tag}]
 121 @itemx --add-comments[=@var{tag}]
 122 @opindex -c@r{, @code{xgettext} option}
 123 @opindex --add-comments@r{, @code{xgettext} option}
 124 Place comment blocks starting with @var{tag} and preceding keyword lines
 125 in the output file.  Without a @var{tag}, the option means to put @emph{all}
 126 comment blocks preceding keyword lines in the output file.
 127
 128 Note that comment blocks supposed to be extracted must be adjacent to
 129 keyword lines.  For example, in the following C source code:
 130
 131 @example
 132 /* This is the first comment.  */
 133 gettext ("foo");
 134
 135 /* This is the second comment: not extracted  */
 136 gettext (
 137   "bar");
 138
 139 gettext (
 140   /* This is the third comment.  */
 141   "baz");
 142 @end example
 143
 144 The second comment line will not be extracted, because there is one
 145 blank line between the comment line and the keyword.
 146
 147 @item --check[=@var{CHECK}]
 148 @opindex --check@r{, @code{xgettext} option}
 149 @cindex supported syntax checks, @code{xgettext}
 150 Perform a syntax check on msgid and msgid_plural.  The supported checks
 151 are:
 152
 153 @table @samp
 154 @item ellipsis-unicode
 155 Prefer Unicode ellipsis character over ASCII @code{...}
 156
 157 @item space-ellipsis
 158 Prohibit whitespace before an ellipsis character
 159
 160 @item quote-unicode
 161 Prefer Unicode quotation marks over ASCII @code{"'`}
 162
 163 @end table
 164
 165 The option has an effect on all input files.  To enable or disable
 166 checks for a certain string, you can mark it with an @code{xgettext:}
 167 special comment in the source file.  For example, if you specify the
 168 @code{--check=space-ellipsis} option, but want to suppress the check on
 169 a particular string, add the following comment:
 170
 171 @example
 172 /* xgettext: no-space-ellipsis-check */
 173 gettext ("We really want a space before ellipsis here ...");
 174 @end example
 175
 176 The @code{xgettext:} comment can be followed by flags separated with a
 177 comma.  The possible flags are of the form @samp{[no-]@var{name}-check},
 178 where @var{name} is the name of a valid syntax check.  If a flag is
 179 prefixed by @code{no-}, the meaning is negated.
 180
 181 Some tests apply the checks to each sentence within the msgid, rather
 182 than the whole string.  xgettext detects the end of sentence by
 183 performing a pattern match, which usually looks for a period followed by
 184 a certain number of spaces.  The number is specified with the
 185 @code{--sentence-end} option.
 186
 187 @item --sentence-end[=@var{TYPE}]
 188 @opindex --sentence-end@r{, @code{xgettext} option}
 189 @cindex sentence end markers, @code{xgettext}
 190 The supported values are:
 191
 192 @table @samp
 193 @item single-space
 194 Expect at least one whitespace after a period
 195
 196 @item double-space
 197 Expect at least two whitespaces after a period
 198
 199 @end table
 200
 201 @end table
 202
 203 @subsection Language specific options
 204
 205 @table @samp
 206 @item -a
 207 @itemx --extract-all
 208 @opindex -a@r{, @code{xgettext} option}
 209 @opindex --extract-all@r{, @code{xgettext} option}
 210 Extract all strings.
 211
 212 This option has an effect with most languages, namely C, C++, ObjectiveC,
 213 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
 214 GCC-source, Glade, Lua, JavaScript, Vala, GSettings.
 215
 216 @item -k[@var{keywordspec}]
 217 @itemx --keyword[=@var{keywordspec}]
 218 @opindex -k@r{, @code{xgettext} option}
 219 @opindex --keyword@r{, @code{xgettext} option}
 220 Specify @var{keywordspec} as an additional keyword to be looked for.
 221 Without a @var{keywordspec}, the option means to not use default keywords.
 222
 223 @cindex adding keywords, @code{xgettext}
 224 @cindex context, argument specification in @code{xgettext}
 225 If @var{keywordspec} is a C identifier @var{id}, @code{xgettext} looks
 226 for strings in the first argument of each call to the function or macro
 227 @var{id}.  If @var{keywordspec} is of the form
 228 @samp{@var{id}:@var{argnum}}, @code{xgettext} looks for strings in the
 229 @var{argnum}th argument of the call.  If @var{keywordspec} is of the form
 230 @samp{@var{id}:@var{argnum1},@var{argnum2}}, @code{xgettext} looks for
 231 strings in the @var{argnum1}st argument and in the @var{argnum2}nd argument
 232 of the call, and treats them as singular/plural variants for a message
 233 with plural handling.  Also, if @var{keywordspec} is of the form
 234 @samp{@var{id}:@var{contextargnum}c,@var{argnum}} or
 235 @samp{@var{id}:@var{argnum},@var{contextargnum}c}, @code{xgettext} treats
 236 strings in the @var{contextargnum}th argument as a context specifier.
 237 And, as a special-purpose support for GNOME, if @var{keywordspec} is of the
 238 form @samp{@var{id}:@var{argnum}g}, @code{xgettext} recognizes the
 239 @var{argnum}th argument as a string with context, using the GNOME @code{glib}
 240 syntax @samp{"msgctxt|msgid"}.
 241 @*
 242 Furthermore, if @var{keywordspec} is of the form
 243 @samp{@var{id}:@dots{},@var{totalnumargs}t}, @code{xgettext} recognizes this
 244 argument specification only if the number of actual arguments is equal to
 245 @var{totalnumargs}.  This is useful for disambiguating overloaded function
 246 calls in C++.
 247 @*
 248 Finally, if @var{keywordspec} is of the form
 249 @samp{@var{id}:@var{argnum}...,"@var{xcomment}"}, @code{xgettext}, when
 250 extracting a message from the specified argument strings, adds an extracted
 251 comment @var{xcomment} to the message.  Note that when used through a normal
 252 shell command line, the double-quotes around the @var{xcomment} need to be
 253 escaped.
 254
 255 This option has an effect with most languages, namely C, C++, ObjectiveC,
 256 Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP,
 257 GCC-source, Glade, Lua, JavaScript, Vala, GSettings, Desktop.
 258
 259 The default keyword specifications, which are always looked for if not
 260 explicitly disabled, are language dependent.  They are:
 261
 262 @itemize
 263 @item
 264 For C, C++, and GCC-source: @code{gettext}, @code{dgettext:2},
 265 @code{dcgettext:2}, @code{ngettext:1,2}, @code{dngettext:2,3},
 266 @code{dcngettext:2,3}, @code{gettext_noop}, and @code{pgettext:1c,2},
 267 @code{dpgettext:2c,3}, @code{dcpgettext:2c,3}, @code{npgettext:1c,2,3},
 268 @code{dnpgettext:2c,3,4}, @code{dcnpgettext:2c,3,4}.
 269
 270 @item
 271 For Objective C: Like for C, and also @code{NSLocalizedString}, @code{_},
 272 @code{NSLocalizedStaticString}, @code{__}.
 273
 274 @item
 275 For Shell scripts: @code{gettext}, @code{ngettext:1,2}, @code{eval_gettext},
 276 @code{eval_ngettext:1,2}.
 277
 278 @item
 279 For Python: @code{gettext}, @code{ugettext}, @code{dgettext:2},
 280 @code{ngettext:1,2}, @code{ungettext:1,2}, @code{dngettext:2,3}, @code{_}.
 281
 282 @item
 283 For Lisp: @code{gettext}, @code{ngettext:1,2}, @code{gettext-noop}.
 284
 285 @item
 286 For EmacsLisp: @code{_}.
 287
 288 @item
 289 For librep: @code{_}.
 290
 291 @item
 292 For Scheme: @code{gettext}, @code{ngettext:1,2}, @code{gettext-noop}.
 293
 294 @item
 295 For Java: @code{GettextResource.gettext:2},
 296 @code{GettextResource.ngettext:2,3}, @code{GettextResource.pgettext:2c,3},
 297 @code{GettextResource.npgettext:2c,3,4}, @code{gettext}, @code{ngettext:1,2},
 298 @code{pgettext:1c,2}, @code{npgettext:1c,2,3}, @code{getString}.
 299
 300 @item
 301 For C#: @code{GetString}, @code{GetPluralString:1,2},
 302 @code{GetParticularString:1c,2}, @code{GetParticularPluralString:1c,2,3}.
 303
 304 @item
 305 For awk: @code{dcgettext}, @code{dcngettext:1,2}.
 306
 307 @item
 308 For Tcl: @code{::msgcat::mc}.
 309
 310 @item
 311 For Perl: @code{gettext}, @code{%gettext}, @code{$gettext}, @code{dgettext:2},
 312 @code{dcgettext:2}, @code{ngettext:1,2}, @code{dngettext:2,3},
 313 @code{dcngettext:2,3}, @code{gettext_noop}.
 314
 315 @item
 316 For PHP: @code{_}, @code{gettext}, @code{dgettext:2}, @code{dcgettext:2},
 317 @code{ngettext:1,2}, @code{dngettext:2,3}, @code{dcngettext:2,3}.
 318
 319 @item
 320 For Glade 1: @code{label}, @code{title}, @code{text}, @code{format},
 321 @code{copyright}, @code{comments}, @code{preview_text}, @code{tooltip}.
 322
 323 @item
 324 For Lua: @code{_}, @code{gettext.gettext}, @code{gettext.dgettext:2},
 325 @code{gettext.dcgettext:2}, @code{gettext.ngettext:1,2},
 326 @code{gettext.dngettext:2,3}, @code{gettext.dcngettext:2,3}.
 327
 328 @item
 329 For JavaScript: @code{_}, @code{gettext}, @code{dgettext:2},
 330 @code{dcgettext:2}, @code{ngettext:1,2}, @code{dngettext:2,3},
 331 @code{pgettext:1c,2}, @code{dpgettext:2c,3}.
 332
 333 @item
 334 For Vala: @code{_}, @code{Q_}, @code{N_}, @code{NC_}, @code{dgettext:2},
 335 @code{dcgettext:2}, @code{ngettext:1,2}, @code{dngettext:2,3},
 336 @code{dpgettext:2c,3}, @code{dpgettext2:2c,3}.
 337
 338 @item
 339 For Desktop: @code{Name}, @code{GenericName}, @code{Comment},
 340 @code{Icon}, @code{Keywords}.
 341 @end itemize
 342
 343 To disable the default keyword specifications, the option @samp{-k} or
 344 @samp{--keyword} or @samp{--keyword=}, without a @var{keywordspec}, can be
 345 used.
 346
 347 @item --flag=@var{word}:@var{arg}:@var{flag}
 348 @opindex --flag@r{, @code{xgettext} option}
 349 Specifies additional flags for strings occurring as part of the @var{arg}th
 350 argument of the function @var{word}.  The possible flags are the possible
 351 format string indicators, such as @samp{c-format}, and their negations,
 352 such as @samp{no-c-format}, possibly prefixed with @samp{pass-}.
 353 @*
 354 @cindex function attribute, __format__
 355 The meaning of @code{--flag=@var{function}:@var{arg}:@var{lang}-format}
 356 is that in language @var{lang}, the specified @var{function} expects as
 357 @var{arg}th argument a format string.  (For those of you familiar with
 358 GCC function attributes, @code{--flag=@var{function}:@var{arg}:c-format} is
 359 roughly equivalent to the declaration
 360 @samp{__attribute__ ((__format__ (__printf__, @var{arg}, ...)))} attached
 361 to @var{function} in a C source file.)
 362 For example, if you use the @samp{error} function from GNU libc, you can
 363 specify its behaviour through @code{--flag=error:3:c-format}.  The effect of
 364 this specification is that @code{xgettext} will mark as format strings all
 365 @code{gettext} invocations that occur as @var{arg}th argument of
 366 @var{function}.
 367 This is useful when such strings contain no format string directives:
 368 together with the checks done by @samp{msgfmt -c} it will ensure that
 369 translators cannot accidentally use format string directives that would
 370 lead to a crash at runtime.
 371 @*
 372 @cindex function attribute, __format_arg__
 373 The meaning of @code{--flag=@var{function}:@var{arg}:pass-@var{lang}-format}
 374 is that in language @var{lang}, if the @var{function} call occurs in a
 375 position that must yield a format string, then its @var{arg}th argument
 376 must yield a format string of the same type as well.  (If you know GCC
 377 function attributes, the @code{--flag=@var{function}:@var{arg}:pass-c-format}
 378 option is roughly equivalent to the declaration
 379 @samp{__attribute__ ((__format_arg__ (@var{arg})))} attached to @var{function}
 380 in a C source file.)
 381 For example, if you use the @samp{_} shortcut for the @code{gettext} function,
 382 you should use @code{--flag=_:1:pass-c-format}.  The effect of this
 383 specification is that @code{xgettext} will propagate a format string
 384 requirement for a @code{_("string")} call to its first argument, the literal
 385 @code{"string"}, and thus mark it as a format string.
 386 This is useful when such strings contain no format string directives:
 387 together with the checks done by @samp{msgfmt -c} it will ensure that
 388 translators cannot accidentally use format string directives that would
 389 lead to a crash at runtime.
 390 @*
 391 This option has an effect with most languages, namely C, C++, ObjectiveC,
 392 Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP,
 393 GCC-source, Lua, JavaScript, Vala.
 394
 395 @item -T
 396 @itemx --trigraphs
 397 @opindex -T@r{, @code{xgettext} option}
 398 @opindex --trigraphs@r{, @code{xgettext} option}
 399 @cindex C trigraphs
 400 Understand ANSI C trigraphs for input.
 401 @*
 402 This option has an effect only with the languages C, C++, ObjectiveC.
 403
 404 @item --qt
 405 @opindex --qt@r{, @code{xgettext} option}
 406 @cindex Qt format strings
 407 Recognize Qt format strings.
 408 @*
 409 This option has an effect only with the language C++.
 410
 411 @item --kde
 412 @opindex --kde@r{, @code{xgettext} option}
 413 @cindex KDE format strings
 414 Recognize KDE 4 format strings.
 415 @*
 416 This option has an effect only with the language C++.
 417
 418 @item --boost
 419 @opindex --boost@r{, @code{xgettext} option}
 420 @cindex Boost format strings
 421 Recognize Boost format strings.
 422 @*
 423 This option has an effect only with the language C++.
 424
 425 @item --debug
 426 @opindex --debug@r{, @code{xgettext} option}
 427 @cindex debugging messages marked as format strings
 428 Use the flags @code{c-format} and @code{possible-c-format} to show who was
 429 responsible for marking a message as a format string.  The latter form is
 430 used if the @code{xgettext} program decided, the former form is used if
 431 the programmer prescribed it.
 432
 433 By default only the @code{c-format} form is used.  The translator should
 434 not have to care about these details.
 435
 436 @end table
 437
 438 This implementation of @code{xgettext} is able to process a few awkward
 439 cases, like strings in preprocessor macros, ANSI concatenation of
 440 adjacent strings, and escaped end of lines for continued strings.
 441
 442 @subsection Output details
 443
 444 @c --no-escape and --escape omitted on purpose.  They are not useful.
 445
 446 @table @samp
 447 @item --color
 448 @itemx --color=@var{when}
 449 @opindex --color@r{, @code{xgettext} option}
 450 Specify whether or when to use colors and other text attributes.
 451 See @ref{The --color option} for details.
 452
 453 @item --style=@var{style_file}
 454 @opindex --style@r{, @code{xgettext} option}
 455 Specify the CSS style rule file to use for @code{--color}.
 456 See @ref{The --style option} for details.
 457
 458 @item --force-po
 459 @opindex --force-po@r{, @code{xgettext} option}
 460 Always write an output file even if no message is defined.
 461
 462 @item -i
 463 @itemx --indent
 464 @opindex -i@r{, @code{xgettext} option}
 465 @opindex --indent@r{, @code{xgettext} option}
 466 Write the .po file using indented style.
 467
 468 @item --no-location
 469 @opindex --no-location@r{, @code{xgettext} option}
 470 Do not write @samp{#: @var{filename}:@var{line}} lines.  Note that using
 471 this option makes it harder for technically skilled translators to understand
 472 each message's context.
 473
 474 @item -n
 475 @itemx --add-location=@var{type}
 476 @opindex -n@r{, @code{xgettext} option}
 477 @opindex --add-location@r{, @code{xgettext} option}
 478 Generate @samp{#: @var{filename}:@var{line}} lines (default).
 479
 480 The optional @var{type} can be either @samp{full}, @samp{file}, or
 481 @samp{never}.  If it is not given or @samp{full}, it generates the
 482 lines with both file name and line number.  If it is @samp{file}, the
 483 line number part is omitted.  If it is @samp{never}, it completely
 484 suppresses the lines (same as @code{--no-location}).
 485
 486 @item --strict
 487 @opindex --strict@r{, @code{xgettext} option}
 488 Write out a strict Uniforum conforming PO file.  Note that this
 489 Uniforum format should be avoided because it doesn't support the
 490 GNU extensions.
 491
 492 @item --properties-output
 493 @opindex --properties-output@r{, @code{xgettext} option}
 494 Write out a Java ResourceBundle in Java @code{.properties} syntax.  Note
 495 that this file format doesn't support plural forms and silently drops
 496 obsolete messages.
 497
 498 @item --stringtable-output
 499 @opindex --stringtable-output@r{, @code{xgettext} option}
 500 Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax.
 501 Note that this file format doesn't support plural forms.
 502
 503 @item --its=@var{file}
 504 @opindex --its@r{, @code{xgettext} option}
 505 Use ITS rules defined in @var{file}.
 506 Note that this is only effective with XML files.
 507
 508 @item --itstool
 509 @opindex --itstool@r{, @code{xgettext} option}
 510 Write out comments recognized by itstool (@uref{http://itstool.org}).
 511 Note that this is only effective with XML files.
 512
 513 @item -w @var{number}
 514 @itemx --width=@var{number}
 515 @opindex -w@r{, @code{xgettext} option}
 516 @opindex --width@r{, @code{xgettext} option}
 517 Set the output page width.  Long strings in the output files will be
 518 split across multiple lines in order to ensure that each line's width
 519 (= number of screen columns) is less or equal to the given @var{number}.
 520
 521 @item --no-wrap
 522 @opindex --no-wrap@r{, @code{xgettext} option}
 523 Do not break long message lines.  Message lines whose width exceeds the
 524 output page width will not be split into several lines.  Only file reference
 525 lines which are wider than the output page width will be split.
 526
 527 @item -s
 528 @itemx --sort-output
 529 @opindex -s@r{, @code{xgettext} option}
 530 @opindex --sort-output@r{, @code{xgettext} option}
 531 @cindex sorting output of @code{xgettext}
 532 Generate sorted output.  Note that using this option makes it much harder
 533 for the translator to understand each message's context.
 534
 535 @item -F
 536 @itemx --sort-by-file
 537 @opindex -F@r{, @code{xgettext} option}
 538 @opindex --sort-by-file@r{, @code{xgettext} option}
 539 Sort output by file location.
 540
 541 @item --omit-header
 542 @opindex --omit-header@r{, @code{xgettext} option}
 543 Don't write header with @samp{msgid ""} entry.
 544
 545 @cindex testing @file{.po} files for equivalence
 546 This is useful for testing purposes because it eliminates a source
 547 of variance for generated @code{.gmo} files.  With @code{--omit-header},
 548 two invocations of @code{xgettext} on the same files with the same
 549 options at different times are guaranteed to produce the same results.
 550
 551 Note that using this option will lead to an error if the resulting file
 552 would not entirely be in ASCII.
 553
 554 @item --copyright-holder=@var{string}
 555 @opindex --copyright-holder@r{, @code{xgettext} option}
 556 Set the copyright holder in the output.  @var{string} should be the
 557 copyright holder of the surrounding package.  (Note that the msgstr
 558 strings, extracted from the package's sources, belong to the copyright
 559 holder of the package.)  Translators are expected to transfer or disclaim
 560 the copyright for their translations, so that package maintainers can
 561 distribute them without legal risk.  If @var{string} is empty, the output
 562 files are marked as being in the public domain; in this case, the translators
 563 are expected to disclaim their copyright, again so that package maintainers
 564 can distribute them without legal risk.
 565
 566 The default value for @var{string} is the Free Software Foundation, Inc.,
 567 simply because @code{xgettext} was first used in the GNU project.
 568
 569 @item --foreign-user
 570 @opindex --foreign-user@r{, @code{xgettext} option}
 571 Omit FSF copyright in output.  This option is equivalent to
 572 @samp{--copyright-holder=''}.  It can be useful for packages outside the GNU
 573 project that want their translations to be in the public domain.
 574
 575 @item --package-name=@var{package}
 576 @opindex --package-name@r{, @code{xgettext} option}
 577 Set the package name in the header of the output.
 578
 579 @item --package-version=@var{version}
 580 @opindex --package-version@r{, @code{xgettext} option}
 581 Set the package version in the header of the output.  This option has an
 582 effect only if the @samp{--package-name} option is also used.
 583
 584 @item --msgid-bugs-address=@var{email@@address}
 585 @opindex --msgid-bugs-address@r{, @code{xgettext} option}
 586 Set the reporting address for msgid bugs.  This is the email address or URL
 587 to which the translators shall report bugs in the untranslated strings:
 588
 589 @itemize -
 590 @item Strings which are not entire sentences; see the maintainer guidelines
 591 in @ref{Preparing Strings}.
 592 @item Strings which use unclear terms or require additional context to be
 593 understood.
 594 @item Strings which make invalid assumptions about notation of date, time or
 595 money.
 596 @item Pluralisation problems.
 597 @item Incorrect English spelling.
 598 @item Incorrect formatting.
 599 @end itemize
 600
 601 It can be your email address, or a mailing list address where translators
 602 can write to without being subscribed, or the URL of a web page through
 603 which the translators can contact you.
 604
 605 The default value is empty, which means that translators will be clueless!
 606 Don't forget to specify this option.
 607
 608 @item -m[@var{string}]
 609 @itemx --msgstr-prefix[=@var{string}]
 610 @opindex -m@r{, @code{xgettext} option}
 611 @opindex --msgstr-prefix@r{, @code{xgettext} option}
 612 Use @var{string} (or "" if not specified) as prefix for msgstr values.
 613
 614 @item -M[@var{string}]
 615 @itemx --msgstr-suffix[=@var{string}]
 616 @opindex -M@r{, @code{xgettext} option}
 617 @opindex --msgstr-suffix@r{, @code{xgettext} option}
 618 Use @var{string} (or "" if not specified) as suffix for msgstr values.
 619
 620 @end table
 621
 622 @subsection Informative output
 623
 624 @table @samp
 625 @item -h
 626 @itemx --help
 627 @opindex -h@r{, @code{xgettext} option}
 628 @opindex --help@r{, @code{xgettext} option}
 629 Display this help and exit.
 630
 631 @item -V
 632 @itemx --version
 633 @opindex -V@r{, @code{xgettext} option}
 634 @opindex --version@r{, @code{xgettext} option}
 635 Output version information and exit.
 636
 637 @end table