doc-footnote produces an error

[clapierre]

doc-footnote should be valid. doc-footnotes is not valid which was a previous issue which has been closed.

from the DPUB-ARIA spec.

doc-footnote Ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text.

[mattgarrish]

What element are you using it on @clapierre ?

[clapierre]

This was from one of a conversion vendor. <section role="doc-footnote" epub:type="footnote" title="Notes" aria-label="Notes">

but it seemed it was allowed on an aside <aside id="id_523" role="doc-footnote" epub:type="footnote"><p class="Note_Top"><a/><a title="footnote-link" href="Preface.xhtml#id_522">1</a>. <i>Congressional Record</i>, October 13, 2009, 24550.</p></aside>

SO I see the problem now they made a section with doc-footnote which wasn't a footnote and the real footnote was contained in that section in the aside.

Where do we spell out which elements each doc-* is valid? Thanks

[laudrain]

@clapierre The reference document is https://idpf.github.io/epub-guides/epub-aria-authoring/ See also: https://www.w3.org/TR/dpub-aria-1.0

[clapierre]

Thanks @laudrain very helpful https://idpf.github.io/epub-guides/epub-aria-authoring/#sec-usage feel free to close this issue.

[mattgarrish]

The reference document is https://idpf.github.io/epub-guides/epub-aria-authoring/

Yes, we recently updated the document to add the list of elements that roles are allowed on. In addition to what is listed in the column, you can add roles to any of the elements listed after the table (these all accept any role).

So in the case of footnote, aside, div, p and other elements can all carry it, but not section.

One thing to be aware of is that if you have a list of notes, you'll need to put doc-endnote on the li elements. doc-footnote can't also be a list item.

[tastytea]

One thing to be aware of is that if you have a list of notes, you'll need to put doc-endnote on the li elements. doc-footnote can't also be a list item.

What am I supposed to do if I have a list of notes but they are footnotes and not endnotes? doc-footnote tells the software to render them in-page.

[mattgarrish]

doc-footnote tells the software to render them in-page.

Sorry, I'm not sure I understand your issue.

ARIA roles are used to create the accessibility tree and inform assistive technologies, so what software are you referring to (is this a specific reading system?) and what rendering do you mean?

If you want pop-out footnotes in some reading systems, you can also add an epub:type attribute with the value "footnote". The attributes are not incompatible with each other.

If you just want to make a list of footnotes, you can add the doc-footnote role to an element within each list item instead of to the list item itself. See https://github.com/w3c/epub-specs/issues/1316#issuecomment-623656810 for an example.

[tastytea]

I just find it a bit weird that it's okay to put doc-endnote on a li element but not doc-footnote. They're essentially the same thing. They both have to be specified in a list at the end of the chapter or document, since there is no way to ensure that footnotes are rendered in the footer of a page.

If you want pop-out footnotes in some reading systems, you can also add an epub:type attribute with the value "footnote". The attributes are not incompatible with each other.

Some reading systems use ARIA roles to figure out if an item is a footnote (rendered in-page) or endnote (no special rendering) How will they behave if epub:type is “footnote” and role is “doc-endnote”? Or should I just drop role?

If you just want to make a list of footnotes, you can add the doc-footnote role to an element within each list item instead of to the list item itself.

Sure, that works as a workaround, but why can't I put it on the li tag? It doesn't make sense to throw errors if it is on a li tag but not if it is on a span tag in a li tag. :confused:

[clapierre]

I just find it a bit weird that it's okay to put doc-endnote on a li element but not doc-footnote

Actually the next version of DPUB-ARIA will be deprecating doc-endnote doc-endnote [Deprecated in DPUB-ARIA 1.1] One of a collection of notes that occur at the end of a work, or a section within it, that provides additional context to a referenced passage of text.

NOTE The doc-endnote role was designed for use as a list item, but due to clarifications in the WAI-ARIA specification, it is not valid as a child of the list role. As the doc-endnotes role already identifies a section of endnotes, authors are instead advised to use the list and listitem roles when native HTML elements cannot be used to structure the entries. The doc-footnote role can be used within each list item to identify individual notes when necessary.

Same for

NOTE The doc-biblioentry role was designed for use as a list item, but due to clarifications in the WAI-ARIA specification, it is not valid as a child of the list role. As the doc-bibliography role already identifies a section of bibliography entries, authors are instead advised to use the list and listitem roles when native HTML elements cannot be used to structure the entries.

[mattgarrish]

I just find it a bit weird that it's okay to put doc-endnote on a li element but not doc-footnote.

It's not okay to put doc-endnote, though. Have a read through the issue I linked to. The doc-endnote role is being deprecated because it doesn't work in the ARIA inheritance model and isn't being replaced.

But more to your question, when you add a role to an element you change its nature to assistive technologies. So because doc-footnote isn't a list item role, it would strip the li tag of its list item nature and turn it into something more like a div or a p tag. That breaks the list semantics for AT users, so they'd no longer be able to access the list as though it were a list.

That's why you can't put any ARIA roles on any element or use them in any situation. Their use has to be consistent with the underlying markup model and the effect it will have on AT. You can make documents entirely unreadable for their intended audience by misusing ARIA roles.

And that's the long story to why there were two roles. ARIA roles aren't context sensitive, so if a role inherits from list items it can only be used as the child of a list element. To allow footnotes to be placed anywhere, not just within a list, it didn't get the same inheritance.

