> On Aug 23, 2018, at 12:37 AM, Geert Janssens <[email protected]> > 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 _______________________________________________ gnucash-devel mailing list [email protected] https://lists.gnucash.org/mailman/listinfo/gnucash-devel
