Adjust EPUB footnotes with backlink before text.

[jgm]

See #4491 which has been abandoned but has several good ideas in it, which I don't want to get lost.

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

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.

See also:

• Amazon kindle guidelines
• iBooks Asset Guide
• DPUB-Aria

[jgm]

Note however that under "backlink with endnote" it recommends putting the backlink at the end, so as not to interfere with note numbering.

<li role="doc-endnote">
   <p>According to the usual nomenclature, the …</p>
   <p><a href="#ref" role="doc-backlink">Go to note reference</a></p>
</li>

[lewer]

Currently, with epub3 writer, the #footnotes section has epub:type="footnotes" and every footnote has <li epub:type="footnote">

As I understand https://kb.daisy.org/publishing/docs/html/notes.html, "footnotes" are what is put in an aside block in the body, while "endnotes" are grouped at the end in a proper section.

So currently pandoc kind of mixes endnotes and foonotes: it uses endnotes but tags them with epub:type="footnotes"

To follow https://kb.daisy.org/publishing/docs/html/notes.html (Example 2 — Grouped notes at the end of a section/work) with minimal changes, what do you think of replacing epub:type="footnotes" with epub:type="endnotes" in the #footnotes section, add role="doc-endnotes" to this same section, and removing epub:type="footnote" on each individual footnote?

[jgm]

Note that where the notes go is sensitive to --reference-location. If you want them t ooccur right after the paragraph in which they're cited, you can use --reference-location=block. An <ol> will still be used, because we want the formatting that brings. We could think about putting the <ol> inside an <aside>, though.

We could also think about using epub:type="endnotes" etc. when --reference-location is set to document (the default).

However, these issues are orthogonal to this issue, which is about backlinks preceding the note, so please open a new issue if you think this should be considered.

[lewer]

Not sure that the issue of footnote/endnote distinction and backlink position are orthogonal. Here https://github.com/jgm/pandoc/pull/4491#issuecomment-378802283, @Porges concluded that backlink should be placed at end for footnotes, and at start for endnotes.

If the notes are inside an <ol> it makes sense to put the backlink at the end to avoid conflicts with <li> numbering. But if the notes are inside an <aside> without <ol>, the backlink can precede the note.

I'll try to propose a PR to continue what was started here: https://github.com/jgm/pandoc/pull/4491 An option to put notes in an <aside> if --reference-location=block and in that case, backlink before the note.

[jgm]

@Porges concluded that backlink should be placed at end for footnotes, and at start for endnotes.

Isn't it the other way round? Backlink should go at the end for endnotes, at the start for footnotes.