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

For the legal notice…

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.

Spread the love