lyx_mirror/lib/docbook/epub3/README

DocBook stylesheets for EPUB 3 output 
=============================================

This directory contains XSL stylesheets
for generating EPUB3 output from DocBook content.
For more information on EPUB3, see:

http://idpf.org/epub/30

These EPUB3 stylesheets are a customization layer on
top of the xhtml5/ stylesheets in this distribution, which
are in turn a customization layer on top of the 
xhtml/ stylesheets in this distribution. 
Using a customization layer enables the EPUB3
stylesheets to inherit all the features of the
XHTML stylesheets while making the minimum changes
for them to produce valid EPUB3.

If you need to customize the epub3 stylesheet, see the section
below titled "Customizing the epub3 stylesheet".

Usage
-----------
The general process for creating an EPUB3 ebook is:

1.  Generate chunked XHTML5 content that validates against
the EPUB3 schemas, and generate the EPUB3 package
files.

2.  Copy any image files into the output directory.

3.  Run a zip command to create an .epub file.

4.  Validate the .epub file.


Following are the steps in more detail.

1.  Create the XHTML5 files.
-----------------------------

The first step is handled by these stylesheets.
To generate EPUB3-compatible XHTML5 files,
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.  Here is an example using xsltproc:

xsltproc \
  --stringparam base.dir ebook1/  \
  epub3/chunk.xsl \
  mybook.xml

