lib/docbook/epub3/README

   1 DocBook stylesheets for EPUB 3 output
   2 =============================================
   3
   4 This directory contains XSL stylesheets
   5 for generating EPUB3 output from DocBook content.
   6 For more information on EPUB3, see:
   7
   8 http://idpf.org/epub/30
   9
  10 These EPUB3 stylesheets are a customization layer on
  11 top of the xhtml5/ stylesheets in this distribution, which
  12 are in turn a customization layer on top of the
  13 xhtml/ stylesheets in this distribution.
  14 Using a customization layer enables the EPUB3
  15 stylesheets to inherit all the features of the
  16 XHTML stylesheets while making the minimum changes
  17 for them to produce valid EPUB3.
  18
  19 If you need to customize the epub3 stylesheet, see the section
  20 below titled "Customizing the epub3 stylesheet".
  21
  22 Usage
  23 -----------
  24 The general process for creating an EPUB3 ebook is:
  25
  26 1.  Generate chunked XHTML5 content that validates against
  27 the EPUB3 schemas, and generate the EPUB3 package
  28 files.
  29
  30 2.  Copy any image files into the output directory.
  31
  32 3.  Run a zip command to create an .epub file.
  33
  34 4.  Validate the .epub file.
  35
  36
  37 Following are the steps in more detail.
  38
  39 1.  Create the XHTML5 files.
  40 -----------------------------
  41
  42 The first step is handled by these stylesheets.
  43 To generate EPUB3-compatible XHTML5 files,
  44 use one of the following stylesheets as you would any
  45 other DocBook XSL stylesheet:
  46
  47 epub3/chunk.xsl           - Chunked output.
  48 epub3/profile-chunk.xsl   - Profiled chunk output.
  49
  50 Although the stylesheet directory contains a docbook.xsl
  51 stylesheet for single file output, that is not useful for
  52 generated EPUB3.
  53
  54 You should set the $base.dir stylesheet param to the
  55 subdirectory that will contain the .xhtml files and
  56 the epub package files.  Here is an example using xsltproc:
  57
  58 xsltproc \
  59   --stringparam base.dir ebook1/  \
  60   epub3/chunk.xsl \
  61   mybook.xml
  62
  63 Make sure you don't include the OEBPS directory in base.dir.
  64
  65 After processing a document with this setting, you should find
  66 the following output:
  67
  68 ebook1/mimetype                - required mimetype file.
  69 ebook1/META-INF/container.xml  - required container file
  70 ebook1/OEBPS/package.opf       - required package file
  71 ebook1/OEBPS/toc.ncx           - optional NCX file for backwards compatibility
  72 ebook1/OEBPS/docbook-epub.css  - CSS file
  73 ebook1/OEBPS/*.xhtml           - The chunked content files.
  74
  75
  76 2.  Copy image files
  77 ---------------------------
  78
  79 Manually copy any image files used in the document
  80 into the corresponding locations in the $base.dir
  81 directory.  For example, if your document contains:
  82
  83   <imagedata fileref="images/caution.png"/>
  84
  85 In this example base.dir, you would copy the file to:
  86
  87   ebook1/OEBPS/images/caution.png
  88
  89 You can get a list of image files from the manifest file
  90 named ebook1/OEBPS/package.opf that is created by the
  91 stylesheet.  It includes references to image files for
  92 callouts and admonitions if they are used in the output.
  93 Note that the header and footer images are turned off for
  94 EPUB3 output.
  95
  96
  97 3.  Create the epub3 file.
  98 -----------------------------
  99 Change to the directory containing the base.dir (ebook1
 100 in this example), and run the following zip command to
 101 create the epub file:
 102
 103 zip -r -X mybook.epub mimetype META-INF OEBPS
 104
 105 The -r option means recursively include all directories.
 106 The -X option excludes extra file attributes (required by epub3).
 107 The "mybook.epub" in this example is the output file.
 108 The other three arguments must appear in this order.
 109
 110
 111 4.  Validating with epubcheck 3
 112 -----------------------------------
 113
 114 There is a java program that can be used to check an
 115 epub3 file for conformance.  It is currently available
 116 from this website:
 117
 118   http://code.google.com/p/epubcheck/wiki/EPUBCheck30
 119
 120 That website provides a download link, and information on
 121 how to run the command.
 122
 123
 124 Testing with EPUB readers
 125 ----------------------------
 126 The EPUB3 standard is not yet widely supported.  The output of
 127 these stylesheets has been tested in the following readers:
 128
 129 Apple iBooks on an iPod and iPad.
 130    - Handles videodata and audiodata.
 131    - Does not format MathML yet.
 132    - Handles SVG.
 133
 134 Firefox browser with the EPUBReader version 1.4.10 add-on.
 135    - Formats MathML nicely.
 136    - Does not handle videodata or audiodata yet.
 137    - Handles SVG.
 138
 139 Ibis EPUB3 preview version
 140    - Does not format MathML yet.
 141    - Does not handle videodata or audiodata yet.
 142    - Handles SVG with external viewer.
 143
 144
 145 Customizing the epub3 stylesheet
 146 ---------------------------------
 147 As with all DocBook stylesheets that generate chunked output, a
 148 customization requires two files: one for chunking behavior and
 149 one for element formatting.  Most people only need to customize
 150 element formatting, but you still need the two files to keep the
 151 proper import precedence.  See this doc for details about this
 152 issue:
 153
 154    http://www.sagehill.net/docbookxsl/ChunkingCustomization.html
 155
 156 Here is an example of the chunking stylesheet, which is the one you
 157 apply to your document when processing:
 158
 159 custom-epub3-chunk.xsl
 160 --------------------------------------------------------------------
 161 <?xml version="1.0"?>
 162 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 163                 xmlns:d="http://docbook.org/ns/docbook"
 164                 version="1.0"
 165                 exclude-result-prefixes="d">
 166
 167 <!-- Import the element customization module, shown below -->
 168 <xsl:import href="custom-epub3-elements.xsl"/>
 169
 170 <!-- import stock DocBook XSL file; use a catalog for local files-->
 171 <xsl:import href="http://cdn.docbook.org/release/xsl/current/xhtml/chunk-common.xsl"/>
 172
 173 <!-- include (not import) stock DocBook XSL file; use a catalog for local files-->
 174 <xsl:include href="http://cdn.docbook.org/release/xsl/current/xhtml/chunk-code.xsl"/>
 175
 176 <!-- include (not import) stock DocBook XSL file; use a catalog for local files-->
 177 <xsl:include href="http://cdn.docbook.org/release/xsl/current/epub3/epub3-chunk-mods.xsl"/>
 178
 179 <!-- Add here any templates that change chunking behavior.
 180 That is, any templates copied from chunk-common.xsl or
 181 chunk-core.xsl and modified.  Any such customized templates
 182 with a @match attribute must also have a priority="1"
 183 attribute to override the original in chunk-code.xsl -->
 184
 185 </xsl:stylesheet>
 186 --------------------------------------------------------------------
 187
 188 The following stylesheet file is imported by the above file.
 189
 190 custom-epub3-elements.xsl
 191 --------------------------------------------------------------------
 192 <?xml version="1.0" encoding="utf-8"?>
 193 <xsl:stylesheet
 194   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 195   xmlns="http://www.w3.org/1999/xhtml"
 196   xmlns:d="http://docbook.org/ns/docbook"
 197   exclude-result-prefixes="#default d"
 198   version="1.0">
 199
 200 <xsl:import href="http://cdn.docbook.org/release/xsl/current/xhtml5/docbook.xsl"/>
 201 <xsl:include href="http://cdn.docbook.org/release/xsl/current/epub3/epub3-element-mods.xsl"/>
 202
 203 <!-- Add here any templates that change element format.  Any
 204 such customized templates with a @match attribute must also
 205 have a priority="1" attribute to override the original.  -->
 206
 207 <!-- Add here any templates that change element formatting.
 208 That is, any templates not copied from chunk-common.xsl or
 209 chunk-core.xsl.  Any customized templates with a @match
 210 attribute must also have a priority="1" attribute to
 211 override the original. -->
 212
 213 </xsl:stylesheet>
 214 --------------------------------------------------------------------
 215
 216
 217
 218 EPUB metadata
 219 ========================
 220 The info child of the document's root element is used
 221 by the stylesheet to create EPUB metadata.  Note that
 222 metadata is plain text, so element content is converted
 223 to text using the XSL normalize-space() function.
 224
 225 Here is the current mapping of info elements to EPUB
 226 metadata.  Any others are ignored for metadata, but
 227 may appear on the EPUB HTML titlepage, depending on the
 228 titlepage customization.
 229
 230 NOTE: the <dc:*> elements (not attributes of meta) duplicate
 231 the meta elements for backwards compatibility, per the
 232 EPUB3 specification.  They can be turned off with the
 233 $epub.include.optional.metadata.dc.elements parameter.
 234
 235 abstract
 236 ---------
 237 The content must be converted to a text string for the
 238 OPF metadata. The stylesheet converts only title, para,
 239 formalpara, and simpara children in an abstract.  All other
 240 child elements are ignored.  It puts any title first.
 241 The OPF output appears as:
 242
 243 <meta property="dcterms:description">title: abstract text</meta>
 244 <dc:description>title: abstract text</dc:description>
 245
 246
 247 author
 248 -------
 249 If uses a personname child, then it applies the
 250 DocBook XSL person.name template to arrange the name.
 251 Otherwise processes org or orgname into the content.
 252 Then it outputs:
 253
 254 <meta id="meta-creator1" property="dcterms:creator">Firstname Surname</meta>
 255 <dc:creator id="pub-creator1">Firstname Surname</dc:creator>
 256
 257 If there are multiple authors, the number in the id attribute
 258 is incremented each time.
 259
 260
 261 authorgroup
 262 -------------
 263 Applies templates to all of its children.
 264
 265
 266 bibliocoverage
 267 ---------------
 268 <meta property="dcterms:coverage">bibliocoverage text</meta>
 269 <dc:coverage>bibliocoverage text</dc:coverage>
 270
 271
 272 biblioid
 273 --------------
 274 This usually has @class="isbn" for the ISBN number.  It is used
 275 as the EPUB3 unique-identifier.  That isbn value
 276 is also output as follows:
 277
 278 <meta id="meta-identifier" property="dcterms:identifier">urn:isbn:value</meta>
 279 <dc:identifier id="pub-identifier">urn:isbn:value</dc:identifier>
 280
 281 A biblioid element with other class names are converted in a similar manner.
 282
 283
 284 bibliorelation
 285 ----------------
 286 <meta property="dcterms:relation">bibliorelation text</meta>
 287 <dc:relation>bibliorelation text</dc:relation>
 288
 289
 290 bibliosource
 291 ----------------
 292 <meta property="dcterms:source">bibliosource text</meta>
 293 <dc:source>bibliosource text</dc:source>
 294
 295
 296 collab
 297 ------------
 298 If a personname child is used, then it calls the
 299 person.name template, otherwise is uses the orgname or
 300 collabname text.
 301
 302 <meta property="dcterms:contributor">collab text</meta>
 303 <dc:contributor>collab text</dc:contributor>
 304
 305
 306 copyright
 307 -------------
 308 Arranges the copyright elements into a text string with
 309 copyright symbol, dates, and holder, and then
 310 generates:
 311
 312 <meta property="dcterms:right">Copyright text</meta>
 313 <dc:right>Copyright text</dc:right>
 314
 315 Also, if there is no info/date element, then the copyright
 316 year is used to generate:
 317
 318 <meta property="dcterms:date">year</meta>
 319 <dc:date>year</dc:date>
 320
 321
 322 corpauthor
 323 ------------
 324 <meta id="meta-creator1" property="dcterms:creator">corpauthor text</meta>
 325 <dc:creator id="pub-creator1">corpauthor text</dc:creator>
 326
 327
 328 corpcredit
 329 ------------
 330 <meta property="dcterms:contributor">corpcredit text</meta>
 331 <dc:contributor>corpcredit text</dc:contributor>
 332
 333
 334 date
 335 -------------
 336 <meta property="dcterms:date">date text</meta>
 337 <dc:date>date text</dc:date>
 338
 339 See also: copyright.
 340
 341
 342 editor
 343 --------------
 344 If a personname child is used, then it calls the
 345 person.name template, otherwise is uses the orgname text.
 346
 347 An editor can be considered as either a creator (when there
 348 is no author) or a contributor.  The stylesheet parameter
 349 'editor.property' can be set to either 'creator' or
 350 'contributor' (default) at runtime.  So the output is either:
 351
 352 <meta property="dcterms:contributor">editor text</meta>
 353 <dc:contributor>editor text</dc:contributor>
 354
 355 or
 356
 357 <meta property="dcterms:creator">editor text</meta>
 358 <dc:creator>editor text</dc:creator>
 359
 360
 361 isbn, issn, etc.
 362 -----------------
 363 Handled like biblioid @class="isbn".
 364
 365
 366 keyword
 367 -----------
 368 <meta property="dcterms:subject">keyword text</meta>
 369 <dc:subject>keyword text</dc:subject>
 370
 371
 372 keywordset
 373 ------------
 374 Applies templates to its children.
 375
 376
 377 othercredit
 378 ------------
 379 Handled like collab.
 380
 381
 382 pubdate
 383 ------------
 384 Handled like date.
 385
 386
 387 publisher
 388 --------------
 389 Applies templates only to publishername.
 390
 391
 392 publishername
 393 ---------------
 394 <meta property="dcterms:publisher">publishername text</meta>
 395 <dc:publisher>publishername text</dc:publisher>
 396
 397
 398 subjectset
 399 --------------
 400 Applies templates to subject/subjecterm descendants.
 401
 402
 403 subjectterm
 404 ------------------
 405 <meta property="dcterms:subject">subjecterm text</meta>
 406 <dc:subject>subjecterm text</dc:subject>
 407