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

[Alexandre Duret-Lutz]

Hi Bruno!

As a few people know, I'm preparing a tutorial for Autotools
that should cover the basics of Autoconf, Automake, Libtool, and
Gettext.

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.  Even though I had a
pretty good idea of what a gettextized package should look like,
and tried to follow the Gettext documentation, I have hit a few
behaviors that were either merly annoying, confusing, or bogus.

Below are my notes about each point, in no specific order.  I'm
sure some of these may appear to be trifling details, and no
doubt many of my suggestions will be naive.  But the overall
intent is to ease the gettextization of a package using today's
tools, and by neophytes.  ("Today's tools" is important to me,
as I'm targeting new autotools users, and don't wan't them to
learn obsolete idioms.)


* 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.  Gettext's FAQ says to
  add the line to configure.ac before running gettextize, so it is
  confusing that gettextize asks for it.

  Also, I suggest s/autoconfiguration/configure/.  (Because
  autoconfiguration might also be understood as running gettextize or
  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.  Later they can learn the subtleties of quoting, but
  quoting each argument is enough initially.  I'm doing this in my
  tutorial and gettextize comes into my way by rewriting what I type :(

  I suggest that either gettextize outputs AM_GNU_GETTEXT_VERSION([0.14.2])
  systematically, or that it respects the quoting that is currently in use
  in configure.ac.

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

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

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

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

* 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, and the
  other ones should help in the long run.  E.g. once Gettext can
  assume newer tools no EXTRA_DIST will be necessary.

* 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?  Why is the
  output of po/Makefile conditional on the presence of POTFILES.in in
  the first place?  I think having config.status aborting with "cannot
  read po/POTFILES.in" would be better than the silence we have now.

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

  This matters when creating an internationalized package from scratch
  (i.e., the small "Hello World"s I'm writing) and when gettextize has
  to be run before autoreconf (which would otherwise create tools/) to
  install the gettext infrastructure the first time.

* Can't gettext.h provide a definition of _() and N_()?
  I presume it's too late now, but it sounds weird to have to
  define _() manually when the default po/Makevars already mention
  them.
  Also note that the Gettext FAQ says to include gettext.h, and then
  to mark strings with _(), but it does not say to define _().

* 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 found it by chance because I was about to
  suggest that $(PACKAGE_BUGREPORT) become the default value and
  looked at po/Makefile.in.in to see whether PACKAGE_BUGREPORT was
  available.)

  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.

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

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

* 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

  So in practice autopoint forces people to always use --force, which
  is a waste of time (because --force updates too much time stamps
  unnecessarily, causing unneeded rebuilds).  Ideally --force should
  be used only in desperate cases, when you got lost.

  Can't this autopoint diagnostic be a warning?

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

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

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

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

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

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

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

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

-- 
Alexandre Duret-Lutz