20140109 (Thursday, 09 January 2014)

The documentation system

I had some visions on what is still needed to make the Lino documentation system usable. Started to write documentation about it in https://www.lino-framework.org/dev/userdocs.html. My motivation is a meeting scheduled for Jan 22nd in Eupen with Gerd and Melanie.

• Added a new currentlanguage directive which solves a subtle problem when documenting multilingual Lino applications: I want to write tickets in the language of the user who reported it. That language is not necessarily English. I don’t want to translate tickets. But I want to expand ddref roles into the user’s language, not to English.

• Added two directives and roles called directive and role in rstgen.sphinxconf. (Edit: which I removed 2014-06-04.)

• New module rstgen.sphinxconf.dirtables with directives to automatically generate tables from the files of a directory.

The idea behind all this was a full ticket management system: since tickets are usually being managed by programmers, it would be normal to store them rather usint .rst files than in a database.

But I abandoned this idea when I saw that the entry_intro directive can’t insert the document’s metadata because these fields become available in the docinfo node only when the document has finished to parse. I would have to defer the rendering until after that.

Before doing this, I’ll rather try from the other side, by storing them in a database.