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

[John Ralls]

> On Aug 23, 2018, at 10:25 AM, Rob Gowin <robg at gowin.net> wrote:
> 
> 
> On Thu, Aug 23, 2018 at 11:40 AM, John Ralls <jralls at ceridwen.us> wrote:
> 
> 
> 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.
> 
> 
> Hmmm. Old thought. :-) I did all of this in the 2015 thread that Geert referenced. (Except I did not use pandoc, and used Asciidoc has my markup variant of choice.) A rendered version of the Tutorial and Concept Guide can be found here: https://github.com/codesmythe/gnucash-guide-asciidoc. For example, click on 'en' then on ch_cbook.adoc to see a rendered version. Then on that page click on the 'Raw' to see the Asciidoc source. I'd also worked out the flow changes to generate PDF, eBook, etc from the Asciidoc sources.
> 
> In https://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038997.html, you asked for buy-in from the non-tech doc writers, and unfortunately, none was found. :-(
> 
> One thing that has changed in the interim is the availability of decent editors that have a live-preview mode that will show the raw Asciidoc on the left and the live-rendered result on the right. For example, Visual Studio Code (available for Mac, Linux, Windows) has an extension for this: https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode (see the demo gif), and VS Code supports Git out of the box.

Rob,

Thanks, I'd forgotten about that. I just tested and Github's online editor is able to render the adoc, so from that standpoint it's equivalent. Since it's supposed to be fully compatible with DocBook (though it requires an external tool like pandoc to convert from DocBook to Asciidoc) it will be a better fit with the existing sources that would any of the other plain-text markup choices.

What about it, (potential) documenters? Is any markup language acceptable or does the solution have to be WYSIWYG with buttons and menus for styling?

Regards,
John Ralls