[GNC-dev] Porting the Tutorial & Concepts Guide to ReadTheDocs.org

[Geert Janssens]

Hi Rob,

I have gathered from irc conversations the you have picked up on your interest 
of converting our documentation to reStructuredText. As I'm unfortunately not 
able to spend much time on irc while you are there, I will add some comments 
on this mailing list thread.

From the little information I have so far it looks like reStructuredText and 
the sphinx tool have everything it takes for a good conversion with plenty of 
benefits.

The only concern that remains for me is as mentioned earlier:
So far I don't see the ability for a master document in which certain sections 
only apply to some languages. To be fair our current documentation doesn't 
support that either as of today, but adding ITS to the current docbook mix 
would allow us to move in that direction.

Personally I find that an important feature to have for our future 
documentation system. Contrary to many other domains, accounting documentation 
is sensitive to regional differences. Each region may have subtle differences 
in how certain things are to be explained.
Luckily there is standardisation which means an estimated 90% of the 
documentation can be shared, but a small portion is region dependent. A 
typical example would be tax rules. Or some concepts only make sense in 
certain regions and don't apply at all in other regions.

Considering most of the documentation is common, a translation flow based on a 
master document with message catalogs makes sense to me. The huge benefit is 
that we can offer user-friendly systems to translators. I seem to remember the 
biggest hurdle for documentation writers and translators is git. Going for a 
gettext based translation system, at least translators would be able to do 
most of their job in tools familiar to them, like weblate or poedit or 
whatever.

But we should take care to also be able to handle that small part that's not. 
And that's where ITS in the docbook context would come in. It allows (among 
others) to mark certain sections as applying only to one specific "language".

That would allow an American document writer to explain the basics of American 
taxes, and a Dutch translator could replace that with a Dutch alternative in 
such a way that if the American section changes the Dutch translation is not 
affected.

And it would allow the American document to explain state taxes. Belgium and 
the Netherlands don't have states, so that section could be omitted in a Dutch 
translation.

I admit not having searched very hard, but I  didn't find something similar 
for reStructuredText or the sphinx build system.

Do you see ways to implement something like that ?

Regards,

Geert

Op zaterdag 25 april 2020 20:16:46 CET schreef Rob Gowin:
> > On Apr 25, 2020, at 2:24 AM, Geert Janssens <geert.gnucash at kobaltwit.be>
> > wrote:
> > 
> > Hi Rob,
> > 
> > Thanks for running this experiment.
> > 
> > The stylesheet used by ReadTheDocs is much more modern than ours and
> > indeed looks much nicer for online consumption. Even the pdf is cleaner.
> > 
> > On the other hand I also have a few concerns/questions:
> > 1. How would a translation flow look like with asciidoc ?
> > 2. Can it support a single master document including sections that should
> > only appear for certain translations ? 3. ReadTheDocs is a hosted
> > service. That's a big change from our current philosophy to self-host as
> > much as possible. Are there self-hosting options ?
> > 
> > Regards,
> > 
> > Geert
> 
> Hi Geert,
> 
> First off, yes, the documentation can be self hosted. I’ve done that here:
> https://gnucash-docs-test.codesmythe.net/index.html
> <https://gnucash-docs-test.codesmythe.net/index.html>. It uses an older
> stylesheet, so looks a little different, and there’s no PDF there. I have
> generated a PDF similar to the ReadTheDocs one locally. Note that this
> experiment uses files in the reStructuredText format, not asciidoc. The
> reST files are generated from the DocBook files using pandoc.
> 
> For translation: The underlying tool used by ReadTheDocs is the Sphinx
> Python Doc Generation Project. Their I18N flow is described here:
> http://www.sphinx-doc.org/en/master/usage/advanced/intl.html
> <http://www.sphinx-doc.org/en/master/usage/advanced/intl.html>. I’m no
> expert in the area, but seems it does support a single master document. I
> don’t know about sections that should only appear for certain translations.
> 
> I’ll jump on IRC sometime this week to discuss translations in more detail.
> 
> Regards,
> 
> Rob