Re: WAI-ARIA Graphics Module

I've filled out the remaining role descriptions and created examples for
each.  Most of the examples are separate files (SVG or HTML).  I embed
these as objects to provide a figure showing the result of the code.

Here's my current draft on rawgit, jumping straight to section 4 (Graphics
Roles):

   - https://rawgit.com/AmeliaBR/aria/aria-graphics/aria/graphics.html#roles

That's a fork of the main repo under my account.  I've submitted a pull
request, but recommended that it be pulled as a separate branch so that the
issues below can be worked on before merging into the main repo or Rich's
changes.  If you think that's unncecessary, merge away.  Either way,
whoever accepts the pull request, please reply to this message with the new
URL that people should be using.

Below I outline the main changes and issues up for debate.

There are now six roles listed:

   - "figure" is pretty much as we've discussed it.  The description is
   based heavily on the HTML 5 figure element spec, with influence from the
   ARIA region role.
      - The example uses an HTML figure with an SVG that has labelled
      sub-figures.

      - "graphicaldoc" (graphical document) and "graphicalobject"
   (graphical object) represent the structured graphic / structured image
   category.  I found that I could explain the purpose more clearly by
   breaking it apart into the two use cases:
      - The graphical doc role would be for a large document section for
      which layout has semantic meaning.  This is the role we would
sub-class for
      chart, map, etc.
      - The example uses a simple electrical circuit diagram

      - The graphical object role would be for a cluster of elements that
   together make up a meaningful whole (but you still want the ability to
   navigate sub-components as accessible objects).  This is the role we would
   sub-class for chart-axis, map-legend, etc.  I specifically call out the
   difference from a group of distinct but related objects.
   - The example is something fun, inspired by Chaals' brainstorming
      example of a child's drawing of a house.

      - "iconbutton" is my name for the icon role.  We can switch back to
   just "icon" if others prefer to keep it short, but I thought a more
   explicit role name might be helpful.
      - I've got some short code snippet examples, but not complete
      embedded files.

      - "img" is an edited version of the text from ARIA 1.1 for the img
   role.  I've added extra sentences distinguishing an img from the other
   graphics roles.
      - The main substantive change is that I've added a SHOULD statement:
      an image should have a complete description.  This is because we now have
      separate roles (symbol and text) for the main use cases for
images where a
      single alt text attribute is sufficient.
      - I've also added an example, an HTML document with inline SVG, where
      each <svg> element acts as an atomic image.

      - "symbol" is pretty much as we have discussed it.  I added a
   sentence referencing
      - I've got a few examples of symbols in HTML and SVG, including a
      re-use of the electrical circuit diagram, and an adaptation of Fred's
      blueprint diagram showing electrical outlets in a room (Fred: I added a
      door to the room.  I thought a room with no windows or doors, but six
      electrical outlets, was a little too philosophical.)

Some general / stylistic comments and remaining issues:

   - I've used semantic linebreaks [1] within the text descriptions.  Some
   of the existing text used automatically wrapping lines, some used hard
   breaks which were too long for my screen.  If we can try to be consistent
   with breaking lines at natural phrases, it will be easier to track edits
   made by different users.

   - As we discussed, I added informative notes with fallback roles after
   each description.  I also used these fallback roles in the examples.

   - I dropped the "g-" prefix for the role names because I found it
   cumbersome and confusing.  Unlike the dpub roles, I don't see a purpose in
   calling these roles out separately.  We want these roles to be integrated
   in with core ARIA roles like group and img.  When we start creating complex
   chart taxonomies, then it would make sense to create a separate namespace
   of roles, since they would be used in specific combinations.  Of course,
   I'm open to counter arguments.

   - For the examples, if I was using SVG title and desc elements, I didn't
   add aria-labelledby and aria-describedby pointing to them (since you
   shouldn't need to!).  This means that Internet Explorer is probably the
   only current browser that will present the full names and descriptions to a
   screen reader (even if it does so with the fallback roles).

   - Where I've included an embedded object as a figure for an example, the
   object element is included inside the <pre> block that defines the
   example.  If there is a better markup for this, please send me a link to
   the syntax.  Or change it yourself and save me the trouble!

   - I was not able to get the automatic cross-references to the main ARIA
   spec working.  I'm currently just using the <rref> and <pref> shorthand
   markup, which creates empty links to non-existent definitions on the same
   page.  If anyone wants to go in and fix this, please do.

   - I haven't touched the introductory sections, since Rich was going to
   work on those & I didn't want to cause a merging mess.

Best,
Amelia

[1]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/