brailleroledescription update

[pkra]

Continues #924

Addressing review comments, part 1

• rephrase opening line - feat: aria-brailleroledescription #924 (comment)
• Braille/braille capitalization - feat: aria-brailleroledescription #924 (comment)
• suffice => overly verbose - feat: aria-brailleroledescription #924 (comment)
• two examples show => example shows - feat: aria-brailleroledescription #924 (comment)

---

Diff

[mcking65]

Looking very good. Have some editorial suggestions.

[cookiecrook]

LGTM including Matt's editorial.

[pkra]

Thanks so much #924 (comment).

[pkra]

I think this is ready.

As mentioned, I've left the author warning as edited by @mcking65.

There's one more question leftover from @cookiecrook had asked:

This line invalidates using img as a short braille description. Was that intentional? Same thing with "toc" if that one makes it from the DPUB module into the core spec.

and I had responded:

I admit I struggle to answer that. The relevant commit is from June and the commit message explicitly mentions this change. I would have said I added it after feedback from the group, but I can't find any minutes around the time that match this idea.

Maybe we can decide that on the next call.

[pkra]

@joanmarie can we add this to the next call's agenda? There's only one minor question left that I'd like to bring up with the group.

[pkra]

Neil at #924 (comment)

I commented on the use of the phrase "Unicode Braille Patterns" earlier and the distinction between the block name and an individual character -- strings consist of characters not patterns, symbols, or glyphs. I'm happy to see that in one instance that distinction is properly used. However, since the time of my comment, there have been several changes to text and I think improper usage has creeped in again.

Examples where I think changes are warranted so that the sentence is technically correct:

1. The value of aria-brailleroledescription consists of a string of either Unicode with no Unicode Braille Patterns (U+2800..U+28FF) or consists of a string of only Unicode Braille Patterns (U+2800..U+28FF) while not only containing Braille Pattern dots-0 (U+2800).

2. If the value of aria-brailleroledescription consists only of Unicode characters that are not Unicode Braille Patterns, translate the value according to the user's preferred translation table

I suggest these become:

1. The string value of aria-brailleroledescription does not contain any characters in Unicode Braille Patterns (U+2800..U+28FF) or consists of only characters in the range U+2801..U+28FF (Unicode Braille Pattern block excluding dots-0).


* Note: the previous statement mentioned it must contain "either Unicode or...". In HTML, all attributes value strings much contain Unicode values, so that statement is not a restriction. In fact, [not all Unicode values are legal,](https://www.w3.org/TR/2012/WD-html-markup-20120329/syntax.html#syntax-text) so it isn't even correct.


1. If the value of aria-brailleroledescription does not contain Unicode Braille Pattern characters, translate the value according to the user's preferred translation table.


* Note: The above is the first clause. I think the second clause would be better written as "Otherwise, pass the value to the user without translation." I don't think it is helpful to write a condition on the second clause as there is no alternative third clause (i.e., AT should do one of those two things).

[pkra]

@NSoiffer thanks for those. I'll make an update to address this.

The only detail I don't plan to address right now is the part in (1) where your version would forbid the use of Dot-0 entirely. That's only because I didn't see anything similar for the "regular" role description, i.e., it doesn't forbid whitespace entirely.

[NSoiffer]

Oops, you are correct that I blew it for excluding Dot-0. I was too aggressive in shortening the language. Hopefully you can keep the gist of the wording change that uses the word "character" where appropriate (i.e., when referring to values in a string).

[pkra]

@NSoiffer thanks for confirming.

[pkra]

I've pushed two commits

• addressing @NSoiffer's editorial comments
• addd @mcking65's comment from last telco that it should not duplicate role or role-description
• removed problematic line identified by @cookiecrook

For the last part, my reasoning was:

a) we noticed it didn't match role-description (but I've filed #1131 as promised),
b) we weren't really sure what it should have said (e.g., "a WAI-ARIA role" seems like it should have been "its WAI-ARIA role"),
c) it would add burden on UAs,
d) we now have an authoring SHOULD NOT.

So I think, this is ready.

[sinabahram]

I'm excited to get this finalized, but I do have the following questions and observations.

