Internationalization documentation fixes. * doc/automake.texi (Uniform): Mention...

diff --git a/ChangeLog b/ChangeLog
index 733dbfda02e988e6c50ee4c447d9f18e20f8af81..47ec0f0a3d0d8e5f77945deba2e3c4d2402c7915 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2010-08-29  Bruno Haible  <bruno@clisp.org>
+
+       Internationalization documentation fixes.
+       * doc/automake.texi (Uniform): Mention the POTS primary.
+       (Internationalization): Many small tweaks.
+       Reported by Ralf Wildenhues.
+
 2010-08-15  Bruno Haible  <bruno@clisp.org>
 
        Document the handling of POT and PO files.

diff --git a/doc/automake.texi b/doc/automake.texi
index 57d472c37ee6af77e347f24d866128af5e8a5f2b..37fc89397fb5a5caebef5a56447d9fc3e0c7392a 100644 (file)
--- 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