[GNC-dev] CMake build system for gnucash-docs

[Geert Janssens]

Op donderdag 5 september 2019 10:11:06 CEST schreef Frank H. Ellenberger:
> Hi,
> 
> Am Mi., 4. Sept. 2019 um 19:19 Uhr schrieb Geert Janssens
> 
> <geert.gnucash at kobaltwit.be>:
> > Op woensdag 4 september 2019 18:44:14 CEST schreef Frank H. Ellenberger:
> > > 2.3 Replace of over a decade outdatet GDP parts: I estimate 99% of xsl
> > > came from them and I suspect it for many output glitches. Also many
> > > docs contain their templates "Do not remove..."
> > > GDP has been the Gnome1 ancestor of GDU, which ended with Gnome2. And
> > > from there came also the OMF generation. But OMF should not simply be
> > > dropped but replaced by other forms of metadata like e.g. .desktop
> > > files.
> > 
> > If you have more details on these, I'm interested.
> 
> After hours I found the main part of my previous research in
> https://wiki.gnucash.org/wiki/Gnome_Doc_Utils

Thanks. I ran across that page a few days ago as well.

> At least as long as a cleanup is not finished, I would prefer to keep
> autotools to run experiments.

I'm trying to understand what exactly you want to do with our documentation 
that is still related to GDP ?
The xsl base files come from the docbook project with a few amendments in a 
higher level directory. Are those amendments originally from GDP or it's 
predecessor ?
In the wiki page you refer to merging templates into our documentation files. 
Does that mean our documents follow an outdated template structure and you 
want to update them to follow a newer structure ?

> > I don't see how .desktop files would replace the .omf file ? Where is that
> > currently being used ?
> See e.g. https://github.com/KDE/khelpcenter/README.metadata

Ah.
We have never formally supported KDE's khelpcenter. GnuCash is currently still 
very much a Gnome oriented application. KDE's help and Gnome's help are not 
compatible.

I personally don't see much gain in trying to support this currently. Our 
application itself expects to find the documentation in the Gnome's help 
specific locations. Adding support for this in gnucash would mean adding KDE 
as an extra target platform with its own set of specific customizations. While 
this is a nice thought (I have even considered this in the past), doing this 
only to be able to open help in KHelpcenter from within gnucash is a bit 
silly.

There's also the other entry point, where a user wants an easy way to open the 
gnucash documentation easily from within the KHelpCenter. That would again 
require our application's desktop file to be altered with KDE help specific 
extensions. And then we'd have to install a copy of our documentation under
/usr/share/doc/HTML instead of /usr/share/help

Again I'm not sure of the benefit of adding support for all that at this 
point. I think more interesting areas of study could be whether we can support 
a Macos native document format or whether the Windows help system has a way of 
identifying application documentation system-wide (that is outside of the 
application) and whether we need to add something to tap into that. Those are 
two platforms we do try to integrate with next to our gnome integration.


As an aside, I have been experimenting a bit to adjust our documentation to 
adhere to the xdg help specification
https://www.freedesktop.org/wiki/Specifications/help-spec/
That is what yelp currently considers its main documentation location 
specification. That would require us to change the installation location
from
/usr/share/gnome/help/<docname>/<lang>
to
/usr/share/help/<lang>/<docname>

and rename the main files from gnucash-guide.xml and gnucash-help.xml to
index.docbook
A first and incomplete experiment is here:
https://github.com/gjanssens/gnucash-docs/tree/xdghelp
In there I did the first part of the above changes. I believe making the full 
transition is best done for master only as it also requires our application to 
use help:<docname> instead of ghelp:<docname> to continue to find its 
documentation.

Regards,

Geert