If you followed the recommended installation procedure for Asciidoc on a Mac, asciidoc and a2x to epub will work but there will still be some packages (like DocBook, dblatex) missing.
How can you tell? If you try to convert an asciidoc text file to pdf by a2x, you will get the following error:
a2x: ERROR: xmllint --nonet --noout --valid file.xml returned non-zero exit status 4
After having spent hours on searching the internet and trying to solve this, I [finally] got a great tip from a colleague, which I really have to blog and maybe help others when facing the same problem. So this is a quick post on how to install asciidoc on Mac containing the DocBook installation for pdf conversion and solving above mentioned issue.
- You install first the appropriate package of MacPorts as found here
- As soon as installation of MacPorts completes, you start the terminal.app
- And enter there
sudo port install asciidoc
This installs asciidoc with docbook and corrects old installations if existing
Note: It requires Xcode and its Command Line tools. Otherwise you’ll get the following warning
Warning: The Command Line Tools for Xcode don't appear to be installed; most ports will likely fail to build. Warning: See http://guide.macports.org/chunked/installing.xcode.html for more information.
Xcode can be downloaded from the App Store, Command Line Tools over Xcode > Preferences > Downloads > Components >
If you now call
a2x -fpdf …
conversion will succeed and you will [finally] get a working pdf file .
If not, install dblatex as well. To do so call
sudo port install dblatex
It takes quit a while, but afterwards you should be able to create pdfs and epubs by a2x.
Cover or legal notice (docinfo.xml)
BTW… to combine a cover page for a epub file and/or legal info for a pdf, place a file starting just like your asciidoc text file and ending by -docinfo.xml in the same directory as your asciidoc file and convert using the docinfo option. So let’s say your asciidoc file is called “book.txt”, which will convert as book.epub. You create a book-docinfo.xml
For the cover image, enter a mediaobject definition as follows
Note: For guide lines to eBook cover design and specifications according to the output device, you may check this post
To convert to epub or pdf and combine with the docinfo file, just call:
a2x -fepub -a docinfo book.txt a2x -fpdf -a docinfo book.txt
Note: Mac OS X Finder or QuickLook cannot show the cover of an ePub file. You need to drag it into iTunes or open by an app like Calibre to make sure it is combined.
Technical