The doc-pagelist code sample has a malformed closing h2 tag. (Happy to do a PR if you like, but it should be a very easy fix.)

Code sample for doc-glossary requires review and/or revision. Required owned elements may need to be revised based on changes made in ARIA 1.1

The implied role of dt is unclear:

• the normative definition is in ARIA in HTML, which says it has an implicit role of 'listitem':
  https://w3c.github.io/html-aria/#dd-dt2
  *, however, the informative allowed ARIA role attribute value described in W3C’s HTML is 'none'
  https://www.w3.org/TR/html/grouping-content.html#elementdef-dt
• and HTML AAM says it should be mapped using the WAI-ARIA mapping for the 'term' role
  https://w3c.github.io/html-aam/#el-dt

This is discussed in

• w3c/html-aria#57
• w3c/html-aam#78
• w3c/aria#504
  cc/@mattgarrish, @rdeltour

doc-example has the superclass section, but it seems to make more sense that it inherit directly from figure, as examples are a specialized type of figure. It also removes the problematic relationship of the figcaption element when the figure element's role is overridden.

See also w3c/html-aria#99

None of the landmark roles in the module require an accessible name, so not sure why this one does in its properties table. Looks like a mistake.

doc-pagebreak has this example:

<span id="pg04" role="doc-pagebreak" title="4"/>

along with "Accessible Name Required" of True.

I would hope that authors would combine the two pieces of information and conclude something like "Authors SHOULD provide an end-user-consumable page number as the name of the pagebreak." That way, a screen reader could include the page number information when the page changes and/or in a "where am I?" command.

As it stands right now, however, the name could be anything. And I've seen authors do strange things over the years.... 🤷‍♀️

(Feature request)

Add a role corresponding to ‘loi’ in the ePub structural semantics. It identifies a section or nav element containing links to the illustrations in the document.

A user might wish to know that a pullquote is present in the document -- even if it is just repeated for visual effect. But https://w3c.github.io/dpub-aria/#example-39 makes that impossible because it uses aria-hidden="true". Hidden content is typically pruned from the accessibility tree.

If there were an ARIA property which allowed authors to mark something as "repeated content" then a screen reader could have an option to hide/show repeated content. Then users who don't want to read the duplicated content would get the same result as aria-hidden="true". But users who do want that repeated content presented would be able to.

I've marked this as "BLOCKED" because ARIA currently has no such feature. But that might change. See w3c/aria#1044.

ARIA is gaining name-from-heading as an option for naming things, see w3c/aria#1860.

Many DPUB roles could benefit from this feature, in particular those roles subclassing roles that will gain nameFrom:heading.

https://www.w3.org/TR/dpub-aria-1.0/#role_definitions

There are no roles for educational publishing in the DPUB-ARIA standard. Visual, or motor impaired people absolutely need to know if some content is an activity, or an assessment (test). As a matter of fact, an assessment will have consequences for them. Furthermore, amoung the activities, it is even better to know about their interactivity type, in order to skip them, or be prepared for such an interaction.

A list of interactive exercises is under construction in the EPUBs Structural Semantics Vocabulary. It now includes the values proposed long ago by the EDUPUB project, which is great news.
You will notice that in this spec, apart from the doc-qna value, no other mapping with DPUB-ARIA roles can be achieved, as they do not exist yet.

If you plan to define a new version of DPUB-ARIA standard, it would be great to take into account the needs of the students with visual, or motor impairment. In educational publishing, some publications are EPUBs, others are not (i.e. web sites, webapps = most of them by the way). As a consequence, EPUB standard will not cover all the user's needs.

Hope this will draw your attention.

At CSUN this year, Paul Radius presented on PDF/UA and mentioned PDFA was working on a comparison table of PDF role mappings to DPUB mappings. Rather than duplicate the work, it seems like the DPUB-ARIA repo could be a good location for an informative, evergreen resource defining the expectations.

I maintain a browser extension that helps people navigate landmark regions and have recently been working on support for the DPUB roles. I was wondering if you are aware of any publicly-available documents using these roles that I can use to test/demonstrate the extension's support for them? (I've had a look around, but not found anything; sorry if I've missed something that's already out there.)

It seems there's something wonky with the relationships established with required owned elements, required context role, and role subclasses defined in DPUB ARIA.

ARIA 1.1 has a note in the Required own elements section that says:

An element with a subclass role of the 'required owned element' does not fulfill this requirement. For example, the list role requires ownership of an element using either the listitem or group role. Although the group role is the superclass of row, adding a owned element with a role of row will not fulfill the requirement that list must own a listitem or a group.

This means for instance that doc-biblioentry cannot be used as the unique children of a list, which invalidates Example 6:

