[GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[John Ralls]

> On Aug 23, 2018, at 12:37 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> Op dinsdag 21 augustus 2018 20:50:38 CEST schreef Geert Janssens:
>> Op dinsdag 21 augustus 2018 17:49:57 CEST schreef Adrien Monteleone:
>>> but is there a list of ’needs’ of the
>>> developers to use when evaluating methods?
>> 
>> I don't think it's ever been formally written down. But here is a first
>> list:
>> 
>> - it should be as easy as possible to use by non-technical people
>> - it should allow multiple output formats. A few the come to mind:
>> html, pdf, epub, mobi, windows compressed help, xml for yelp,...
>> - it should support both on-screen output as printable output. This is
>> mostly relevant for image resolutions.
>> - it should support the usual typical documentation constructs, like
>> chapters, sections, subsections, indexes, links, tables, images,...
>> - it should be manageable. That is there should be mechanisms to support
>> multiple versions of one document simultaneously. A typical use case is that
>> some feature gets documented that is in both the current version and the
>> future one, so this document snippet should be in both versions of the
>> documentation as well. While a snippet that's only for the newer version
>> should only be in the future version of the documentation. And after a few
>> months it should still be obvious which snippets have been integrated in
>> which versions.
>> - I would like to see a WYSIWYM ("what you see is what you mean") kind of
>> editor for the documentation process.
>> 
>> This is non-exhaustive and I expect the other developers may have even more
>> requirements.
>> 
> Add a way to relatively easily manage translations of the documentation.

That's almost a new subject entirely. Except for Italian, the "translated" documents are more like "rewritten in another language". I think that's a good thing because it affords a more natural, idiomatic experience to readers, but I imagine (I have to imagine, I'm nowhere near fluent enough in any language other than English to have experience) that it's also more work on the part of the foreign-language authors.

The alternative is to run gettext on the doc sources and have a po file for the translation. Cristian Marchi set that up for Italian, but it has an unfortunate side effect: If the translation isn't kept up to date with the documentation progressively more of it becomes "fuzzy" and reverts to English. I tried for a while to do fresh it.po builds, but it was soon clear that it was a bad idea and so we're back to using a mostly frozen, monolithic, it/gnucash-guide.xml and it/gnucash-help.xml from 2.4.

Regards,
John Ralls