From a22b7426addeecab5ac1a357141bc572d0bd49eb Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Sun, 29 Aug 2010 17:26:56 +0200 Subject: [PATCH] Internationalization documentation fixes. * doc/automake.texi (Uniform): Mention the POTS primary. (Internationalization): Many small tweaks. Reported by Ralf Wildenhues. --- ChangeLog | 7 +++ doc/automake.texi | 117 +++++++++++++++++++++++----------------------- 2 files changed, 66 insertions(+), 58 deletions(-) diff --git a/ChangeLog b/ChangeLog index 733dbfda0..47ec0f0a3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2010-08-29 Bruno Haible + + Internationalization documentation fixes. + * doc/automake.texi (Uniform): Mention the POTS primary. + (Internationalization): Many small tweaks. + Reported by Ralf Wildenhues. + 2010-08-15 Bruno Haible Document the handling of POT and PO files. diff --git a/doc/automake.texi b/doc/automake.texi index 57d472c37..37fc89397 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -281,29 +281,29 @@ Built Sources Internationalization -* POT Files:: Declaring a POT file -* Parametrizing xgettext:: Declaring how a POT file gets created -* Message catalog translations::Declaring the translations -* Message catalog installation::Declaring how message catalogs get installed -* Other POT files details:: Rarely used settings for POT files +* POT Files:: Declaring a POT file +* Parameterizing xgettext:: Declaring how a POT file gets created +* Message catalog translations:: Declaring the translations +* Message catalog installation:: Declaring how message catalogs get installed +* Other POT files details:: Rarely used settings for POT files -Parametrizing xgettext +Parameterizing xgettext -* A POT file's _SOURCES:: Declaring the source files. -* A POT file's _COPYRIGHT_HOLDER:: The message catalogs' copyright holder -* A POT file's _MSGID_BUGS_ADDRESS:: Allowing translators to report bugs -* Additional xgettext options:: Fine tuning of xgettext -* Multiple xgettext invocations:: Advanced uses of xgettext +* A POT file's _SOURCES:: Declaring the source files +* A POT file's _COPYRIGHT_HOLDER:: The message catalogs' copyright holder +* A POT file's _MSGID_BUGS_ADDRESS:: Allowing translators to report bugs +* Additional xgettext options:: Fine-tuning of xgettext +* Multiple xgettext invocations:: Advanced uses of xgettext Message catalog installation -* A POT file's _CATALOGFORMAT:: Formats of compiled message catalogs -* A POT file's _LOCALE_CATEGORIES:: Using different locale categories +* A POT file's _CATALOGFORMAT:: Formats of compiled message catalogs +* A POT file's _LOCALE_CATEGORIES:: Using different locale categories Other POT files details -* A POT file's _USE_MSGCTXT:: Declaring whether msgctxt is used -* A POT file's _MSGMERGE_OPTIONS:: Specifying options for msgmerge +* A POT file's _USE_MSGCTXT:: Declaring whether msgctxt is used +* A POT file's _MSGMERGE_OPTIONS:: Specifying options for msgmerge Other GNU Tools @@ -2047,7 +2047,7 @@ objects are not installed either. The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA}, -@samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}. +@samp{HEADERS}, @samp{POTS}, @samp{MANS}, and @samp{TEXINFOS}. @vindex PROGRAMS @vindex LIBRARIES @vindex LISP @@ -3897,14 +3897,15 @@ you have an @command{emacs} that supports Emacs Lisp). @acindex AM_POT_TOOLS The @code{AM_POT_TOOLS} macro performs tests for the @code{POTS} primary. -See @pxref{Programming Languages, , Programming Languages, gettext, +See @ref{Programming Languages, , Programming Languages, gettext, GNU gettext tools} for a list of programming languages that support localization through PO files. The @code{AM_POT_TOOLS} macro determines whether internationalization -should be used. If so, it sets the @code{USE_NLS} variable to @samp{yes}, -otherwise to @samp{no}. It also determines the right values for Makefile -variables used by the Makefile rules for the POT and PO files. +should be used (@pxref{Internationalization}). If so, it sets the +@code{USE_NLS} variable to @samp{yes}, otherwise to @samp{no}. It also +determines the right values for Makefile variables used by the Makefile +rules for the POT and PO files. @item AM_PROG_AS @acindex AM_PROG_AS @@ -7406,8 +7407,8 @@ is converting @file{.h} files into @file{.c} files. @chapter Internationalization An internationalized program is a program that can communicate with the -user in his native language, provided that some translation work has been -done. An internationalized program can be localized to a certain +user in his/her native language, provided that some translation work has +been done. An internationalized program can be localized to a certain language by translating the messages by which the program communicates with the user. These message are grouped in files called ``message catalogs''. @@ -7433,15 +7434,15 @@ Gettext tools are in use: @item The file that contains the English messages and translation hints is called a POT file (Portable Object Template) and usually named -@code{@var{domain}.pot}. The @var{domain} is a identifier for the +@code{@var{domain}.pot}. The @var{domain} is an identifier for the translation domain. Different packages must use different @var{domain}s. -Therefore, usually, the @var{domain} is the same as the package name. +Therefore the @var{domain} is usually the same as the package name. @item The file that contains the translation produced by a translation team is called a PO file (Portable Object) and usually named @code{@var{domain}-@var{ll}.po} or -@code{@var{domain}-@var{ll}_@var{CC}.po}. Here @var{ll} is the +@code{@var{domain}-@var{ll}_@var{CC}.po}. Here, @var{ll} is the language code identifier according to ISO 639, and the optional @var{CC} is the country code identifier according to ISO 3166. The optional @var{CC} is only needed to distinguish different dialects of the same @@ -7450,22 +7451,22 @@ different from @code{pt} (Portuguese). @end itemize @menu -* POT Files:: Declaring a POT file -* Parametrizing xgettext:: Declaring how a POT file gets created -* Message catalog translations::Declaring the translations -* Message catalog installation::Declaring how message catalogs get installed -* Other POT files details:: Rarely used settings for POT files +* POT Files:: Declaring a POT file +* Parameterizing xgettext:: Declaring how a POT file gets created +* Message catalog translations:: Declaring the translations +* Message catalog installation:: Declaring how message catalogs get installed +* Other POT files details:: Rarely used settings for POT files @end menu @node POT Files @section POT Files -In Automake, a message catalog template (POT file) is a primary. The -Makefile rules generated by Automake also handle all the PO files that -belong to the POT file. +In Automake, a message catalog template (POT file) is declared through +the @samp{POTS} primary. The Makefile rules generated by Automake also +handle all the PO files that belong to the POT file. For execution, the PO files get compiled to ``compiled message -catalogs''. These a usally @code{.mo} files (MO = Machine Object). +catalogs''. These a usually @file{.mo} files (MO = Machine Object). They get installed in an appropriate subdirectory of @code{$(localedir)}. The declaration of an installable message catalog domain therefore looks @@ -7484,19 +7485,19 @@ same directory. When you use the @code{POTS} primary, you need to invoke @code{AM_POT_TOOLS} directly or indirectly from @file{configure.ac}. -@node Parametrizing xgettext -@section Parametrizing xgettext +@node Parameterizing xgettext +@section Parameterizing xgettext The POT file gets created through an invocation of the @code{xgettext} program (@pxref{xgettext Invocation, , xgettext, gettext, GNU gettext tools}). @menu -* A POT file's _SOURCES:: Declaring the source files. -* A POT file's _COPYRIGHT_HOLDER:: The message catalogs' copyright holder -* A POT file's _MSGID_BUGS_ADDRESS:: Allowing translators to report bugs -* Additional xgettext options:: Fine tuning of xgettext -* Multiple xgettext invocations:: Advanced uses of xgettext +* A POT file's _SOURCES:: Declaring the source files +* A POT file's _COPYRIGHT_HOLDER:: The message catalogs' copyright holder +* A POT file's _MSGID_BUGS_ADDRESS:: Allowing translators to report bugs +* Additional xgettext options:: Fine-tuning of xgettext +* Multiple xgettext invocations:: Advanced uses of xgettext @end menu @node A POT file's _SOURCES @@ -7547,7 +7548,7 @@ po_maude_pot_COPYRIGHT_HOLDER = Yoyodyne, Inc. The value of this variable is the copyright holder that gets inserted into the header of the POT file. Set this to the copyright holder of the surrounding package. (Note that the msgid strings, extracted from the -package's sources, belong to the copyright holder of the package.) +package's sources, belong to the copyright holder of the package.) Translators are expected to transfer the copyright for their translations to this person or entity, or to disclaim their copyright. The empty string stands for the public domain; in this case the translators are @@ -7562,7 +7563,7 @@ be declared like this: @smallexample locale_POTS = po/maude.pot -po_maude_pot_MSGID_BUGS_ADDRESS = bug-maude@@yoyodyne.com +po_maude_pot_MSGID_BUGS_ADDRESS = bug-maude@@yoyodyne.example.com @end smallexample The value of this variable is the email address or URL to which the @@ -7581,7 +7582,7 @@ understood. Strings which make invalid assumptions about notation of date, time or money. @item -Pluralisation problems. +Pluralization problems. @item Incorrect English spelling. @item @@ -7594,7 +7595,7 @@ which the translators can contact you. You don't need to specify the bug reporting address here if you have already done so through the third argument of @code{AC_INIT}, see -@xref{Initializing configure, , Initializing @code{configure}, autoconf, +@ref{Initializing configure, , Initializing @code{configure}, autoconf, The Autoconf Manual}. @node Additional xgettext options @@ -7630,7 +7631,7 @@ to instruct @code{xgettext} to mark all translatable strings in @samp{gettext} invocations that occur as fifth argument to this function as @samp{c-format}. -See @pxref{xgettext Invocation, , xgettext, gettext, GNU gettext tools} +See @ref{xgettext Invocation, , xgettext, gettext, GNU gettext tools} for the list of options that @code{xgettext} accepts. @end defmac @@ -7704,8 +7705,8 @@ want them installed (for example, if they are part of a test suite only), you specify the POT file in the @code{noinst_POTS} variable. @menu -* A POT file's _CATALOGFORMAT:: Formats of compiled message catalogs -* A POT file's _LOCALE_CATEGORIES:: Using different locale categories +* A POT file's _CATALOGFORMAT:: Formats of compiled message catalogs +* A POT file's _LOCALE_CATEGORIES:: Using different locale categories @end menu @node A POT file's _CATALOGFORMAT @@ -7718,17 +7719,17 @@ that your package is using. Several formats are supported: @table @code @item mo -This is the GNU @code{.mo} format. It is used for C, C++, and many other +This is the GNU @file{.mo} format. It is used for C, C++, and many other programming languages. @item qm This is the message catalog format of the Qt library @url{http://qt.nokia.com/}. @item properties -This is the Java @code{.properties} format. For details, see -@xref{Java, , Java, gettext, GNU gettext tools}. +This is the Java @file{.properties} format. For details, see +@ref{Java, , Java, gettext, GNU gettext tools}. @item class -This is the Java @code{.class} format. For details, see -@xref{Java, , Java, gettext, GNU gettext tools}. +This is the Java @file{.class} format. For details, see +@ref{Java, , Java, gettext, GNU gettext tools}. @item resources.dll This is the message catalog format of C#. @item msg @@ -7776,8 +7777,8 @@ If not specified, this variable defaults to @code{LC_MESSAGES} only. There are two more variables associated with a POT file. @menu -* A POT file's _USE_MSGCTXT:: Declaring whether msgctxt is used -* A POT file's _MSGMERGE_OPTIONS:: Specifying options for msgmerge +* A POT file's _USE_MSGCTXT:: Declaring whether msgctxt is used +* A POT file's _MSGMERGE_OPTIONS:: Specifying options for msgmerge @end menu @node A POT file's _USE_MSGCTXT @@ -7789,8 +7790,8 @@ po_maude_pot_USE_MSGCTXT = no @end smallexample This tells whether the POT file contains messages with an @code{msgctxt} -context. Possible values are ``yes'' and ``no''. Set this to yes if the -package uses functions taking also a message context, like the +context. Possible values are @samp{yes} and @samp{no}. Set this to yes +if the package uses functions taking also a message context, like the @code{pgettext} function, or if in _XGETTEXT_OPTIONS you define keywords with a context argument. If set to yes, GNU gettext tools older than gettext 0.15 will not be considered. The default is @code{yes}. @@ -7803,7 +7804,7 @@ locale_POTS = po/maude.pot po_maude_pot_MSGMERGE_OPTIONS = @end smallexample -These options get passed to @code{msgmerge}. +These options get passed to @command{msgmerge}. Useful options are in particular: @table @code -- 2.47.2