Using AsciiDoc for Documentation

Rob Gowin robg at gowin.net
Sun Aug 30 20:16:24 EDT 2015


[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


More information about the gnucash-devel mailing list