[GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)

[Geert Janssens]

Op dinsdag 21 augustus 2018 17:49:57 CEST schreef Adrien Monteleone:
> Thanks for the background info Geert,
> 
> I recall a discussion some time ago about the tools and methods used to
> generate the documentation, and I think based on that thread and the info
> you’ve just provided that the solution lies in a new method entirely.
> (frames aren’t really the best option as you noted)
> 


> I’ll try to dig up that old thread,
This comes up every now an then...

There was a long thread in 2015 suggesting asciidoc, latex or libreoffice as 
alternative formats:
https://lists.gnucash.org/pipermail/gnucash-devel/2015-August/038976.html
https://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038984.html

This was preceded by another thread on this topic:
https://lists.gnucash.org/pipermail/gnucash-devel/2015-August/038952.html

And that thread referred back to a similar thread in 2013:
http://lists.gnucash.org/pipermail/gnucash-devel/2013-December/036626.html

And in May 2017 there was another foray into 'new documentation tooling' land 
as part of this thread:
https://lists.gnucash.org/pipermail/gnucash-devel/2017-May/040600.html

I'm sure there will be more of them.

> but is there a list of ’needs’ of the
> developers to use when evaluating methods?
> 
I don't think it's ever been formally written down. But here is a first list:

- it should be as easy as possible to use by non-technical people
- it should allow multiple output formats. A few the come to mind:
html, pdf, epub, mobi, windows compressed help, xml for yelp,...
- it should support both on-screen output as printable output. This is mostly 
relevant for image resolutions.
- it should support the usual typical documentation constructs, like chapters, 
sections, subsections, indexes, links, tables, images,...
- it should be manageable. That is there should be mechanisms to support 
multiple versions of one document simultaneously. A typical use case is that 
some feature gets documented that is in both the current version and the 
future one, so this document snippet should be in both versions of the 
documentation as well. While a snippet that's only for the newer version 
should only be in the future version of the documentation. And after a few 
months it should still be obvious which snippets have been integrated in which 
versions.
- I would like to see a WYSIWYM ("what you see is what you mean") kind of 
editor for the documentation process.

This is non-exhaustive and I expect the other developers may have even more 
requirements.

> The only thing I can find recently is that the intended approach was to
> create an “O’Reilly” style book, (just a goal or hard and fast
> requirement?) and I recall there needed to be a means to generate PDF,
> .mobi, and .epub versions.
> 
> As for the current method, I see docbook has something called docbook-xslt
> which is a stylesheet approach to layout and other visuals. It seems geared
> more toward print than web, but I supposed it could be used for such. This
> strikes me though as trying to find a means to keep using the proverbial
> hammer rather than a more appropriate tool. Though, I do see Gnome is still
> using Docbook and their user help is well integrated into their website as
> individual web pages, (breadcrumbs and all) and not anything resembling a
> printed page.

I believe the gnome project is using Mallard (http://projectmallard.org/). 
Aside from that they also expect there writers to work with git.

Geert