[GNC-dev] Documentation Source Format (was: Register Documentation Improvements)

[John Ralls]

> On Aug 23, 2018, at 12:52 PM, John Ralls <jralls at ceridwen.us> wrote:
> 
> 
> 
>> 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?

Frank opened a bug [1] about this in early 2014 after a lengthy discussion here, and Geert added a summary of the mailing list discussion. One pearl from that: The potential documenters of the day thought that Asciidoc was "still too difficult to learn for non-technical people".

Frank brought up another option on that bug today: Calibre [2], which can do conversions among a variety of formats. DocBook isn't one of them, but EPUB is and we generate EPUB from DocBook as part of the release process. It's also able to handle DOCX and ODT as an input format (as is pandoc), and it's able to edit EPUB (an HTML+CSS variant).

Perhaps one of the Davids would consider trying it out.

Regards,
John Ralls

[1] https://bugs.gnucash.org/show_bug.cgi?id=722016
[2] https://calibre-ebook.com/