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

[Adrien Monteleone]

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