[GNC-dev] Register Documentation Improvements (was Re: [GNC] Column widths again)
adrien.monteleone at lusfiber.net
Tue Aug 21 11:49:57 EDT 2018
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.
> 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:
>> 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:
>> 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
> 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
> 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.
More information about the gnucash-devel