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

Rob Gowin robg at gowin.net
Thu Aug 23 13:25:51 EDT 2018


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


More information about the gnucash-devel mailing list