diff options
| -rw-r--r-- | doc/ChangeLog | 27 | ||||
| -rw-r--r-- | doc/Makefile.am | 7 | ||||
| -rw-r--r-- | doc/gettext.texi | 416 | ||||
| -rw-r--r-- | doc/msgattrib.texi | 139 | ||||
| -rw-r--r-- | doc/msgcat.texi | 128 | ||||
| -rw-r--r-- | doc/msgcmp.texi | 49 | ||||
| -rw-r--r-- | doc/msgcomm.texi | 123 | ||||
| -rw-r--r-- | doc/msgconv.texi | 98 | ||||
| -rw-r--r-- | doc/msgen.texi | 89 | ||||
| -rw-r--r-- | doc/msgexec.texi | 111 | ||||
| -rw-r--r-- | doc/msgfmt.texi | 163 | ||||
| -rw-r--r-- | doc/msggrep.texi | 149 | ||||
| -rw-r--r-- | doc/msginit.texi | 64 | ||||
| -rw-r--r-- | doc/msgmerge.texi | 168 | ||||
| -rw-r--r-- | doc/msgunfmt.texi | 101 | ||||
| -rw-r--r-- | doc/msguniq.texi | 117 | ||||
| -rw-r--r-- | doc/xgettext.texi | 205 |
17 files changed, 1922 insertions, 232 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 1959a2f..03489f6 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,30 @@ +2001-10-11 Bruno Haible <haible@clisp.cons.org> + + * msgattrib.texi: New file. + * msgcat.texi: New file. + * msgcmp.texi: New file. + * msgcomm.texi: New file. + * msgconv.texi: New file. + * msgen.texi: New file. + * msgexec.texi: New file. + * msgfmt.texi: New file, partially from node "msgfmt Invocation". + * msggrep.texi: New file. + * msginit.texi: New file. + * msgmerge.texi: New file. + * msgunfmt.texi: New file. + * msguniq.texi: New file. + * xgettext.texi: New file, partially from node "xgettext Invocation". + * gettext.texi (Top): Add a fourth author. + (xgettext Invocation): Reorganize and move to xgettext.texi. + (Creating): Move most of contents to node "Header Entry". + (msginit Invocation): New node. + (msgmerge Invocation): Include msgmerge.texi. + (Manipulating): New chapter. + (msgfmt invocation): Reorganize and move to msgfmt.texi. + (msgunfmt invocation): New node. + (History): Update. + * Makefile.am (gettext_TEXINFOS): Add the new files. + 2001-09-18 Bruno Haible <haible@clisp.cons.org> * gettext.texi: Use file suffix .po instead of .pox. diff --git a/doc/Makefile.am b/doc/Makefile.am index fbae27e..ce84685 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -31,7 +31,12 @@ RM = rm -f MAKEINFO = env LANG= LANGUAGE= @MAKEINFO@ info_TEXINFOS = gettext.texi -gettext_TEXINFOS = iso-639.texi iso-3166.texi +# List of texinfo sources @included by gettext.texi, excluding version.texi. +gettext_TEXINFOS = \ + xgettext.texi msginit.texi msgmerge.texi msgcat.texi msgconv.texi \ + msggrep.texi msgexec.texi msguniq.texi msgcomm.texi msgcmp.texi \ + msgattrib.texi msgen.texi msgfmt.texi msgunfmt.texi \ + iso-639.texi iso-3166.texi EXTRA_DIST = iso-639.sed iso-3166.sed ISO_639 ISO_3166 nls.texi matrix.texi $(EXTRA_DIST_html) diff --git a/doc/gettext.texi b/doc/gettext.texi index 8967a91..ad4876d 100644 --- a/doc/gettext.texi +++ b/doc/gettext.texi @@ -51,6 +51,7 @@ by the Foundation. @author Ulrich Drepper @author Jim Meyering @author Fran@,{c}ois Pinard +@author Bruno Haible @page @vskip 0pt plus 1filll @@ -82,6 +83,7 @@ by the Foundation. * Template:: Making the PO Template File * Creating:: Creating a New PO File * Updating:: Updating Existing PO Files +* Manipulating:: Manipulating PO Files * Binaries:: Producing Binary MO Files * Users:: The User's View * Programmers:: The Programmer's View @@ -124,6 +126,11 @@ Making the PO Template File * xgettext Invocation:: Invoking the @code{xgettext} Program +Creating a New PO File + +* msginit Invocation:: Invoking the @code{msginit} Program +* Header Entry:: Fields in the Header Entry + Updating Existing PO Files * msgmerge Invocation:: Invoking the @code{msgmerge} Program @@ -143,9 +150,22 @@ Using Translation Compendia * Creating Compendia:: Merging translations for later use * Using Compendia:: Using older translations if they fit +Manipulating PO Files + +* msgcat Invocation:: Invoking the @code{msgcat} Program +* msgconv Invocation:: Invoking the @code{msgconv} Program +* msggrep Invocation:: Invoking the @code{msggrep} Program +* msgexec Invocation:: Invoking the @code{msgexec} Program +* msguniq Invocation:: Invoking the @code{msguniq} Program +* msgcomm Invocation:: Invoking the @code{msgcomm} Program +* msgcmp Invocation:: Invoking the @code{msgcmp} Program +* msgattrib Invocation:: Invoking the @code{msgattrib} Program +* msgen Invocation:: Invoking the @code{msgen} Program + Producing Binary MO Files * msgfmt Invocation:: Invoking the @code{msgfmt} Program +* msgunfmt Invocation:: Invoking the @code{msgunfmt} Program * MO Files:: The Format of GNU MO Files The User's View @@ -1893,148 +1913,42 @@ This section explains how to use @code{xgettext} for this purpose. @node xgettext Invocation, , Template, Template @section Invoking the @code{xgettext} Program -@c FIXME: Rewrite. - -@example -xgettext [@var{option}] @var{inputfile} @dots{} -@end example - -@table @samp -@item -a -@itemx --extract-all -Extract all strings. - -@item -c [@var{tag}] -@itemx --add-comments[=@var{tag}] -Place comment block with @var{tag} (or those preceding keyword lines) -in output file. - -@item -C -@itemx --c++ -Recognize C++ style comments. - -@itemx --debug -Use the flags @kbd{c-format} and @kbd{possible-c-format} to show who was -responsible for marking a message as a format string. The latter form is -used if the @code{xgettext} program decided, the format form is used if -the programmer prescribed it. - -By default only the @kbd{c-format} form is used. The translator should -not have to care about these details. - -@item -d @var{name} -@itemx --default-domain=@var{name} -Use @file{@var{name}.po} for output (instead of @file{messages.po}). - -The special domain name @file{-} or @file{/dev/stdout} means to write -the output to @file{stdout}. - -@item -D @var{directory} -@itemx --directory=@var{directory} -Change to @var{directory} before beginning to search and scan source -files. The resulting @file{.po} file will be written relative to the -original directory, though. - -@item -f @var{file} -@itemx --files-from=@var{file} -Read the names of the input files from @var{file} instead of getting -them from the command line. - -@itemx --force -Always write an output file even if no message is defined. +@include xgettext.texi -@item -h -@itemx --help -Display this help and exit. +@node Creating, Updating, Template, Top +@chapter Creating a New PO File -@item -I @var{list} -@itemx --input-path=@var{list} -List of directories searched for input files. - -@item -j -@itemx --join-existing -Join messages with existing file. - -@item -k @var{word} -@itemx --keyword[=@var{keywordspec}] -Additional keyword to be looked for (without @var{keywordspec} means not to -use default keywords). - -If @var{keywordspec} is a C identifer @var{id}, @code{xgettext} looks -for strings in the first argument of each call to the function or macro -@var{id}. If @var{keywordspec} is of the form -@samp{@var{id}:@var{argnum}}, @code{xgettext} looks for strings in the -@var{argnum}th argument of the call. If @var{keywordspec} is of the form -@samp{@var{id}:@var{argnum1},@var{argnum2}}, @code{xgettext} looks for -strings in the @var{argnum1}st argument and in the @var{argnum2}nd argument -of the call, and treats them as singular/plural variants for a message -with plural handling. - -The default keyword specifications, which are always looked for if not -explicitly disabled, are @code{gettext}, @code{dgettext:2}, -@code{dcgettext:2}, @code{ngettext:1,2}, @code{dngettext:2,3}, -@code{dcngettext:2,3}, and @code{gettext_noop}. - -@item -m [@var{string}] -@itemx --msgstr-prefix[=@var{string}] -Use @var{string} or "" as prefix for msgstr entries. - -@item -M [@var{string}] -@itemx --msgstr-suffix[=@var{string}] -Use @var{string} or "" as suffix for msgstr entries. - -@item --no-location -Do not write @samp{#: @var{filename}:@var{line}} lines. - -@item -n -@itemx --add-location -Generate @samp{#: @var{filename}:@var{line}} lines (default). - -@item --omit-header -Don't write header with @samp{msgid ""} entry. - -This is useful for testing purposes because it eliminates a source -of variance for generated @code{.gmo} files. We can ship some of -these files in the GNU @code{gettext} package, and the result of -regenerating them through @code{msgfmt} should yield the same values. - -@item -p @var{dir} -@itemx --output-dir=@var{dir} -Output files will be placed in directory @var{dir}. - -@item -s -@itemx --sort-output -Generate sorted output and remove duplicates. - -@item --strict -Write out a strict Uniforum conforming PO file. - -@item -v -@itemx --version -Output version information and exit. +When starting a new translation, the translator creates a file called +@file{@var{LANG}.po}, as a copy of the @file{@var{package}.pot} template +file with modifications in the initial comments (at the beginning of the file) +and in the header entry (the first entry, near the beginning of the file). -@item -x @var{file} -@itemx --exclude-file=@var{file} -Entries from @var{file} are not extracted. +The easiest way to do so is by use of the @samp{msginit} program. +For example: -@end table +@example +$ cd @var{PACKAGE}-@var{VERSION} +$ cd po +$ msginit --verbose +@end example -Search path for supplementary PO files is: -@file{/usr/local/share/nls/src/}. +The alternative way is to do the copy and modifications by hand. +To do so, the translator copies @file{@var{package}.pot} to +@file{@var{LANG}.po}. Then she modifies the initial comments and +the header entry of this file. -If @var{inputfile} is @samp{-}, standard input is read. +@menu +* msginit Invocation:: Invoking the @code{msginit} Program +* Header Entry:: Filling in the Header Entry +@end menu -This implementation of @code{xgettext} is able to process a few awkward -cases, like strings in preprocessor macros, ANSI concatenation of -adjacent strings, and escaped end of lines for continued strings. +@node msginit Invocation, Header Entry, Creating, Creating +@section Invoking the @code{msginit} Program -@node Creating, Updating, Template, Top -@chapter Creating a New PO File +@include msginit.texi -When starting a new translation, the translator copies the -@file{@var{package}.pot} template file to a file called -@file{@var{LANG}.po}. Then she modifies the initial comments and -the header entry of this file. +@node Header Entry, , msginit Invocation, Creating +@section Filling in the Header Entry The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST AUTHOR <EMAIL@@ADDRESS>, YEAR" ought to be replaced by sensible @@ -2167,7 +2081,7 @@ You can find them by searching for the @samp{msgid_plural} keyword. The format of the plural forms field is described in @ref{Plural forms}. @end table -@node Updating, Binaries, Creating, Top +@node Updating, Manipulating, Creating, Top @chapter Updating Existing PO Files @c FIXME: Rewrite. @@ -2189,26 +2103,7 @@ format of the plural forms field is described in @ref{Plural forms}. @node msgmerge Invocation, Translated Entries, Updating, Updating @section Invoking the @code{msgmerge} Program -@c FIXME: Rewrite. - -@c @example -@c tupdate --help -@c tupdate --version -@c tupdate @var{new} @var{old} -@c @end example - -@c File @var{new} is the last created PO file (generally by -@c @code{xgettext}). It need not contain any translations. File -@c @var{old} is the PO file including the old translations which will -@c be taken over to the newly created file as long as they still match. - -@c When English messages change in the programs, this is reflected in -@c the PO file as extracted by @code{xgettext}. In large messages, that -@c can be hard to detect, and will obviously result in an incomplete -@c translation. One of the virtues of @code{tupdate} is that it detects -@c such changes, saving the previous translation into a PO file comment, -@c so marking the entry as obsolete, and giving the modified string with -@c an empty translation, that is, marking the entry as untranslated. +@include msgmerge.texi @node Translated Entries, Fuzzy Entries, msgmerge Invocation, Updating @section Translated Entries @@ -3028,93 +2923,139 @@ msgcat --use-first -o update.po compendium1.po compendium2.po file.po msgmerge update.po file.pot | sed -e '/^#~/d' > file.po @end example -@node Binaries, Users, Updating, Top -@chapter Producing Binary MO Files +@node Manipulating, Binaries, Updating, Top +@chapter Manipulating PO Files -@c FIXME: Rewrite. +Sometimes it is necessary to manipulate PO files in a way that is better +performed automatically than by hand. GNU @code{gettext} includes a +complete set of tools for this purpose. + +When merging two packages into a single package, the resulting POT file +will be the concatenation of the two packages' POT files. Thus the +maintainer must concatenate the two existing package translations into +a single translation catalog, for each language. This is best performed +using @samp{msgcat}. It is then the translators' duty to deal with any +possible conflicts that arose during the merge. + +When a translator takes over the translation job from another translator, +but she uses a different character encoding in her locale, she will +convert the catalog to her character encoding. This is best done through +the @samp{msgconv} program. + +When a maintainer takes a source file with tagged messages from another +package, he should also take the existing translations for this source +file (and not let the translators do the same job twice). One way to do +this is through @samp{msggrep}, another is to create a POT file for +that source file and use @samp{msgmerge}. + +When a translator wants to adjust some translation catalog for a special +dialect or orthography - for example, German as written in Switzerland +versus German as written in Germany -, she needs to apply some text +processing to every message in the catalog. The tool for doing this is +@samp{msgexec}. + +Another use of @code{msgexec} is to produce approximately the POT file for +which a given PO file was made. This can be done through a filter command +like @samp{msgexec sed -e d | sed -e '/^# /d'}. Note that the original +POT file may have had different comments and different plural message counts, +that's why it's better to use the original POT file if available. + +When third party tools create PO or POT files, sometimes duplicates cannot +be avoided. But the GNU @code{gettext} tools give an error when they +encounter duplicate msgids in the same file and in the same domain. +To merge duplicates, the @code{msguniq} program can be used. + +@samp{msgcomm} is a more general tool for keeping or throwing away +duplicates, occurring in different files. + +@samp{msgcmp} can be used to check whether a translation catalog is +completely translated. + +@samp{msgattrib} can be used to select and extract only the fuzzy +or untranslated messages of a translation catalog. + +@samp{msgen} is useful as a first step for preparing English translation +catalogs. It copies each message's msgid to its msgstr. @menu -* msgfmt Invocation:: Invoking the @code{msgfmt} Program -* MO Files:: The Format of GNU MO Files +* msgcat Invocation:: Invoking the @code{msgcat} Program +* msgconv Invocation:: Invoking the @code{msgconv} Program +* msggrep Invocation:: Invoking the @code{msggrep} Program +* msgexec Invocation:: Invoking the @code{msgexec} Program +* msguniq Invocation:: Invoking the @code{msguniq} Program +* msgcomm Invocation:: Invoking the @code{msgcomm} Program +* msgcmp Invocation:: Invoking the @code{msgcmp} Program +* msgattrib Invocation:: Invoking the @code{msgattrib} Program +* msgen Invocation:: Invoking the @code{msgen} Program @end menu -@node msgfmt Invocation, MO Files, Binaries, Binaries -@section Invoking the @code{msgfmt} Program +@node msgcat Invocation, msgconv Invocation, Manipulating, Manipulating +@section Invoking the @code{msgcat} Program -@c FIXME: Rewrite. +@include msgcat.texi -@example -Usage: msgfmt [@var{option}] @var{filename}.po @dots{} -@end example +@node msgconv Invocation, msggrep Invocation, msgcat Invocation, Manipulating +@section Invoking the @code{msgconv} Program -@table @samp -@item -a @var{number} -@itemx --alignment=@var{number} -Align strings to @var{number} bytes (default: 1). -@c Currently the README mentions that this constant could be changed by -@c the installer by changing the value in config.h. Should this go away? +@include msgconv.texi -@item -h -@itemx --help -Display this help and exit. +@node msggrep Invocation, msgexec Invocation, msgconv Invocation, Manipulating +@section Invoking the @code{msggrep} Program -@item --no-hash -Binary file will not include the hash table. - -@item -o @var{file} -@itemx --output-file=@var{file} -Specify output file name as @var{file}. - -@itemx --strict -Direct the program to work strictly following the Uniforum/Sun -implementation. Currently this only affects the naming of the output -file. If this option is not given the name of the output file is the -same as the domain name. If the strict Uniforum mode is enabled the -suffix @file{.mo} is added to the file name if it is not already -present. - -We find this behaviour of Sun's implementation rather silly and so by -default this mode is @emph{not} selected. - -@item -v -@itemx --verbose -Detect and diagnose input file anomalies which might represent -translation errors. The @code{msgid} and @code{msgstr} strings are -studied and compared. It is considered abnormal that one string -starts or ends with a newline while the other does not. - -Also, if the string represents a format string used in a -@code{printf}-like function both strings should have the same number of -@samp{%} format specifiers, with matching types. If the flag -@code{c-format} or @code{possible-c-format} appears in the special -comment @key{#,} for this entry a check is performed. For example, the -check will diagnose using @samp{%.*s} against @samp{%s}, or @samp{%d} -against @samp{%s}, or @samp{%d} against @samp{%x}. It can even handle -positional parameters. - -Normally the @code{xgettext} program automatically decides whether a -string is a format string or not. This algorithm is not perfect, -though. It might regard a string as a format string though it is not -used in a @code{printf}-like function and so @code{msgfmt} might report -errors where there are none. Or the other way round: a string is not -regarded as a format string but it is used in a @code{printf}-like -function. +@include msggrep.texi -So solve this problem the programmer can dictate the decision to the -@code{xgettext} program (@pxref{c-format}). The translator should not -consider removing the flag from the @key{#,} line. This "fix" would be -reversed again as soon as @code{msgmerge} is called the next time. +@node msgexec Invocation, msguniq Invocation, msggrep Invocation, Manipulating +@section Invoking the @code{msgexec} Program -@item -V -@itemx --version -Output version information and exit. +@include msgexec.texi -@end table +@node msguniq Invocation, msgcomm Invocation, msgexec Invocation, Manipulating +@section Invoking the @code{msguniq} Program + +@include msguniq.texi + +@node msgcomm Invocation, msgcmp Invocation, msguniq Invocation, Manipulating +@section Invoking the @code{msgcomm} Program + +@include msgcomm.texi + +@node msgcmp Invocation, msgattrib Invocation, msgcomm Invocation, Manipulating +@section Invoking the @code{msgcmp} Program -If input file is @samp{-}, standard input is read. If output file -is @samp{-}, output is written to standard output. +@include msgcmp.texi -@node MO Files, , msgfmt Invocation, Binaries +@node msgattrib Invocation, msgen Invocation, msgcmp Invocation, Manipulating +@section Invoking the @code{msgattrib} Program + +@include msgattrib.texi + +@node msgen Invocation, , msgattrib Invocation, Manipulating +@section Invoking the @code{msgen} Program + +@include msgen.texi + +@node Binaries, Users, Manipulating, Top +@chapter Producing Binary MO Files + +@c FIXME: Rewrite. + +@menu +* msgfmt Invocation:: Invoking the @code{msgfmt} Program +* msgunfmt Invocation:: Invoking the @code{msgunfmt} Program +* MO Files:: The Format of GNU MO Files +@end menu + +@node msgfmt Invocation, msgunfmt Invocation, Binaries, Binaries +@section Invoking the @code{msgfmt} Program + +@include msgfmt.texi + +@node msgunfmt Invocation, MO Files, msgfmt Invocation, Binaries +@section Invoking the @code{msgunfmt} Program + +@include msgunfmt.texi + +@node MO Files, , msgunfmt Invocation, Binaries @section The Format of GNU MO Files The format of the generated MO files is best described by a picture, @@ -5529,11 +5470,11 @@ like GUI resources or package descriptions can make use of the gettext approach. @menu -* Language Implementors:: -* Programmers for other Languages:: -* Translators for other Languages:: -* List of Programming Languages:: -* List of Data Formats:: +* Language Implementors:: The Language Implementor's View +* Programmers for other Languages:: The Programmer's View +* Translators for other Languages:: The Translator's View +* List of Programming Languages:: Individual Programming Languages +* List of Data Formats:: Internationalizable Data @end menu @node Language Implementors, Programmers for other Languages, Programming Languages, Programming Languages @@ -6663,6 +6604,19 @@ Fran@,{c}ois also wrote PO mode in June 1995 with the collaboration of Greg McGary, as a kind of contribution to Ulrich's package. He also gave a hand with the GNU @code{gettext} Texinfo manual. +In 1997, Ulrich Drepper released the GNU libc 2.0, which included the +@code{gettext}, @code{textdomain} and @code{bindtextdomain} functions. + +In 2000, Ulrich Drepper added plural form handling (the @code{ngettext} +function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x, +which is the first free C library with full internationalization support. + +Ulrich being quite busy in his role of General Maintainer of GNU libc, +he handed over the GNU @code{gettext} maintenance to Bruno Haible in +2000. Bruno added the plural form handling to the tools as well, added +support for UTF-8 and CJK locales, and wrote a few new tools for +manipulating PO files. + @node References, , History, Conclusion @section Related Readings diff --git a/doc/msgattrib.texi b/doc/msgattrib.texi new file mode 100644 index 0000000..dfe50b5 --- /dev/null +++ b/doc/msgattrib.texi @@ -0,0 +1,139 @@ +@example +msgattrib [@var{option}] [@var{inputfile}] +@end example + +The @code{msgattrib} program filters the messages of a translation catalog +according to their attributes, and manipulates the attributes. + +@subsection Input file location + +@table @samp +@item @var{inputfile} +Input PO file. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If no @var{inputfile} is given or if it is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Message selection + +@table @samp +@item --translated +Keep translated messages, remove untranslated messages. + +@item --untranslated +Keep untranslated messages, remove translated messages. + +@item --no-fuzzy +Remove `fuzzy' marked messages. + +@item --only-fuzzy +Keep `fuzzy' marked messages, remove all other messsages. + +@item --no-obsolete +Remove obsolete #~ messages. + +@item --only-obsolete +Keep obsolete #~ messages, remove all other messages. + +@end table + +@subsection Attribute manipulation + +Attributes are modified after the message selection/removal has been +performed. + +@table @samp +@item --set-fuzzy +Set all messages `fuzzy'. + +@item --clear-fuzzy +Set all messages non-`fuzzy'. + +@item --set-obsolete +Set all messages obsolete. + +@item --clear-obsolete +Set all messages non-obsolete. + +@item --fuzzy +Synonym for @samp{--only-fuzzy --clear-fuzzy}: It keeps only the fuzzy +messages and removes their `fuzzy' mark. + +@item --obsolete +Synonym for @samp{--only-obsolete --clear-obsolete}: It keeps only the +obsolete messages and makes them non-obsolete. + +@end table + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if it contains no message. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item -n +@itemx --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/msgcat.texi b/doc/msgcat.texi new file mode 100644 index 0000000..f94aa77 --- /dev/null +++ b/doc/msgcat.texi @@ -0,0 +1,128 @@ +@example +msgcat [@var{option}] [@var{inputfile}]... +@end example + +The @code{msgcat} program concatenates and merges the specified PO files. +It finds messages which are common to two or more of the specified PO files. +By using the @code{--more-than} option, greater commonality may be requested +before messages are printed. Conversely, the @code{--less-than} option may be +used to specify less commonality before messages are printed (i.e. +@samp{--less-than=2} will only print the unique messages). Translations, +comments and extract comments will be cumulated, except that if +@code{--use-first} is specified, they will be taken from the first PO file +to define them. File positions from all PO files will be cumulated. + +@subsection Input file location + +@table @samp +@item @var{inputfile} @dots{} +Input files. + +@item -f @var{file} +@itemx --files-from=@var{file} +Read the names of the input files from @var{file} instead of getting +them from the command line. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If @var{inputfile} is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Message selection + +@table @samp +@item -< @var{number} +@itemx --less-than=@var{number} +Print messages with less than @var{number} definitions, defaults to infinite +if not set. + +@item -> @var{number} +@itemx --more-than=@var{number} +Print messages with more than @var{number} definitions, defaults to 0 if not +set. + +@item -u +@itemx --unique +Shorthand for @samp{--less-than=2}. Requests that only unique messages be +printed. + +@end table + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item -t +@itemx --to-code=@var{name} +Specify encoding for output. + +@item --use-first +Use first available translation for each message. Don't merge several +translations into one. + +@item --force-po +Always write an output file even if it contains no message. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item -n +@itemx --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/msgcmp.texi b/doc/msgcmp.texi new file mode 100644 index 0000000..8f0273f --- /dev/null +++ b/doc/msgcmp.texi @@ -0,0 +1,49 @@ +@example +msgcmp [@var{option}] @var{def}.po @var{ref}.pot +@end example + +The @code{msgcmp} program compares two Uniforum style .po files to check that +both contain the same set of msgid strings. The @var{def}.po file is an +existing PO file with the translations. The @var{ref}.pot file is the last +created PO file, or a PO Template file (generally created by @code{xgettext}). +This is useful for checking that you have translated each and every message +in your program. Where an exact match cannot be found, fuzzy matching is +used to produce better diagnostics. + +@subsection Input file location + +@table @samp +@item @var{def}.po +Translations. + +@item @var{ref}.pot +References to the sources. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. + +@end table + +@subsection Operation modifiers + +@table @samp +@item -m +@itemx --multi-domain +Apply @var{ref}.pot to each of the domains in @var{def}.po. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/msgcomm.texi b/doc/msgcomm.texi new file mode 100644 index 0000000..1bb6cad --- /dev/null +++ b/doc/msgcomm.texi @@ -0,0 +1,123 @@ +@example +msgcomm [@var{option}] [@var{inputfile}]... +@end example + +The @code{msgcomm} program finds messages which are common to two or more +of the specified PO files. +By using the @code{--more-than} option, greater commonality may be requested +before messages are printed. Conversely, the @code{--less-than} option may be +used to specify less commonality before messages are printed (i.e. +@samp{--less-than=2} will only print the unique messages). Translations, +comments and extract comments will be preserved, but only from the first +PO file to define them. File positions from all PO files will be +cumulated. + +@subsection Input file location + +@table @samp +@item @var{inputfile} @dots{} +Input files. + +@item -f @var{file} +@itemx --files-from=@var{file} +Read the names of the input files from @var{file} instead of getting +them from the command line. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If @var{inputfile} is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Message selection + +@table @samp +@item -< @var{number} +@itemx --less-than=@var{number} +Print messages with less than @var{number} definitions, defaults to infinite +if not set. + +@item -> @var{number} +@itemx --more-than=@var{number} +Print messages with more than @var{number} definitions, defaults to 1 if not +set. + +@item -u +@itemx --unique +Shorthand for @samp{--less-than=2}. Requests that only unique messages be +printed. + +@end table + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if it contains no message. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item -n +@itemx --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@item --omit-header +Don't write header with @samp{msgid ""} entry. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/msgconv.texi b/doc/msgconv.texi new file mode 100644 index 0000000..1d1ae1b --- /dev/null +++ b/doc/msgconv.texi @@ -0,0 +1,98 @@ +@example +msgconv [@var{option}] [@var{inputfile}] +@end example + +The @code{msgconv} program converts a translation catalog to a different +character encoding. + +@subsection Input file location + +@table @samp +@item @var{inputfile} +Input PO file. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If no @var{inputfile} is given or if it is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Conversion target + +@table @samp +@item -t +@itemx --to-code=@var{name} +Specify encoding for output. + +@end table + +The default encoding is the current locale's encoding. + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if it contains no message. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/msgen.texi b/doc/msgen.texi new file mode 100644 index 0000000..32bca0e --- /dev/null +++ b/doc/msgen.texi @@ -0,0 +1,89 @@ +@example +msgen [@var{option}] @var{inputfile} +@end example + +The @code{msgen} program creates an English translation catalog. The +input file is the last created English PO file, or a PO Template file +(generally created by xgettext). Untranslated entries are assigned a +translation that is identical to the msgid, and are marked fuzzy. + +@subsection Input file location + +@table @samp +@item @var{inputfile} +Input PO or POT file. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If @var{inputfile} is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if it contains no message. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/msgexec.texi b/doc/msgexec.texi new file mode 100644 index 0000000..c718e41 --- /dev/null +++ b/doc/msgexec.texi @@ -0,0 +1,111 @@ +@example +msgexec [@var{option}] @var{filter} [@var{filter-option}] +@end example + +The @code{msgexec} program applies a filter to all translations of a +translation catalog. + +@subsection Input file location + +@table @samp +@item -i @var{inputfile} +@itemx --input=@var{inputfile} +Input PO file. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If no @var{inputfile} is given or if it is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection The filter + +The @var{filter} can be any program that reads a translation from standard +input and writes a modified translation to standard output. A frequently +used filter is @samp{sed}. + +@subsection Useful @var{filter-option}s when the @var{filter} is @samp{sed} + +@table @samp +@item -e @var{script} +@itemx --expression=@var{script} +Add @var{script} to the commands to be executed. + +@item -f @var{scriptfile} +@itemx --file=@var{scriptfile} +Add the contents of @var{scriptfile} to the commands to be executed. + +@item -n +@itemx --quiet +@itemx --silent +Suppress automatic printing of pattern space. + +@end table + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if it contains no message. + +@item --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/msgfmt.texi b/doc/msgfmt.texi new file mode 100644 index 0000000..dc30e45 --- /dev/null +++ b/doc/msgfmt.texi @@ -0,0 +1,163 @@ +@example +msgfmt [@var{option}] @var{filename}.po @dots{} +@end example + +The @code{msgfmt} programs generates a binary message catalog from a textual +translation description. + +@subsection Input file location + +@table @samp +@item @var{filename}.po @dots{} + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If an input file is @samp{-}, standard input is read. + +@subsection Operation mode + +@table @samp +@item -j +@itemx --java +Java mode: generate a Java @code{ResourceBundle} class. + +@item --java2 +Like --java, and assume Java2 (JDK 1.2 or higher). + +@end table + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@item --strict +Direct the program to work strictly following the Uniforum/Sun +implementation. Currently this only affects the naming of the output +file. If this option is not given the name of the output file is the +same as the domain name. If the strict Uniforum mode is enabled the +suffix @file{.mo} is added to the file name if it is not already +present. + +We find this behaviour of Sun's implementation rather silly and so by +default this mode is @emph{not} selected. + +@end table + +If the output @var{file} is @samp{-}, output is written to standard output. + +@subsection Output file location in Java mode + +@table @samp +@item -r @var{resource} +@itemx --resource=@var{resource} +Specify the resource name. + +@item -l @var{locale} +@itemx --locale=@var{locale} +Specify the locale name, either a language specification of the form @var{ll} +or a combined language and country specification of the form @var{ll_CC}. + +@item -d @var{directory} +Specify the base directory of classes directory hierarchy. + +@end table + +The class name is determined by appending the locale name to the resource name, +separated with an underscore. The @samp{-d} option is mandatory. The class +is written under the specified directory. + +@subsection Input file interpretation + +@table @samp +@item -c +@itemx --check +Perform all the checks implied by @code{--check-format}, @code{--check-header}, +@code{--check-domain}. + +@item --check-format +Check language dependent format strings. + +If the string represents a format string used in a +@code{printf}-like function both strings should have the same number of +@samp{%} format specifiers, with matching types. If the flag +@code{c-format} or @code{possible-c-format} appears in the special +comment @key{#,} for this entry a check is performed. For example, the +check will diagnose using @samp{%.*s} against @samp{%s}, or @samp{%d} +against @samp{%s}, or @samp{%d} against @samp{%x}. It can even handle +positional parameters. + +Normally the @code{xgettext} program automatically decides whether a +string is a format string or not. This algorithm is not perfect, +though. It might regard a string as a format string though it is not +used in a @code{printf}-like function and so @code{msgfmt} might report +errors where there are none. + +To solve this problem the programmer can dictate the decision to the +@code{xgettext} program (@pxref{c-format}). The translator should not +consider removing the flag from the @key{#,} line. This "fix" would be +reversed again as soon as @code{msgmerge} is called the next time. + +@item --check-header +Verify presence and contents of the header entry. @xref{Header Entry}, +for a description of the various fields in the header entry. + +@item --check-domain +Check for conflicts between domain directives and the @code{--output-file} +option + +@item -C +@itemx --check-compatibility +Check that GNU msgfmt behaves like X/Open msgfmt. This will give an error +when attempting to use the GNU extensions. + +@item -f +@itemx --use-fuzzy +Use fuzzy entries in output. Note that using this option is usually wrong, +because fuzzy messages are exactly those which have not been validated by +a human translator. + +@end table + +@subsection Output details + +@table @samp +@item -a @var{number} +@itemx --alignment=@var{number} +Align strings to @var{number} bytes (default: 1). +@c Currently the README mentions that this constant could be changed by +@c the installer by changing the value in config.h. Should this go away? + +@item --no-hash +Don't include a hash table in the binary file. Lookup will be more expensive +at run time (binary search instead of hash table lookup). + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@item --statistics +Print statistics about translations. + +@item -v +@itemx --verbose +Increase verbosity level. + +@end table diff --git a/doc/msggrep.texi b/doc/msggrep.texi new file mode 100644 index 0000000..a9c48b2 --- /dev/null +++ b/doc/msggrep.texi @@ -0,0 +1,149 @@ +@example +msggrep [@var{option}] [@var{inputfile}] +@end example + +The @code{msggrep} program extracts all messages of a translation catalog +that match a given pattern or belong to some given source files. + +@subsection Input file location + +@table @samp +@item @var{inputfile} +Input PO file. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If no @var{inputfile} is given or if it is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Message selection + +@example + [-N @var{sourcefile}]... [-M @var{domainname}]... [-K @var{msgid-pattern}] [-T @var{msgstr-pattern}] +@end example + +A message is selected if +@itemize @bullet +@item it comes from one of the specified source files, +@item or if it comes from one of the specified domains, +@item or if @samp{-K} is given and its key (msgid or msgid_plural) matches + @var{msgid-pattern}, +@item or if @samp{-T} is given and its translation (msgstr) matches + @var{msgstr-pattern}. +@end itemize + +When more than one selection criterion is specified, the set of selected +messages is the union of the selected messages of each criterion. + +@var{msgid-pattern} or @var{msgstr-pattern} syntax: +@example + [-E | -F] [-e @var{pattern} | -f @var{file}]... +@end example +@var{pattern}s are basic regular expressions by default, or extended regular +expressions if -E is given, or fixed strings if -F is given. + +@table @samp +@item -N @var{sourcefile} +@itemx --location=@var{sourcefile} +Select messages extracted from @var{sourcefile}. + +@item -M @var{domainname} +@itemx --domain=@var{domainname} +Select messages belonging to domain @var{domainname}. + +@item -K +@itemx --msgid +Start of patterns for the msgid. + +@item -T +@itemx --msgstr +Start of patterns for the msgstr. + +@item -E +@itemx --extended-regexp +Specify that @var{pattern} is an extended regular expression. + +@item -F +@itemx --fixed-strings +Specify that @var{pattern} is a set of newline-separated strings. + +@item -e @var{pattern} +@itemx --regexp=@var{pattern} +Use @var{pattern} as a regular expression. + +@item -f @var{file} +@itemx --file=@var{file} +Obtain @var{pattern} from @var{file}. + +@item -i +@itemx --ignore-case +Ignore case distinctions. + +@end table + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if it contains no message. + +@item --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item --sort-by-file +Sort output by file location. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/msginit.texi b/doc/msginit.texi new file mode 100644 index 0000000..80212a1 --- /dev/null +++ b/doc/msginit.texi @@ -0,0 +1,64 @@ +@example +msginit [@var{option}] +@end example + +The @code{msginit} program creates a new PO file, initializing the meta +information with values from the user's environment. + +@subsection Input file location + +@table @samp +@item -i @var{inputfile} +@itemx --input=@var{inputfile} +Input POT file. + +@end table + +If no @var{inputfile} is given, the current directory is searched for the +POT file. If it is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified PO file. + +@end table + +If no output file is given, it depends on the @samp{--locale} option or the +user's locale setting. If it is @samp{-}, the results are written to +standard output. + +@subsection Output details + +@table @samp +@item -l @var{ll_CC} +@itemx --locale=@var{ll_CC} +Set target locale. @var{ll} should be a language code, and @var{CC} should +be a country code. The default is the user's locale setting. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@item -v +@itemx --verbose +Increase verbosity level. + +@end table diff --git a/doc/msgmerge.texi b/doc/msgmerge.texi new file mode 100644 index 0000000..40a515a --- /dev/null +++ b/doc/msgmerge.texi @@ -0,0 +1,168 @@ +@example +msgmerge [@var{option}] @var{def}.po @var{ref}.pot +@end example + +The @code{msgmerge} program merges two Uniforum style .po files together. +The @var{def}.po file is an existing PO file with translations which will +be taken over to the newly created file as long as they still match; +comments will be preserved, but extracted comments and file positions will +be discarded. The @var{ref}.pot file is the last created PO file with +up-to-date source references but old translations, or a PO Template file +(generally created by @code{xgettext}); any translations or comments +in the file will be discarded, however dot comments and file positions +will be preserved. Where an exact match cannot be found, fuzzy matching +is used to produce better results. + +@subsection Input file location + +@table @samp +@item @var{def}.po +Translations referring to old sources. + +@item @var{ref}.pot +References to the new sources. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@item -C @var{file} +@itemx --compendium=@var{file} +Specify an additional library of message translations. @xref{Compendium}. +This option may be specified more than once. + +@end table + +@subsection Operation mode + +@table @samp +@item -U +@itemx --update +Update @var{def}.po. Do nothing if @var{def}.po is already up to date. + +@end table + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Output file location in update mode + +The result is written back to @var{def}.po. + +@table @samp +@item --backup=@var{control} +Make a backup of @var{def}.po + +@item --suffix=@var{suffix} +Override the usual backup suffix. + +@end table + +The version control method may be selected via the @code{--backup} option +or through the @code{VERSION_CONTROL} environment variable. Here are the +values: + +@table @samp +@item none +@itemx off +Never make backups (even if @code{--backup} is given). + +@item numbered +@itemx t +Make numbered backups. + +@item existing +@itemx nil +Make numbered backups if numbered backups for this file already exist, +otherwise make simple backups. + +@item simple +@itemx never +Always make simple backups. + +@end table + +The backup suffix is @samp{~}, unless set with @code{--suffix} or the +@code{SIMPLE_BACKUP_SUFFIX} environment variable. + +@subsection Operation modifiers + +@table @samp +@item -m +@itemx --multi-domain +Apply @var{ref}.pot to each of the domains in @var{def}.po. + +@end table + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if it contains no message. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@item -v +@itemx --verbose +Increase verbosity level. + +@item -q +@itemx --quiet +@itemx --silent +Suppress progress indicators. + +@end table diff --git a/doc/msgunfmt.texi b/doc/msgunfmt.texi new file mode 100644 index 0000000..f8f68d2 --- /dev/null +++ b/doc/msgunfmt.texi @@ -0,0 +1,101 @@ +@example +msgunfmt [@var{option}] [@var{file}]... +@end example + +The @code{msgunfmt} program converts a binary message catalog to a +Uniforum style .po file. + +@subsection Operation mode + +@table @samp +@item -j +@itemx --java +Java mode: generate a Java @code{ResourceBundle} class. + +@end table + +@subsection Input file location + +@table @samp +@item @var{file} @dots{} +Input .mo files. + +@end table + +If no input @var{file} is given or if it is @samp{-}, standard input is read. + +@subsection Input file location in Java mode + +@table @samp +@item -r @var{resource} +@itemx --resource=@var{resource} +Specify the resource name. + +@item -l @var{locale} +@itemx --locale=@var{locale} +Specify the locale name, either a language specification of the form @var{ll} +or a combined language and country specification of the form @var{ll_CC}. + +@end table + +The class name is determined by appending the locale name to the resource name, +separated with an underscore. The class is located using the @code{CLASSPATH}. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if it contains no message. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@item -v +@itemx --verbose +Increase verbosity level. + +@end table diff --git a/doc/msguniq.texi b/doc/msguniq.texi new file mode 100644 index 0000000..7438ca6 --- /dev/null +++ b/doc/msguniq.texi @@ -0,0 +1,117 @@ +@example +msguniq [@var{option}] [@var{inputfile}] +@end example + +The @code{msguniq} program unifies duplicate translations in a translation +catalog. It finds duplicate translations of the same message ID. Such +duplicates are invalid input for other programs like @code{msgfmt}, +@code{msgmerge} or @code{msgcat}. By default, duplicates are merged +together. When using the @samp{--repeated} option, only duplicates are +output, and all other messages are discarded. Comments and extracted +comments will be cumulated, except that if @samp{--use-first} is +specified, they will be taken from the first translation. File positions +will be cumulated. When using the @samp{--unique} option, duplicates are +discarded. + +@subsection Input file location + +@table @samp +@item @var{inputfile} +Input PO file. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If no @var{inputfile} is given or if it is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +Write output to specified file. + +@end table + +The results are written to standard output if no output file is specified +or if it is @samp{-}. + +@subsection Message selection + +@table @samp +@item -d +@itemx --repeated +Print only duplicates. + +@item -u +@itemx --unique +Print only unique messages, discard duplicates. + +@end table + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item -t +@itemx --to-code=@var{name} +Specify encoding for output. + +@item --use-first +Use first available translation for each message. Don't merge several +translations into one. + +@item --force-po +Always write an output file even if it contains no message. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item -n +@itemx --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table diff --git a/doc/xgettext.texi b/doc/xgettext.texi new file mode 100644 index 0000000..5bf260d --- /dev/null +++ b/doc/xgettext.texi @@ -0,0 +1,205 @@ +@example +xgettext [@var{option}] [@var{inputfile}] @dots{} +@end example + +The @code{xgettext} program extracts translatable strings from given +input files. + +@subsection Input file location + +@table @samp +@item @var{inputfile} @dots{} +Input files. + +@item -f @var{file} +@itemx --files-from=@var{file} +Read the names of the input files from @var{file} instead of getting +them from the command line. + +@item -D @var{directory} +@itemx --directory=@var{directory} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting @file{.po} +file will be written relative to the current directory, though. + +@end table + +If @var{inputfile} is @samp{-}, standard input is read. + +@subsection Output file location + +@table @samp +@item -d @var{name} +@itemx --default-domain=@var{name} +Use @file{@var{name}.po} for output (instead of @file{messages.po}). + +@item -o @var{file} +@itemx --output=@var{file} +Write output to specified file (instead of @file{@var{name}.po} or +@file{messages.po}). + +@item -p @var{dir} +@itemx --output-dir=@var{dir} +Output files will be placed in directory @var{dir}. + +@end table + +If the output @var{file} is @samp{-} or @samp{/dev/stdout}, the output +is written to standard output. + +@subsection Choice of input file language + +@table @samp +@item -L @var{name} +@itemx --language=@var{name} +Specifies the language of the input files. The supported languages +are @code{C}, @code{C++}, @code{ObjectiveC}, @code{PO}, @code{Java}, +@code{YCP}. + +@item -C +@itemx --c++ +This is a shorthand for @code{--language=C++}. + +@end table + +By default the language is guessed depending on the input file name +extension. + +@subsection Operation mode + +@table @samp +@item -j +@itemx --join-existing +Join messages with existing file. + +@item -x @var{file} +@itemx --exclude-file=@var{file} +Entries from @var{file} are not extracted. @var{file} should be a PO or +POT file. + +@item -c [@var{tag}] +@itemx --add-comments[=@var{tag}] +Place comment block with @var{tag} (or those preceding keyword lines) +in output file. + +@end table + +@subsection Language=C/C++ specific options + +@table @samp +@item -a +@itemx --extract-all +Extract all strings. + +@item -k @var{keywordspec} +@itemx --keyword[=@var{keywordspec}] +Additional keyword to be looked for (without @var{keywordspec} means not to +use default keywords). + +If @var{keywordspec} is a C identifer @var{id}, @code{xgettext} looks +for strings in the first argument of each call to the function or macro +@var{id}. If @var{keywordspec} is of the form +@samp{@var{id}:@var{argnum}}, @code{xgettext} looks for strings in the +@var{argnum}th argument of the call. If @var{keywordspec} is of the form +@samp{@var{id}:@var{argnum1},@var{argnum2}}, @code{xgettext} looks for +strings in the @var{argnum1}st argument and in the @var{argnum2}nd argument +of the call, and treats them as singular/plural variants for a message +with plural handling. + +The default keyword specifications, which are always looked for if not +explicitly disabled, are @code{gettext}, @code{dgettext:2}, +@code{dcgettext:2}, @code{ngettext:1,2}, @code{dngettext:2,3}, +@code{dcngettext:2,3}, and @code{gettext_noop}. + +@item -T +@itemx --trigraphs +Understand ANSI C trigraphs for input. + +@itemx --debug +Use the flags @kbd{c-format} and @kbd{possible-c-format} to show who was +responsible for marking a message as a format string. The latter form is +used if the @code{xgettext} program decided, the format form is used if +the programmer prescribed it. + +By default only the @kbd{c-format} form is used. The translator should +not have to care about these details. + +@end table + +This implementation of @code{xgettext} is able to process a few awkward +cases, like strings in preprocessor macros, ANSI concatenation of +adjacent strings, and escaped end of lines for continued strings. + +@subsection Output details + +@c --no-escape and --escape omitted on purpose. They are not useful. + +@table @samp +@item --force-po +Always write an output file even if no message is defined. + +@item -i +@itemx --indent +Write the .po file using indented style. + +@item --no-location +Do not write @samp{#: @var{filename}:@var{line}} lines. + +@item -n +@itemx --add-location +Generate @samp{#: @var{filename}:@var{line}} lines (default). + +@item --strict +Write out a strict Uniforum conforming PO file. Note that this +Uniforum format should be avoided because it doesn't support the +GNU extensions. + +@item -w @var{number} +@itemx --width=@var{number} +Set the output page width. Long strings in the output files will be +split across multiple lines in order to ensure that each line's width +(= number of screen columns) is less or equal to the given @var{number}. + +@item -s +@itemx --sort-output +Generate sorted output. Note that using this option makes it much harder +for the translator to understand each message's context. + +@item -F +@itemx --sort-by-file +Sort output by file location. + +@item --omit-header +Don't write header with @samp{msgid ""} entry. + +This is useful for testing purposes because it eliminates a source +of variance for generated @code{.gmo} files. With @code{--omit-header}, +two invocations of @code{xgettext} on the same files with the same +options at different times are guaranteed to produce the same results. + +@item --foreign-user +Omit FSF copyright in output. This can be useful for translators +outside the GNU project. + +@item -m [@var{string}] +@itemx --msgstr-prefix[=@var{string}] +Use @var{string} (or "" if not specified) as prefix for msgstr entries. + +@item -M [@var{string}] +@itemx --msgstr-suffix[=@var{string}] +Use @var{string} (or "" if not specified) as suffix for msgstr entries. + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +Display this help and exit. + +@item -V +@itemx --version +Output version information and exit. + +@end table |