Re: gettext-0.14.2: suggestions to ease gettextization + a few bugs

[Bruno Haible]

Hi Alexandre,

Many thanks for the 19 constructive suggestions.

> http://www-src.lip6.fr/homepages/Alexandre.Duret-Lutz/autotools.html
>
> I'm currently working on the Gettext section, and had to prepare
> a small Hello World for this purpose.

On page 462, the src/say.c lacks the #include <stdio.h> that is found
earlier, on page 457.

On page 468, I find the "mkdir tools" command astonishing. It actually
belongs earlier, namely when you used AC_CONFIG_AUX_DIR([tools]).

On page 475, instead of "Your Name, Maybe", I'd suggest to write
"Your Name or Your Employer" (because often the copyright is with the
employer).

On page 477, the second capture title should be "po/POTFILES.in", not
"po/Makevars".

> * gettextize prints
> 
>   | Please use AM_GNU_GETTEXT([external]) in order to cause
>   | autoconfiguration to look for an external libintl.
> 
>   even if the line is already in configure.ac.

I'm changing gettextize to not print this recommendation if it is already
fulfilled.

>   Also, I suggest s/autoconfiguration/configure/.  (Because
>   autoconfiguration might also be understood as running gettextize or
>   autoconf.)

I think it's important to share common terms. What is your definition of
"configuration", "configure", "autoconfiguration", "autoconfiscation"?
I'd say,
  - "configuration" means setting parameters (usually manually),
  - "configure" is a generated file,
  - "autoconfiguration" means the automatic setting of parameters, i.e. the
    execution of "configure" and "config.status",
  - "autoconfiscation" means changing a package so that it uses GNU autoconf.

> * If configure.ac contains `AM_GNU_GETTEXT_VERSION([0.14.2])',
>   gettextize rewrites it as `AM_GNU_GETTEXT_VERSION(0.14.2)' without
>   the quotes.  This is mildly annoying.  Although both syntax are
>   clearly equivalent, the second syntax can give newcomers the
>   impression that quotes are generally meaningless.
> 
>   I think it's better to give newcomers the habit to routinely quote
>   each argument.

Agreed. I'm changing gettextize to always put brackets around the
AM_GNU_GETTEXT_VERSION argument.

> * gettextize rewrites
> 
>     AC_CONFIG_FILES([Makefile src/Makefile])
> 
>   into
> 
>     AC_CONFIG_FILES([Makefile src/Makefile po/Makefile.in m4/Makefile ])
> 
>   with a unaesthetic space at the end.
> 
>   The same tragedy happens in Makefile.am:
> 
>     SUBDIRS = src
> 
>   becomes
> 
>     SUBDIRS = po m4  src
> 
>   with two spaces between `m4' and `src'.
> 
>   I feel a bit picky to complain about this, but OTOH I think many
>   people who like good-looking files would have to fix these manually.
>   The less cleanup we have to do after gettextize the better.

OK, I'm changing gettextize to avoid this extra space after the inserted
items.

> * gettextize installs m4/Makefile.am
> 
>   Since Automake 1.8, m4 files used by configure.ac are automatically
>   distributed and do not need any EXTRA_DIST.  There is no need to
>   create a m4/Makefile.am if none exists, and there is no need to
>   update an existing m4/Makefile.am (unless it is to remove mentions
>   of old m4 files...)
> 
>   It would be nice if gettextize could offer a means to follow this
>   recommended usage.  I presume you'll come after me with a chainsaw
>   if I suggest to drop support for older Automake releases, so maybe
>   you can consider an heuristic along the lines of:
> 
>     if the m4/ directory exists but does not contain a Makefile.am, do
>     not create an m4/Makefile.am.

I'm changing gettextize to use the following heuristic:

      if aclocal's version is 1.8 or newer and m4/ does not contain a
      Makefile.am, do not create an m4/Makefile.am.

This does not catch cases where a packages uses

   ACLOCAL_AMFLAGS = -I `cd m4 && pwd`

instead of

   ACLOCAL_AMFLAGS = -I m4

(if it wants to gets the contents of the *.m4 files copied into aclocal.m4),
but I presume that such uses are rare. gettextize adds "-I m4" to the
ACLOCAL_AMFLAGS anyway.

I won't sue anyone with a chainsaw for not wanting old automake releases:
Up until automake 1.4 they were quite buggy.

gettext 0.14.2 dropped the support for packages which use autoconf-2.13.
Maybe Tom Dickey will persecute me now...

