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

[John Ralls]

> On Aug 23, 2018, at 12:45 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> Op dinsdag 21 augustus 2018 21:24:25 CEST schreef John Ralls:
>>> On Aug 21, 2018, at 11:50 AM, Geert Janssens <geert.gnucash at kobaltwit.be>
>>> wrote: - it should allow multiple output formats. A few the come to mind:
>>> html, pdf, epub, mobi, windows compressed help, xml for yelp,...
>> 
>> We don't need a single tool to do that; in fact we don't use a single tool
>> now. We create Windows compressed html (.chm) with HTML Help Workshop from
>> the xslt-created HTML and mobi with calibre from the xslt-created epub.
>> 
> It appears while writing down the requirements, I was more considering our 
> documentation system as a whole, not just a single tool. I agree this can 
> consist of several tools glued together.
> 
> I think what matters is the people actually writing the documentation should 
> have to learn as few as possible to keep the barrier for contribution very 
> low. More on that in reply to your other message.
> 
>> That aside, I think we should reconsider windows compressed help.
>> Microsoft's own Windows 10 applications seem to open the browser to the
>> relevant documentation page on www.microsoft.com and the help browser is
>> still decorated with Windows 2000 frame and controls. It looks quite
>> jarring. We could more easily just open the documents in a GtkWebkitWebView
>> just like reports.
> 
> I'm all for this. In fact I have proposed this in the past. That also rids us 
> of one of the more annoying build dependencies on Windows (HtmlHelp).
> 
> It would be nice if our html version of the docs would get some css love in 
> that case though. Wading through plain rendered html is an equally 2000'ish 
> experience.

I've been having another look at https://pandoc.org/. It consumes several flavors of markdown and wiki markup as well as DocBook. It emits an impressive range of output formats including DocBook, GNU texinfo (which is completely unrelated to TeX), LaTeX, HTML, and Epub; the only deficiency from our view would be that it doesn't directly emit PDF. It can do so indirectly via LaTeX or we could generate DocBook and continue to use Apache XML-Format-Objects.

My original thought was that contributors could use it to convert the current DocBook sources to Microsoft Word or LibreOffice format, edit in a familiar word processor, and then use pandoc to convert back to DocBook. That didn't work out very well in testing. 

So a new thought: One of the core devs use pandoc to convert the DocBook source to one of the markup/markdown variants, do the necessary manual fixups and commit the result. If we want DocBook for some reason the build process would use pandoc to generate it.

If we had GitHub-flavored markdown sources then https://github.com/gnucash/gnucash-docs would show rendered documentation and one could use the "preview" button to check basic layout; it would appear pretty similar to how the document would look in a PDF or eBook rendering.

Regards,
John Ralls