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

[Geert Janssens]

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