>   You can use `EXTRA_DIST = m4/ChangeLog' in the top-directory to
>   distribute the ChangeLog, like you do for files in tools/.

Oh yes, I wouldn't have noticed this pitfall: A ChangeLog file gets distributed
automatically, but an m4/ChangeLog file doesn't! Thanks for the reminder.

>   Personally I prefer one global ChangeLog per package so likewise I
>   wish gettextize would not create m4/ChangeLog if none already exist.

The location of the ChangeLog files depends on the size of the package and
the taste of the maintainer. This is one of the things gettextize cannot
guess. And introducing a command line option just for this? Hardly worth it.
The maintainer can copy the piece of ChangeLog from one file to another if
he desires to do so.

> * Speaking of EXTRA_DIST and tools/ files, it would be nice if some
>   gettext macro could call AC_REQUIRE_AUX_FILE, as in
> 
>   m4_ifdef([AC_REQUIRE_AUX_FILE],
>   [AC_REQUIRE_AUX_FILE([config.rpath])dnl
>    AC_REQUIRE_AUX_FILE([mkinstalldirs])])
> 
>   This macro will be recognized by the next major releases of
>   Autoconf and Automake.   This cause three things to happen:
>    1. Automake installs the file if it knows it
>    2. Automake complains if the file is missing from the AUX dir
>    3. Automake automatically distribute the file
>   The second point might help to diagnose broken setups

Generally it's a bad idea to mention file names in autoconf macros, because
it cuts down the freedom of the programmer who uses this macro. But since
in this case lib-link.m4 and nls.m4 already mention the two files,
things don't get much worse if I follow your advice. Thanks. In particular,
forgetting config.rpath is a quite frequent mistake.

> * If you forget to create po/POTFILES.in, you are definitively lost:
>   configure will not create po/Makefile and make will therefore fail
>   in the po directory.  This is very frustrating because you have
>   absolutely no clue why po/Makefile does not exist.
> 
>   I presume someone trying to figure out how to get such po/Makefile
>   would logically try adding AC_CONFIG_FILES([po/Makefile]), creating
>   more issues rather than fixing them.  I really doubt the average
>   developer is brave enough to delve po.m4 :)
> 
>   Can't this be diagnosed in some way at configure time?

I think this is better avoided by letting gettextize create an empty
po/POTFILES.in.

>   Why is the
>   output of po/Makefile conditional on the presence of POTFILES.in in
>   the first place?

This is what allows packages to have multiple po/ directories under different
names or in different locations. Look into gdb, for example. It has several
po/ directories.

>   I think having config.status aborting with "cannot
>   read po/POTFILES.in" would be better than the silence we have now.

POTFILES.in is currently the trigger for AM_GNU_GETTEXT's actions. You can
suggest a different trigger, but I don't know it is worth yet another
complexity.

> * If configure.ac has AC_CONFIG_AUX_DIR([tools]) and the tools/
>   directory does not exist, gettextize should create it before trying
>   to copy config.rpath and mkinstalldirs.  Just like it does for m4/.

I don't agree. If configure.ac has AC_CONFIG_AUX_DIR([tools]) then the
maintainer is responsible for having created this directory.

> * Can't gettext.h provide a definition of _() and N_()?

A few years ago there were indeed copies of gettext.h floating around which
defined also _. This led to uncertainties who was responsible for defining _,
and led to constructs like the following:

  #ifndef _
  # include "gettext.h"
  # define _(x) gettext (x)
  #endif

As you can see, this is twice as many lines of code than the more
straightforward

  #include "gettext.h"
  #define _(x) gettext (x)

that we use now.

And you cannot eliminate the doubts about the responsibility for defining _
because
  - _ is a macro that you cannot easily grep for,
  - _ as a macro name is formally not in the user's namespace,
  - therefore some projects will want to use a different macro name.

>   Also note that the Gettext FAQ says to include gettext.h, and then
>   to mark strings with _(), but it does not say to define _().

To which FAQ are you referring? The FAQ.html doesn't talk about this;
and the tutorial.html mentions the need to #define _(STRING).

> * The comment of MSGID_BUGS_ADDRESS in po/Makevars.template should
>   really state that it defaults to $(PACKAGE_BUGREPORT), the third
>   argument of AC_INIT.

I don't think this would be appropriate: It would only invite the maintainers
to not think about the issue (to which mailing list or alias they want the
msgid-bugreports be mailed).

>   I assume anyone who use the same address in configure.ac and
>   po/Makevars would like not to define MSGID_BUGS_ADDRESS, to have
>   only one definition.

Not sure about this.

> * Once you have gettextized your package, filled po/Makevars and
>   po/POTFILES.in, but *before* you have marked any string for
>   translation and touched anything in your source files, it seems
>   natural (to me) to run "make distcheck" to ensure that installing
>   gettext didn't break anything.
> 
>   However distcheck fails.
> 
>   I analyze this as follows:
> 
>     1) xgettext does not create any pot file when there is no strings
>        to extract.  That sounds counterintuitive to me, I was expecting
>        a pot file with only one string: the first "special" one.
> 
>     2) Although $(DOMAIN).pot does not exist, `make dist' does not fails!
>        During its execution you can see
> 
>        cp: cannot stat `./amhello.pot': No such file or directory
> 
>        but no abortion.  I believe the `cp' in the dist2 rule
>        should be changed into `cp ... || exit 1'.
> 
>     3) Because stamp-po is distributed and depends on $(DOMAIN).pot, but
>        $(DOMAIN).pot is not being output nor distributed, stamp-po is
>        being rebuilt every time you type "make".  distcheck thus rightly
>        complains that stamp-po has been rebuilt although it is distributed.

1) is OK: We don't want a programmer to annoy the translation teams with
empty .pot files. I'm fixing 3) in Makefile.in.in.

About 2): The 'dist' code in Makefile.in.in was modeled after the one
generated by automake. Now I see that meanwhile automake generates the
idiom 'cp -pR ... || exit 1'; I'll use the same as well.

> * gettextize install mkinstalldirs from Automake 1.9.4 while gettext
>   itself uses Automake 1.9.5.  Is this intended?  Looking into
>   gettext-0.14.2/config/ I can see a mix of files from both releases.

This happened because I wanted to include the fixes of 'missing' and
'mdate-sh' that were done in 1.9.5, but at the same time wanted to
minimize other risks one day before release. Such a mix can be considered
normal: I don't expect incompatibilities between automake-1.x.y and -1.x.z.

> * It is annoying that `autopoint' diagnoses things like
> 
>      autopoint: File tools/mkinstalldirs has been locally modified.
> 
>   as errors (with $? != 0).
> 
>   If I do
> 
>      autoreconf --install --force
> 
>   (1) autopoint will first install the copy of mkinstalldirs from
>   Automake 1.9.4, then (2) automake 1.9.5 will then overwrite this
>   with its own copy.
> 
>   This is not yet a problem.  However if I later do
> 
>      autoreconf --install  # without --force
> 
>   it fails with
> 
>     autopoint: File tools/mkinstalldirs has been locally modified.
>     autopoint: *** Some files have been locally modified. Not overwriting 
> them because --force has not been specified. For your convenience, you find 
> the local modifications in the file '/tmp/ar4jE6Uu/gtqa6Wvn/autopoint.diff'.
>     autopoint: *** Stop.
>     autoreconf: autopoint failed with exit status: 1
>     autoreconf: cannot empty /tmp/ar4jE6Uu: Is a directory

