Home » Featured, General Computing, Headline

Fixing the ePub problem with Docbook-XSL/A2X/Asciidoc

1 March 2011 2 Comments
Fixing the ePub problem with Docbook-XSL/A2X/Asciidoc

If you are using AsciiDoc (and A2X) to convert documentation to ePub you’ll probably have run into a problem as follows:

In CygWin, to generate an epub file I use this command:
a2x -fepub myFile.txt --no-xmllint --verbose

This was giving me this error:

>> warning: failed to load external entity
>> “http://docbook.sourceforge.net/release/xsl/current/epub/docbook.xsl”;
>> compilation error: file /etc/asciidoc/docbook-xsl/epub.xsl line 13
>> element import
>> xsl:import : unable to load
>> http://docbook.sourceforge.net/release/xsl/current/epub/docbook.xsl

Note I am using Docbook-XSL 1.75.2.

The issue was reported on the Arch Linux distro recently here:

and on Google Groups here:


Typically there is a mapping from URIs in XML/XSL sheets to local versions of those files. Xslt-proc uses this to speed up processing by avoiding the download. The issue in this case is the mapping for ePub files did not exist (not sure why).

The Fix: It turns out the fix is simple but took a while to figure out. I downloaded the latest DocBook-XSL version – (http://sourceforge.net/projects/docbook/files/docbook-xsl) and unzipped. This will contain a folder for ePub/docbook.xsl.

Next locate the mapping file, this is usually /etc/xml/catalog.

Inside it’ll have mappings from web-URIs to local-URIs. Something like this:

<rewriteURI uriStartString=”http://docbook.sourceforge.net/release/xsl/current” rewritePrefix=”/usr/share/xml/docbook/xsl-stylesheets-1.76.1/”/>

You just need to ensure your ePub folder is included as a sub-folder off of this local path. Manually copy it from wherever you unzipped to the right spot (in my case /usr/share/xml/docbook/xsl-stylesheets-1.76.1/epub) and you’re done.

Now you can generate ePub format for all those non-Kindle book readers.


  • Elvin85 said:

    Interesting solution. But i haven’t used a2x. I use Calibre for converting files. I hope that i haven’t lost anything with using just Calibre :)

  • klaatu said:

    Great tip, thanks.
    It looks like a wholesale update to docbook 1.77.1 is worth the trouble. I downloaded 1.77.1 and untarred it into /usr/share/xml/docbook/xsl-stylesheets-1.77.1

    then ran a quick su -c ‘sed -i ‘s/76/77/g’ /etc/xml/catalog’

    And everything worked splendidly.

Leave your response!

Add your comment below, or trackback from your own site. You can also subscribe to these comments via RSS.

Be nice. Keep it clean. Stay on topic. No spam.

You can use these tags:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

This is a Gravatar-enabled weblog. To get your own globally-recognized-avatar, please register at Gravatar.