Using gnome-doc-utils for help files

[Christian Stimming]

Am Donnerstag, 5. Juli 2007 16:16 schrieb Josh Sled:
> Pierre-Antoine Lacaze <pa.lacaze at laposte.net> writes:
> > I'm beginning the French translation of Gnucash's help, and have been
> > suggested that it would be a good move to look into converting
> > gnucash-help to gnome-doc-utils [1]. g-d-u is supposedly the preferred
> > way for documentation handling, and make use of po files.

Without having looked too much into g-d-u details I'd *strongly* adverse 
moving our user documentation to po files! Po files are great for smaller 
chunks of translations which can be translated more or less independent from 
one another. Our documentation, with the "Guide and Concepts" being the best 
part of it all, is clearly not at all translatable in a 
paragraph-by-paragraph way, independently of one another. 

Also, one of the largest advantages of po files, which is the easy 
visualization of changed strings, becomes moot if these strings are longer 
than 1-2 lines. For longer strings, po only says "this whole paragraph has 
changed in *some* way", whereas .xml or .sgml or even .txt would give you a 
diff showing the exact line that changed. (Diffs are not possible for po.) 

IMHO the arbitrary division of the help documents into separate po strings 
doesn't offer any advantage at all. I don't agree with this being "a 
preferred way". Well, maybe for a subset of user documentation: This *might* 
be suitable to the kind of help you'd expect when pressing F1 somewhere, 
which gives you 2-3 sentences about what is currently going on. But this is 
not at all suitable for our large Guide document.

> > I more or less ported it already, and would like to know if there is a
> > compelling reason not to move over.
> >
> > I fear myself with po files the lack of flexibility required in highly
> > technical, country-specific documentation.

If you still think this might be interesting, then I'd be interested to see 
the .pot file that comes out of the g-d-u conversion (or part of it). I would 
clearly recommend against it, though.

Regards,

Christian

> [1] http://lists.gnucash.org/logs/2007-07-02.html#T16:29:51
> [2] http://lists.gnucash.org/logs/2007-07-03.html#T14:35:27