Revisiting annotation use cases and potential markup

Since we are discussing this tomorrow in the PFWG I thought I would write
up white I've learned discussing this 1 on 1 with a few folks who were
really interested in it, so far. So this is just food for thought for the
discussion tomorrow.

* Annotation use cases and possible markup *

High level questions to think about:


   -

   What is an annotation, vs. a role, vs. a stylistic or decorative piece
   of information? Note that UI Automation supports control types (roles),
   annotations and styles. I suggest that an annotation is something that has
   an in-page link to additional information that is visible within the page.
   -

   Do we need an annotation type at all, or is aria-details enough. I
   suggest that we may want to avoid this at first, and add later if necessary.


High level use cases: document editor, code editor

Specific use cases that have come up (not all of these have turned out to
need new markup): highlight, reference, error, warning, description,
bookmark, suggestion, attribution, edit/history, comment, breakpoint

Markup that has been suggested:

   -

   aria-details to point to in-page related content
   -

   aria-hasannotation or aria-detailstype to say something about an
   optional or required target, e.g. aria-hasannotation="comment". To me, it
   is unclear whether we really should add this kind of markup or not.


The following use cases are probably not annotations:

   -

   highlight  --  author can just use something like role=mark or em/strong
   -

   error, e.g. in code in code editor: use aria-invalid="true" +
   aria-errormessage=id
   -

   warning, e.g. in code editor: ARIA WG may want to add
   aria-invalid="warning" + (like error, also can use aria-errormessage=id)
   -

   bookmark -- not sure how important this is right now, sounds like <a
   name> or @id, which we already have.


The following are annotations:

   -

   comment  -- use aria-details. If we want to specify the type of
   annotation, could use aria-hasannotation="comment"
   -

   suggestion -- this is basically a comment on a change.
   -

      The change can be marked up via ins/del, and surround these with an
      element that has aria-details pointing to a generated comment that
      describes the change, when it happened, who made it, etc.
      -

      There may be an additional comment from a person describing their
      reason for the change
      -

      If want to specify type, use aria-hasannotation="suggestion" --
      unlike comments, suggestions can be accepted or rejected, but can just be
      buttons within the comment
      -

   attribution/edit/history/notice - similar to suggestion -- use <ins>
   and/or <del> with optional software-generated comment, like “Format change
   by Honest Abe”.


Other:

   -

   description -- just use aria-details, not sure there is enough reason
   for a type to differentiate it from other annotations


   -

   reference -- use dpub role=”doc-noteref” from dpub + aria-details
   pointing to the note. Can use role="doc-endnote" or doc-note on the note
   itself.


Unsure:

   -

   breakpoint  in code editor --
   -

      Tends to be a visual button that allows editing of the breakpoint
      conditions. Could use something like role="button" aria-label="breakpoint
      13 enabled" aria-haspopup="list"
      -

      However, also would be good for user to know they entered a
      breakpoint, so entire range of text should be annotated. This one may
      actually be a reason that we want to specify the annotation type
separately
      from aria-details.


Feel free to add your comments or we can just discuss tomorrow in the WG.

Thanks!
Aaron