[Po4a-devel][RFCs] configuration file format (+ addendum change?)

[Jordi Vilalta]

On Wed, 30 Jun 2004 martin.quinson@free.fr wrote:

> Hello,
> 
> now that po4a is rather stable and reliable (thanks to the test suite), my 
> feeling is that the main showstopper preventing po4a from being widly used is 
> the way to use it. It's far too complicated, with 2 tools to use at each 
> update, each of them requiring 3 or more options. My goal (beside becoming 
> imortal/worldmaster/whatever) would be to solve that situation. 
> 
> I would like to come up with a design of configuration file which would allow 
> people to do the two most often used actions (po4a-updatepo & po4a-translate) 
> in one shoot as simple as "po4a -c configuration_file".

Interesting. Would it coexist with the current tools, or would it stand in 
for them?

> 
> The chalenge here is to not report the complexity into the config file, but 
> come up with a simple design.
> 
> I'm thinking about that since a long time, and I'm still unsure about how to 
> achieve it. For each master file (ie, file to be translated), we have to 
> express its format, and the corresponding localized files. If possible, I 
> would like it to be analog with the format used in po-debconf and the gnome 
> l10n tools.
> 
> The following may do the trick:
> [<format>] <master_file> <lang>:<localized_file>+
> 
> We also need to express where the translation files are (pot+po). In order to 
> not break the compatibility, the pseudo-format "po4a/paths" could be 
> introduced.
> 
> For example,
> [po4a/paths] doc/l10n/project.doc.pot fr:doc/l10n/fr.po de:doc/l10n/de.po
> [sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml de:doc/de/mein_cram.sgml
> [pod] script fr:doc/fr/script.1 de:doc/de/script.1
> 
> Then, the po4a tool would create a potfile by aggregating the parsed content 
> of all master files, updating all po files against that file, and then 
> generate each localized files from each of them.
> 

Very clear and compact. The only thing I think can cause confusion is 
using the same syntax for the pot/po files. I think it should have some 
distinction, but this way it would be easier to parse. What's your 
intention?

> 
> I guess it would do the trick, but there at least one limitation: we cannot 
> add addendums in that way. Anyway, the addendums are not very practical right 
> now, and we may want to change them. One good thing would be to embeed them 
> into the po file. Having only one file containing all input from translator 
> would ease the interactions with the developers.
> 
> It could be done by dealing specifically with msgids named something 
> like "po4a-addendum:<filename>:<addendum_count>". In that case, the 
> translation of this msgid would be an addendum against this file. The header 
> could be placed into the msgid, also.
> 
> Another possible limitation is that all this relies on the fact that the 
> programes with which I aim at being compatible are smart enough to ignore the 
> lines for format they don't know about. I didn't check this out. Denis?
> If not, it may be a bit artificial.

I haven't used addendums yet, but it seems a complex issue. If you create 
automaticaly a po msgid for each master file, many of them would be 
wasted, because not all files need addendums (I think).

It also may not be directly translator's job, as it may need knowledge of 
the document format in use. Using separate files keeps po files more 
readable.

What about simplifying the format of the addendums? For example, to a 
title and a content (plain text) so that this same addendum could be used 
for all documents (each module could transform this plain text to its own 
format), and then you only would need to say what files use the addendum 
and what not.

Another approach would be to use the current addendums, and think some 
syntax to integrate them into the previous config format. For example:

[pod] script fr:doc/fr/script.1 adden_fr:doc/l10n/script_adden_fr.po de:doc/de/script.1 adden_de:doc/l10n/script_adden_de.po

> 
> Yet another limitation is that I have no idea about how to handle module 
> options...

What about:

[mod] sgml -options...
[mod] pod -options...

I don't like mixing different kinds of options with a so similar syntax, 
but it's the same issue as the main pot/po files I said above. Find an 
alternative for that, and you'll probably find how to handle module 
options.

> 
> 
> Once we come up with a configuration file design, doing the actual script 
> should be rather easy (even if TransTractor also have to be modified to export 
> some more functions):
> parse_config($cfg_file);
> 
> # make a big pot
> my $potfile=Locale::Po4a::Po->new();
> foreach ($format,$master) {
>  my $doc=Locale::Po4a::Chooser::new($format);
>  $doc->setpoout($potfile);    # trivial function to write, check getpoout
>  $doc->process('file_in_name' => $master);
>  $potfile = $doc->getpoout(); # private function to export
> }
> $potfile->writefile($potfile_name);
> 
> # update all po files, just like in po4a-updatepo
> 
> # update all translations
> foreach ($format,$master,$localized) {
>  my $doc=Locale::Po4a::Chooser::new($format);
>  $doc->setpoin($potfile);
>  $doc->process('file_in_name' => $master,
>                'file_out_name' => $localized);
> }
> 
> I didn't test this _at all_, since my hard disk didn't came back to life yet 
> (tomorow, hopefully). I'm still under webmail, under windows (erk)...
> 
> 
> So. What do you guys think about that? Isn't that neat?

It can be done currently with makefiles, but that system would approach 
its use to basic users (or directly, to translators).

Regards,

Jordi Vilalta