ePub converter feedback

[Boris Schäling <boris@highscore.de>]

After a month of experiments with the ePub converter and the ePub file
format I managed to create the eBook files I'm happy with. Here's an
overview of the problems I ran into (for those who plan to use the ePub
converter in the future :-): 

* In order to use the ePub converter on Windows the Ruby script must be
patched - see
http://sourceforge.net/tracker/?func=detail&aid=2925646&group_id=21935&atid=
373747 and
http://sourceforge.net/tracker/?func=detail&aid=2925648&group_id=21935&atid=
373747. As a temporary file is not deleted you might also want to read
http://sourceforge.net/tracker/?func=detail&aid=2930097&group_id=21935&atid=
373747. 

* The ePub style sheet sets generate.toc to "book toc,title". As Keith
recommends not to generate a XHTML TOC (see
http://lists.oasis-open.org/archives/docbook/201001/msg00069.html)
generate.toc should be set to something else (like "book nop"). 

* The ePub style sheet overwrites a template for d:bridgehead and two more
templates called section.heading and component.title. I mention this because
I was confused about the output first. There are of course other templates
overwritten to generate a proper .epub file. However these templates were
changed because of "SEO customization" (that's the comment in the style
sheet). This kind of automatic SEO customization caused a problem to me and
I had to overwrite the templates again (a parameter like seo.customization
would be nice :-). 

* The ePub style sheet supports a cover page but not a title page. If you
process a <book> and you want the title page of the book to be seen by an
ePub reading system you must patch the ePub style sheet. The title page is
generated and included in the .epub file but it is not referenced anywhere
(and thus invisible to ePub reading systems). To make the title page visible
a reference must be included in the <manifest> and <spine> section of
content.opf (and ideally a reference is also included in the <guide>
section). This can be done by overwriting the templates opf.manifest and
opf.guide. It's also necessary to set the variable root.is.a.chunk to 1. The
details can be found here:
http://lists.oasis-open.org/archives/docbook/201001/msg00071.html. Whether
this patch causes problems in other cases is currently unknown:
http://lists.oasis-open.org/archives/docbook-apps/201001/msg00068.html. 

I ran into some more problems which are indirectly related to the ePub
converter: 

* Adobe Digital Editions shows a ? for every &#13; entity. This is a problem
if xsltproc is used and text files are x-included which use \r\n end line
markers (see https://bugzilla.gnome.org/show_bug.cgi?id=608333). I've
converted all text files to Unix format and hope I don't forget to do this
again when I update those files with various Windows programs. :-/ 

* The ePub validator epubcheck complains about invalid markup code in the
<metadata> section (in content.opf) if /book/info/* contains not only text
nodes. For example I use <link> in /book/info/holder which is converted to a
XHTML link <a> in the <metadata> section. According to epubcheck it's not
allowed to use a XHTML link in the <metadata> section though. I fixed the
problem by overwriting the template for d:link and mode="titlepage.mode"
(but you might run into similar problems with other tags which are valid
according to the DocBook specification). 

* If you have preformatted blocks with long lines (eg. source code listings)
and don't want to or can't reformat them setting the CSS property
"white-space" to "pre-wrap" helps (see
http://getsatisfaction.com/oreilly/topics/horrible_epub_monospace_font_in_so
ny_reader_prs_700bc). 

Boris