[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
gettext-0.14.2: suggestions to ease gettextization + a few bugs
From: |
Alexandre Duret-Lutz |
Subject: |
gettext-0.14.2: suggestions to ease gettextization + a few bugs |
Date: |
Sat, 05 Mar 2005 01:58:59 +0100 |
User-agent: |
Gnus/5.110003 (No Gnus v0.3) Emacs/21.3.50 (gnu/linux) |
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
- gettext-0.14.2: suggestions to ease gettextization + a few bugs,
Alexandre Duret-Lutz <=
outdated URL in config.guess, Paul Eggert, 2005/03/07
Re: gettext-0.14.2: suggestions to ease gettextization + a few bugs, Paul Eggert, 2005/03/07
Re: gettext-0.14.2: suggestions to ease gettextization + a few bugs, Karl Berry, 2005/03/08