diff options
Diffstat (limited to 'epub3/README')
| -rw-r--r-- | epub3/README | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/epub3/README b/epub3/README new file mode 100644 index 0000000..477e785 --- /dev/null +++ b/epub3/README @@ -0,0 +1,329 @@ +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> + |