Re: po / pot file integration: documentation

[Bruno Haible]

Hi Ralf,

Thanks for the nits and spelling fixes.

> > 2010-08-15  Bruno Haible  <address@hidden>
> > 
> >       Document the handling of POT and PO files.
> 
> s/handling/intended &/  ?

Well, once it's committed and merged, it won't be "intended" only.

> > +* Parametrizing xgettext::      Declaring how a POT file gets created
> 
> My dictionary accepts 'parametrizing', but I wonder whether
> 'parameterizing' is the more common spelling.

The Merriam-Webster dictionary
<http://www.merriam-webster.com/dictionary/parametrize> says that the
verb is called "parameterize" but the -ized and -izing forms exist in
both spellings. <http://dictionary.reference.com/browse/parametrize>
knows also 'parametrize' as verb. In the Google test "parameterizing"
wins over "parametrizing" with 231000 : 80000 hits.

> > +* 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
> 
> Does info cope with no whitespace after ::?

Yes, it does. But the rest of the Automake manual uses at least 2 spaces after
::, and it's indeed nicer.

> > +* A POT file's _SOURCES::            Declaring the source files.
> 
> Let's drop trailing period in menus, automake.texi has only a couple of
> them.

OK.

> > +* A POT file's _MSGID_BUGS_ADDRESS:: Allowing translators to report bugs
> 
> BUGS_ADDRESS or BUG_ADDRESS?  Oh well, I guess that was already set in
> stone years ago; it slightly conflicts with current Autoconf usage of
> the term.

Autoconf's usage is PACKAGE_BUGREPORT - which might probably better have been
spelled PACKAGE_BUG_REPORT. So for a POT file we have the choice among
  foo_pot_MSGID_BUGS_ADDRESS
  foo_pot_MSGID_BUGREPORT_ADDRESS
  foo_pot_MSGID_BUG_REPORT_ADDRESS
But since for the PO file format
<http://www.gnu.org/software/gettext/manual/html_node/Header-Entry.html>
I chose the keyword 'Report-Msgid-Bugs-To', I'm going for
foo_pot_MSGID_BUGS_ADDRESS. It's also long enough to type for the user.

> > +* Additional xgettext options::      Fine tuning of xgettext
> 
> I think it's "Fine-tuning".

Yes, thanks.

> > +The @code{AM_POT_TOOLS} macro performs tests for the @code{POTS} primary.
> > +See @pxref{Programming Languages, , Programming Languages, gettext,
> 
> @pxref prints a lower-case "see" in the PDF output, here you could best
> remove the initial "See" and use @xref.

But then I get a makeinfo warning that I cannot fix without adding a misplaced
comma. I'm changing it to "See @ref{...} ..." instead.

> > +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. 
> 
> Adding  (@pxref{Internationalization})  would be good here.

Yes, good point.

> > +An internationalized program is a program that can communicate with the
> > +user in his native language, provided that some translation work has been
> 
> Let's avoid 'his', so how about 'its users in their native language'?

I think a singular is more appropriate here, because different users may have
different native languages. But if you find 'his' discriminating, I'll write
'his/her'.

> > address@hidden@var{domain}.pot}.  The @var{domain} is a identifier for the
> 
> @address@hidden

In info and HTML output, @code and @file are identical. In PDF @file produces
extra quotes around the string, which IMO is confusing here, because there's
enough font changes.

> an identifier

Yes, thanks.

> > +Therefore, usually, the @var{domain} is the same as the package name.
> 
> I think this is slightly more common: Therefore, the @var{domain} is
> usually the same ...

OK.

> > address@hidden
> > +The file that contains the translation produced by a translation team
> > +is called a PO file (Portable Object) and usually named
> > address@hidden@address@hidden or
> > address@hidden@address@hidden@var{CC}.po}.  Here @var{ll} is the
> 
> Again, @file, two instances.

See above. I find the quotes are too distracting here.

> Here, ...

OK.