Make sure you don't include the OEBPS directory 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-epub.css  - CSS file
ebook1/OEBPS/*.xhtml           - The chunked content files.


2.  Copy image files
---------------------------

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 includes references to image files for
callouts and admonitions if they are used in the output.
Note that the header and footer images are turned off for
EPUB3 output.


3.  Create the epub3 file.
-----------------------------
Change to the directory containing the base.dir (ebook1
in this example), and run the following zip command to
create the epub file:

zip -r -X mybook.epub mimetype META-INF OEBPS 

The -r option means recursively include all directories.
The -X option excludes extra file attributes (required by epub3).
The "mybook.epub" in this example is the output file.
The other three arguments must appear in this order.


4.  Validating 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.


Customizing the epub3 stylesheet
---------------------------------
As with all DocBook stylesheets that generate chunked output, a
customization requires two files: one for chunking behavior and
one for element formatting.  Most people only need to customize
element formatting, but you still need the two files to keep the
proper import precedence.  See this doc for details about this
issue:

   http://www.sagehill.net/docbookxsl/ChunkingCustomization.html

Here is an example of the chunking stylesheet, which is the one you
apply to your document when processing:

custom-epub3-chunk.xsl
--------------------------------------------------------------------
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:d="http://docbook.org/ns/docbook"
                version="1.0"
                exclude-result-prefixes="d">

<!-- Import the element customization module, shown below -->
<xsl:import href="custom-epub3-elements.xsl"/>

<!-- import stock DocBook XSL file; use a catalog for local files-->
<xsl:import href="http://cdn.docbook.org/release/xsl/current/xhtml/chunk-common.xsl"/>

<!-- include (not import) stock DocBook XSL file; use a catalog for local files-->
<xsl:include href="http://cdn.docbook.org/release/xsl/current/xhtml/chunk-code.xsl"/>

<!-- include (not import) stock DocBook XSL file; use a catalog for local files-->
<xsl:include href="http://cdn.docbook.org/release/xsl/current/epub3/epub3-chunk-mods.xsl"/>

<!-- Add here any templates that change chunking behavior.
That is, any templates copied from chunk-common.xsl or
chunk-core.xsl and modified.  Any such customized templates
with a @match attribute must also have a priority="1"
attribute to override the original in chunk-code.xsl -->

</xsl:stylesheet>
--------------------------------------------------------------------

The following stylesheet file is imported by the above file.

custom-epub3-elements.xsl
--------------------------------------------------------------------
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:d="http://docbook.org/ns/docbook"
  exclude-result-prefixes="#default d"
  version="1.0">

<xsl:import href="http://cdn.docbook.org/release/xsl/current/xhtml5/docbook.xsl"/>
<xsl:include href="http://cdn.docbook.org/release/xsl/current/epub3/epub3-element-mods.xsl"/>

<!-- Add here any templates that change element format.  Any
such customized templates with a @match attribute must also
have a priority="1" attribute to override the original.  -->

<!-- Add here any templates that change element formatting.
That is, any templates not copied from chunk-common.xsl or
chunk-core.xsl.  Any customized templates with a @match
attribute must also have a priority="1" attribute to
override the original. -->

</xsl:stylesheet>
--------------------------------------------------------------------



EPUB metadata
========================
The info child of the document's root element is used
by the stylesheet to create EPUB metadata.  Note that
metadata is plain text, so element content is converted
to text using the XSL normalize-space() function.

Here is the current mapping of info elements to EPUB
metadata.  Any others are ignored for metadata, but
may appear on the EPUB HTML titlepage, depending on the
titlepage customization.

NOTE: the <dc:*> elements (not attributes of meta) duplicate
the meta elements for backwards compatibility, per the
EPUB3 specification.  They can be turned off with the 
$epub.include.optional.metadata.dc.elements parameter.

abstract
---------
The content must be converted to a text string for the
OPF metadata. The stylesheet converts only title, para,
formalpara, and simpara children in an abstract.  All other
child elements are ignored.  It puts any title first.
The OPF output appears as:

<meta property="dcterms:description">title: abstract text</meta>
<dc:description>title: abstract text</dc:description>


author
-------
If uses a personname child, then it applies the
DocBook XSL person.name template to arrange the name.
Otherwise processes org or orgname into the content.
Then it outputs:

<meta id="meta-creator1" property="dcterms:creator">Firstname Surname</meta>
<dc:creator id="pub-creator1">Firstname Surname</dc:creator>

If there are multiple authors, the number in the id attribute
is incremented each time.


authorgroup
-------------
Applies templates to all of its children.


bibliocoverage
---------------
<meta property="dcterms:coverage">bibliocoverage text</meta>
<dc:coverage>bibliocoverage text</dc:coverage>


biblioid
--------------
This usually has @class="isbn" for the ISBN number.  It is used
as the EPUB3 unique-identifier.  That isbn value
is also output as follows:

<meta id="meta-identifier" property="dcterms:identifier">urn:isbn:value</meta>
<dc:identifier id="pub-identifier">urn:isbn:value</dc:identifier>

A biblioid element with other class names are converted in a similar manner.


bibliorelation
----------------
<meta property="dcterms:relation">bibliorelation text</meta>
<dc:relation>bibliorelation text</dc:relation>


bibliosource
----------------
<meta property="dcterms:source">bibliosource text</meta>
<dc:source>bibliosource text</dc:source>


collab
------------
If a personname child is used, then it calls the
person.name template, otherwise is uses the orgname or
collabname text.

<meta property="dcterms:contributor">collab text</meta>
<dc:contributor>collab text</dc:contributor>


copyright
-------------
Arranges the copyright elements into a text string with
copyright symbol, dates, and holder, and then
generates:

<meta property="dcterms:right">Copyright text</meta>
<dc:right>Copyright text</dc:right>

Also, if there is no info/date element, then the copyright
year is used to generate:

<meta property="dcterms:date">year</meta>
<dc:date>year</dc:date>


corpauthor
------------
<meta id="meta-creator1" property="dcterms:creator">corpauthor text</meta>
<dc:creator id="pub-creator1">corpauthor text</dc:creator>


corpcredit
------------
<meta property="dcterms:contributor">corpcredit text</meta>
<dc:contributor>corpcredit text</dc:contributor>


date
-------------
<meta property="dcterms:date">date text</meta>
<dc:date>date text</dc:date>

See also: copyright.


editor
--------------
If a personname child is used, then it calls the
person.name template, otherwise is uses the orgname text.

An editor can be considered as either a creator (when there
is no author) or a contributor.  The stylesheet parameter
'editor.property' can be set to either 'creator' or
'contributor' (default) at runtime.  So the output is either:

<meta property="dcterms:contributor">editor text</meta>
<dc:contributor>editor text</dc:contributor>

or

<meta property="dcterms:creator">editor text</meta>
<dc:creator>editor text</dc:creator>


isbn, issn, etc.
-----------------
Handled like biblioid @class="isbn".


keyword
-----------
<meta property="dcterms:subject">keyword text</meta>
<dc:subject>keyword text</dc:subject>


keywordset
------------
Applies templates to its children.


othercredit
------------
Handled like collab.


pubdate 
------------
Handled like date.


publisher
--------------
Applies templates only to publishername.


publishername
---------------
<meta property="dcterms:publisher">publishername text</meta>
<dc:publisher>publishername text</dc:publisher>


subjectset
--------------
Applies templates to subject/subjecterm descendants.


subjectterm
------------------
<meta property="dcterms:subject">subjecterm text</meta>
<dc:subject>subjecterm text</dc:subject>