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

[Alexandre Duret-Lutz]

>>> "Bruno" == Bruno Haible <address@hidden> writes:

[...]

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

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

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

Thanks a lot!  These will be fixed in my next update.

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

Not sure what you mean here.  Where is "earlier"?  The very
first time AC_CONFIG_AUX_DIR was introduced?

It's not needed there because autoreconf is always used, and
autoreconf creates the directory when it is missing.

It's needed with gettextize, because gettextize has to run
before autoreconf.

 >> * gettextize prints
 >> 
 >> | Please use AM_GNU_GETTEXT([external]) in order to cause
 >> | autoconfiguration to look for an external libintl.
[...]
 >> Also, I suggest s/autoconfiguration/configure/.  (Because
 >> autoconfiguration might also be understood as running gettextize or
 >> autoconf.)

 Bruno> I think it's important to share common terms. What is
 Bruno> your definition of "configuration", "configure",
 Bruno> "autoconfiguration", "autoconfiscation"?

I agree with all your definitions.  But I'm suggesting this
change to help newcomers with limited vocabulary (and so you
don't need to define the term you use).  

The Autoconf manual mentions "autoconfiscate", but it does not
use "autoconfiguration".  Instead it says "`configure' will
enter cross compilation mode", "`configure' will detect the
appropriate path", etc.  It's clear enough that I think no new
term is necessary.

[...]

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

:) :)

I meant much much newer.  The 1.4 code base is 6-year old.
AFAIC anything older than 1.8 is a relic :) (And by consequence,
Autoconf releases older than 2.58 can be thrown away.)

[...]

 Bruno> gettext 0.14.2 dropped the support for packages which
 Bruno> use autoconf-2.13.

That's really good news!  I would be interested to know how much
complaints about this you (will) receive.  Or maybe you won't
receive them directly, but you will notice some.

 Bruno> Maybe Tom Dickey will persecute me now...

Call me a pervert, but I'd like to see that once :)

[...]

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

 Bruno> This does not catch cases where a packages uses

 Bruno> ACLOCAL_AMFLAGS = -I `cd m4 && pwd`

Ah, right.  Didn't thought of that.  Those will have to touch
m4/Makefile.am first.

[...]

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

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

Maybe Automake should distribute automatically the "common
files" (i.e. those files displayed by automake --help) for
directories listed in AC_CONFIG_AUX_DIR and AC_CONFIG_MACRO_DIR?

That wouldn't really help here, though, because
AC_CONFIG_MACRO_DIR is not yet really useful today, few people
use it, and you have to deal with Autoconf releases that don't
have this macro anyway...

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

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

Not only copy the contents, but also delete the file, and remove
it from the Makefile.am.  One each upgrade.  Quite tiresome :(

What's wrong with assuming that if 
   1) m4/ already exists, and
   2) m4/ does not have a ChangeLog
then the maintainer do not want one?

Obviously if m4/ did not exist, you cannot guess, and I agree
this isn't worth an option.  But if m4/ already exists you don't
even have to guess: just look whether there is one or not.

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

Indeed!

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

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

Thanks for explaining.

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

No, it's OK, I think an empty POTFILES.in is simple enough.

Maybe paste the two above paragraphs as comments in po.m4?  I
really couldn't have guessed the rationale by looking at the
code.

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

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

Why bother the maintainer with something the tool can do?
AC_CONFIG_AUX_DIR([tools]) clearly expresses the maintainer's
intent to have a tools/ directory, so I see no harm in creating
it.

Diagnosing the missing directory frustrates the maintainer
unnecessarily ("Oh yes, I did forget to create that directory.
Sigh.").  There is already far to much sources of frustration in
autotools :(  Besides, diagnosing this requires as much effort
as creating the directory!

Note that presently gettextize does none of the above: it simply
tries to copy its auxiliary scripts and ignores cp's errors.
This is how I came to that suggestion.  When it occurred to
me, I didn't see the cp errors, because they had already been
moved off-screen by all the messages about installing *.m4
files, and gettextize exited with $? = 0.

Presently, autoreconf will create the AC_CONFIG_AUX_DIR
directory if it does not exist.  I'm going to change automake so
it does it too (for the sake of people not using autoreconf),
because it is just easy to do and useful.

[...]

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

 Bruno> To which FAQ are you referring? 

Sorry, I was referring to gettext-tools/doc/FAQ.html.  The answer
to question "How do I make use of gettext() in my package?" has
these two points:

     * In the source file defining the main() function of the program,
       add these lines to the header                                  
       #include <locale.h>          
       #include "gettext.h"
       and these lines near the beginning of the main() function:      
       setlocale (LC_ALL, "");
       bindtextdomain (PACKAGE, LOCALEDIR);                             
       textdomain (PACKAGE);               
     * Mark all strings that should be translated with _(), like this:
       _("No errors found."). While doing this, try to turn the strings
       [...]

The second point actually suggests to use _(), so people may
expect this to be defined somewhere.

It's true that the use of "gettext.h" discussed here is related
to the main(), and not the _(), so my initial comment is wrong.
Sorry.  Still, other people might get it wrong in the same way.

I think starting the second item with

   Define _() as
   #include "gettext.h"
   #define _(x) gettext(x)
   and mark all strings ....

would be clear enough.

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

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

Just for clarity: I wasn't suggesting to remove the line and its
comments from Makevars.template -- I think showing the empty
variable with a comment already invites the maintainer to fill it.

Anyway, I don't really mind if it is not documented.  But then
it opens two other questions:
  1) is the current undocumented default a feature we can rely on?
  2) is the definition of PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ in
     Makefile.in.in something that will stay there?

if the answer to 1) is no, people can still say 
  MSGID_BUGS_ADDRESS = $(PACKAGE_BUGREPORT)
unless the answer to 2) is also negative.

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

 Bruno> Not sure about this.

Huh?  For the same reason we all like the have the version
number of the package defined in a single place.  (Although
admittedly the bug report address changes less often than the
version number.)

[...]

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

 Bruno> This happened because I wanted to include the fixes of 'missing' and
 Bruno> 'mdate-sh' that were done in 1.9.5, but at the same time wanted to
 Bruno> minimize other risks one day before release. 


Amusingly the change I considered the more risky here were
precisely those of `missing' and `mdate-sh' :)

