Re: po / pot file integration: documentation

[Ralf Wildenhues]

Hello Bruno,

* Bruno Haible wrote on Sun, Aug 29, 2010 at 06:56:01PM CEST:
> > > 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.

Well, some patches down the road, yes, I guess.

> > > +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.

Which texinfo version are you using?  Of course the latter is also ok.

> > > +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'.

Yes, please.  Thanks.  Or, if you like, my suggestion with "in their
native languages".

> > > 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.

But that's not something to hack around with bad markup, never.
Instead, if that is confusing, then we should turn off the extra quotes
globally, there's got to be some texinfo setting for that.  (Such a
patch should be strictly separate though, and I'd want to look at the
output first.)

> > > 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.

See above.  ;-)

> > > +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".

Well, "note" is almost like "see", so I think it's intended to not be
there.  But fine with me.

Thanks,
Ralf