> On Aug 23, 2018, at 12:52 PM, John Ralls <jra...@ceridwen.us> wrote: > > > >> On Aug 23, 2018, at 10:25 AM, Rob Gowin <r...@gowin.net> wrote: >> >> >> On Thu, Aug 23, 2018 at 11:40 AM, John Ralls <jra...@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/ _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
