mirror of
https://git.rtems.org/rtems-source-builder
synced 2024-10-09 07:15:10 +08:00
211 lines
7.0 KiB
Plaintext
211 lines
7.0 KiB
Plaintext
AsciiDoc EPUB Notes
|
|
===================
|
|
|
|
|
|
Restrictions
|
|
------------
|
|
- If the date format of the DocBook 'data' element is not formatted like
|
|
`YYYY[-MM[-DD]]` you will get an error like the following one when
|
|
validating with `epubcheck(1)`:
|
|
|
|
ERROR: doc/article.epub/OEBPS/content.opf(6): date value 'Dec 2003'
|
|
is not valid, YYYY[-MM[-DD]] expected
|
|
|
|
- Navigation headers are suppressed by `docbook-xsl/epub.xsl` (see
|
|
<<X3,bug report>>).
|
|
|
|
|
|
DocBook XSL Stylesheets related limitations and bugs
|
|
----------------------------------------------------
|
|
|
|
=== epub: toc.section.depth parameter ignored
|
|
https://sourceforge.net/tracker/?func=detail&aid=3043393&group_id=21935&atid=373747
|
|
|
|
epub outputs include every section in the table of contents regardless of the
|
|
toc.section.depth XSL Stylesheets parameter
|
|
(http://docbook.sourceforge.net/release/xsl/current/doc/html/toc.section.depth.html).
|
|
This behavior is specific to epub (xhtml and fo outputs honor
|
|
toc.section.depth).
|
|
|
|
Environment: DocBook XSL 1.75.2; Xubuntu 10.04
|
|
|
|
Also epub/docbook.xsl has written a hard-coded illegal dtb:depth value of -1
|
|
into the toc.ncx navigation control file:
|
|
|
|
<ncx:meta name="dtb:depth" content="-1"/>
|
|
|
|
Shouldn't it be a positive integer equal to the depth navPoint nesting in the
|
|
navMap element (see
|
|
http://www.niso.org/workrooms/daisy/Z39-86-2005.html#NavMeta)? Though epubcheck 1.05 doesn't flag it as invalid -- are they both wrong?
|
|
|
|
|
|
[[X1]]
|
|
=== epub: untitled DocBook sidebar emits invalid XHTML
|
|
https://sourceforge.net/tracker/index.php?func=detail&aid=2840768&group_id=21935&atid=373747
|
|
|
|
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).
|
|
|
|
Environment: DocBook XSL 1.75.2; Xubuntu 10.04
|
|
|
|
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:
|
|
|
|
<sidebar>
|
|
<simpara>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</simpara>
|
|
</sidebar>
|
|
|
|
Generates this EPUB XHTML:
|
|
|
|
<div class="sidebar"><p class="title"><b/></p><p>Lorem ipsum dolor
|
|
sit amet, consectetuer adipiscing elit.</p></div>
|
|
|
|
This problem is not picked up by either the epubcheck or the W3C
|
|
validators.
|
|
|
|
The problem does not occur generating XHTML which emits the following
|
|
for the above example:
|
|
|
|
<div class="sidebar"><p class="title"><b></b></p><p>Lorem ipsum
|
|
dolor sit amet, consectetuer adipiscing elit.</p></div>
|
|
|
|
|
|
=== epub: Unreferenced callout icons in OPF
|
|
NOTE: A workaround for this problem was added in `a2x(1)` version
|
|
8.6.5.
|
|
|
|
https://sourceforge.net/tracker/?func=detail&aid=2854075&group_id=21935&atid=373747
|
|
|
|
Environment: DocBook XSL 1.75.2; Xubuntu 8.04
|
|
|
|
When callouts are used in a document and callout graphics are disabled
|
|
(callout.graphics=0) the generated 'contents.opf' 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:
|
|
|
|
image file OEBPS/images/icons/callouts/1.png is missing
|
|
|
|
It appears that epub is adding the icons to the OPF without
|
|
first checking the callout.graphics parameter.
|
|
|
|
|
|
=== epub: Table grids not generated
|
|
https://sourceforge.net/tracker/?func=detail&aid=2849647&group_id=21935&atid=373747
|
|
|
|
Environment: DocBook XSL 1.75.2; Xubuntu 8.04
|
|
|
|
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:
|
|
|
|
epub DocBook XSL generates:
|
|
|
|
<td style="text-align: left" valign="top">
|
|
|
|
i.e. epub is not generating CSS borders (same for generated th elements).
|
|
|
|
Compare this with the (correct) xhtml DocBook XSL generates the correct border
|
|
styles:
|
|
|
|
<td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">
|
|
|
|
|
|
|
|
=== epub: htmltoc is not generated
|
|
https://sourceforge.net/tracker/?func=detail&aid=2849686&group_id=21935&atid=373747
|
|
|
|
Environment: DocBook XSL 1.75.2; Xubuntu 8.04
|
|
|
|
If DocBook XSL TOC generation is specified the generated
|
|
'contents.opf' contains an 'htmltoc' element but the referenced TOC file
|
|
is not generated by DocBook XSL. For example the contents.opf contains:
|
|
|
|
<item id="htmltoc" media-type="application/xhtml+xml" href="ar01-toc.html"/>
|
|
|
|
but the actual TOC file `OEBPS/ar01-toc.html` is missing and epubcheck
|
|
generates validation errors like:
|
|
|
|
ERROR: doc/article.epub: OPS/XHTML file OEBPS/ar01-toc.html is missing
|
|
|
|
|
|
=== epub: leading dot in directory name error
|
|
https://sourceforge.net/tracker/?func=detail&aid=2849683&group_id=21935&atid=373747
|
|
|
|
Environment: DocBook XSL 1.75.2; Xubuntu 8.04
|
|
|
|
Specifying paths with a leading dot causes problems, for example:
|
|
|
|
<xsl:param name="html.stylesheet" select="'./docbook-xsl.css'"/>
|
|
|
|
This generates validation errors like:
|
|
|
|
ERROR: article.epub/OEBPS/index.html(4):
|
|
'OEBPS/./docbook-xsl.css': referenced resource missing in the package
|
|
|
|
The file is in the archive at the correct location, just doesn't
|
|
seem to like './' in the path name -- the path needs to be normalized
|
|
before being written to the contents.opf.
|
|
|
|
It's not just the validator, the file is missing when the EPUB is viewed
|
|
(in bookworm).
|
|
|
|
This works fine:
|
|
|
|
<xsl:param name="html.stylesheet" select="'docbook-xsl.css'"/>
|
|
|
|
|
|
[[X2]]
|
|
=== epub: admonition icon images missing from contents.opf
|
|
NOTE: A workaround for this problem was added in `a2x(1)` version
|
|
8.6.5.
|
|
|
|
https://sourceforge.net/tracker/?func=detail&aid=2849681&group_id=21935&atid=373747
|
|
|
|
Environment: DocBook XSL 1.75.2; Xubuntu 8.04
|
|
|
|
When admonition icons are specified epubcheck generates validation
|
|
errors like:
|
|
|
|
ERROR: article.epub/OEBPS/index.html(4):
|
|
'OEBPS/images/icons/note.png': referenced resource exists,
|
|
but not declared in the OPF file
|
|
|
|
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.
|
|
|
|
|
|
[[X3]]
|
|
=== Table width attribute validation error
|
|
https://sourceforge.net/tracker/?func=detail&aid=2848734&group_id=21935&atid=373747
|
|
|
|
Environment: DocBook XSL 1.75.2; Xubuntu 8.04
|
|
|
|
I get the following validation errors when navigation headers are in
|
|
included in the generated XHTML:
|
|
|
|
ERROR: article.epub/OEBPS/ix01.html(3): attribute "width" not allowed
|
|
at this point; ignored
|
|
|
|
This is because DocBook XSL has emitted invalid XHTML 1.1: tables
|
|
using the 'width' element are generated automatically in navigation
|
|
headers.
|
|
|
|
Though, admittedly, navigation is redundant if you're reading with an
|
|
EPUB reader. Suppress by setting the suppress.navigation param to 1.
|
|
|
|
Is this a DocBook XSL bug?
|
|
|
|
|
|
The Linux zip(1) command
|
|
------------------------
|
|
If you use the Linux `zip(1)` command to update or create EPUB files
|
|
you must use the `-X`, `--no-extra` command-line option, if you do not
|
|
the platform dependent extra fields will confuse `epubcheck(1)` which
|
|
will emit errors like ``extra field length for first filename must be
|
|
0, but was 28''.
|