Several fixes for EPUB footnotes #4491
Conversation
|
It looks like there are only reader tests for EPUB at the moment? |
epub:type="footnotes" on footnotes section in EPUB308172db to
a04b51c
Compare
|
It's great to see someone taking a look at the EPUB output and how it's rendered on a kindle. The existing behavior of the HTML (and consequently EPUB) writer puts the footnotes in an
P.S. I had assumed EPUB writer tests would be in |
|
@mb21 I also posted on pandoc-discuss to explain the changes in more detail, some of your questions are answered there. I'll try to answer the others later today. |
|
Maybe let's try to keep the discussion to one place (I guess this pull request since we're already here)... P.S. I guess it would make most sense if the position/display of the backlink could be overridden using CSS... |
|
Yes, I'll merge that info back into the PR (just haven't done it yet) |
|
@Porges, would it be possible that you could upload sample documents (for both ePub2 and ePub3) so that changes could be checked before they are merged? |
1. Backlinks must be at the start of the footnote or it causes Kindle software to mangle the display of footnotes (several footnotes are run together, and soft footnote links do not work as pop-overs). 2. Also, Amazon "strongly recommends" the use of the `aside` element. This is also recommended by Apple. So when using EPUB3 or HTML5, use `aside` elements instead of a list. Due to part 1, we have numbered backlinks at the start of footnotes, so I also changed EPUB2 to wrap with `div` (instead of `aside`) to remove the redundant numbering, and to be consistent with EPUB3 output.
|
Updated original comment with more context from my pandoc-discuss message. |
Yes, this alone fixes the problem, and no, I don't know why. My best guess is that it's looking for the back-link as a marker for where the footnote starts and then reading onward from there, but that's not based on much evidence...
Yes, I had thought putting What I was trying to do was to fix the initial problem with minimal impact on other facilities. Adding support to Aside: (😉) One thing I did realize while making this change is that the way that Pandoc currently outputs footnotes in EPUB should really be called "endnotes". DPUB-ARIA is very explicit about this (note that
So the "holistic" solution to footnotes might be to add
|
|
Okay, to further complicate matters, the EPUB 3 Accessibility Guidelines are now deprecated (since I linked them from my PR!) and the new site is the DAISY Accessible Publishing Knowledge Base, which now has different examples for footnotes and endnotes! The guidelines are quite clear now:
For footnotes:
For endnotes:
So the new "holistic" plan is something like: add
However, this doesn't fix Kindle display for endnotes which have back-links at the end. I'll try experimenting some more and see if I can come up with some HTML which makes Kindles work again without having the back-link at the start for the endnote. |
|
Sounds promising... just a few notes:
Actually, we've started using extensions in different input and output, e.g. we could do
Does this also depend on how you convert the ePUB to |
No, the problem exists with either method.
This is true, but it would be nice to have it work in both cases. |
|
When I get time/energy I'm going to try implementing the approach outlined in the last comment. |
|
@Porges thanks for your work on this. I wonder if we could start with something simple. The guidelines say:
According to this, it's fine to put the footnotes at the end of the section in lists, which is what we currently do. So, all we really need to do is change the backlink to precede the text, and make sure all the links and cross-references and containing sections conform to guidelines, right? We could think about doing fancier stuff later, and it might interact with a current PR adding an Endnote type. But for now I'd prefer to do the simplest thing that would work. |
|
Closing this because I think the design & discussion has moved on @jgm? |
|
I was keeping this open because I thought we should at least do the following:
If you'd prefer, though, we could make a new issue with this. |
|
@jgm, sure, feel free to take the code I had if needed. I'm just trying to clear up my old PRs and don't have time to contribute to this at the moment. |
With the current EPUB output (after converting with Kindle previewer and copying to Kindle...), the pop-over footnotes will often have problems:
Here's an example showing the footnotes running together:
I believe that both of these problems are caused by having the footnote back-link at the end of the footnote. Changing the link to be at the start of the footnote fixes this. (I don't know why this causes problems with the Kindle software.)
Here's the same footnote after making this change:
Putting the '↩' back-link at the start of the footnote doesn't make much sense, so I changed it to a numeric back-link instead. This was based on the examples given in both the Amazon Kindle Publishing Guidelines and the EPUB3 Accessibility Guidelines.
However, making the back-link numeric meant that the ordered list that Pandoc outputs for footnotes would duplicate the numbering provided in the back-link. To avoid this (and implement something suggested on #1995), I've also changed the footnote output to use
<aside>(on HTML5/EPUB3) or fall back to<div>(on HTML4/EPUB2). Using asides is something that is "strongly recommended" by Amazon's guidelines, and is what Apple recommends in the iBooks Asset Guide. (There is an additional feature provided by iBooks which is that the asides are hidden from the main flow of the text.) So we seem to be able to solve two issues at once 🙂I've also checked the new output in Calibre, Edge, Kindle Previewer, and iBooks to confirm that it works as expected.