1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 10.0.0a2" />
<title>AsciiDoc EPUB Notes</title>
<link rel="stylesheet" href="./asciidoc.css" type="text/css" />
<link rel="stylesheet" href="./layout2.css" type="text/css" />
<script type="text/javascript" src="./asciidoc.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install();
/*]]>*/
</script>
</head>
<body style="max-width:70em">
<div id="layout-menu-box">
<div id="layout-menu">
<div>»<a href="index.html">Home</a></div>
<div>»<a href="userguide.html">User Guide</a></div>
<div>»<a href="INSTALL.html">Installation</a></div>
<div>»<a href="faq.html">FAQ</a></div>
<div>»<a href="manpage.html">asciidoc(1)</a></div>
<div>»<a href="a2x.1.html">a2x(1)</a></div>
<div>»<a href="asciidocapi.html">API</a></div>
<div>»<a href="plugins.html">Plugins</a></div>
<div>»<a href="http://powerman.name/doc/asciidoc">Cheatsheet</a></div>
<div>»<a href="testasciidoc.html">Tests</a></div>
<div>»<a href="CHANGELOG.html">ChangeLog</a></div>
<div>»<a href="support.html">Support</a></div>
<div id="page-source">»<a href="epub-notes.txt">Page Source</a></div>
</div>
</div>
<div id="layout-content-box">
<div id="layout-banner">
<div id="layout-title">AsciiDoc</div>
<div id="layout-description">Text based document generation</div>
</div>
<div id="layout-content">
<div id="header">
<h1>AsciiDoc EPUB Notes</h1>
</div>
<div id="content">
<div class="sect1">
<h2 id="_restrictions">Restrictions</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
If the date format of the DocBook <em>data</em> element is not formatted like
<code>YYYY[-MM[-DD]]</code> you will get an error like the following one when
validating with <code>epubcheck(1)</code>:
</p>
<div class="literalblock">
<div class="content">
<pre><code>ERROR: doc/article.epub/OEBPS/content.opf(6): date value 'Dec 2003'
is not valid, YYYY[-MM[-DD]] expected</code></pre>
</div></div>
</li>
<li>
<p>
Navigation headers are suppressed by <code>docbook-xsl/epub.xsl</code> (see
<a href="#X3">bug report</a>).
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_docbook_xsl_stylesheets_related_limitations_and_bugs">DocBook XSL Stylesheets related limitations and bugs</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_epub_toc_section_depth_parameter_ignored">epub: toc.section.depth parameter ignored</h3>
<div class="paragraph"><p><a href="https://sourceforge.net/tracker/?func=detail&aid=3043393&group_id=21935&atid=373747">https://sourceforge.net/tracker/?func=detail&aid=3043393&group_id=21935&atid=373747</a></p></div>
<div class="paragraph"><p>epub outputs include every section in the table of contents regardless of the
toc.section.depth XSL Stylesheets parameter
(<a href="https://cdn.docbook.org/release/xsl/snapshot/doc/fo/toc.section.depth.html">https://cdn.docbook.org/release/xsl/snapshot/doc/fo/toc.section.depth.html</a>).
This behavior is specific to epub (xhtml and fo outputs honor
toc.section.depth).</p></div>
<div class="paragraph"><p>Environment: DocBook XSL 1.75.2; Xubuntu 10.04</p></div>
<div class="paragraph"><p>Also epub/docbook.xsl has written a hard-coded illegal dtb:depth value of -1
into the toc.ncx navigation control file:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><ncx:meta name="dtb:depth" content="-1"/></code></pre>
</div></div>
<div class="paragraph"><p>Shouldn’t it be a positive integer equal to the depth navPoint nesting in the
navMap element? Though epubcheck 1.05 doesn’t flag it as invalid — are they both wrong?</p></div>
</div>
<div class="sect2">
<h3 id="X1">epub: untitled DocBook sidebar emits invalid XHTML</h3>
<div class="paragraph"><p><a href="https://sourceforge.net/tracker/index.php?func=detail&aid=2840768&group_id=21935&atid=373747">https://sourceforge.net/tracker/index.php?func=detail&aid=2840768&group_id=21935&atid=373747</a></p></div>
<div class="paragraph"><p>I get the same problem, but is confined to EPUB outputs (not XHTML)
and results in the sidebar and all subsequent text on the page
displayed in bold text in both Firefox 3.6.8 and Google Chrome
5.0.375.125 (I haven’t checked other browsers).</p></div>
<div class="paragraph"><p>Environment: DocBook XSL 1.75.2; Xubuntu 10.04</p></div>
<div class="paragraph"><p>If a DocBook sidebar element does not have a title then the emitted
title is (I haven’t checked other browsers).
set to <b/> instead of <b></b>, for example this DocBook markup:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><sidebar>
<simpara>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</simpara>
</sidebar></code></pre>
</div></div>
<div class="paragraph"><p>Generates this EPUB XHTML:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><div class="sidebar"><p class="title"><b/></p><p>Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.</p></div></code></pre>
</div></div>
<div class="paragraph"><p>This problem is not picked up by either the epubcheck or the W3C
validators.</p></div>
<div class="paragraph"><p>The problem does not occur generating XHTML which emits the following
for the above example:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><div class="sidebar"><p class="title"><b></b></p><p>Lorem ipsum
dolor sit amet, consectetuer adipiscing elit.</p></div></code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_epub_unreferenced_callout_icons_in_opf">epub: Unreferenced callout icons in OPF</h3>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">A workaround for this problem was added in <code>a2x(1)</code> version
8.6.5.</td>
</tr></table>
</div>
<div class="paragraph"><p><a href="https://sourceforge.net/tracker/?func=detail&aid=2854075&group_id=21935&atid=373747">https://sourceforge.net/tracker/?func=detail&aid=2854075&group_id=21935&atid=373747</a></p></div>
<div class="paragraph"><p>Environment: DocBook XSL 1.75.2; Xubuntu 8.04</p></div>
<div class="paragraph"><p>When callouts are used in a document and callout graphics are disabled
(callout.graphics=0) the generated <em>contents.opf</em> still contains
references to all the callout icons even though none are not
referenced in the generated XHTML content. This results in 10
epubcheck validation errors like:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>image file OEBPS/images/icons/callouts/1.png is missing</code></pre>
</div></div>
<div class="paragraph"><p>It appears that epub is adding the icons to the OPF without
first checking the callout.graphics parameter.</p></div>
</div>
<div class="sect2">
<h3 id="_epub_table_grids_not_generated">epub: Table grids not generated</h3>
<div class="paragraph"><p><a href="https://sourceforge.net/tracker/?func=detail&aid=2849647&group_id=21935&atid=373747">https://sourceforge.net/tracker/?func=detail&aid=2849647&group_id=21935&atid=373747</a></p></div>
<div class="paragraph"><p>Environment: DocBook XSL 1.75.2; Xubuntu 8.04</p></div>
<div class="paragraph"><p>DocBook XSL epub does not appear to process the DocBook table element rowsep
and colsep attributes — table grids are not displayed. The DocBook
<table rowsep="1" colsep="1"> results in:</p></div>
<div class="paragraph"><p>epub DocBook XSL generates:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><td style="text-align: left" valign="top"></code></pre>
</div></div>
<div class="paragraph"><p>i.e. epub is not generating CSS borders (same for generated th elements).</p></div>
<div class="paragraph"><p>Compare this with the (correct) xhtml DocBook XSL generates the correct border
styles:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"></code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_epub_htmltoc_is_not_generated">epub: htmltoc is not generated</h3>
<div class="paragraph"><p><a href="https://sourceforge.net/tracker/?func=detail&aid=2849686&group_id=21935&atid=373747">https://sourceforge.net/tracker/?func=detail&aid=2849686&group_id=21935&atid=373747</a></p></div>
<div class="paragraph"><p>Environment: DocBook XSL 1.75.2; Xubuntu 8.04</p></div>
<div class="paragraph"><p>If DocBook XSL TOC generation is specified the generated
<em>contents.opf</em> contains an <em>htmltoc</em> element but the referenced TOC file
is not generated by DocBook XSL. For example the contents.opf contains:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><item id="htmltoc" media-type="application/xhtml+xml" href="ar01-toc.html"/></code></pre>
</div></div>
<div class="paragraph"><p>but the actual TOC file <code>OEBPS/ar01-toc.html</code> is missing and epubcheck
generates validation errors like:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>ERROR: doc/article.epub: OPS/XHTML file OEBPS/ar01-toc.html is missing</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_epub_leading_dot_in_directory_name_error">epub: leading dot in directory name error</h3>
<div class="paragraph"><p><a href="https://sourceforge.net/tracker/?func=detail&aid=2849683&group_id=21935&atid=373747">https://sourceforge.net/tracker/?func=detail&aid=2849683&group_id=21935&atid=373747</a></p></div>
<div class="paragraph"><p>Environment: DocBook XSL 1.75.2; Xubuntu 8.04</p></div>
<div class="paragraph"><p>Specifying paths with a leading dot causes problems, for example:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><xsl:param name="html.stylesheet" select="'./docbook-xsl.css'"/></code></pre>
</div></div>
<div class="paragraph"><p>This generates validation errors like:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>ERROR: article.epub/OEBPS/index.html(4):
'OEBPS/./docbook-xsl.css': referenced resource missing in the package</code></pre>
</div></div>
<div class="paragraph"><p>The file is in the archive at the correct location, just doesn’t
seem to like <em>./</em> in the path name — the path needs to be normalized
before being written to the contents.opf.</p></div>
<div class="paragraph"><p>It’s not just the validator, the file is missing when the EPUB is viewed
(in bookworm).</p></div>
<div class="paragraph"><p>This works fine:</p></div>
<div class="literalblock">
<div class="content">
<pre><code><xsl:param name="html.stylesheet" select="'docbook-xsl.css'"/></code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="X2">epub: admonition icon images missing from contents.opf</h3>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">A workaround for this problem was added in <code>a2x(1)</code> version
8.6.5.</td>
</tr></table>
</div>
<div class="paragraph"><p><a href="https://sourceforge.net/tracker/?func=detail&aid=2849681&group_id=21935&atid=373747">https://sourceforge.net/tracker/?func=detail&aid=2849681&group_id=21935&atid=373747</a></p></div>
<div class="paragraph"><p>Environment: DocBook XSL 1.75.2; Xubuntu 8.04</p></div>
<div class="paragraph"><p>When admonition icons are specified epubcheck generates validation
errors like:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>ERROR: article.epub/OEBPS/index.html(4):
'OEBPS/images/icons/note.png': referenced resource exists,
but not declared in the OPF file</code></pre>
</div></div>
<div class="paragraph"><p>i.e. The admonition icon is in the EPUB file but DocBook XSL has not
been added to the content.opf manifest. Compare this with callout icons
which are processed correctly.</p></div>
</div>
<div class="sect2">
<h3 id="X3">Table width attribute validation error</h3>
<div class="paragraph"><p><a href="https://sourceforge.net/tracker/?func=detail&aid=2848734&group_id=21935&atid=373747">https://sourceforge.net/tracker/?func=detail&aid=2848734&group_id=21935&atid=373747</a></p></div>
<div class="paragraph"><p>Environment: DocBook XSL 1.75.2; Xubuntu 8.04</p></div>
<div class="paragraph"><p>I get the following validation errors when navigation headers are in
included in the generated XHTML:</p></div>
<div class="literalblock">
<div class="content">
<pre><code>ERROR: article.epub/OEBPS/ix01.html(3): attribute "width" not allowed
at this point; ignored</code></pre>
</div></div>
<div class="paragraph"><p>This is because DocBook XSL has emitted invalid XHTML 1.1: tables
using the <em>width</em> element are generated automatically in navigation
headers.</p></div>
<div class="paragraph"><p>Though, admittedly, navigation is redundant if you’re reading with an
EPUB reader. Suppress by setting the suppress.navigation param to 1.</p></div>
<div class="paragraph"><p>Is this a DocBook XSL bug?</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_the_linux_zip_1_command">The Linux zip(1) command</h2>
<div class="sectionbody">
<div class="paragraph"><p>If you use the Linux <code>zip(1)</code> command to update or create EPUB files
you must use the <code>-X</code>, <code>--no-extra</code> command-line option, if you do not
the platform dependent extra fields will confuse <code>epubcheck(1)</code> which
will emit errors like “extra field length for first filename must be
0, but was 28”.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Version 9.1.0<br />
Last updated 2021-02-12 04:05:21 UTC<br />
AsciiDoc is a trademark of the Eclipse Foundation, Inc.
</div>
<div id="footer-badges">
<a href="https://validator.w3.org/check?uri=referer">
<img style="border:0;width:88px;height:31px"
src="https://www.w3.org/Icons/valid-xhtml11-blue"
alt="Valid XHTML 1.1" height="31" width="88" />
</a>
<a href="https://jigsaw.w3.org/css-validator/">
<img style="border:0;width:88px;height:31px"
src="https://jigsaw.w3.org/css-validator/images/vcss-blue"
alt="Valid CSS!" />
</a>
</div>
</div>
</div>
</div>
</body>
</html>
|
