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
