Add mark role

[aleventhal]

Closes issue #508

---

Preview | Diff

[joanmarie]

Nit: We need to add the role to the role categorization. See the bulleted lists found in https://w3c.github.io/aria/#roles_categorization

[aleventhal]

@joanmarie @jnurthen I've updated the PR to match the HTML spec text and add mark to the role categorization section.

[joanmarie]

See inline comment about breaking up definition into more than one paragraph.

[carmacleod]

The HTML text for mark element is pretty obscure without examples. (i.e. why "one document"? And the "previously unexpected scrutiny" sentence is really long...):

The mark element represents a run of text in one document marked or highlighted for reference purposes, due to its relevance in another context.

When used in a quotation or other block of text referred to from the prose, it indicates a highlight that was not originally present but which has been added to bring the reader's attention to a part of the text that might not have been considered important by the original author when the block was originally written, but which is now under previously unexpected scrutiny. When used in the main prose of a document, it indicates a part of the document that has been highlighted due to its likely relevance to the user's current activity.

I kinda preferred the original description:

A mark contains a run of content, marked or highlighted to indicate that other content refers to it, or to indicate special relevance to the user's current activity.

Or the "similar to HTML but more clearly written" MDN text for mark element:

The HTML <mark> element represents text which is marked or highlighted for reference or notation purposes, due to the marked passage's relevance or importance in the enclosing context.

Typical use cases for <mark> include:

• When used in a quotation (<q>) or block quote (<blockquote>), it generally indicates text which is of special interest but is not marked in the original source material, or material which needs special scrutiny even though the original author didn't think it was of particular importance. Think of this like using a highlighter pen in a book to mark passages that you find of interest.
• Otherwise, <mark> indicates a portion of the document's content which is likely to be relevant to the user's current activity. This might be used, for example, to indicate the words that matched a search operation.

If we keep the HTML description, it really needs to be clarified with an example or two.

[aleventhal]

@joanmarie Can you offer guidance on these remarks? I agree with Carolyn that the original HTML spec text is not ideal. I don't think the MDN text is ideal either. @anyone feel free to suggest some text.

The HTML text for mark element is pretty obscure without examples. (i.e. why "one document"? And the "previously unexpected scrutiny" sentence is really long...):

The mark element represents a run of text in one document marked or highlighted for reference purposes, due to its relevance in another context.
When used in a quotation or other block of text referred to from the prose, it indicates a highlight that was not originally present but which has been added to bring the reader's attention to a part of the text that might not have been considered important by the original author when the block was originally written, but which is now under previously unexpected scrutiny. When used in the main prose of a document, it indicates a part of the document that has been highlighted due to its likely relevance to the user's current activity.

I kinda preferred the original description:

A mark contains a run of content, marked or highlighted to indicate that other content refers to it, or to indicate special relevance to the user's current activity.

Or the "similar to HTML but more clearly written" MDN text for mark element:

The HTML <mark> element represents text which is marked or highlighted for reference or notation purposes, due to the marked passage's relevance or importance in the enclosing context.
Typical use cases for <mark> include:

• When used in a quotation (<q>) or block quote (<blockquote>), it generally indicates text which is of special interest but is not marked in the original source material, or material which needs special scrutiny even though the original author didn't think it was of particular importance. Think of this like using a highlighter pen in a book to mark passages that you find of interest.
• Otherwise, <mark> indicates a portion of the document's content which is likely to be relevant to the user's current activity. This might be used, for example, to indicate the words that matched a search operation.

If we keep the HTML description, it really needs to be clarified with an example or two.

[carmacleod]

Not gonna lie, I thought my text was shorter and more to the point.

Yep. :)

But it's probably clearer overall to consistently copy over the exact HTML spec text

Not sure... and what if it changes? Maintenance hassle...

I was caught off guard by the stuff about in a quotation vs prose.

I was caught off guard by "a run of text in one document", which would naturally be followed by
"... in another document", but instead is followed by "... in another context".
I would change "document" to "context".

I also liked the MDN idea of breaking up that dense HTML paragraph into a list of "Typical use cases".

And I found the analogy, "Think of this like using a highlighter pen in a book to mark passages that you find of interest.", quite helpful.

[joanmarie]

I personally like the MDN text. What do others think?

[aleventhal]

@joanmarie @jnurthen @carmacleod How about this? It is quite similar to the MDN text.

[carmacleod]

Nice! I like it. Only a couple of nits, mentioned above.

[aleventhal]

@carmacleod Thanks, good catches. What do you think now?

[carmacleod]

+1
Ship it! :)

[joanmarie]

LGTM. Thanks!