[GNC-dev] Help documentation

Tue Feb 16 19:16:09 EST 2021

Am 16.02.21 um 18:21 schrieb John Ralls:
> The way we manage program help has four serious problems:
> 
> 1. It's separate from the program--not even in the same git repository--so changes to the program are seldom reflected in the help. Very little of it has been touched in the last 10 years.
> 
> 2. It's largely monolithic which makes it resistant to translation, so while the program is translated into 58 languages, the help has only 3, only 1 of which, German, is up to date.

No, it is a 1.x stub with a few recent appendixes, but the guide is
almost complete and recent.

> 3. It's formatted with Docbook, an XML dialect with no usable editing or translation tools, so authors and translators must learn to edit XML by hand and learn to work the document build system so that they can build to HTML and then review their work in their browser. Pretty damn tedious.

Rant: Also in the wiki, whichs language should be easier to learn, In
see not many contributions.

> 4. A lot of GnuCash is completely undocumented.
> 
> Note that unlike the Tutorial and Context Guide sections of the help are reachable by context help buttons throughout the UI. ISTM that should make it more amenable to translation with gettext.
> 
> I think that if the help documentation was kept close to the UI code that it would be both easier for developers to keep it in sync with code changes and for code reviewers to insist that they do so. Integrating it with the build system that they already use routinely would remove a bit of the tedium, but even better would be finding a format for which a Free WYSIWYG editor is available or better still where contributors could edit directly on Github and create a PR using the fairly simple Github online UI, making editing accessible to non-developers (that would suggest that the format should be either Github-flavored markdown or restructured text, the formats for which Github supports WYSIWYG editing).
> 
> A somewhat geekier alternative--though still far more accessible than Docbook in a separate repo--is Doxygen markup. We already use that extensively for the API (though not extensively enough, there's a lot of undocumented API). Unfortunately Doxygen doesn't provide a way to extract msgids so we'd have to either build in a format that xgettext understands or extend Doxygen.

Gettext is nice for programmers (usually short strings with perhaps
format parameters) and most familar for most of us, but for "real text"
not neccessary the best format. That should probably be examined more.

Doxygen can also output xml or MarkDown as closest to rst.

We should also consider docutils/sphinx. That would allow connecting to
the translation-toolkit, which we already use on weblate. It seems also
to have a C/C++ parser.

The main problem seems a Guile/Scheme/Lisp parser, which I did not see
in both. But things like report options should not be ignored.

Most of the static part of the GUI is in the glade files, which are XML.
It should not be very hard to XSLT the nodes for the structure, and
finally labels and tooltips.

> Regardless of the markup style we need to work out exactly where in the source tree to locate the help strings and how to connect them to their respective help buttons. 

Yesterday I linked the forgotten
https://wiki.gnucash.org/wiki/Settings_Wording from
https://wiki.gnucash.org/wiki/GUI_Guidelines

> Regards,
> John Ralls

Regards
Frank