[GNC-dev] Porting the Tutorial & Concepts Guide to ReadTheDocs.org
jralls at ceridwen.us
Thu Feb 11 19:41:27 EST 2021
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.
> 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
> 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
> 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
> 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
> 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 ?
> 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>
>>> 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 ?
>> Hi Geert,
>> First off, yes, the documentation can be self hosted. I’ve done that here:
>> <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>. 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.
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
More information about the gnucash-devel