Tech Blog

I've been updaging our existing documentation which was written in AsciiDoc and also creating new documentation recently.

Our normal process is to update the source text file, commit to our SVN and the run the documentation build script from the deployment server to create the HTML and PDF versions of the document.

This works fine from our server but to speed things up while I was writing the documents and make sure I had the formatting correct I thought I'd install AsciiDoc on my laptop and 'build' the document locally before committing to SVN, building and checking.

Installing AsciiDoc is simple enough using MacPorts:

Creating a html version of your AsciiDoc is simple at this point:

That will output a file called sample.html in the same directory as the source file. No worries ...

To create a PDF or an ePub, it's recommended that you use the a2x command instead of asciidoc though.

According to the AsciiDoc website "a2x is A toolchain manager for AsciiDoc (converts Asciidoc text files to other file formats)"

So I gave this a try:

It generated the following error though!

It took a bit of Googling (sp?) but I found the core of my solution in this post:Fixing the ePub problem with Docbook-XSL/A2X/Asciidoc

The only 'tricky' part was finding my catalogue.xml, which ended up being in /opt/local/share/xsl/docbook-xsl ... and I modified the contents to be:

Once I had done that, everything generated fine :)

The next thing I need to work on is getting the default XSLT template cleaned up :)

HTH

A.J.