[b1a51ac1] | 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 | Usage
|
---|
| 20 | -----------
|
---|
| 21 | The general process for creating an EPUB3 ebook is:
|
---|
| 22 |
|
---|
| 23 | 1. Generate chunked XHTML5 content that validates against
|
---|
| 24 | the EPUB3 schemas, and generate the EPUB3 package
|
---|
| 25 | files.
|
---|
| 26 |
|
---|
| 27 | 2. Copy any image files into the output directory.
|
---|
| 28 |
|
---|
| 29 | 3. Run a zip command to create an .epub file.
|
---|
| 30 |
|
---|
| 31 | 4. Validate the .epub file.
|
---|
| 32 |
|
---|
| 33 |
|
---|
| 34 | Following are the steps in more detail.
|
---|
| 35 |
|
---|
| 36 | 1. Create the XHTML5 files.
|
---|
| 37 | -----------------------------
|
---|
| 38 |
|
---|
| 39 | The first step is handled by these stylesheets.
|
---|
| 40 | To generate EPUB3-compatible XHTML5 files,
|
---|
| 41 | use one of the following stylesheets as you would any
|
---|
| 42 | other DocBook XSL stylesheet:
|
---|
| 43 |
|
---|
| 44 | epub3/chunk.xsl - Chunked output.
|
---|
| 45 | epub3/profile-chunk.xsl - Profiled chunk output.
|
---|
| 46 |
|
---|
| 47 | Although the stylesheet directory contains a docbook.xsl
|
---|
| 48 | stylesheet for single file output, that is not useful for
|
---|
| 49 | generated EPUB3.
|
---|
| 50 |
|
---|
| 51 | You should set the $base.dir stylesheet param to the
|
---|
| 52 | subdirectory that will contain the .xhtml files and
|
---|
| 53 | the epub package files. Here is an example using xsltproc:
|
---|
| 54 |
|
---|
| 55 | xsltproc \
|
---|
| 56 | --stringparam base.dir ebook1/OEBPS/ \
|
---|
| 57 | epub3/chunk.xsl \
|
---|
| 58 | mybook.xml
|
---|
| 59 |
|
---|
| 60 | After processing a document with this setting, you should find
|
---|
| 61 | the following output:
|
---|
| 62 |
|
---|
| 63 | ebook1/mimetype - required mimetype file.
|
---|
| 64 | ebook1/META-INF/container.xml - required container file
|
---|
| 65 | ebook1/OEBPS/package.opf - required package file
|
---|
| 66 | ebook1/OEBPS/toc.ncx - optional NCX file for backwards compatibility
|
---|
| 67 | ebook1/OEBPS/docbook-epub.css - CSS file
|
---|
| 68 | ebook1/OEBPS/*.xhtml - The chunked content files.
|
---|
| 69 |
|
---|
| 70 |
|
---|
| 71 | 2. Copy image files
|
---|
| 72 | ---------------------------
|
---|
| 73 |
|
---|
| 74 | Manually copy any image files used in the document
|
---|
| 75 | into the corresponding locations in the $base.dir
|
---|
| 76 | directory. For example, if your document contains:
|
---|
| 77 |
|
---|
| 78 | <imagedata fileref="images/caution.png"/>
|
---|
| 79 |
|
---|
| 80 | In this example base.dir, you would copy the file to:
|
---|
| 81 |
|
---|
| 82 | ebook1/OEBPS/images/caution.png
|
---|
| 83 |
|
---|
| 84 | You can get a list of image files from the manifest file
|
---|
| 85 | named ebook1/OEBPS/package.opf that is created by the
|
---|
| 86 | stylesheet. It includes references to image files for
|
---|
| 87 | callouts and admonitions if they are used in the output.
|
---|
| 88 | Note that the header and footer images are turned off for
|
---|
| 89 | EPUB3 output.
|
---|
| 90 |
|
---|
| 91 |
|
---|
| 92 | 3. Create the epub3 file.
|
---|
| 93 | -----------------------------
|
---|
| 94 | Change to the directory containing the base.dir (ebook1
|
---|
| 95 | in this example), and run the following zip command to
|
---|
| 96 | create the epub file:
|
---|
| 97 |
|
---|
| 98 | zip -r -X mybook.epub mimetype META-INF OEBPS
|
---|
| 99 |
|
---|
| 100 | The -r option means recursively include all directories.
|
---|
| 101 | The -X option excludes extra file attributes (required by epub3).
|
---|
| 102 | The "mybook.epub" in this example is the output file.
|
---|
| 103 | The other three arguments must appear in this order.
|
---|
| 104 |
|
---|
| 105 |
|
---|
| 106 | 4. Validating with epubcheck 3
|
---|
| 107 | -----------------------------------
|
---|
| 108 |
|
---|
| 109 | There is a java program that can be used to check an
|
---|
| 110 | epub3 file for conformance. It is currently available
|
---|
| 111 | from this website:
|
---|
| 112 |
|
---|
| 113 | http://code.google.com/p/epubcheck/wiki/EPUBCheck30
|
---|
| 114 |
|
---|
| 115 | That website provides a download link, and information on
|
---|
| 116 | how to run the command.
|
---|
| 117 |
|
---|
| 118 |
|
---|
| 119 | Testing with EPUB readers
|
---|
| 120 | ----------------------------
|
---|
| 121 | The EPUB3 standard is not yet widely supported. The output of
|
---|
| 122 | these stylesheets has been tested in the following readers:
|
---|
| 123 |
|
---|
| 124 | Apple iBooks on an iPod and iPad.
|
---|
| 125 | - Handles videodata and audiodata.
|
---|
| 126 | - Does not format MathML yet.
|
---|
| 127 | - Handles SVG.
|
---|
| 128 |
|
---|
| 129 | Firefox browser with the EPUBReader version 1.4.10 add-on.
|
---|
| 130 | - Formats MathML nicely.
|
---|
| 131 | - Does not handle videodata or audiodata yet.
|
---|
| 132 | - Handles SVG.
|
---|
| 133 |
|
---|
| 134 | Ibis EPUB3 preview version
|
---|
| 135 | - Does not format MathML yet.
|
---|
| 136 | - Does not handle videodata or audiodata yet.
|
---|
| 137 | - Handles SVG with external viewer.
|
---|
| 138 |
|
---|
| 139 |
|
---|
| 140 | EPUB metadata
|
---|
| 141 | ========================
|
---|
| 142 | The info child of the document's root element is used
|
---|
| 143 | by the stylesheet to create EPUB metadata. Note that
|
---|
| 144 | metadata is plain text, so element content is converted
|
---|
| 145 | to text using the XSL normalize-space() function.
|
---|
| 146 |
|
---|
| 147 | Here is the current mapping of info elements to EPUB
|
---|
| 148 | metadata. Any others are ignored for metadata, but
|
---|
| 149 | may appear on the EPUB HTML titlepage, depending on the
|
---|
| 150 | titlepage customization.
|
---|
| 151 |
|
---|
| 152 | NOTE: the <dc:*> elements (not attributes of meta) duplicate
|
---|
| 153 | the meta elements for backwards compatibility, per the
|
---|
| 154 | EPUB3 specification. They can be turned off with the
|
---|
| 155 | $epub.include.optional.metadata.dc.elements parameter.
|
---|
| 156 |
|
---|
| 157 | abstract
|
---|
| 158 | ---------
|
---|
| 159 | The content must be converted to a text string for the
|
---|
| 160 | OPF metadata. The stylesheet converts only title, para,
|
---|
| 161 | formalpara, and simpara children in an abstract. All other
|
---|
| 162 | child elements are ignored. It puts any title first.
|
---|
| 163 | The OPF output appears as:
|
---|
| 164 |
|
---|
| 165 | <meta property="dcterms:description">title: abstract text</meta>
|
---|
| 166 | <dc:description>title: abstract text</dc:description>
|
---|
| 167 |
|
---|
| 168 |
|
---|
| 169 | author
|
---|
| 170 | -------
|
---|
| 171 | If uses a personname child, then it applies the
|
---|
| 172 | DocBook XSL person.name template to arrange the name.
|
---|
| 173 | Otherwise processes org or orgname into the content.
|
---|
| 174 | Then it outputs:
|
---|
| 175 |
|
---|
| 176 | <meta id="meta-creator1" property="dcterms:creator">Firstname Surname</meta>
|
---|
| 177 | <dc:creator id="pub-creator1">Firstname Surname</dc:creator>
|
---|
| 178 |
|
---|
| 179 | If there are multiple authors, the number in the id attribute
|
---|
| 180 | is incremented each time.
|
---|
| 181 |
|
---|
| 182 |
|
---|
| 183 | authorgroup
|
---|
| 184 | -------------
|
---|
| 185 | Applies templates to all of its children.
|
---|
| 186 |
|
---|
| 187 |
|
---|
| 188 | bibliocoverage
|
---|
| 189 | ---------------
|
---|
| 190 | <meta property="dcterms:coverage">bibliocoverage text</meta>
|
---|
| 191 | <dc:coverage>bibliocoverage text</dc:coverage>
|
---|
| 192 |
|
---|
| 193 |
|
---|
| 194 | biblioid
|
---|
| 195 | --------------
|
---|
| 196 | This usually has @class="isbn" for the ISBN number. It is used
|
---|
| 197 | as the EPUB3 unique-identifier. That isbn value
|
---|
| 198 | is also output as follows:
|
---|
| 199 |
|
---|
| 200 | <meta id="meta-identifier" property="dcterms:identifier">urn:isbn:value</meta>
|
---|
| 201 | <dc:identifier id="pub-identifier">urn:isbn:value</dc:identifier>
|
---|
| 202 |
|
---|
| 203 | A biblioid element with other class names are converted in a similar manner.
|
---|
| 204 |
|
---|
| 205 |
|
---|
| 206 | bibliorelation
|
---|
| 207 | ----------------
|
---|
| 208 | <meta property="dcterms:relation">bibliorelation text</meta>
|
---|
| 209 | <dc:relation>bibliorelation text</dc:relation>
|
---|
| 210 |
|
---|
| 211 |
|
---|
| 212 | bibliosource
|
---|
| 213 | ----------------
|
---|
| 214 | <meta property="dcterms:source">bibliosource text</meta>
|
---|
| 215 | <dc:source>bibliosource text</dc:source>
|
---|
| 216 |
|
---|
| 217 |
|
---|
| 218 | collab
|
---|
| 219 | ------------
|
---|
| 220 | If a personname child is used, then it calls the
|
---|
| 221 | person.name template, otherwise is uses the orgname or
|
---|
| 222 | collabname text.
|
---|
| 223 |
|
---|
| 224 | <meta property="dcterms:contributor">collab text</meta>
|
---|
| 225 | <dc:contributor>collab text</dc:contributor>
|
---|
| 226 |
|
---|
| 227 |
|
---|
| 228 | copyright
|
---|
| 229 | -------------
|
---|
| 230 | Arranges the copyright elements into a text string with
|
---|
| 231 | copyright symbol, dates, and holder, and then
|
---|
| 232 | generates:
|
---|
| 233 |
|
---|
| 234 | <meta property="dcterms:right">Copyright text</meta>
|
---|
| 235 | <dc:right>Copyright text</dc:right>
|
---|
| 236 |
|
---|
| 237 | Also, if there is no info/date element, then the copyright
|
---|
| 238 | year is used to generate:
|
---|
| 239 |
|
---|
| 240 | <meta property="dcterms:date">year</meta>
|
---|
| 241 | <dc:date>year</dc:date>
|
---|
| 242 |
|
---|
| 243 |
|
---|
| 244 | corpauthor
|
---|
| 245 | ------------
|
---|
| 246 | <meta id="meta-creator1" property="dcterms:creator">corpauthor text</meta>
|
---|
| 247 | <dc:creator id="pub-creator1">corpauthor text</dc:creator>
|
---|
| 248 |
|
---|
| 249 |
|
---|
| 250 | corpcredit
|
---|
| 251 | ------------
|
---|
| 252 | <meta property="dcterms:contributor">corpcredit text</meta>
|
---|
| 253 | <dc:contributor>corpcredit text</dc:contributor>
|
---|
| 254 |
|
---|
| 255 |
|
---|
| 256 | date
|
---|
| 257 | -------------
|
---|
| 258 | <meta property="dcterms:date">date text</meta>
|
---|
| 259 | <dc:date>date text</dc:date>
|
---|
| 260 |
|
---|
| 261 | See also: copyright.
|
---|
| 262 |
|
---|
| 263 |
|
---|
| 264 | editor
|
---|
| 265 | --------------
|
---|
| 266 | If a personname child is used, then it calls the
|
---|
| 267 | person.name template, otherwise is uses the orgname text.
|
---|
| 268 |
|
---|
| 269 | An editor can be considered as either a creator (when there
|
---|
| 270 | is no author) or a contributor. The stylesheet parameter
|
---|
| 271 | 'editor.property' can be set to either 'creator' or
|
---|
| 272 | 'contributor' (default) at runtime. So the output is either:
|
---|
| 273 |
|
---|
| 274 | <meta property="dcterms:contributor">editor text</meta>
|
---|
| 275 | <dc:contributor>editor text</dc:contributor>
|
---|
| 276 |
|
---|
| 277 | or
|
---|
| 278 |
|
---|
| 279 | <meta property="dcterms:creator">editor text</meta>
|
---|
| 280 | <dc:creator>editor text</dc:creator>
|
---|
| 281 |
|
---|
| 282 |
|
---|
| 283 | isbn, issn, etc.
|
---|
| 284 | -----------------
|
---|
| 285 | Handled like biblioid @class="isbn".
|
---|
| 286 |
|
---|
| 287 |
|
---|
| 288 | keyword
|
---|
| 289 | -----------
|
---|
| 290 | <meta property="dcterms:subject">keyword text</meta>
|
---|
| 291 | <dc:subject>keyword text</dc:subject>
|
---|
| 292 |
|
---|
| 293 |
|
---|
| 294 | keywordset
|
---|
| 295 | ------------
|
---|
| 296 | Applies templates to its children.
|
---|
| 297 |
|
---|
| 298 |
|
---|
| 299 | othercredit
|
---|
| 300 | ------------
|
---|
| 301 | Handled like collab.
|
---|
| 302 |
|
---|
| 303 |
|
---|
| 304 | pubdate
|
---|
| 305 | ------------
|
---|
| 306 | Handled like date.
|
---|
| 307 |
|
---|
| 308 |
|
---|
| 309 | publisher
|
---|
| 310 | --------------
|
---|
| 311 | Applies templates only to publishername.
|
---|
| 312 |
|
---|
| 313 |
|
---|
| 314 | publishername
|
---|
| 315 | ---------------
|
---|
| 316 | <meta property="dcterms:publisher">publishername text</meta>
|
---|
| 317 | <dc:publisher>publishername text</dc:publisher>
|
---|
| 318 |
|
---|
| 319 |
|
---|
| 320 | subjectset
|
---|
| 321 | --------------
|
---|
| 322 | Applies templates to subject/subjecterm descendants.
|
---|
| 323 |
|
---|
| 324 |
|
---|
| 325 | subjectterm
|
---|
| 326 | ------------------
|
---|
| 327 | <meta property="dcterms:subject">subjecterm text</meta>
|
---|
| 328 | <dc:subject>subjecterm text</dc:subject>
|
---|
| 329 |
|
---|