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

[John Ralls]

> On Sep 8, 2018, at 8:52 AM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> wrote:
> 
> 
> 
> 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.

Heh, I expect no useful parts at all because I don’t think many users even approach Help by starting with Yelp or KDEHelp and going through the index. I think most everyone nowadays starts at some web search engine and nearly all the rest start at the help menu in-app.

The Italian translation is the only one using po files, but its processing is frozen because when you reprocess it most of the msgids turn fuzzy and it becomes English with scattered Italian. We may as well remove the infrastructure and leave just the last gnucash-guide.xml and gnucash-help.xml.

At some point we’re going to have to drop both Italian and Japanese documentation for being obsolete.

As for Scrollkeeper, it’s embalmed body is still on Sourceforge because that’s what Sourceforge does with dead projects. The last release was in 2002 and the repository is read-only (and not online) because it’s CVS and SourceForge has removed everything except the checkout infrastructure for CVS. Debian maintains a Scrollkeeper package with the following note: "This dummy package is designed to facilitate upgrades for systems with scrollkeeper installed. It will bring its replacement, named rarian, instead.” Rarian also seems to have ceased development about 10 years ago. Although downloads are hosted at https://rarian.freedesktop.org/Releases <https://rarian.freedesktop.org/Releases>, there’s no repository for it in either git.freedesktop.org <http://git.freedesktop.org/> or gitlab.freedesktop.org <http://gitlab.freedesktop.org/>. None of the current https://gitlab.gnome.org/GNOME/yelp <https://gitlab.gnome.org/GNOME/yelp>,   https://gitlab.gnome.org/GNOME/yelp <https://gitlab.gnome.org/GNOME/yelp>-tools, or  https://gitlab.gnome.org/GNOME/gnome-doc-utils <https://gitlab.gnome.org/GNOME/gnome-doc-utils> sources reference Rarian at all except in ChangeLog entries and those only in Yelp. ISTM we can safely remove all of the OMF processing.

Regards,
John Ralls