À quelque chose malheur est bon.  If you had actually diffed
mkinstalldirs, seen the small change it underwent, and included
the new version, we wouldn't have seen the autopoint error on
this file.

 Bruno> I don't expect incompatibilities between automake-1.x.y and -1.x.z.

That's really OK for the public interfaces (i.e., the
Makefile.am, the Makefile rules, the scripts options, etc.), but
it's totally unwarranted for the implementation details.  The
way scripts, Makefile.ins, and m4 macros interact are
implementation details, and you cannot mix different versions of
these and expect things to work.

See node "Upgrading" in the Automake manual.

Basically the aux scripts should be considered part of the
Automake output just like Makefile.ins, and these two things
should have the same version to ensure compatibility.

For instance you cannot use py-compile from Automake 1.9.3 with
Makefiles generated by Automake 1.9.4, because fixing a bug
required to change part of the interface between this script and
the Makefile.

(I admit it's hard to imagine some addition to the interface of
mkinstalldirs, but I would not hesitate if it was required to
fix a bug.)

 Bruno> Yes, the documentation is one of the two reasons why I
 Bruno> cannot assign the version number 1.0 to GNU gettext :-(

Now you have teased my curiosity.  May I ask what is the other reason?

Here is a 20th point, to make an even count:

* gettext-tools/TODO says that Perl, Shell scripts, and Scheme
  are not supported, while the top-level NEWS says they are!
-- 
Alexandre Duret-Lutz