Several fixes for EPUB footnotes

[Porges]

With the current EPUB output (after converting with Kindle previewer and copying to Kindle...), the pop-over footnotes will often have problems:

1. Several footnotes run together and appear as one when clicking on a footnote.
2. Some footnotes do not work at all with pop-over and the link will jump you directly to the footnote section.

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.

[Porges]

It looks like there are only reader tests for EPUB at the moment?

[mb21]

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 ol in a section at the end of the document, which makes perfect sense for a document to be printed, or rendered without javascript or fancy on-hover/on-click CSS. As such, and also for backwards-compatibility, I guess we should at least preserve an option to keep the old behavior. I also totally agree with adding epub:type="footnotes". Then there are two changes which you mention that might be independent of each other?

• Moving the backlink to the front: does this alone fix the kindle-problem of mangling several footnotes together? If so, do you have a guess to why? Because naively I would expect the human reader to want to encounter the backlink after having read the footnotes, not before (i.e. how does this affect the rendering in other epub readers?)
• Using an aside for footnotes seems to make sense if the aside is placed in the body text as well, not at the end. (Maybe you can link to Kindle/Apple recommendations?) Placing the footnotes in an aside in the middle of the text flow might make sense as an option, in addition to the existing way. The new way might be toggled with the inline_notes extension, which currently only the markdown reader uses, but the HTML writer could make use of it as well. (Ah yes, or indeed better the --reference-location option...?)

P.S. I had assumed EPUB writer tests would be in /test/epub/ (e.g. `-f native formatting.native -o formatting.epub) but seeing that your pull request doesn't fail tests maybe they're not properly called in the test suite...?

[Porges]

@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.

[mb21]

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...

[Porges]

Yes, I'll merge that info back into the PR (just haven't done it yet)

[ousia]

@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?

[Porges]

Yes, I also need to rebase as #4489 was fixed by c997f11 so is no longer needed in this PR.

[Porges]

Updated original comment with more context from my pandoc-discuss message.

[Porges]

Moving the backlink to the front: does this alone fix the kindle-problem of mangling several footnotes together? If so, do you have a guess to why? Because naively I would expect the human reader to want to encounter the backlink after having read the footnotes, not before (i.e. how does this affect the rendering in other epub readers?)

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...

Using an aside for footnotes seems to make sense if the aside is placed in the body text as well, not at the end. (Maybe you can link to Kindle/Apple recommendations?) Placing the footnotes in an aside in the middle of the text flow might make sense as an option, in addition to the existing way. The new way might be toggled with the inline_notes extension, which currently only the markdown reader uses, but the HTML writer could make use of it as well. (Ah yes, or indeed better the --reference-location option...?)

Yes, I had thought putting asides inline, but there are some issues with doing it. For example the Kindle software doesn't hide asides by default (but iBooks does) so we'd have to ship additional CSS to make this consistent, or you'd have footnotes appearing in the main flow of the text.

What I was trying to do was to fix the initial problem with minimal impact on other facilities. Adding support to --reference-location (or maybe --footnote-location) would be good but would require more work (I don't think inline_notes should affect output, it's only an input-side thing). I'd like to fix the display problem by itself first and then look at more flexibility later.

---

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 doc-footnote is tied to epub:type="footnote", so the semantics should be the same):

The doc-footnote role is only for representing individual notes that occur within the body of a work. For collections of notes that occur at the end of a section, see doc-endnotes.

---

So the "holistic" solution to footnotes might be to add --footnote-location (which perhaps defaults to --reference-location but may be set independently). The valid values are only block or section, document is not supported (or is treated as section).

• block would place the footnotes into an aside after the current block, and Pandoc will have custom CSS to hide it (except they need to be shown when printing, etc).
• section would place the footnotes at the end of the EPUB file (i.e. whatever --epub-chapter-level splits the document into), and these would be marked as endnotes with epub:type and ARIA role, and not using aside.

[Porges]

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:

• Identify footnotes within the text using the aside element. [WCAG 1.3.1]
• Group footnotes or endnotes at the end of a section or work in lists. [WCAG 1.3.1]
• Link note references to their notes. [WCAG 1.3.1]
• Backlink notes at the end of a section or work to their references. [WCAG 1.3.1]

For footnotes:

The backlink precedes the note text so that the user will be aware that such a link is available.

For endnotes:

The backlink follows the note text to avoid any conflicts with automatic list numbering. The link is placed in its own element so that the user does not have to listen to the note before being able to activate it.

---

So the new "holistic" plan is something like: add --footnote-location (which defaults to --reference-location but may be set independently). The valid values are only block or section, document is not supported (or is treated as section). [Alternately we call the options "footnote" and "endnote"?]

• section (which is very close to the current placement method):

  1. footnotes go at end of current EPUB file (i.e. whatever --epub-chapter-level splits the document into)
  2. placed in ol/li,
  3. back-link at end,
  4. with DPUB-ARIA/EPUB "endnote" semantics.

• block (which would be the new placement method):

  1. footnotes go after current block,
  2. placed in aside,
  3. back-link at the start,
  4. with DPUB-ARIA/EPUB "footnote" semantics.

---

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.

[mb21]

Sounds promising... just a few notes:

I don't think inline_notes should affect output, it's only an input-side thing

Actually, we've started using extensions in different input and output, e.g. we could do -t epub+inline_notes. But maybe you're right that in this case it's better to use the existing --reference-location option.

However, this doesn't fix Kindle display for endnotes which have back-links at the end.

Does this also depend on how you convert the ePUB to mobi? Using calibre or the official amazon tool?
Also, couldn't the user just use --reference-location=block if he/she want to convert to mobi afterwards?

[Porges]

Does this also depend on how you convert the ePUB to mobi? Using calibre or the official amazon tool?

No, the problem exists with either method.

Also, couldn't the user just use --reference-location=block if he/she want to convert to mobi afterwards?

This is true, but it would be nice to have it work in both cases.

[Porges]

When I get time/energy I'm going to try implementing the approach outlined in the last comment.

[jgm]

@Porges thanks for your work on this. I wonder if we could start with something simple. The guidelines say:

• Identify footnotes within the text using the aside element. [WCAG 1.3.1]
• Group footnotes or endnotes at the end of a section or work in lists. [WCAG 1.3.1]
• Link note references to their notes. [WCAG 1.3.1]
• Backlink notes at the end of a section or work to their references. [WCAG 1.3.1]
• For footnotes, the backlink precedes the note text so that the user will be aware that such a link is available.

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.

[Porges]

Closing this because I think the design & discussion has moved on @jgm?

[jgm]

I was keeping this open because I thought we should at least do the following:

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?

If you'd prefer, though, we could make a new issue with this.

[Porges]

@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.