Re: [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 
>  wrote:
> 
> 
> 
> Am 08.09.2018 um 05:06 schrieb John Ralls:
>> 
>> 
>>> On Sep 7, 2018, at 4:54 PM, Frank H. Ellenberger 
>>>  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:
 
 
 
 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 
>> , but the Gnome docs use 
>> 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 

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

[Frank H. Ellenberger]

Am 08.09.2018 um 05:06 schrieb John Ralls:
> 
> 
>> On Sep 7, 2018, at 4:54 PM, Frank H. Ellenberger 
>>  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:
>>>
>>> 
>>>
>>> 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 
> , but the Gnome docs use 
> 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

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel