Are there standard HTML or ARIA things I can do to make that possible?

Do you have a screen shot (good) and/or some example HTML content (even better) that is a prototypical example of these areas?

Created attachment 156553 [details]
Screenshot of note

I'll give you both. Attaching the screenshot, and here's the HTML:

<div class="note">
  <div class="inner">
    <div class="contents">
      <p class="p">You must have the <span class=" sys">telepathy-idle</span>
      package installed in order to use IRC in <span class="app">Empathy</span>.</p>
    </div>
  </div>
</div>

There are three wrapper divs here. The "note" div wraps the whole note. The "inner" div wraps everything. It's there so that the position of the note graphic can be set correctly in RTL locales. (It's set as a background image). The "contents" div only wraps the normal text contents, which for this note is everything. But if this note had a title, it would be outside "contents", and look something like this:

<div class="note">
  <div class="inner">
    <div class="title">Install <span class="sys">telepathy-idle</span></div>
    <div class="contents">
      <p class="p">You must have the <span class=" sys">telepathy-idle</span>
      package installed in order to use IRC in <span class="app">Empathy</span>.</p>
    </div>
  </div>
</div>

At the moment, if you were to add a title attribute to the paragraph, the title text would be exposed as the accessible description. Then a screen reader could* present that attribute.

Of course, it would probably make more sense to associate the title attribute with the div to which it applies. Right now, were you to do so, WebKitGtk would not include the div in the accessible hierarchy. If an element has a title attribute, however, WebKitGtk should include it no matter waht. Therefore, I've opened the following WebKitGtk bug: https://bugs.webkit.org/show_bug.cgi?id=36371

*Tip: (Or Warning:) At the moment, there is no Orca script for WebKitGtk content in general or Yelp in particular. That means that even after this issue is addressed in WebKitGtk and in Yelp, Orca still will not announce it.

Notes can have multiple paragraphs, or any other block content. If I set the title on the first paragraph, I'd think that would confuse users. And if I set it on all of them, I'd think that would annoy them. So, yeah, I can definitely put the right HTML stuff in, if we have good support for it.

What would we like as a title? Is it enough to just say "Note"? Note that we have a few different types of notes. What I posted was a basic note. There's also advanced, important, tip, and warning. And I was thinking of adding a special note type for package installation notes like this one.

Thanks Shaun! The support will be in place between now and then. :-) And done sooner rather than later.

As for what the title should be.... I think it should correspond to whatever the background image is. In other words, whatever I would infer about the nature of the content by looking at the image, it would be nice to present to the user. (Does that make sense?)

Sure, that makes sense. So a short title like "Note" or "Advanced" is good enough? If we get this in before I get a designer to draw me an advanced icon, we could end up with the accessible information being better than the visual cue. :)

Also, will titles work in Gecko? Is it worth me pushing it into 2.30.1? I already have the strings "Note", "Important", "Tip", and "Warning" in gnome-doc-utils, so I could get titles on those four without a string freeze break. And since I don't even have an icon for advanced (and I don't think we use it anywhere yet), I could just call those the generic "Note" to avoid adding a string.

(In reply to comment #7)
> Sure, that makes sense. So a short title like "Note" or "Advanced" is good
> enough?

I think it's not just good enough; I think it's appropriate. Longer titles merely delay the user from accessing the desired content, namely the text.

(In reply to comment #8)
> Also, will titles work in Gecko?

Gecko tends to derive the accessible name from the title attribute (which is not always ideal). What it would do in this particular case (i.e. for an object of ATK_ROLE_SECTION) -- and what Orca would do in response -- is something I would need to investigate further.

> Is it worth me pushing it into 2.30.1?

I don't believe it would hurt anything if you feel like doing so.

Implemented for both DocBook and Mallard in yelp-xsl git master.