Epub output bugs: images, tables, lists, title page, covers

[Anne Gentle]

Bugs found in testing epub format at the Austin Hackathon 11-11-11:

Tiny images, example Img 3.1 in the CF Dev Guide.
Doc change history table missing.
Note icon missing (would guess Warning/Important icons also missing but no Warnings exist in the guides).
Code example shading - non-existant I think.
Title page missing (on iPad ebook reader)
No cover.

[Tom Fifield (fifieldt)]

Hi,

Is this bug still valid?

[Anne Gentle (annegentle)]

Yes, similar to 980396 it is a maven plugin bug. Eventually we can move it to another location once that tool moves under CI.

[Tom Fifield (fifieldt)]

Moving up in priority - as we have books that we pretty much need to have in this format, the fact we can't do epub properly is now a bug rather than a wishlist feature.

[Tom Fifield (fifieldt)]

generate-epub doesn't work at the moment due to

* use of xpointer
* missing cover

  file:/home/fifieldt/temp/clouddocs-maven-plugin/openstack-manuals/doc/install-guide/target/docbkx/images/cloud/openstack-cover.st: /home/fifieldt/temp/clouddocs-maven-plugin/openstack-manuals/doc/install-guide/target/docbkx/images/cloud/openstack-cover.st (No such file or directory)

[Tom Fifield (fifieldt)]

our pom.xmls often specify:

<pubdate/>

which breaks the cover

[Tom Fifield (fifieldt)]

Got the install guide to build.

To update the report from 2011

* No cover
* Table of contents has only one level of numbering
* No note/warning icons or boxes
* No images
* No code example shading
* No doc change history table (page exists, but no table below the text)
* Procedures poorly spaced
* No table support

* Title is there
* List of tables/figures is there
* Glossary works
* External links work
* Internal links work
* Table of contents at start of chapter works
* Spacing between chapters is good
* Spacing between sections is generally good

[Tom Fifield (fifieldt)]

note/warning admonitions don't work because the generated files refer to PNG files, but the code only moves SVG files into target/images/

[Tom Fifield (fifieldt)]

Images don't work at all because they are not included in the epub

[Tom Fifield (fifieldt)]

PNGs are not created because the rasterize() function is commented out. It looks like it hasn't been completed.

[Tom Fifield (fifieldt)]

If you change the hardcoding, the rasterize function does work.

However, images will still not be loaded, as they use hardcoded paths,

[Tom Fifield (fifieldt)]

* images for admonitions have hardcoded paths (eg file:/home..../target../images/...png)
* regular docbook included images have relative paths, but they look for images a directory up

eg

target/docbkx/epub/bk-openstack-install-guide/ch12s04.html: minimal installation:</p><p><span class="inlinemediaobject"><img src="../figures/swift_install_arch.png" alt="Example of Object Storage installation architecture"/></span></p></div></body></html>

[Tom Fifield (fifieldt)]

https://review.openstack.org/#/c/107825/

[Tom Fifield (fifieldt)]

With the above patch merged, status is now:

* No cover
* Table of contents has only one level of numbering
* No code example shading
* No doc change history table (page exists, but no table below the text)
* Procedures poorly spaced
* No table support

Fixed things:
* Title is there
* List of tables/figures is there
* Glossary works
* External links work
* Internal links work
* Table of contents at start of chapter works
* Spacing between chapters is good
* Spacing between sections is generally good

* No images - fixed
* No note/warning icons or boxes - fixed

[Tom Fifield (fifieldt)]

This bug should be re-targetted to the RST docs, given XML is eventually EoL, I think?

[Anne Gentle (annegentle)]

You might as well close this one as it's history would just confuse people, and then the "task" is "test epub/mobi output from Sphinx." Then the bugs would be against upstream Sphinx but with luck it'll work just fine.