Generating PDFs and ePubs from an AsciiDoc ... on a Mac
Posted At : August 11, 2011 9:41 AM
2 Comments
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:
$ a2x -fepub -dbook -L sample.txt
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:
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<!-- XML Catalog file for DocBook XSL Stylesheets v1.76.1 -->
<rewriteURI uriStartString="/usr/local/docbook-xsl-1.76.1/epub" rewritePrefix="./"/>
<rewriteSystem systemIdStartString="/usr/local/docbook-xsl-1.76.1/epub" rewritePrefix="./"/>
</catalog>
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.
