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:
https://bugs.archlinux.org/task/22746?project=1&string=docbook-xsl

and on Google Groups here:

http://groups.google.com/group/asciidoc/browse_thread/thread/fdd5194c09bd4b87

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.