Hi Ralf, Thanks for the nits and spelling fixes.
> > 2010-08-15 Bruno Haible <br...@clisp.org> > > > > 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'. > > +...@code{@var{domain}.pot}. The @var{domain} is a identifier for the > > @fi...@var{domain}.pot} 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. > > +...@item > > +The file that contains the translation produced by a translation team > > +is called a PO file (Portable Object) and usually named > > +...@code{@var{domai...@var{ll}.po} or > > +...@code{@var{domai...@var{ll}_@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 bug-ma...@yoyodyne.example.com. > > +...@item > > +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 > > +...@xref{initializing 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}. > > + > > +...@node Additional xgettext options > > +...@subsection Additional @code{xgettext} options > > + > > +Additional command-line options for the @code{xgettext} invocation can be > > +specified through the _XGETTEXT_OPTIONS variable. For example: > > + > > +...@smallexample > > +locale_POTS = po/maude.pot > > +po_maude_pot_XGETTEXT_OPTIONS = \ > > + --keyword=_ --flag=_:1:pass-c-format \ > > + --keyword=N_ --flag=N_:1:pass-c-format > > +...@end smallexample > > + > > +...@acindex 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. > > +...@table @code > > +...@item mo > > +This is the GNU @code{.mo} format. It is used for C, C++, and many other > > @file{.mo} OK. > > +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 > > @file OK. > > +...@xref{java, , Java, gettext, GNU gettext tools}. > > @ref, or s/see @xref/@pxref/ Thanks. @ref is what I need here. > > +...@item class > > +This is the Java @code{.class} format. For details, see > > @file OK. > > +...@xref{java, , 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