1. For the intro summary, we have "Defines a human-readable, author-localized abbreviated description for the role of an element, which is intended to be converted into Braille."

Should we say presented in Braille? Conversion seems loaded with questions around translation VS not, which are handled later on in the definition, so should we avoid ambiguity here?

2. We have "Authors MUST NOT use aria-brailleroledescription without providing a more specific aria-roledescription."

I understand the point, but can we clarify more specific than what? Right now, it kind of reads like the aria-roledescription must be more specific than aria-brailleroledescription, which is most definitely not the point of that statement.

Maybe we just want to drop the words "more specific" or at least "more".

3. This sentence really raised eyebrows for me. "In general, aria-brailleroledescription should only be used in rare cases when a aria-roledescription is excessively verbose when rendered in Braille."

Yes, I agree that is a majority use case, but should we really restrict all possible uses? I know it says "should" not "must", but still, that seems restrictive. Do we know for sure there are not cases, for example in educational contexts, where a particular Braille role is simply more appropriate independent of its length?

What about in a simple case where I wish to explore the most appropriate UI principles for two different user groups, speech users and Braille users. So, I construct an experiment to measure the efficacy of particular roles expressed in speech and others in Braille, and length is not the only variable I care to explore? For example, I could argue that speech generally should follow semantic prioritization, or putting important stuff up front, which is why most screen readers announce roles first in a virtual cursor context but not in a focus traversal context. But, do we actually have data on this for Braille? For all we know the geometric advantages of edge based detection would imply that a longer label, but with consistent spacing offers efficiencies in certain working contexts.

It just seems a bit too restrictive without offering evidence, but please don't misunderstand me. I know how valuable and prime a principle it is to be efficient on a Braille display, so I think it is a healthy default position, but I just wish to make sure we feel very certain that length should really surpass all else.

4. I humbly submit that the cognitive load to parse this sentence is exponentially higher than anything else in the description. "The value of aria-brailleroledescription does not contain any characters in Unicode Braille Patterns (U+2800..U+28FF) or consists of only characters in Unicode Braille Patterns (U+2800..U+28FF) while not only containing Braille Pattern dots-0 (U+2800)."

It is crystal clear, but I feel it requires thinking like an engineer, technical writer, or attorney. I feel like we can do a little bit better with those three requirements by explicitly enumerating them. In addition to enumerating them, perhaps we can offer an example to illustrate the two possibilities, one with unicode Braille and one without, along with it must not only consist of 2800. Even a four row good/bad table could go a long way?

5. Just a quick grammar thing here. "Instead, aria-brailleroledescription is meant be used only when aria-roledescription cannot provide an adequate braille representation, "

I believe we meant "meant to be"

6. In the code example, the image has an empty alt with aria-label labeling the planet. Is there a reason why this is done instead of the alt being set to Jupiter and reducing the use of aria attributes by 1? Does accessible name calc result in different results in those two cases? If not, then shouldn't the approach that always minimizes aria usage be preferred?

7. The code, when viewed as HTML, exposes escape characters, like so:

<img alt="" src="images/jupiter.jpg"/>

I didn't quote the above since it's code. Notice the backslash character seemingly escaping the equal sign.

8. We have the following sentence. "In the previous example, a braille display may display "Jupiter, pln" in Braille rather than the verbose "Jupiter, planet"."

Wouldn't a Braille display actually show those reversed e.g. "pln Jupiter"?

Thanks for entertaining this long comment.

[pkra]

Thanks, @sinabahram. I don't have a strong opinion on any of these but some editorial comments below.

