#20935: ePub documentation not valid
-------------------------------------+-------------------------------------
Reporter: mabdullah | Owner: Fredrik
| Malmfors
Type: Bug | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Fredrik Malmfors):
This will be a long read, but in short, I managed to cut the error count
from 84 down to 1 (patch provided). While digging I also found some
interesting problems that are just as relevant to the html documentation,
as they are to the epub.
As Carlton suggested, I’ve been using Sphinx 2.0 branch (instead of any
official release, the 2.2.2 version released yesterday still gives the
errors in the thousands) along with Epubcheck version 4.2.2.
Initially, Epubcheck returned 84 errors, which is already significantly
less than before. The error(s) Carlton mentioned
{{{
ERROR(RSC-005):
../django/docs/_build/epub/Django.epub/_modules/django/contrib/auth.xhtml(76,47):
Error while parsing file:
}}}
is no longer present, and seems to have been resolved on Sphinx part.
Anyway, here I’ll go through the remaining errors one by one:
== Error reporting and Deploying Static Files
- 3 x ERROR(RSC-005):
django/docs/_build/epub/Django.epub/content.opf(621,32): Error while
parsing file: Itemref refers to the same manifest entry as a previous
itemref
- 6 x ERROR(RSC-005):
django/docs/_build/epub/Django.epub/toc.ncx(1949,52): Error while parsing
file: different playOrder values for navPoint/navTarget/pageTarget that
refer to same target
**Problem**
These errors occurs from the chapters Error reporting and Deploying Static
Files, appearing twice in the ToC. This is true for the html docs aswell,
not just the epub. In essence, the same chapters can be found both under “
How-to guides“, and under “How-to guides / Deploying Django”. This is seen
clearly in the screenshot below (from the website):
[[Image(ToC_error_reporting)]]
This violates the ToC correlation with the reading order. It also leads to
problems in the epub since (if going through reading order) only the first
reference is being rendered, and the second one is missing.
**Fix**
I removed the second reference. I beleive Error reporting and Deploying
Static Files can stand on their own outside of deployment. Also, the
deployment checklist already refers to both of these at least once. Please
let me know if you have another suggestion.
== SVGs (temporarily fixed)
- 2 * ERROR(OPF-073):
django/docs/_build/epub/Django.epub/_images/triage_process.svg(2,98):
External identifiers must not appear in the document type declaration.
- 71 * ERROR(HTM-003):
django/docs/_build/epub/Django.epub/_images/triage_process.svg(60,31):
External entities are not allowed in EPUB v3 documents. External entity
declaration found: %svg-model.mod.
**Problem**
These errors are caused by the <!DOCTYPE> tag in SVGs. Neither sketch nor
illustrator includes !DOCTYPE nowadays in SVGs. It also seems like SVG 2.0
does not care about !DOCTYPE at all.
**Fix**
I have removed the <!DOCTYPE> in both SVGs for now. Hopefully !DOCTYPE
won’t be included in exports from future versions of OmniGirrafe.
== Duplicate cover-page in spine (Unresolved)
- 1 * ERROR(RSC-005):
django/docs/_build/epub/Django.epub/content.opf(980,43): Error while
parsing file: Itemref refers to the same manifest entry as a previous
itemref
**Problem**
The epub build contains a file content.opf, where items are added to the
manifest. There is also is a <spine>, with references to the items in the
manifest.
The item corresponding to the cover-page, epub-1, gets added (again) to
the end of the spine where it should not. This breaks EPUB 3.2 rules since
items must only be refered to once.
The first entry is controlled by the
{{{
epub_cover = ('', 'epub-cover.html')
}}}
in conf.py. This one is nessecary for the epub-cover to be displayed at
all.
Why it get’s added a second time to the spine at the end, I haven’t yet
found an explaination for.
**Fix**
None. This does not seem to be a critical issue though.
== Unnecessary reference to search page
- 1 * ERROR(RSC-007):
django/docs/_build/epub/Django.epub/intro/whatsnext.xhtml(34,62):
Referenced resource 'search.xhtml' could not be found in the EPUB.
**Problem**
In intro/whatsnext.html, we have the following lines:
- so finding what you need can sometimes be tricky. A few good places to
start
- are the :ref:`search` and the :ref:`genindex`.
The :ref:`search` creates a link straight to the search page.
''HTML''
When pressing the link we come to an empty page with the text “No search
query given”. This is because the search.html only displays the results of
the given search from the search bar.
''Epub''
When klicking the ‘search’ link, nothing happens. Even more reason to
remove it.
**Fix**
I updated the text to instead refer to buildin search functionality.
== ToC ordering (proposed solutions / maybe)
1.
- WARNING(NAV-011): django/docs/_build/epub/Django.epub/nav.xhtml(442,81):
'toc' nav must be in reading order; link target 'topics/class-based-
views/index.xhtml#basic-examples' is before the previous link's target in
spine order.
- INFO(INF-001): django/docs/_build/epub/Django.epub/nav.xhtml(442,81):
The previous rule is under review and its severity may change in a future
release. See the discussion at https://github.com/w3c/publ-epub-
revision/issues/1283
The reason for this warning is that the ToC refers to the sections of
topics/class-based-views/index AFTER the included content tree. This makes
for a slightly counter intuitive ToC.
[B,C,D]
This is likely not an issue if reading everyting on the index page before
going to the other pages, but it makes the ToC feel counter intuitive.
And, following the ToC ordering indicates that you should read the
mentioned chapters, and THEN go back again to the index file.
2.
- WARNING(NAV-011):
django/docs/_build/epub/Django.epub/nav.xhtml(1377,77): 'toc' nav must be
in reading order; link target 'ref/class-based-
views/index.xhtml#specification' is before the previous link's target in
spine order.
- INFO(INF-001): django/docs/_build/epub/Django.epub/nav.xhtml(1377,77):
The previous rule is under review and its severity may change in a future
release. See the discussion at https://github.com/w3c/publ-epub-
revision/issues/1283
Similar to the one above, except in /ref.
3.
WARNING(NAV-011): django/docs/_build/epub/Django.epub/nav.xhtml(1444,59):
'toc' nav must be in reading order; link target
'ref/contrib/index.xhtml#admin' is before the previous link's target in
spine order.
INFO(INF-001): django/docs/_build/epub/Django.epub/nav.xhtml(1444,59): The
previous rule is under review and its severity may change in a future
release. See the discussion at https://github.com/w3c/publ-epub-
revision/issues/1283
This sections includes first a local ToC to all the contribs, then, still
in the index file, a breif description of each. This might make sense when
reading, but it makes for a duplicate looking ToC.
[Img]
Proposed solutions for these warnings:
1. Move the inline sections in the index file to to its own file, and add
it to the local ToC. This would solve the ToC issues, though it would
require rearranging documentation.
2. Find a way to exclude the inline sections from the ToC. This would make
the warnings go away, and would have a ToC that corresponds to reading
order. Though, I have not yet found a clean way to do so.
== ToC depth issue in iBooks
A last note on the ToC issue in iBooks. iBooks (at least on macOS) can
only deal with a ToC depth of 2. It’s also not collapsable. This gives a
ToC that is both far to long, and is also not consistent, since sections
on the same level can appear on different levels in iBooks and vice versa.
By setting
{{{
epub_tocdepth = 2
}}}
instead of 3 in conf.py, the ToC in iBooks is both consistent and of good
length.
The problem with this approach is the loss of detail in Calibre, that can
handle a ToC depth of 3, and where levels are collapsable. I’m leaving
this for now, since not everyone uses iBooks. I’m not sure about which
epub-readers are most common.
--
Ticket URL: <https://code.djangoproject.com/ticket/20935#comment:14>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/067.f8414f116bc670cd83c2da27ca1c69ee%40djangoproject.com.