<section role="doc-bibliography">
   <h1>Cited Works</h1>
   <div role="list">
      <p role="doc-biblioentry" id="b8cab5dd-bc24-459c-9858-7afa9da69b64">
         John Steinbeck, The Grapes of Wrath (New York: The Viking Press, 1939)
      </p>
   </div>
   …
</section>

In other words, doc-bibliography is only usable on li children of ol and ul.

Can we clarify that with the ARIA folks (cc @w3c/aria)? This looks like an oversight in how DPUB extends ARIA, or maybe even in ARIA's own extensibility.

I was just going back over the 1.1 changes and noticed that the new doc-pageheader and doc-pagefooter roles both disallow doc-pagebreak.

This restriction makes sense for footers because we say that the page break identifies the start of its page, but I don't see why we should ban page breaks from headers. It just forces duplicated numbers in close proximity as far as I can tell. I think this restriction may have slipped in when we were discussing an alternative doc-pagenum role for the headers and footers, so didn't want the numbering roles to overlap.

I'd like to remove the restriction from the header definition and give some context for why it exists for footers.

Before I open a pull request, though, does this change make sense to you @aleventhal? (i.e., it doesn't present any problems for your potential use of the new header and footer roles, does it?)

Originally opened in https://github.com/w3c/dpub-aria-2.0/issues/1 :

Opening this issue to get feedback on desired additions.

(Copying follow-up comments below.)

doc-pagebreak currently only supports name from author. Shouldn’t is also support name from content?

The following code looks reasonable to me:

<span id="pg04" role="doc-pagebreak">4</span>

See also #6.

@jnurthen dpub-aria roles that inherit from section or landmark (maybe others) are missing "(deprecated on this role in ARIA 1.2)" on aria-disabled, aria-errormessage, aria-haspopup, and aria-invalid. Do you know what needs to be done to fix this?

The text for doc-footnote says it is only for use outside of doc-endnotes, but that was true prior to deprecating doc-endnote.

It should be updated to allow anywhere, but note to see the doc-endnotes role for lists of notes.

Opened originally in w3c/aria#652 :

The mapping for doc-pullquote is "none" in the specification but "section" in the AAM. I recall this was changed to allow users access to the pullquotes, but the specification needs to reflect the change.

It's not obvious to me whether the page number assigned to a page break is for the page before or after the break. I'm guessing it's the page before, because there is no page break at the very top of the document, so there would be no way to indicate that page number.

Here's the current spec text:

					<p>A separator denoting the position before which a break occurs between two contiguous pages in
						a statically paginated version of the content.</p>
					<p>Page break locators are also commonly used to provide static markers in purely digital
						publications (i.e., where no statically paginated equivalent exists). These markers provide
						consistent navigation regardless of differences in font and screen size that can otherwise
						affect the dynamic pagination of the content.</p>
					<p>The name of the page break SHOULD be an end user-consumable page number so that assistive
						technologies can announce the page as needed (e.g., in a command to indentify the current
						page).</p>
					<aside class="example">
						<p>The following example shows three equivalent patterns for marking up page breaks in
							digital publications. Either the <code>aria-label</code> or <code>title</code>
							attributes can be used to assign the accessible name when an explicit page number is not
							provided.</p>

The a element in the doc-noteref example needs an href attribute, as reported in w3c/html-aria#101 (comment)

Hi everyone,

as the title suggests, I'm here because I'd need to use role="doc-glossary" on the <aside> tag. However, both EPUBCheck and ACE report errors. ACE reports that "ARIA role doc-glossary is not allowed for given element". As far as I understand, <aside> has the implicit role "complementary", which is a subclass role of "landmark", which in turn is the superclass indicated for doc-glossary.

Also, looking at the Accessible Publishing Knowledge Base by DAISY, <aside> is listed among the possible elements doc-glossary is allowed on (http://kb.daisy.org/publishing/docs/html/dpub-aria/doc-glossary.html).

As for the content of the <aside>, the error occurs both if we have a definition list (<dl> with <dt> and <dd>, possibly with role="term" on <dt>), or if we have a <p> with <dfn> to identify the term.

In the specific use case, I have an EPUB with boxes (<aside>) that contain definitions of words and therefore represent small glossaries, so using doc-glossary would give more semantics.

Can anyone help me understand the problem?

..

Several DPUB ARIA roles are defined as subclassing the landmark role. This is notably the case of roles identifying sections/divisions of a publication (e.g. doc-chapter, doc-part, etc).

In EPUB, I think it is fairly common practice to find the corresponding epub:type values set to body elements. EPUBs are a collection of HTML documents, so if one document represents a publication division, I think it makes sense that the body itself carries the matching landmark semantics. Setting these on body was also a practice explicitly acknowledged but the EPUB Structural Semantics Vocabulary .

However, ARIA in HTML currently disallows any role being set on the body element.

Starting from v4.2.0, EPUBCheck will report any doc-* roles set on the body element. If people used epub:type on body, and try to apply DPUB ARIA roles by following the mapping guide, they will be confused.

I don't know the impact on AT of overriding the role of body elements; I think some ATs change their reading mode when landing on a body, so overriding the role could wreak havoc (which could be the reason why it is disallowed in ARIA in HTML). Testing with browsers+AT would be needed before filing any issue to ARIA in HTML.

In the mean time, maybe we could at least add a note to the SSV/DPUB-ARIA mapping document?

ping @mattgarrish @TzviyaSiegman

In many books, you will find examples of text messages, such as written letters, emails, chat messages, text messages, and so on, that are graphically formatted to clearly indicate where the message begins and ends. For example, messages may be indented or written in italics or bold or in a different font. However, there does not appear to be a standardized way of semantically identifying these elements.

HTML tags such as <blockquote> are often used for text quotations, but they do not seem suitable in this case since text messages are not quotations of other text.

Orr request is to explore possible ways for semantic identification of text messages such as these. This could be useful to improve the accessibility of digital content and make it more understandable for readers with certain disabilities.

Throughout dpub-aria H1 is used within document sections. This seems to rely on the (unimplemented) HTML outline algorithm. We should change all usages of H1 in the examples to something more appropriate in real context so as not to imply that th e HTML outline algorithm is useful.

The definition for doc-glossary says you should identify the terms in the glossary and mentions using dl as an option, but ARIA 1.2 removes the association of dt and dd with the term and definition roles. dl, dt, and dd will eventually map to associationlist roles in ARIA 1.3. Only dfn identifies terms.

Since the associationlist roles are not specific to term/definition (and ARIA 1.2/ARIA in HTML currently have no associations for dl elements), I'm thinking we should add a dfn tag inside the dt in the example.

PRINT LIKE NOTE DISPLAY
Role=doc-endnote (singular) has been deprecated in DPUB-ARIA 1.1, which makes sense, as every single note placed under an element with role=doc-endnotes (plural) will necessarly be a doc-endnote (singular). It is useless to specify it.

On the contrary, individual footnotes still have a role=doc-footnote (singular) value, though there can be several individual footnotes in the bottom of a page (footer => footnote). We are still missing a role=doc-footnotes (plural) value. Furthermore, it makes things inconsistent with end notes modeling, though the two usecases are very similar, as print publications group the notes' content in specific paper zones.

We are still missing tables' notes too (role=doc-tablenote and/or role=doc-tablenotes) by the way.

DIGITAL SPECIFIC NOTE DISPLAY
Finally, we are missing a role for cleaver digital publications, that don't want to display notes' content away from their notes' references (as print publications do, for medium reasons). These digital publications prefer to display notes' content right over the notes' reference (as a pop-up/hover text). No DPUB ARIA role matches this usecase presently (doc-footnote is a misinterpretation). We would need a doc-notecontent (or doc-notebody) value for this.

In most cases it makes no sense to allow an author name for DPUB roles, and in fact could lead to confusion.
Name From = "prohibited" is new in ARIA 1.2. We should go through the roles and determine which should not have a label.
Probably most of the ones that are currently "author" should be prohibited. It doesn't make sense to have a named bibliography entry, table of contents, etc. In publishing or word processing, any relevant text is generally visible on the page.

Examples of core ARIA roles where naming is prohibited: https://w3c.github.io/aria/#namefromprohibited

Moved from w3c/dpub#24

Without these semantics, screen readers cannot provide their users with settings to turn on/off the visibility of running headers and footers, which may have important information, or the user may wish to examine for authoring purposes.

Many dpub roles are named-from-author. However, only the example for doc-glossary actually names the relevant element.

A lot of novels contain letters that are styled differently from the current text. Today e-mails and SMS have also been added, as they are part of our everyday life, and have replaced physical letters.
Blind people do not access the visual styling that signal these inclusions (through specific styles driven by CSS classes). While reading, they are missing a very important part of information. TTS would need a semantic attribute to inform them of this inclusion into the narration. No digital publishing ARIA role is available yet for this sake. Could we add 3 new doc roles in the standard ?

• doc-letter
• doc-e-mail
• doc-sms

Thnks

Originally opened in w3c/aria#692 :

This occurs twice, but that might be springing from a single occurrence in the source. There's a cromulent use of 'principle' elsewhere that should be left unchanged.

This short review is for the following spec: Digital Publishing WAI-ARIA Module 1.1.

1. If the spec (or its implementation) contains any natural language text that will be read by a human (this includes error messages or other UI text, JSON strings, etc, etc), ensure that there’s metadata about and support for basic things such as language and text direction. Also check the detailed guidance for Language and Text direction.

   • Not applicable
   • The DPUB-ARIA spec only adds new role attribute values

2. If the spec (or its implementation) allows content authors to produce typographically appealing text, either in its own right, or in association with graphics. take into account the different typographic styles used around the world (for things such as line-breaking, text justification, emphasis or other text decorations, text selection and units, etc.) Also check the detailed guidance for Typographic support.

   • Not applicable
   • Role values are not rendered as text

3. If the spec (or its implementation) allows the user to point into text, creates text fragments, concatenates text, allows the user to select or step through text (using a cursor or other methods), etc. make allowances for the ways different scripts handle units of text. Also check the detailed guidance for Text-processing.

   • Not applicable

4. If the spec (or its implementation) allows searching or matching of text, including syntax and identifiers understand the implications of normalisation, case folding, etc. Also check the detailed guidance for Text-processing.

   • Not applicable

5. If the spec (or its implementation) sorts text ensure that it does so in locally relevant ways. Also check the detailed guidance for Text-processing.

   • Not applicable

6. If the spec (or its implementation) captures user input ensure that it also captures metadata about language and text direction, and that it accommodates locale-specific input methods.

   • Not applicable

7. If the spec (or its implementation) deals with time in any way that will be read by humans and/or crosses time zone boundaries ensure that it will represent time as expected in locales around the world, and manage the relationship between local and global/absolute time. Also check the detailed guidance for Local dates, times and formats.

   • Not applicable

8. If the spec (or its implementation) allows any character encoding other than UTF-8. make sure you have a convincing argument as to why, and then ensure that the character encoding model is correct. Also check the detailed guidance for Characters.

   • Not applicable

9. If the spec (or its implementation) defines markup ensure support for internationalisation features and avoid putting human-readable text in attribute values or plain-text elements. Also check the detailed guidance for Markup & syntax.

   • Not applicable

10. If the spec (or its implementation) deals with names, addresses, time & date formats, etc ensure that the model is flexible enough to cope with wide variations in format, levels of data, etc. Also check the detailed guidance for Local dates, times and formats.

    • Not applicable

11. If the spec (or its implementation) describes a format or data that is likely to need localization. ensure that there’s an approach in place which allows effective storage and labelling of, and access to localised alternatives for strings, text, images, etc.

    Exposing the roles to assistive technologies is covered by the DPUB-AAM specification. The various platforms allow for localisation of these role values.

12. If the spec (or its implementation) makes any reference to or relies on any cultural norms ensure that it can be adapted to suit different cultural norms around the world (ranging from depictions of people or gestures, to expectations about gender roles, to approaches to work and life, etc).

    • Not applicable
    • The publishing roles describe common publishing structures that are widely known throughout the world.

Issue request from Web Publishing WG F2F Meeting...

For EPUB structural vocabulary see: https://idpf.github.io/epub-vocabs/structure/

The above epub:type values are used by Reading Systems to afford footnote pop-up support (and indication of paper page-breaks). These all have mappings to ARIA roles.

If Reading Systems were to recognize the mapped ARIA roles to provide the affordances that they currently ascribe to epub:type... is this "wrong"? Would such drive creation of content that is sub-optimal from an A11Y perspective?

Use of this approach (using ARIA role mapping) seems better than exploring creation of another (non-epub:type) mechanism for defining said semantics.

Moved from w3c/dpub#25

Without this semantic, , screen readers cannot provide their users with settings to turn on/off the visibility of column break, which the user may wish to examine for authoring purposes.

When reviewing this the primary role is listed first, then you have examples, and afterwards you get the characteristics, but the characteristics doesn't include the primary role i.e. doc-chapter.

Either move the characteristics above the example section or include the primary role in each of the characteristic sections.

i.e.

As opened originally in w3c/aria#654 :

doc-subtitle currently only lists "author" in the "name from" field, but "contents" also looks reasonable here.

I'm really not clear how a document title which is rendered in the document should be marked up. Its not really an H1 as it doesn't take a part in the table of contents - and it is not the <TITLE> element in HTML as it is rendered in the document. Should there be a role for this?

A small correction in the section 3.1 Definition of Roles.

The entry for doc-pagelist is listed between doc-pagebreak and doc-pagefooter.
To keep alphabetical order doc-pagelist should be listed between doc-pageheader and doc-part.

Originally opened in w3c/aria#656 :

In https://www.w3.org/TR/2017/PR-dpub-aria-1.0-20171102/#role_definitions one reads:
An illustratration of a key concept of the work, such as a code listing, case study or problem.
s/illustratration/illustration/

doc-example can be used on a <figure> that has no <figcaption>; however, a figure with a figcaption may not have any roles (to maintain the parent/child relation).
See w3c/html-aria#209

The doc-example documentation suggests using role="doc-example" on a <figure> element with a <figcaption>, which is invalid.