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 and admonition icons are suppressed by
  `docbook-xsl/epub.xsl`
  (see <<X2,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
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
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.


=== 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
------------------------
The Linux zip(1) command does not seem to be able to generate EPUB
compatible zip files -- the 'mimetype' file contents start at 0x3b,
not the required 0x38 and the validator generates this error:

  $ zip -0 test.epub mimetype 
    adding: mimetype (stored 0%)

  $ hexdump -C test.epub
  00000000  50 4b 03 04 0a 00 00 00  00 00 99 50 21 3b 6f 61  |PK.........P!;oa|
  00000010  ab 2c 14 00 00 00 14 00  00 00 08 00 15 00 6d 69  |.,............mi|
  00000020  6d 65 74 79 70 65 55 54  09 00 03 01 49 9c 4a 01  |metypeUT....I.J.|
  00000030  49 9c 4a 55 78 04 00 e9  03 e9 03 61 70 70 6c 69  |I.JUx......appli|
  00000040  63 61 74 69 6f 6e 2f 65  70 75 62 2b 7a 69 70 50  |cation/epub+zipP|
  00000050  4b 01 02 17 03 0a 00 00  00 00 00 99 50 21 3b 6f  |K...........P!;o|
  00000060  61 ab 2c 14 00 00 00 14  00 00 00 08 00 0d 00 00  |a.,.............|
  00000070  00 00 00 00 00 00 00 a4  81 00 00 00 00 6d 69 6d  |.............mim|
  00000080  65 74 79 70 65 55 54 05  00 03 01 49 9c 4a 55 78  |etypeUT....I.JUx|
  00000090  00 00 50 4b 05 06 00 00  00 00 01 00 01 00 43 00  |..PK..........C.|
  000000a0  00 00 4f 00 00 00 00 00                           |..O.....|
  000000a8

  $ epubcheck test.epub 
  Epubcheck Version 1.0.3

  ERROR: test.epub: mimetype contains wrong type (application/epub+zip expected)
  ERROR: test.epub: META-INF/container.xml is missing

If there's some zip(1) command-line option I'm missing I'd be keen to
know about it.

