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

[John Ralls]

Adrien,

If you mean https://help.gnome.org <https://help.gnome.org/>, those docs are built using Yelp tools, see https://gitlab.gnome.org/GNOME?utf8=%E2%9C%93&filter=yelp <https://gitlab.gnome.org/GNOME?utf8=%E2%9C%93&filter=yelp>. Most of that documentation seems pretty cursory, even for largish apps like Gnome Web (aka Epiphany).

Not all “Gnome” projects are included there. The GIMP and Inkscape (though I guess since Inkscape doesn’t keep their repo on gitlab.gnome.org <http://gitlab.gnome.org/> they’re no more a Gnome app than we are), for example, both maintain their own documentation (in DocBook) and doc build scripts.

Gimp’s docs are similar to ours if one doesn’t use viewdoc: They stand apart; there are links to the previous and next pages, there’s a “home” link back to the TOC, but nothing tying it to the main website.

Inkscape doesn’t really have a comprehensive manual. There’s a man page (not on their website) and 9 single-page tutorials (written in DocBook) that are displayed as regular website content pages with no extra links beyond the site menubar across the top.

No doubt that viewdoc.phtml could be improved. As Geert noted it’s pretty basic, just 144 lines of php. If someone fluent in modern php and css would like to overhaul and modernize the website we’d welcome it, but I think the core team’s time is better spent on GnuCash itself.

Regards,
John Ralls

> On Aug 21, 2018, at 8:49 AM, Adrien Monteleone <adrien.monteleone at lusfiber.net> wrote:
> 
> 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, but is there a list of ’needs’ of the developers to use when evaluating methods?
> 
> 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.
> 
> Regards,
> Adrien
> 
>> On Aug 21, 2018, at 2:46 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
>> 
>> Op dinsdag 21 augustus 2018 02:44:59 CEST schreef Adrien Monteleone:
>>> David C,
>>> 
>>> So for clarification this is the first link you posted about:
>>>> https://www.gnucash.org/docs/v3/C/gnucash-guide/txns-register-oview.html#t
>>>> xns-regstyle1
>>> Notice this is in the folder /docs/v3/C/gnucash-guide/
>>> 
>>> But the link on the Documentation page and the link you included (both in 
>> that first post and in the last one) that said how you got there was this:
>>>> https://www.gnucash.org/viewdoc.phtml?rev=3&lang=C&doc=help
>>> 
>>> So yes, that IS version 3 (listed here as ‘rev=3’) but that’s not the same
>>> link as above. (though it might be the exact same content, I didn’t check)
>>> 
>>> I can’t find any way, other than typing it in directly, to get to the
>>> /docs/v3/C/ directory wherein lies the /gnucash-guide/ and /gnucash-help/
>>> folders and contents. All of the links on the documentation page seem to
>>> point instead to the /viewdoc.phtml which never changes the URL as you
>>> navigate the document. (my guess is the viewdoc.phtml template is serving
>>> the pages physically located in /docs/v3/C/, we just can’t see the real
>>> URL)
>> 
>> The viewdoc.phtml page is a first and imperfect attempt to integrate the 
>> documentation in the website.
>> 
>> It ensures that while presenting the documentation the main website's 
>> navigation menus and style are still visible. Before that page existed 
>> clicking on a documentation link would suddenly remove all website decorations 
>> and just show you the documentation on a plain white page with no option to 
>> navigate to other parts of the main website.
>> 
>> viewdoc.phtml is just a wrapper that opens the actual documentation in a 
>> separate frame. If you ask your browser to open that frame in its own window 
>> you'll see the direct links David posted here.
>> 
>> The use of a frame is old-fashioned and has indeed many limitations. It was 
>> the only option at the time that could be implemented with reasonable effort.
>> 
>> Of course it would be much nicer to have bread crumbs and clear links for each 
>> page. And a documentation navigation menu integrated in the website's main 
>> decorations.
>> 
>> However from how I understand this would mean to create a specialized docbook 
>> style used exclusively to generate the documentation section of our website. I 
>> believe the way we currently generate the gnucash html documentation is not 
>> fit for integration. Writing such a specialized docbook style is possible, but 
>> I never found time to dig in.
>> 
>> Regards,
>> 
>> Geert
> 
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel