diff options
Diffstat (limited to 'doc/asciidoc/examples/website/epub-notes.txt')
| -rw-r--r-- | doc/asciidoc/examples/website/epub-notes.txt | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/doc/asciidoc/examples/website/epub-notes.txt b/doc/asciidoc/examples/website/epub-notes.txt new file mode 100644 index 0000000..0b942ba --- /dev/null +++ b/doc/asciidoc/examples/website/epub-notes.txt @@ -0,0 +1,210 @@ +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''. |