Using AsciiDoc for Documentation

[Mike Evans]

On Sun, 30 Aug 2015 19:16:24 -0500
Rob Gowin <robg at gowin.net> wrote:

> [Hello List. Long time GnuCash user, -devel list lurker,
>  coming out of the shadows.]
> 
> > On Aug 29, 2015, at 5:43 AM, Mike Evans <mikee at saxicola.co.uk> wrote:
> > Another random thought then.
> >
> > I use asciidoc for pretty much all the docs I write, not much
> > admittedly but it's easy to learn and can produce many output formats.
> > I just used https://github.com/oreillymedia/docbook2asciidoc to
> > convert the guide to asciidoc using:
> >
> > $ java -jar /home/mikee/Projects/docbook2asciidoc/saxon9he.jar
> >     -s gnucash-guide.xml -o gnucash-guide.asc
> >     /home/mikee/Projects/docbook2asciidoc/d2a.xsl  chunk-output=true
> >
> > This produces an asccidoc file for each chapter plus the master page.
> >
> > [...]
> >
> > I'm not an expert on XML parsing using .xsl stylesheets but I suspect
> > this could be easily(?) remedied by editing the d2a.xsl to correctly
> > include the figures[...]
> 
> I am also a fan of using AsciiDoc as a documentation format. A
> while back I did some of the XSL hacking Mike refers to that is needed
> to get a decent conversion from the existing DocBook files. It's to
> the point where I would like to get some feedback.
> 
> I've done a first-pass conversion of the English version of the T & CG to
> AsciiDoc at https://github.com/codesmythe/gnucash-docs/tree/asciidoc/guide/C
> .
> You can click on the *.asc files there like ch_oview.asc to see GitHub's
> rendered verison of the file, including non-SVG images. (Note that SVG files
> and inter-chapter links don't work on GitHub's render.) You can click on the
> 'Raw' button for a file to see the AsciiDoc source. The source needs  clean
> up
> (lines too long, etc), but it is clean enough for folks to get an idea of
> the
> syntax. The GitHub web interace is useful because I think small edits could
> be
> done and sent as pull requests all from the web.
> 
> Like Mike said, the AsciiDoc tools (asciidoctor, at http://asciidoctor.org
> in
> this case) support the generation of DocBook XML files, so it's relatively
> simple to insert AsciiDoc support into the  current document generation
> flow.
> The asciidoctor tool generates DocBook output, and the existing flow for
> generating PDFs, HTML, EPUB, MOBI etc. works the same. My branch has the
> changes to the various Makefile.am files to support this. Those interested
> should be able to clone the repo, switch to the asciidoc branch and then
> 'make
> pdf' as usual. Note that the 'configure' script will expect to find the
> asciidoctor program on the system. I think the generated PDF is reasonably
> close to the original for a first pass proof of concept.  I've tested the
> flow
> on OS X and Fedora 21. Dunno about Windows.
> 
> Hopefully this little demo can move the documentation file format
> discussion
> forward a bit. :-) Thoughts?
> 
> 
> Regards,
> 
> Rob

Hi Rob

Looks good to me. Still a few minor bugs with the Asciidoc.  

Some of the Figure titles are missing
Second level bullet indents missing

But these are minor and some tweaking of the XSL should fix that.  Speaking of which, I notice the XSL isn't in github can you make that available somewhere so others can chip in with help? I'd also like to generate the Asciidoc locally so I can ensure both formats are from the same source for comparison purposes.

Now you (we) have to convince others to use Asciidoc!

I use Geany for my coding/writing and there is a Markdown plugin for preview, no Asciidoc at the moment though.  I'm looking at the PEG code to see how difficult it would be to produce an Asciidoc previewer plugin.  It may be beyond my learning tolerance though.

Mike E



-- 
PGP key:
http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x00CDB13500D7AB53