Friday, July 9, 2021

I committed my recent work on makehelp (#4172). I started to understand a few things. Time to write some documentation.

makehelp now generates only the actor pages (and an index page), IOW a page per actor but no more pages per model and per plugin. That’s because actor pages are the only ones to be opened by the help button. Each actor page should directly refer to the relevant places in the reference documentation and the user guide.

Note that reference documentation is a new glossary term. We should say reference documentation instead of developer guide because this kind of documentation is actually not only for developers, they are also for key users. These “reference docs” are currently integrated into the developer guide, but this might change.

I moved the logic for loading help texts at startup into a separate class lino.core.help.HelpTextsLoader. The HTL is instantiated temporarily by the lino.core.kernel.Kernel.kernel_startup(). The makedocs command instantiates it another time because it also uses the first paragraph of actor class descriptions, which the kernel does not store. All this is still experimental.

I moved all the help functionality, including the OpenHelpWindow action to a new plugin lino.modlib.help and make it an optional feature. I renamed makedocs to makehelp.

To make my work more visible we should start to update the demo sites more often, and to run makedocs each time there. Here it gets related to the #2480 ticket: it would be cool to have an impressive series of Lino demo sites on Heroku, each with a usable user guide….

My goal for this time is that when clicking on the ? button, Lino opens a page that is actually useful for an end user. Or more precisely a page that has a chance to be useful, when documentation is written accordingly. Because that’s another pair of shoes: defining the right conventions and habits of where to write what. This is currently still a big mess, and reviewing all docs is a big work. But I am advancing…

TODO: Test whether translation actually works.