DocBook Files

DocBook stylesheets for EPUB 3 output - BETA 3
=============================================
30 September 2011
Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

This directory contains a beta version of XSL stylesheets
for generating EPUB3 output from DocBook 4 content.
The stylesheets should work for DocBook5 content by first
stripping off the namespace, but that feature has not
yet been extensively tested.

These beta EPUB3 stylesheets rely on the beta HTML5 
stylesheets included in this distribution.

Changes in Beta 3
---------------------

1.  Added param 'epub.include.optional.metadata.dc.elements' to
toggle adding extra dc: elements for epub2 readers.

2.  Added error checking of modified date to terminate if
no generated date is available (required in EPUB3).

3.  Added these new <meta> elements to the .opf file:

  a.  property="dcterms:creator" for author element.
  b.  property="dcterms:creator" or "dcterms:contributor" for editor (see below).
  c.  property="dcterms:contributor" for othercredit, corpcredit, and collab.
  d.  property="dcterms:date" for date or pubdate.
  d.  property="dcterms:subject" for keywordset/keyword.
  f.  property="dcterms:coverage" for bibliocoverage.
  f.  property="dcterms:relation" for bibliorelation.
  f.  property="dcterms:source" for bibliosource.

4.  Added these new duplicate dc: metadata elements for EPUB2 compatibility:

dc:creator
dc:contributor
dc:date
dc:description
dc:subject
dc:publisher
dc:coverage
dc:relation
dc:source
dc:rights

5.  Changed epub:type value for section to either 'subchapter'
for level1 section or 'dvision' for other section levels.

6.  Added new empty utility template 'user.manifest.items', which
allows adding additional items to the manifest. For example, to
embed a font:

<xsl:template name="user.manifest.items" xmlns="http://www.idpf.org/2007/opf">
  <item id="font.dejavu.serif" href="fonts/DejaVuSerif.ttf" media-type="font/opentype"/>
</xsl:template>

9. Uses mediaobject/textobject as the fallback for a 
videoobject or audioobject.  epubcheck.b2 asks for 
such fallback.

10.  Adds a properties="svg mathml" or either value to the item element
for a chunk that contains svg and/or mathml content.

11.  Adds param 'editor.property' to select either 'creator'
or 'contributor' value for an editor element.

Changes in Beta 2
---------------------

1.  Fix table attributes for revhistory in titlepage.mode.

2.  Remove common.entities declaration from xhtml5/docbook.xsl.

Installation
--------------
These stylesheets are customizations of the
existing stylesheets in the "xhtml/" directory in
the docbook-xsl-1.76.1 distribution.  This archive
should be unzipped within your local installation of
docbook-xsl-1.76.1.  It will create two new directories:

docbook-xsl-1.76.1/xhtml5
docbook-xsl-1.76.1/epub3

There are relative paths in the files that rely on
this arrangement of files.

Usage
-----------
Use one of the following stylesheets as you would any
other DocBook XSL stylesheet:

epub3/chunk.xsl           - Chunked output.
epub3/profile-chunk.xsl   - Profiled chunk output.

Although the stylesheet directory contains a docbook.xsl
stylesheet for single file output, that is not useful for
generated EPUB3.  

You should set the $base.dir stylesheet param to the 
subdirectory that will contain the .xhtml files and
the epub package files.  For example:

base.dir=ebook1/OEBPS/

(be sure to include the trailing slash in base.dir).

After processing a document with this setting, you should find
the following output:

ebook1/mimetype                - required mimetype file.
ebook1/META-INF/container.xml  - required container file
ebook1/OEBPS/package.opf       - required package file
ebook1/OEBPS/toc.ncx           - optional NCX file for backwards compatibility
ebook1/OEBPS/docbook.css       - CSS file
ebook1/OEBPS/*.xhtml           - The chunked content files.


Creating an EPUB3 file
---------------------------

1.  Manually copy any image files used in the document
into the corresponding locations in the $base.dir
directory.  For example, if your document contains:

  <imagedata fileref="images/caution.png"/>

In this example base.dir, you would copy the file to:

  ebook1/OEBPS/images/caution.png

You can get a list of image files from the manifest file
named ebook1/OEBPS/package.opf that is created by the
stylesheet.  It currently will *not* include generated
image files for callouts, header/footers, and admonitions.
That feature will be added later.

2.  cd to the directory containing your mimetype files,
which would be ebook1 in this example.

3.  Run the following zip commands to create the epub file:

  zip -X0 mybook.epub mimetype   

  zip -r -X9 mybook.epub META-INF OEBPS 

The first command adds the 'mimetype' file first and uncompressed.
The -X option excludes extra file attributes (required by epub3).
The numbers indicate the degree of compression.
The -r option means recursively include all directories.
The "mybook.epub" in this example is the output file.


Testing with epubcheck 3
---------------------------

There is a java program that can be used to check an
epub3 file for conformance.  It is currently available 
from this website:

  http://code.google.com/p/epubcheck/wiki/EPUBCheck30

That website provides a download link, and information on
how to run the command.

Testing with EPUB readers
----------------------------
The EPUB3 standard is not yet widely supported.  The output of
these stylesheets has been tested in the following readers:

Apple iBooks on an iPod and iPad.
   - Handles videodata and audiodata.
   - Does not format MathML yet.
   - Handles SVG.

Firefox browser with the EPUBReader version 1.4.10 add-on.
   - Formats MathML nicely.
   - Does not handle videodata or audiodata yet.
   - Handles SVG.

Ibis EPUB3 preview version
   - Does not format MathML yet.
   - Does not handle videodata or audiodata yet.
   - Handles SVG with external viewer.