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

Thu Feb 11 20:10:11 EST 2021

I think the functionality of Locale Filter could be done using the Sphinx ‘ifconfig’ extension[1]. It allows content selection based on a Python expression involving variables set in the Sphinx conf.py file.

[1] https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html <https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html>

Rob

> On Feb 11, 2021, at 6:41 PM, John Ralls <jralls at ceridwen.us> wrote:
> 
> 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
> 