#20935: ePub documentation not valid
-------------------------------+------------------------------------
Reporter: mabdullah | Owner: nobody
Type: Bug | Status: new
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
-------------------------------+------------------------------------
Changes (by Carlton Gibson):
* easy: 0 => 1
Comment:
=== SVG
The SVG diagrams were generated using OmniGraffle. 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''.)
--
Ticket URL: <https://code.djangoproject.com/ticket/20935#comment:9>
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 django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/067.dd1addf212d8bd422681b3b18ceb2906%40djangoproject.com.
