[GNC-dev] Docs under Linux; was: GNOME Template in Guide but not Help

Frank H. Ellenberger frank.h.ellenberger at gmail.com
Sat Sep 8 11:52:23 EDT 2018



Am 08.09.2018 um 05:06 schrieb John Ralls:
> 
> 
>> On Sep 7, 2018, at 4:54 PM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> wrote:
>>
>> Hi David,
>>
>> Am 07.09.2018 um 17:29 schrieb David T. via gnucash-devel:
>>> Hello,
>>>
>>> In digging around the documentation source XML files (gnucash-help.xml and gnucash-guide.xml) I noticed that gnucash-guide.xml includes:
>>>
>>> <!--
>>>      (Do not remove this comment block.)
>>>  Template Maintained by the GNOME Documentation Project:
>>> 	  http://developer.gnome.org/projects/gdp
>>>  Template version: 2.0 beta
>>>  Template last modified Feb 12, 2002
>>> -->
>>>
>>> I tried the link, but it is broken, moreover, gnucash-help.xml does not include this information. Is this supposed to be here, and if so, why isn’t it used in gnucash-help.xml?

Most of our makefiles are copied from scollkeeper-example2 with a
similar timestamp. Should we remove them too? ;-)
There is still a manual online:
http://scrollkeeper.sourceforge.net/documentation/scrollkeeper_example2_manual/index.html

>> As you can see from the date in the template and John mentioned before
>> in another thread, almost our whole docs build system was unmaintained
>> for over a decade.
>>
>> In Gnome 2 this templates were replaced by the GNOME Documentation Build
>> Utilities (GDU). See my "research" in
>> https://wiki.gnucash.org/wiki/Gnome_Doc_Utils
>>
>> ISTM that I opened a bug report too, but can not find it now.
>>
>> For some unknown reason, help has the template in each chapter. Probably
>> the maintainer at that time was testing the right way and got disrupted.
>> I /believe/, having one template per book, not per chapter is the right way.
>>
>> The purpose is to collect the infos required to generate the OMF, the
>> digital equivalent of the index cards in the library.
>>
>> The question, when I got distracted, was:
>> should we make GDU a build dependency or must we adapt the useful parts?
>>
>> Or in other words: can we keep our translations as they are or requires
>> GDU to convert them to gettext-po files. The downside of po files can be
>> seen in out frozen italian translation.
> 
> 
> Gnome Doc Utils last release was in 2012. It *did* get migrated to an active gitlab project,  https://gitlab.gnome.org/GNOME/gnome-doc-utils <https://gitlab.gnome.org/GNOME/gnome-doc-utils>, but the Gnome docs use https://gitlab.gnome.org/GNOME/yelp-tools/ <https://gitlab.gnome.org/GNOME/yelp-tools/> now. A rather cursory web-search suggests that Yelp doesn’t use OMF anymore, and it’s not really clear to me that our users really benefit much from our using Yelp anyway, any more than they do from our using the Windows Help Browser. I propose in the near term that we just open the docs in the default browser (we already do that for Mac and have since 2.4.0) and try for 4.0 to open them in a GtkWebkitWebView like we do reports.

The whole help under Linux has become a mess:
OMFs are an XDG standard and used by rarian, the tool which creates
yelps index, but KHelpcenter uses .desktop files instead. By this .omf
or .desktop metafiles the docs appear in the index of the respective
help viewer and can be read there without starting the program or
searching the files on the disk.

Gnome3 yelp-tools support only mallard, which seems to be a mixture of
Docbook and DITA. Because GDP suggests also a licence change, they seem
not to offer conversion tools.

One benefit of both help viewers: they can also display man and info
pages. So with the respective 'Xhelp:', 'man:' or 'info:' URL one could
link also such elements.

The KHelpcenter works on html files. From my observations html files are
some 25% larger than xml files and need some time to generate. So
proofreading is much faster done with yelp on the docbook main file.

> 
> I think that means we shouldn’t make GDU a doc-system dependency

I believe, if you work on the italian translation it is already there.

 and that there may be fewer “useful parts” than you expect.
> 
> Regards,
> John Ralls

Regards
Frank



More information about the gnucash-devel mailing list