Moving forward, there will just be footnotes, and if you want to make a list of them just wrap them in a list.

Some reading systems use ARIA roles to figure out if an item is a footnote (rendered in-page) or endnote (no special rendering)

I'm still not sure what you mean by "rendered in-page"? If you mean a reading system will actually format them at the bottom of a virtual page, I haven't seen that done and don't expect it's technically feasible to do.

How will they behave if epub:type is “footnote” and role is “doc-endnote”? Or should I just drop role?

The only special formatting I'm aware of is pop-ups, and I believe that's mostly done based on epub:type being set to footnote. If any are picking up on the ARIA role, it won't lead to any inconsistency since doc-endnote doesn't have a future.

[tastytea]

Thank you for your answers.

It's not okay to put doc-endnote, though. Have a read through the issue I linked to. The doc-endnote role is being deprecated because it doesn't work in the ARIA inheritance model and isn't being replaced.

Maybe it shouldn't be recommended anymore then. This is the error message I get from EPUBCheck 4.2.5 if I use <li role="doc-footnote">:

Error while parsing file: value of attribute "role" is invalid; must be equal to "doc-biblioentry", "doc-endnote", "listitem", "menuitem", "menuitemcheckbox", "menuitemradio", "none", "option", "presentation", "radio", "separator", "tab" or "treeitem"

I'm still not sure what you mean by "rendered in-page"? If you mean a reading system will actually format them at the bottom of a virtual page, I haven't seen that done and don't expect it's technically feasible to do.

Yes, KOReader and I think coolreader do that.

[mattgarrish]

Maybe it shouldn't be recommended anymore then.

Yes, we're working on moving DPUB-ARIA 1.1 forward. This may be something worth fixing in advance, though. @rdeltour?

The Ace validator does a better job of checking for proper ARIA use as well as other common accessibility pitfalls that epubcheck doesn't catch.

Yes, KOReader and I think coolreader do that.

Interesting. I'll have to have a look. Thanks for the pointer!

[rdeltour]

Yes, we're working on moving DPUB-ARIA 1.1 forward. This may be something worth fixing in advance, though. @rdeltour?

That particular message (value of attribute "role" is invalid) comes from the validation against the HTML schemas. We have not much control on that message.

In fact, I'm not quite sure how to fix this: if the schema is updated to disallow doc-endnote, then it won't be listed in the list of allowed role, but then it will be rejected altogether which is probably too strong.

If we want to be proactive, we should probably open an issue on the HTML validator, and see how they deal with deprecation of attribute values.

[mattgarrish]

If we want to be proactive, we should probably open an issue on the HTML validator, and see how they deal with deprecation of attribute values.

Ya, but that probably means waiting for 1.1 as they don't usually fix for in-progress specs.

I was only thinking of a schematron warning when doc-endnote or doc-biblioentry are used. Something we could dispose of easily once officially corrected. But off the top of my head I can't remember if we implement our own schematron checks on top of xhtml content documents.

[rdeltour]

I was only thinking of a schematron warning when doc-endnote or doc-biblioentry are used. Something we could dispose of easily once officially corrected. But off the top of my head I can't remember if we implement our own schematron checks on top of xhtml content documents.

Ok I see! Yes we do have schematron checks for XHTML.

[schnerring]

Given the valid doc-notes example from the 1.0 spec:

<section role="doc-endnotes">
   <h2>Notes</h2>
   <ol>
      <li id="6baa07af" role="doc-endnote">Additional results of this study can be found at … </li>
      <li id="7b2c0555" role="doc-endnote">…</li>
      …
   </ol>
</section>

And the valid doc-notes example from the 1.1 spec:

<section role="doc-endnotes">
   <h2>Notes</h2>
   <ol>
      <li id="6baa07af">
         <p role="doc-footnote">Additional results of this study can be found at … </p>
      </li>
      <li id="7b2c0555">
         <p role="doc-footnote">…</p>
      </li>
      …
   </ol>
</section>

Am I correct to assume that just replacing doc-endnote with doc-footnote on the li element is the WRONG approach to move forward to spec 1.1?

<section role="doc-endnotes">
   <h2>Notes</h2>
   <ol>
      <!-- invalid -->
      <li id="6baa07af" role="doc-footnote">Additional results of this study can be found at … </li>
      <!-- invalid -->
      <li id="7b2c0555" role="doc-footnote">…</li>
      …
   </ol>
</section>

[mattgarrish]

Am I correct to assume that just replacing doc-endnote with doc-footnote on the li element is the WRONG approach to move forward to spec 1.1?

Right, the problem is that we were told after the 1.0 release that roles defined in modules like dpub-aria cannot satisfy the child role requirements of roles in aria core. That's why doc-endnote is deprecated. You can't simply swap it to doc-footnote as that would completely break the list semantics as it doesn't inherit from listitem, and even if it did it would also be invalid for the same reason doc-endnote can't fulfill the list role requirement.

The 1.1 example you've quoted is no longer valid, by the way. There's an updated working draft coming soon. In it, endnotes are implied on the immediate list item descendants of a doc-endnotes marked section and the use of doc-footnote is not allowed. This was done to avoid the ambiguity of whether the content within the list item is a footnote or endnote.

But this does make things simpler, as you can simply drop the explicit role and there's still an assumption that the list items are endnotes.

Until 1.1 gets out of draft stage, it's probably better to refer to the latest editor's draft.