Opened 3 years ago

Last modified 6 months ago

#20935 new Bug

ePub documentation not valid

Reported by: mabdullah Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: danielroschka@… Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

There is an error in the generated epub that prevents it from opening. Running the epub though the validator also reports an error.
http://validator.idpf.org/

Attachments (1)

Screen Shot 2013-08-19 at 12.10.05 PM.png (231.3 KB) - added by mabdullah 3 years ago.
DJango 1.5.2 EPub validation failure.

Download all attachments as: .zip

Change History (7)

Changed 3 years ago by mabdullah

DJango 1.5.2 EPub validation failure.

comment:1 Changed 3 years ago by Tim Graham

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Resolution: fixed
Status: newclosed
Summary: EPub error.EPub error with 1.5.x documentation

Retriggering the build at https://readthedocs.org/builds/django/ seems to have fixed this.

comment:2 Changed 3 years ago by michal@…

Resolution: fixed
Status: closednew
Summary: EPub error with 1.5.x documentationePub documentation not valid
Version: 1.5master

Validation for lastest ePub (1.7a2) at http://validator.idpf.org/ fails.
Import to Google Books fails.
File can not be open in some Android eBook readers.

comment:3 Changed 3 years ago by Tim Graham

Triage Stage: UnreviewedAccepted

I've checked both the version from readthedocs and a locally generated one using make epub and I see hundreds of validation warnings in both cases.

comment:4 Changed 3 years ago by afuna

There are 3000+ validation warnings/errors generated by epubcheck. The good news is that these fall into only a dozen or so categories:

1) 1 times ERROR: value of attribute "href" is invalid; must be a URI
2) 1 times ERROR: attribute "id" not allowed here; expected attribute "charset", "defer", "src" or "xml:space"
3) 2 times ERROR: element "form" not allowed anywhere; expected the element end-tag, text or element "a", "abbr", "acronym", "address", "applet", "b", "bdo", "big", "blockquote", "br", "cite", "code", "del", "dfn", "div", "dl", "em", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "i", "iframe", "img", "ins", "kbd", "map", "noscript", "ns:svg", "object", "ol", "p", "pre", "q", "samp", "script", "small", "span", "strong", "sub", "sup", "table", "tt", "ul" or "var" (with xmlns:ns="http://www.w3.org/2000/svg")
4) 2 times ERROR: attribute "start" not allowed here; expected attribute "dir", "id", "lang", "style", "title" or "xml:lang"
5) 3 times ERROR: hyperlink to non-standard resource <...> of type <...>
6) 3 times ERROR: element "dc:date" not allowed anywhere; expected the element end-tag or text
7) 7 times ERROR: <...>: referenced resource missing in the package.
8) 678 times ERROR: value of attribute "id" is invalid; must be an XML name without colons
9) 2400 times ERROR: <...>: fragment identifier is not defined in <...>
10) 5 times HINT: Link attribute with no value
11) 1 times WARNING: use of non-registered URI scheme type in href: irc://irc.freenode.net/django-dev
12) 4 times WARNING: hyperlink to resource outside spine <...>
13) 8 times WARNING: use of non-registered URI scheme type in href: irc://irc.freenode.net/django
----
3115 total

comment:5 Changed 6 months ago by Daniel Roschka

I looked a bit into this issue and it seems to be mostly related to the template in use. So by further customizing the template we should be able to fix these warnings.

The djangodocs-epub theme inherits from epub which inherits from basic. Interestingly most of these issues are already present in upstreams epub theme, as it inherits from basic which is just an HTML-theme and doesn't know about epub at all.

Simply extending templates from basic and overwriting blocks doesn't work for all warnings, as some of them are outside of blocks and even if they are in blocks it means mostly replicating the existing logic of these blocks, so the cleanest solution seems to be to build an epub theme, which doesn't inherit from any other theme. That would also allow us to make better use of epub-specific features, but of course is no quick and easy undertaking.

comment:6 Changed 6 months ago by Daniel Roschka

Cc: danielroschka@… added
Note: See TracTickets for help on using tickets.
Back to Top