Opened 6 years ago

Last modified 7 days 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: yes 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 6 years ago.
DJango 1.5.2 EPub validation failure.

Download all attachments as: .zip

Change History (10)

Changed 6 years ago by mabdullah

DJango 1.5.2 EPub validation failure.

comment:1 Changed 6 years ago by Tim Graham

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 6 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 6 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 6 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 3 years 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 3 years ago by Daniel Roschka

Cc: danielroschka@… added

comment:7 Changed 15 months ago by Claude Paroz

https://github.com/sphinx-doc/sphinx/issues/5070 (issue with internal anchors) has just been fixed. After the 1.7.6 sphinx release is out and deployed on readthedocs, we may check the document validity again.

comment:8 Changed 10 days ago by Katie McLaughlin

readthedocs.org urls have moved since this ticket was filed, new URL: https://readthedocs.org/projects/django/downloads/

Tested the downloads for latest, stable, 2.2.x and 3.0x

They appear to load in ebook reviews (calibre, apple books)

The validator http://validator.idpf.org/ does still return errors, but they aren't breaking errors (from what I can tell):

6 x toc.ncx - Error while parsing file: different playOrder values for navPoint/navTarget/pageTarget that refer to same target
72 x *.svg - External entities are not allowed in EPUB v3 documents.
2639 x *.xhtml - Fragment identifier is not defined.

Two minor svg errors that might be important:

_images/django_unittest_classes_hierarchy.svg - Error while parsing file: element "dc:date" not allowed anywhere; expected the element end-tag or text
_images/triage_process.svg Error while parsing file: element "dc:date" not allowed anywhere; expected the element end-tag or text

Vote to close

comment:9 Changed 7 days ago by Carlton Gibson

Easy pickings: set

SVG

The SVG diagrams were generated using OmniGraffle. Latest versions still generate the invalid SVG. I've filed a bug report with them, which I'd guess they'd address, so we can update the files as-and-when.

In the meantime, the images look to view without problem. (In Apple Books, the background gradient on the unit test classes diagram is not rendered entirely perfectly, but it is so in Firefox and Safari, so I suspect that is Apple Books...)

Fragment Identifier

Re the two-thousand-odd Fragment identifier is not defined. errors, I think those should be (cough) straight-forward enough to fix.

The issue is in cross links:

genindex.xhtml:979 has:

        <li><a href="ref/templates/builtins.xhtml#std-templatefilter-addslashes">template filter</a>

But the destination is ref/templates/builtins.xhtml:1220, which has:

<span id="std:templatefilter-addslashes">...

std:templatefilter-addslashes is not std-templatefilter-addslashes.

Same with testing/topics/advanced.html:639 pointing to ref/settings.xhtml:553. There std-setting-TEST_SERIALIZE is not std:setting-TEST_SERIALIZE.

It looks like a different rule is just being applied to generate the url anchor fragments. (A fix there may just be finding an error in sphinx and reporting it.)
If we can solve that, then the vast majority of the output is eliminated.

From there, I suspect the remaining errors won't look so intimidating.

I'm going to mark this Easy pickings. It may take some detective work to pin down exactly the issue for the fragment identifiers (Is it something we can fix or is it a bug in Sphinx?) but I think it would be a good first issue if someone is willing to pick it up.

For me, downloading EPUBCheck to run locally was very helpful: https://github.com/w3c/epubcheck/releases
(It has a good README in the download but, $ java -jar epubcheck.jar django.epub was the essence of it.)

Vote to close

Yes, I kind of see that: the EPUB does work. But it's not optimal. The errors are leading to a lack of cross links (at least). If we could clear them up, I'd guess it would improve presentation... If someone is prepared to have a look, I think it's would be nice to have. (The TOC is not super helpful as presented in Apple Books at least. There's too much info there. I wonder if section content pages are possible... anyhow, for later.)

(For reference, I ran EPUB check on an EPUB from a quite large technical book publisher and they had 3 "resource isn't defined" type errors and then 250-ish Content file contains script which is not supported in EPUB v2 which I guess is progressive enhancement.)

Last edited 7 days ago by Carlton Gibson (previous) (diff)
Note: See TracTickets for help on using tickets.
Back to Top