> > +In Automake, a message catalog template (POT file) is a primary.
> 
> I think the Automake lingo is that _POTS is the primary

OK, I'm reformulating this as "a message catalog template (POT file) is
declared through the 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).
> 
> usually
> @file{.mo}

OK.

> > +surrounding package.  (Note that the msgid strings, extracted from the
> 
> @samp{msgid}  ?  Is it worth explaining this term here?

The sentence already contains an explanation. I don't think it's needed
to explain it.

> > +package's sources,  belong to the copyright holder of the package.)
> 
> s/  / /

Yes.

> > +po_maude_pot_MSGID_BUGS_ADDRESS = bug-maude@@yoyodyne.com
> 
> There was an example domain for email addresses, but it wasn't
> example.com IIRC.

Eric adds:
> example.com is the preferred name set aside for this use, by RFC 2606:
> http://en.wikipedia.org/wiki/Example.com

OK, I'm changing the address to address@hidden

> > address@hidden
> > +Pluralisation problems.
> 
> So far most of the manual has been using US English spelling, let's keep
> it that way.

What a pity that Britain lost the war in 1781...

> > +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
> > address@hidden configure, , Initializing @code{configure}, autoconf,
> 
> This is where  s/see @xref/@pxref/  would make sense.  :-)

In info mode, @pxref does not produce the word 'see'. I'm therefore changing
it to "see @ref".

> > +The Autoconf Manual}.
> > +
> > address@hidden Additional xgettext options
> > address@hidden Additional @code{xgettext} options
> > +
> > +Additional command-line options for the @code{xgettext} invocation can be
> > +specified through the _XGETTEXT_OPTIONS variable.  For example:
> > +
> > address@hidden
> > +locale_POTS = po/maude.pot
> > +po_maude_pot_XGETTEXT_OPTIONS = \
> > +  --keyword=_ --flag=_:1:pass-c-format \
> > +  --keyword=N_ --flag=N_:1:pass-c-format
> > address@hidden smallexample
> > +
> > address@hidden AM_XGETTEXT_OPTION
> > +Additional command-line options for the @code{xgettext} invocation can
> 
> Is it worth starting with "Alternatively, additional ..." to avoid
> sounding like a typo/repetition?

It's not alternative: the options from the _XGETTEXT_OPTIONS variable and the
options specified with AM_XGETTEXT_OPTION are combined. The word "also" avoids
sounding like a repetition.

> > +See @pxref{xgettext Invocation, , xgettext, gettext, GNU gettext tools}
> 
> s/See @pxref/@xref/  as above.

Actually I need "See @ref" here.

> > address@hidden @code
> > address@hidden mo
> > +This is the GNU @code{.mo} format.  It is used for C, C++, and many other
> 
> @file{.mo}

OK.

> > +programming languages.
> > address@hidden qm
> > +This is the message catalog format of the Qt library
> > address@hidden://qt.nokia.com/}.
> > address@hidden properties
> > +This is the Java @code{.properties} format.  For details, see
> 
> @file

OK.

> > address@hidden, , Java, gettext, GNU gettext tools}.
> 
> @ref, or s/see @xref/@pxref/

Thanks. @ref is what I need here.

> > address@hidden class
> > +This is the Java @code{.class} format.  For details, see
> 
> @file

OK.

> > address@hidden, , Java, gettext, GNU gettext tools}.
> 
> see above

likewise

> > +the @code{LC_MESSAGES} locale category, but they can rarely also
> > +be useful in other categories.
> 
> they can sometimes be useful in other categories

No, it's really rare that you want something to depends on LC_TIME,
LC_ADDRESS, LC_IDENTIFICATION, or similar.

> > +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
> 
> @samp{yes} and @samp{no}

Yes, thanks.

> > +These options get passed to @code{msgmerge}.
> 
> @command{msgmerge}

OK.

> The chapter would be even better with some @cindex entries for the
> concepts and @vindex for variables, primaries, etc.

OK.

I've pushed the changes on the pot-primary branch.

Bruno