Ouch. This was unintended. I'm changing this diagnostic to a warning, when
it occurs with the mkinstalldirs. (mkinstalldirs is special here because
gettextize/automake is not the only provider.)

> * The manual at
>   http://www.gnu.org/software/gettext/manual/gettext.html is outdated
>   (generated in 2002), and does not specify which version of Gettext
>   it documents.

Yes, sadly...

>   Also it was generated with texi2html and use numbered anchors.  This
>   makes it impossible to reference some specific section of the manual
>   from another web page, because the number of the link might as well
>   refer to some other section in the next release.

Yes, you need to say mention the top-level entry page of the manual
and the chapter/section name, if you want a reference that is stable over
time.

>   Recent makeinfo
>   releases generate html with stable anchors (and I think I've heard
>   that so does recent texi2html releases, but I can't see the point in
>   texi2html anymore).

texi2html's output has an aesthetic quality that makeinfo's output still
hasn't reached in the 4.8 release.

> * The chapter "11 The Translator's View" is quite confusing.  It is
>   written in the first person, but looks like a patchwork of mails
>   where "I" is not always the same person.  (My impression is that
>   François Pinard is speaking most of the time, but in "11.4.3 Mailing
>   Lists" he is clearly being talked to.)  It also contains sentences
>   like "Jim, please note that..." which I don't think should appear in
>   a manual.  At least if this chapter was really presented as a
>   succession of mails, it would be easier to follow.

Yes, the documentation is one of the two reasons why I cannot assign the
version number 1.0 to GNU gettext :-( Help from a native English speaker
is welcome; native American speakers are also accepted.

> * The node `po/Makevars' is the only node of section "12.4 Files You
>   Must Create or Alter" that do not mention the filename in the title
>   of the section.  This is more confusing in dvi/ps/pdf outputs, where
>   node names is not chown.
> 
>   I suggest to rename "12.4.3 `Makefile' pieces in `po/'" into "12.4.3
>   `po/Makevars' in `po/' for consistency with sibling sections.

OK. Done.

> * Nodes `config.guess' and `mkinstalldirs' really should state that
>   these files are installed by gettextize!  (Telling people where to
>   find up-to-date files is OK too, but if newcomers doesn't waste
>   their time fetching these files it's better...)

Well, I thought it was clear from the doc that once you followed the
steps recommended by gettextize, you're set.

> * The location of config.guess and config.sub in node config.guess is
>   out of date.  IFAIK these files are now only available from the
>   config CVS repository at Savannah.

OK, I'm updating the manual and the gettextize output. Note that config.guess
itself (!) also contains a reference to the outdated location
  ftp://ftp.gnu.org/pub/gnu/config/

> * Node `config.h.in': if intl/ is not used, config.h does not need
>   to be at the top-level as the title implies, does it?

Right. I'm adding an explanation about this.

> * Node `src/Makefile': unlike node `Makefile', this one does not
>   state what to do when using Automake.

Right. I'm adding a note about this.

Bruno