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 |
|
---|