Regarding point 2., I probably copied the "more specific" from aria-roledescription (where it refers to being more specific than the role). I agree "more specific" can be confusing; "valid" is probably also sufficient (unless that's considered extraneous/implied in a spec context).

Points 5-8, I think, are simply mistakes that I'll be happy to fix.

[pkra]

Note to self: address #1142 (comment) (prohibit on role=generic)

[pkra]

Just to recap today's call:

Re #1097 (comment), I will fix point 2) as well since "more specific" was copied from roledescription.

Since points 1, 3, and 4 have been revised several times to find consensus, I'd suggest to leave them as is. I suspect we'll work out more details down the road.

[sinabahram]

As promised on today's call, I reviewed my previous feedback. Yes I'm willing to live with 1, 3, and 4 not being addressed, so I'm going to wait for a commit addressing 2, and then hopefully that means 2, 5, 6, 7, and 8 are all addressed. At which point, I'm happy to review/approve this.

[sinabahram]

Happy to approve once final changes per comment thread are in.

[pkra]

@sinabahram thank you for the review! I'll work those in for next week.

[pkra]

@sinabahram I've just pushed a fix for point 2), removing the "more specific" part as discussed. I hope this addresses everything. As with the braillelabel, I'd like to first merge before addressing the complex sentence about braille patterns.

[sinabahram]

Does this fix also address points 5 through 8 that were mentioned as being able to be handled before? I still see empty alt text in the code snippet; for example, which makes me think I’m either not looking at the most up to date version or maybe this was not handled in the latest update?

[pkra]

Thanks. 39af2b3 adressed those points.

[sinabahram]

Clearly, I’m doing something wrong, as when I go here: https://raw.githack.com/w3c/aria/39af2b360f4f549166f9ca7189ddcb8ec191f7f7/index.html#aria-brailleroledescription I see the same code snippet from before with that Jupiter button having the empty alt on the button, which is my way of checking if I’m looking at the right version or not. I went to the PR. I selected to show all the changes, not just one from a single commit, and I then selected raw, and simply changed the domain to raw.githack.com to view it in the browser. Not sure what I’m missing here ….

[carmacleod]

@sinabahram We use pr-preview on this repo, so the easiest way to see a current preview is to look for a link called "Preview" and a link called "Diff" that are automatically generated (and kept up-to-date) by a friendly bot and inserted at the end of the initial comment. HTH!

[pkra]

@sinabahram sorry, I misunderstood your earlier question. Let me know if there's anything else I can do to make review easier.

[sinabahram]

That is super helpful RE diff and preview links, thank you. Here is the link I am now looking at: https://pr-preview.s3.amazonaws.com/pkra/aria/pull/1097.html#aria-brailleroledescription here is the source code I see in that Jupiter example: <button aria-roledescription="planet" aria-brailleroledescription="pln" id="jupiter" aria-label="jupiter"> <img alt="" src="images/jupiter.jpg"/> </button> As I now have mentioned several times, that still has ‘alt=””’. Am I just completely failing at GitHub at this point, or is that still there, even though it’s supposed to be filled in and aria-label removed as has been confirmed by @pkra patiently multiple times now? I also note that I see more commits listed on the PR than I do in that comment, and furthermore, the last edit by PR bot was back in January 16, not when @pkra’s last comment was. This has surpassed frustrating into silly, so I apologize if I’m failing at the most basic aspect of review *sheepish smile*. I welcome any advice on what I’m doing wrong.

[pkra]

@sinabahram thanks for taking the time to go through it again. I'm afraid I misread an earlier comment of yours.

Originally, your review had pointed out extra backslashes in the code sample, in particular the alt text. I had addressed this by removing the backslashes. Now I see that later on you pointed out empty alt-text which I completely misread, thinking of the backslash issue.

Perhaps I can pretend to have an excuse since the sample is based on your playground repo. In any case, the button has an aria-label so it seems to me the img might have an empty alt. But I don't mind changing it.

Let me know what you'd prefer.

[sinabahram]

Well, it seems like we should change it, as that’s the right thing to do, from what I know from graceful degradation or progressive enhancement, whichever way we wish to look at it. I think not relying on ARIA wherever possible is accepted as the defacto approach, but I’m happy to be educated on this. And RE that code from the workshop, I think we actually had to do that to make up for an NVDA bug or something, can’t remember, but it would definitely be good not to propagate that workaround, and I may just be misremembering it. Also, everything else looks fine, since I’ve now read it like 5 times, 😊.

[pkra]

@sinabahram I've updated the code sample (and re-applied a commit that was on the wrong branch on my end).

[pkra]

Oh, posting just as you approved. Thanks!

[sinabahram]

I've approved the changes. We are good to go on this one.

[pkra]

Just to link this here as well: #1205 has been opened to improve the note.