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 <jra...@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.gnuc...@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.gnuc...@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@gnucash.org >> https://lists.gnucash.org/mailman/listinfo/gnucash-devel > _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel