mirror of
https://git.linuxfromscratch.org/lfs.git
synced 2025-08-01 17:15:13 +01:00
15c7d39533
git-svn-id: http://svn.linuxfromscratch.org/LFS/trunk/BOOK@10355 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689
330 lines
8.7 KiB
Plaintext
330 lines
8.7 KiB
Plaintext
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.
|
|
|
|
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/OEBPS/ \
|
|
epub3/chunk.xsl \
|
|
mybook.xml
|
|
|
|
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.
|
|
|
|
|
|
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>
|
|
|