add dpub-aria roles for footnotes

[xi]

The Digital Publishing WAI-ARIA Module 1.0 has recently become a W3C recommendation. It contains semantic structures that are derived from EPUB.

I added the appropriate roles to footnotes. Note that I chose to use doc-endnote rather than doc-footnote because of this section of the spec:

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.

Note that in order to be fully compliant the backlink needs an accessible name. The current name is '↩︎' which is not very useful. We could duplicate the title as aria-label, but by default the title is currently empty.

[michelf]

Looks good. I'm still a bit hesitant to call this an endnote, but it does indeed match the spec better despite the divergent names.

As for giving a name/title/label to the backlink, there's already a fn_backlink_title configuration variable you can use to set a title attribute, but I leave it empty by default because any meaningful word we could use here is language-dependent.

[xi]

Should I duplicate fn_backlink_title as aria-label?

[michelf]

Perhaps. I think most people who take the time to set this configuration variable use something that would be appropriate for the aria label, but I can't be sure.

As for endnote vs. footnote, do you know how accessibility tools treat the two, or the absence of either? I'm a bit worried about adding this blindly without knowing what effect it has in practice.

It'd be nice if the test cases involving for footnotes in MDTest were updated too.

[xi]

It'd be nice if the test cases involving for footnotes in MDTest were updated too.

I tried to do that in michelf/mdtest#9. Unfortunately, I do not currently have access to a working PHP setup, so it should be tested thouroughly.

As for endnote vs. footnote, do you know how accessibility tools treat the two, or the absence of either? I'm a bit worried about adding this blindly without knowing what effect it has in practice.

To be honest I have no clue. The spec is fairly new, so I can imagine that it has not yet been implemented in a lot of tools.

In my experience, new features often have a chicken-egg problem: AT vendors do not add support because few pages use the feature and authors do not use the feature because it is not supported in AT. My idea was that adding this to markdown could be a catalyst. I can completely understand if you want to wait for wider support though.

[michelf]

It's nice that ARIA is doing something about this. Honestly, I think footnote markup should be directly part of the HTML spec, not solely an accessibility-oriented feature. Footnotes are so prevalent that they are worthy of discussion in the HTML spec... but the markup they suggest isn't that useful.

There is surprisingly little talk out there about aria's footnote and endnote roles. This is the best I could find. It looks like the distinction between the two had to be made because you can't have the same role for an item in a list and one that is embedded from its context (basically a presentational issue).

It's going to be awkward to add this "endnote" role for a feature everyone calls footnote when aria also has a "footnote" role we could use. If the end result for the user is the same, I'd rather go for the one called "footnote" because it's the right word and will cause less confusion to those who care about the HTML output. If the treatment is different, I'd at least like to avoid accessibility tools announcing those as "endnotes" for users, so again "footnote" wins. But given the aria spec tries to differentiate the two I guess it's possible "footnote" would result in less optimal navigation, I guess.

So I can't really decide what to do because I can't weight the pros and cons. It seems to me like neither choice is right.

I'd love to break the chicken and egg problem, but I think I'll wait a bit until I can find clearer guidance.

[xi]

First of all, a big thanks to you. It never happened to me that I wrote a pull request and the maintainer got so deep into it!

I wrote a mail to [email protected] asking for help on this. Maybe something will come of it.

Reading the spec again I still think that endnote is the appropriate concept here. Note for example that doc-endnotes is a landmark role, therefore it is simple to navigate to to that section. Footnotes (in dpub-aria) have nothing like this.

[TzviyaSiegman]

Sorry for the delayed response. The reason that we created both the doc-footnote and doc-endnote roles is to allow for placement in different contexts. ARIA is not flexible about context, so we needed to create roles that would allow for notes inline (https://www.w3.org/TR/dpub-aria/#doc-footnote) and notes in a collection at the end of a section (https://www.w3.org/TR/dpub-aria/#doc-endnote).

Endnotes are widely understood, so it shouldn't be all that confusing given that endnotes and footnotes are the same except in positioning and collection.

If you need to have a footnote semantic a workaround would be to add a div inside each list item and put the role on that instead of on the list item. It's not elegant, but it wouldn't cause issues in parsing the markup

[michelf]

@TzviyaSiegman Thanks for your input.

@xi Let's go with doc-endnote. I still think it's awkward to have to use "endnote" instead of "footnote", but the alternatives are no better. I really wish those could be called footnotes. Hopefully it won't come to bite me (in term of confused users) in the future.

So I take this is ready to merge as soon as I have some time to test it (probably by next week). Thank you for the patch.

[xi]

Thanks to @TzviyaSiegman for the quick feedback. Happy to see this going forward!

[xi]

The current draft for dpub-aria 1.1 removes the doc-endnote role. Not final yet, but the markup probably will need some changes in the future. https://w3c.github.io/dpub-aria/#doc-endnotes