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

[John Ralls]

A couple of references to what Geert is talking about:

The W3C specification for Internationaliation Tag Set Locale Filters: https://www.w3.org/TR/its20/#LocaleFilter
Geert had in mind to use ITS Tool for processing Locale Filter tags; the relevant documentation is at http://itstool.org/documentation/its.html. No Anchors, scroll to Locale Filter.

I don't see anything similar in the rather sparse reST/Sphinx i18n docs, but ISTM we could probably accomplish something similar with the build system as long as the locale-unique material is in its own file. With a little more work we could invent a reST directive to hold the locale filter tags and preprocess the file before handing it off to Sphinx.

Regards,
John Ralls


> On Feb 10, 2021, at 5:43 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> 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
> 
> 
> 
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel