gnome-doc-utils updating po files

[Shaun McCance <shaunm gnome org>]

Currently, gnome-doc-utils will update documentation po files whenever
the source documentation files are updated.  It happens because of this:

$(_DOC_LC_DOCS) : $(_DOC_PO_FILES)
$(_DOC_PO_FILES) : $(_DOC_C_DOCS)

Basically, the translated docs depend on the po files, and the po files
depend on the source docs.  And that makes a certain amount of sense,
from a "they really do" point of view.

But this means that maintainers and documenters end up updating the po
files.  Without extra action on their parts, they'll commit this.

Here's the options:

1. Make $(_DOC_LC_DOCS) not depend on $(_DOC_PO_FILES)

Probably a bad idea.  This means that updates to the po files won't
trigger updates to the translated documentation files.

2. Make $(_DOC_PO_FILES) not depend on $(_DOC_C_DOCS)

A little better.  Updates to the po files will cause updates to the
translated documentation files, which are generally not kept inside
CVS.  Updates to the C docs won't automatically update the po files,
so explicit action will have to be taken to do so.

3. Remove entirely the logic to build $(_DOC_PO_FILES)

For the sake of make, we'd just touch the po files whenever needed.
I don't like this option, as the po update logic is non-trivial,
and it is nice to have it in the Makefile.


If we want to make po updates not automatic, then (2) is probably
our best action.  But here's the deal: Currently, the Makefile rule
is the only reliable way of updating the po files.  The files are
under xml2po's control, not intltool's.  And there's no POTFILES
or anything, so xml2po needs the Makefile to tell it what files
to extract strings from.

Of course, with option (2), you could always explicitly update
your po file using make, like so: 'make de/de.po'.  The problem
is that translators rarely go through the autogen/configure/make
song and dance.  It's a hassle for them.  I fear that without the
automatic update, po files will never get updated.

So what we want is a way for xml2po to be able to know what source
files to extract strings from without having to build everything.
We have two options here:

1. Make xml2po able to parse the Makefile.am.

This is doable.  Danilo already has code to do it.  The problem
is that we'd have to make sure to track the right variables.  If
I add stuff in gnome-doc-utils.make, we need to make sure xml2po
knows about it.  Currently, xml2po doesn't have to know anything,
since gnome-doc-utils.make tells xml2po what it needs to know.

2. Have gnome-doc-utils.make output a POTFILES.

Here, gnome-doc-utils.make would use the same logic it already
has to output a single file listing the source documents.  This
file would be put in CVS, even though it's auto-generated.  It
could be used by xml2po to determine how to do the updates.


The only other problem is that translators absolutely can not
really *test* their translations without going through the
build procedure.  Honestly, I don't see how we can really
change that.

Thoughts?

--
Shaun