abbr-design-pattern: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
m (Replace <entry-title> with {{DISPLAYTITLE:}})
 
(37 intermediate revisions by 17 users not shown)
Line 1: Line 1:
= Abbr design pattern =
{{DISPLAYTITLE: abbr design pattern }}
== Purpose ==
Use the [[abbr-design-pattern]] when you have localized, language, or design-specific human readable information that you want to markup and also provide a more globally human and machine readable alternative.


== Purpose ==
* Authors {{mustnot}} use the [[abbr-design-pattern]] to hide data.
* Use the [[abbr-design-pattern]] to make text that is human readable also formally machine readable
* The contents of the <code>&lt;abbr></code> tag's <code>title</code> attribute {{must}} be both human-readable and human-listenable (e.g. for screenreaders), and {{should}} use a globally/internationally human readable format.
* Avoiding using the [[abbr-design-pattern]] to re-encode human text or to hide data
* For dates and times, authors {{should}} use the HTML5 <code>&lt;time></code> element instead of <code>&lt;abbr></code>. (ed: Once common tools like [[chrome-extensions]], [[h2vx]], [[operator]] all support the HTML5 time element, let's upgrade this statement to a {{must}}).


== How to use it ==
== How to use it ==
* enclose the human-friendly text that you want to make machine readable with <code>&lt;abbr></code>  
* enclose the preferred local human readable text that you want to make globally human & machine readable with <code>&lt;abbr></code>  
* as per the [[class-design-pattern]], add the appropriate <code>class</code> attribute to the <code>abbr</code> element
* add the relevant microformats property names to the <code>&lt;abbr></code> tag's <code>class</code> attribute
* add a <code>title</code> attribute to the <code>abbr</code> element with the machine readable data as the value
* add a <code>title</code> attribute to the <code>abbr</code> element with the globally human & machine readable data as the value
* The end result {{must}} be human readable & listenable, when reading/speaking the abbr element's contents and its surroundings ''and'' when reading/speaking the abbr element's title attribute with its surrounding text.


== Example ==
== Example ==
The [[datetime-design-pattern]] formally encodes (the notoriously unparsable) datetimes into an <code>abbr</code> element.
The [[date-design-pattern]] formally encodes globally human readable ISO dates into an <code>abbr</code> element. Per the documentation/research on the [[date-design-pattern]] page, ISO8601 dates, e.g. of the form YYYY-MM-DD, are the most globally/internationally date format.
 
Note: that dates and times {{should}} be marked up with the HTML5 time element. These examples illustrate both span/abbr markup for pre-HTML5 tools, and time element support for HTML5-capable tools.


Before:
Before:


<pre>
<div style="background:#EEE">
The party is at 10 o'clock on the 10th.
<source lang=html4strict style="background:none">
</pre>
The party is on the 10th.
</source>
</div>
 
After:
 
<div style="background:#FFE;border:solid .17em yellow">
<source lang=html4strict>
The party is on <abbr class="dtstart" title="2005-10-10">the 10th</abbr>.
</source>
</div>
 
Better (with HTML5 time instead of abbr)
 
<div style="background:#EFE;border:double .5em green">
<source lang=html4strict>
The party is on <time class="dtstart" datetime="2005-10-10">the 10th</time>.
</source>
</div>
 
You could also use the abbr-design-pattern to markup colloquial time references, but those should also use the HTML5 time element, e.g.
 
Before:
 
<div style="background:#EEE">
<source lang=html4strict>
The party is at 10 o'clock.
</source>
</div>


After:
After:


<pre>
<div style="background:#FFE;border:solid .17em yellow">
The party is at  
<source lang=html4strict>
<abbr class="dtstart" title="20051010T10:10:10-0100">10 o'clock on the 10th</abbr>.
The party is at <abbr class="dtstart" title="10:00">10 o'clock</abbr>.
</pre>
</source>
</div>
 
Better (with HTML5 time instead of abbr)
 
<div style="background:#EFE;border:double .5em green">
<source lang=html4strict>
The party is at <time class="dtstart" datetime="10:00">10 o'clock</time>.
</source>
</div>
 
==Alternative presentations==
Note that the following are all equivalent, to a microformat parser:
 
<div style="background:#FFE;border:solid .17em yellow">
<source lang="html4strict">
<span class="dtstart">2007-05-01</span>
 
<abbr class="dtstart" title="2007-05-01">1 May 2007</abbr>
 
<abbr class="dtstart" title="2007-05-01">1st May 2007</abbr>.
 
<abbr class="dtstart" title="2007-05-01">May 1st 2007</abbr>.
 
<abbr class="dtstart" title="2007-05-01">The first of May, 2007</abbr>.
 
<abbr class="dtstart" title="2007-05-01">2007-05-01</abbr>.
 
<abbr class="dtstart" title="2007-05-01">Tuesday, 1 May 2007</abbr>
 
<abbr class="dtstart" title="2007-05-01">2007, day 121</abbr>
 
<abbr class="dtstart" title="2007-05-01">May Day, 2007</abbr>
 
<abbr class="dtstart" title="2007-05-01" lang="FR">1er mai, 2007</abbr>
 
<abbr class="dtstart" title="2007-05-01" lang="ES">1 de mayo, 2007</abbr>
</source>
 
and the following may be used in, say, a list, table, or page, headed "2007":
 
<source lang=html4strict>
<abbr class="dtstart" title="2007-05-01">1 May</abbr>
</source>
</div>
 
Better (with HTML5 time element)
 
<div style="background:#EFE;border:double .5em green">
<source lang="html4strict">
<time class="dtstart">2007-05-01</time>
 
<time class="dtstart" datetime="2007-05-01">1 May 2007</time>
 
<time class="dtstart" datetime="2007-05-01">1st May 2007</time>.
 
<time class="dtstart" datetime="2007-05-01">May 1st 2007</time>.
 
<time class="dtstart" datetime="2007-05-01">The first of May, 2007</time>.
 
<time class="dtstart" datetime="2007-05-01">2007-05-01</time>.
 
<time class="dtstart" datetime="2007-05-01">Tuesday, 1 May 2007</time>
 
<time class="dtstart" datetime="2007-05-01">2007, day 121</time>
 
<time class="dtstart" datetime="2007-05-01">May Day, 2007</time>
 
<time class="dtstart" datetime="2007-05-01" lang="FR">1er mai, 2007</time>
 
<time class="dtstart" datetime="2007-05-01" lang="ES">1 de mayo, 2007</time>
 
<time class="dtstart" datetime="2007-05-01">1 May</time>
</source>
</div>
 
=== anti-patterns ===
These are all past examples that are usages to '''avoid'''.
 
Authors {{mustnot}} use the <code>abbr</code> element as shown in these examples, as either the element text or the <code>title</code> attribute text are not easily human readable.
 
<div style="background:#FEE;border:dashed .17em red">
<source lang=html4strict>
<span class="dtstart">20070501</span>
<abbr class="dtstart" title="20070501">1 May 2007</abbr>
<abbr class="dtstart" title="20070501">1st May 2007</abbr>.
<abbr class="dtstart" title="20070501">May 1st 2007</abbr>.
<abbr class="dtstart" title="20070501">The first of May, 2007</abbr>.
<abbr class="dtstart" title="20070501">2007-05-01</abbr>.
<abbr class="dtstart" title="20070501">Tuesday, 1 May 2007</abbr>
<abbr class="dtstart" title="20070501">2007, day 121</abbr>
<abbr class="dtstart" title="20070501">May Day, 2007</abbr>
<abbr class="dtstart" title="20070501" lang="FR">1er mai, 2007</abbr>
<abbr class="dtstart" title="20070501" lang="ES">1 de mayo, 2007</abbr>
<abbr class="dtstart" title="20070501">1 May</abbr>
</source>
</div>
 
The lack of dashes in "20070501" makes it read like a large number, not a date, both when viewing it, and when listening to it being read by a screenreader.


== Discussion ==
== Discussion ==
''This discussion is culled from [http://microformats.org/discuss/mail/microformats-discuss/2005-October/001277.html here]''. Consider two possible uses for the [[abbr-design-pattern]]:
=== about datetimes ===
'''Avoid''' using the [[abbr-design-pattern]] for datetimes.


<ol>
E.g. Authors {{must}} avoid doing this:
<li>
using ABBR to encode machine readable data around human readable data


<pre>
<div style="background:#FEE;border:dashed .17em red">
<abbr class="dtstart" title="20051010T10:10:10-0100">10 o'clock on the 10th</abbr>
<source lang=html4strict>
</pre>
<abbr class="dtstart" title="20051012T11:10-0100">10 past 11 o'clock on the 12th</abbr>
</li>
</source>
<li>
</div>
using ABBR to encode more formal human data around something less formal  
 
Ideally use the HTML5 time element:
 
<div style="background:#EFE;border:double .5em green">
<source lang=html4strict>
<time class="dtstart" datetime="2005-10-12T11:10-0100">10 past 11 o'clock on the 12th</time>
</source>
</div>
 
Note the use of the hyphenated date to make it more human readable, as the more readable that even machine data is made, the greater the chance that a human will be able to accurately check it and verify that it matches the locale/language-specific contents of the time element.
 
Alternatively, if the microformats tools you're using don't support HTML5 (yet), you may use the [[value-class-pattern]] with the [[abbr-design-pattern]]:
 
<div style="background:#FFE;border:solid .17em yellow">
<source lang=html4strict>
<span class="dtstart">
<abbr class="value" title="11:10">10 past 11 o'clock</abbr> on  
<abbr class="value" title="2005-10-10">the 10th</abbr>
</span>
</source>
</div>
 
=== informal names ===
Using ABBR to encode more formal human data around something less formal:


<pre>
<source lang=html4strict>
<abbr class="author" title="Danny Ayers">Danny</abbr>  
<abbr class="author" title="Danny Ayers">Danny</abbr>  
</pre>
</source>
</li>
 
</ol>
This use is discouraged under the [http://c2.com/cgi-bin/wiki?DontRepeatYourself Don't Repeat Yourself principle], as it is a case of *more* information being less visibly present, namely, the family name in this case.
If someone is not willing to make some information visible, then we
shouldn't be encouraging them to store that information invisibly or less visibly,
for all the same reasons that invisible metadata is bad/futile in the first place."
 
=== screen readers ===
The <code>title</code> attribute of the <code>&lt;abbr></code> tag {{must}} always be human readable and ''speakable''.
 
Screenreaders such as JAWS and others which use title attributes from abbr, and when used properly (as in this example below from the WCAG group), pronounce words which would otherwise be unreadable or confusing.
 
<source lang=html4strict>
<p>Sugar is commonly sold in 5 <abbr title="pound">lb.</abbr> bags.</p>
<p>Welcome to the <abbr title="World Wide Web">WWW</abbr>!</p>
</source>


Use #1 is encouraged if there's a reasonable need for it. Use #2 is discouraged under the [http://c2.com/cgi-bin/wiki?DontRepeatYourself Don't Repeat Yourself principle], as: "#2 is a case of *more* information being invisibly present, namely, the
If screen readers are unable to turn title content into something comprehensible, this will lead to accessibility failures. Here is a bad example:
last name in this case. If someone is not willing to make some information visible, then we
shouldn't be encouraging them to store that information invisibly, for all
the same reasons that invisible metadata is bad/futile in the first place."


''I'd like to delete this below, as the points are covered above''
<div style="background:#FEE;border:dashed .17em red">
<source lang=html4strict>
we're having a party on
<abbr class="dtstart" title="20070312T1700-06">
March 12, 2007 at 5 PM
</abbr>
</source>
</div>


* Theoretically, this could be done with almost any HTML element. But is it a good idea? If it's not, is abbr the only one? [[DavidJanes]]
would be read by Jaws as
* abbr-design-pattern should be avoided, if possible. [[User:RobertBachmann|RobertBachmann]]
** why, or under what circumstances? For example, it is quite useful with datetimes. Should there not be other potentially analogous situations? [[DavidJanes]]
** Under circumstances where the text in the title would be gobbledegook if read by a screenreader. JAWS and other screenreaders use abbr, when used properly (as in this example from the WCAG group) to pronounce words which would otherwise be unreadable or confusing.


<pre>
<pre>
<p>Sugar is commonly sold in 5 <abbr title="pound">lb.<abbr> bags.</p>
we're having a party on Twenty million seventy-thousand three-hundred twelve tee seventeen-hundred dash zero six.  
<p>Welcome to the <abbr title="World Wide Web">WWW</abbr>!</p>
</pre>
</pre>


A Datetime as a title would not be a good use of abbr, and is using abbr in the wrong direction.
The [http://www.webstandards.org/2007/04/27/haccessibility/ accessibility task force] from webstandards.org recommended:
 
<div style="background:#EEE">
<source lang=html4strict>
<span class="dtstart" title="20070312T1700-06">
March 12, 2007 at 5 PM, Central Standard Time
</span>
</source>
</div>
 
or
 
<div style="background:#EEE">
<source lang=html4strict>
<span class="dtstart">
March 12, 2007 at 5 PM, Central Standard Time
<span class="value" title="20070312T1700-06"></span>
</span>
</source>
</div>
 
But both these approaches are problematic due to the title attribute being not easily human readable/verifiable because of:
* unhyphenated date, e.g. bad: 20070312; good:2007-03-12
* uncoloned time, e.g. bad: 1700; good: 17:00
* timezone offset without minutes, e.g. bad: -06; better: -0600
* combining date, time, and timezone into a single string without human-friendly separators
 
However, based on this input and subsequent research into better alternatives, the microformats community developed the [[value-class-pattern]] with the following two alternatives:
 
<div style="background:#FFE;border:solid .17em yellow">
<source lang=html4strict>
<span class="dtstart">
<abbr class="value" title="2007-03-12">March 12, 2007</abbr>
at <abbr class="value" title="17:00">5 PM</abbr>,
<abbr class="value" title="-0600">Central Standard Time</abbr>
</span>
</source>
</div>
 
or
 
<div style="background:#FFE;border:solid .17em yellow">
<source lang=html4strict>
<span class="dtstart"><span class="value-title" title="2007-03-12T17:00-0600"></span>
March 12, 2007 at 5 PM, Central Standard Time
</span>
</source>
</div>
 
And again, the even better alternative is to use the HTML5 time element:
 
<div style="background:#EFE;border:double .5em green">
<source lang=html4strict>
<time class="dtstart" datetime="2007-03-12 17:00-0600">
March 12, 2007 at 5 PM, Central Standard Time
</time>
</source>
</div>


== See Also ==
== See Also ==
* [[abbr-design-pattern-issues]]
* [[Main_Page#Design_Patterns|All microformat design patterns]]
* [[Main_Page#Design_Patterns|All microformat design patterns]]
* [http://microformats.org/discuss/mail/microformats-discuss/2005-October/001277.html discussion in microformats-discuss]
* [[datetime-design-pattern]] uses [[abbr-design-pattern]]
* [[datetime-design-pattern]] uses [[abbr-design-pattern]]
* [http://www.w3.org/TR/REC-html40/struct/text.html#edef-ABBR HTML 4.01 definition]
* [http://www.w3.org/TR/REC-html40/struct/text.html#edef-ABBR HTML 4.01 definition]

Latest revision as of 16:20, 18 July 2020

Purpose

Use the abbr-design-pattern when you have localized, language, or design-specific human readable information that you want to markup and also provide a more globally human and machine readable alternative.

  • Authors MUST NOT use the abbr-design-pattern to hide data.
  • The contents of the <abbr> tag's title attribute MUST be both human-readable and human-listenable (e.g. for screenreaders), and SHOULD use a globally/internationally human readable format.
  • For dates and times, authors SHOULD use the HTML5 <time> element instead of <abbr>. (ed: Once common tools like chrome-extensions, h2vx, operator all support the HTML5 time element, let's upgrade this statement to a MUST).

How to use it

  • enclose the preferred local human readable text that you want to make globally human & machine readable with <abbr>
  • add the relevant microformats property names to the <abbr> tag's class attribute
  • add a title attribute to the abbr element with the globally human & machine readable data as the value
  • The end result MUST be human readable & listenable, when reading/speaking the abbr element's contents and its surroundings and when reading/speaking the abbr element's title attribute with its surrounding text.

Example

The date-design-pattern formally encodes globally human readable ISO dates into an abbr element. Per the documentation/research on the date-design-pattern page, ISO8601 dates, e.g. of the form YYYY-MM-DD, are the most globally/internationally date format.

Note: that dates and times SHOULD be marked up with the HTML5 time element. These examples illustrate both span/abbr markup for pre-HTML5 tools, and time element support for HTML5-capable tools.

Before: 

The party is on the 10th.

After: 

The party is on <abbr class="dtstart" title="2005-10-10">the 10th</abbr>.

Better (with HTML5 time instead of abbr) 

The party is on <time class="dtstart" datetime="2005-10-10">the 10th</time>.

You could also use the abbr-design-pattern to markup colloquial time references, but those should also use the HTML5 time element, e.g.

Before: 

The party is at 10 o'clock.

After: 

The party is at <abbr class="dtstart" title="10:00">10 o'clock</abbr>.

Better (with HTML5 time instead of abbr) 

The party is at <time class="dtstart" datetime="10:00">10 o'clock</time>.

Alternative presentations

Note that the following are all equivalent, to a microformat parser: 

<span class="dtstart">2007-05-01</span>

<abbr class="dtstart" title="2007-05-01">1 May 2007</abbr>

<abbr class="dtstart" title="2007-05-01">1st May 2007</abbr>.

<abbr class="dtstart" title="2007-05-01">May 1st 2007</abbr>.

<abbr class="dtstart" title="2007-05-01">The first of May, 2007</abbr>.

<abbr class="dtstart" title="2007-05-01">2007-05-01</abbr>.

<abbr class="dtstart" title="2007-05-01">Tuesday, 1 May 2007</abbr>

<abbr class="dtstart" title="2007-05-01">2007, day 121</abbr>

<abbr class="dtstart" title="2007-05-01">May Day, 2007</abbr>

<abbr class="dtstart" title="2007-05-01" lang="FR">1er mai, 2007</abbr>

<abbr class="dtstart" title="2007-05-01" lang="ES">1 de mayo, 2007</abbr>

and the following may be used in, say, a list, table, or page, headed "2007": 

<abbr class="dtstart" title="2007-05-01">1 May</abbr>

Better (with HTML5 time element) 

<time class="dtstart">2007-05-01</time>

<time class="dtstart" datetime="2007-05-01">1 May 2007</time>

<time class="dtstart" datetime="2007-05-01">1st May 2007</time>.

<time class="dtstart" datetime="2007-05-01">May 1st 2007</time>.

<time class="dtstart" datetime="2007-05-01">The first of May, 2007</time>.

<time class="dtstart" datetime="2007-05-01">2007-05-01</time>.

<time class="dtstart" datetime="2007-05-01">Tuesday, 1 May 2007</time>

<time class="dtstart" datetime="2007-05-01">2007, day 121</time>

<time class="dtstart" datetime="2007-05-01">May Day, 2007</time>

<time class="dtstart" datetime="2007-05-01" lang="FR">1er mai, 2007</time>

<time class="dtstart" datetime="2007-05-01" lang="ES">1 de mayo, 2007</time>

<time class="dtstart" datetime="2007-05-01">1 May</time>

anti-patterns

These are all past examples that are usages to avoid.

Authors MUST NOT use the abbr element as shown in these examples, as either the element text or the title attribute text are not easily human readable. 

<span class="dtstart">20070501</span> 
<abbr class="dtstart" title="20070501">1 May 2007</abbr>
<abbr class="dtstart" title="20070501">1st May 2007</abbr>.
<abbr class="dtstart" title="20070501">May 1st 2007</abbr>.
<abbr class="dtstart" title="20070501">The first of May, 2007</abbr>.
<abbr class="dtstart" title="20070501">2007-05-01</abbr>.
<abbr class="dtstart" title="20070501">Tuesday, 1 May 2007</abbr>
<abbr class="dtstart" title="20070501">2007, day 121</abbr>
<abbr class="dtstart" title="20070501">May Day, 2007</abbr>
<abbr class="dtstart" title="20070501" lang="FR">1er mai, 2007</abbr>
<abbr class="dtstart" title="20070501" lang="ES">1 de mayo, 2007</abbr>
<abbr class="dtstart" title="20070501">1 May</abbr>

The lack of dashes in "20070501" makes it read like a large number, not a date, both when viewing it, and when listening to it being read by a screenreader.

Discussion

about datetimes

Avoid using the abbr-design-pattern for datetimes.

E.g. Authors MUST avoid doing this: 

<abbr class="dtstart" title="20051012T11:10-0100">10 past 11 o'clock on the 12th</abbr>

Ideally use the HTML5 time element: 

<time class="dtstart" datetime="2005-10-12T11:10-0100">10 past 11 o'clock on the 12th</time>

Note the use of the hyphenated date to make it more human readable, as the more readable that even machine data is made, the greater the chance that a human will be able to accurately check it and verify that it matches the locale/language-specific contents of the time element.

Alternatively, if the microformats tools you're using don't support HTML5 (yet), you may use the value-class-pattern with the abbr-design-pattern: 

<span class="dtstart">
 <abbr class="value" title="11:10">10 past 11 o'clock</abbr> on 
 <abbr class="value" title="2005-10-10">the 10th</abbr>
</span>

informal names

Using ABBR to encode more formal human data around something less formal: 

<abbr class="author" title="Danny Ayers">Danny</abbr>

This use is discouraged under the Don't Repeat Yourself principle, as it is a case of *more* information being less visibly present, namely, the family name in this case. If someone is not willing to make some information visible, then we shouldn't be encouraging them to store that information invisibly or less visibly, for all the same reasons that invisible metadata is bad/futile in the first place."

screen readers

The title attribute of the <abbr> tag MUST always be human readable and speakable.

Screenreaders such as JAWS and others which use title attributes from abbr, and when used properly (as in this example below from the WCAG group), pronounce words which would otherwise be unreadable or confusing. 

<p>Sugar is commonly sold in 5 <abbr title="pound">lb.</abbr> bags.</p>
<p>Welcome to the <abbr title="World Wide Web">WWW</abbr>!</p>

If screen readers are unable to turn title content into something comprehensible, this will lead to accessibility failures. Here is a bad example: 

we're having a party on 
<abbr class="dtstart" title="20070312T1700-06">
 March 12, 2007 at 5 PM
</abbr>

would be read by Jaws as 

we're having a party on Twenty million seventy-thousand three-hundred twelve tee seventeen-hundred dash zero six.

The accessibility task force from webstandards.org recommended: 

<span class="dtstart" title="20070312T1700-06">
 March 12, 2007 at 5 PM, Central Standard Time
</span>

or 

<span class="dtstart">
 March 12, 2007 at 5 PM, Central Standard Time
 <span class="value" title="20070312T1700-06"></span>
</span>

But both these approaches are problematic due to the title attribute being not easily human readable/verifiable because of:

  • unhyphenated date, e.g. bad: 20070312; good:2007-03-12
  • uncoloned time, e.g. bad: 1700; good: 17:00
  • timezone offset without minutes, e.g. bad: -06; better: -0600
  • combining date, time, and timezone into a single string without human-friendly separators

However, based on this input and subsequent research into better alternatives, the microformats community developed the value-class-pattern with the following two alternatives: 

<span class="dtstart">
<abbr class="value" title="2007-03-12">March 12, 2007</abbr>
 at <abbr class="value" title="17:00">5 PM</abbr>, 
<abbr class="value" title="-0600">Central Standard Time</abbr>
</span>

or 

<span class="dtstart"><span class="value-title" title="2007-03-12T17:00-0600"></span>
 March 12, 2007 at 5 PM, Central Standard Time
</span>

And again, the even better alternative is to use the HTML5 time element: 

<time class="dtstart" datetime="2007-03-12 17:00-0600">
 March 12, 2007 at 5 PM, Central Standard Time
</time>

See Also

Retrieved from "http://microformats.org/wiki/index.php?title=abbr-design-pattern&oldid=69524"