This is a document written using ReMarkable, a shorthand syntax for generating HTML.

{	"date"		:	200809251233,
	"updated"	:	200810011126,
	"licence"	:	"cc-by",
	"tags"		:	["code-is-art", "web-dev"]
}

<section>
# How To Use {``<abbr>``|The “abbr” Element} In HTML5, _and_ In General #

*Warning:* This article is now obsolete, please read the new article <Abbreviations, Definitions & Citations Revisited (/code/abbr_redux)>.

							* * *

*Before I begin*, I should profess that I am completely accountable for having never followed any of these rules in the past. However, the whole reason for writing this article was to solve that problem. Since moving to my <new website back-end (/code/uth5_new-website-ish)>, I decided to go through the entire site’s contents with a fine brush and polish all of the code.

In doing that, I discovered how vague I was on the semantics of the ``abbr`` element, and working through all the test-cases that have sprung up in the wealth of HTML I’ve written for this site, I’ve documented here my new understanding of the often-abused ``abbr`` element.


Ⅰ. Abbreviations _are not_ Dictionary Definitions (#abbr-not)
============================================================================================================================
Let’s first define «abbreviation» clearly:

|	An abbreviation is where you have shortened one or more words into:¬
|	either one word, or an alternative phrase or acronym
|
| Kroc Camen

The problem with the use of {``<abbr>``|the “abbr” element} so far, has been that developers have assumed that every abbreviation and acronym has had to be defined in full. This is incorrect.

~~~ HTML ~~~>
BAD:	I made some <abbr title="American Standard Code for Information Interchange">ASCII</abbr> art.
<~~~

An ``abbr`` element expands its contents into the desired spoken form. When you read a document, you naturally expand the abbreviations as appropriate in your mind.

~~~ HTML ~~~>
GOOD:	Red <abbr title="versus">vs.</abbr> Blue
<~~~

You would not read out aloud the abbreviated “et cetera” in “Granny went to the market and bought apples, bread & milk etc.” as _“eee-tee-see”_? So as it should be with HTML abbreviations. Here are some examples:

~~~ HTML ~~~>
BAD:	My <abbr title="Cascading Style Sheets">CSS</abbr> is tweaked almost daily.
GOOD:	My <abbr title="style sheet">CSS</abbr> is tweaked almost daily.
<~~~

Here we’ve used the ``abbr`` element to span over an abbreviation and provide an alternative, natural way of reading the abbreviation.

~~~ HTML ~~~>
GOOD:	price <abbr title="does not equal">!=</abbr> <abbr title="total cost of ownership">TCO</abbr>
<~~~

We have adapted something unpronounceable as letters into something perfectly readable.

In general, abbreviations should maintain the grammar. Whilst not necessary, this example demonstrates how grammatical flow can be improved, whilst also expanding a Latin abbreviation:

~~~ HTML ~~~>
Along the way, open-source has forgotten what it really means (<abbr title="that is,">i.e.</abbr> in real life) to give.
<~~~

Try and communicate your intentions. If you would personally read something one-way, define the abbreviation how you intend it to be read:

~~~ HTML ~~~>
Switch to using the <abbr title="“wizzy-wig”">WYSIWYG</abbr> editor, instead.
<~~~

In the example below however, there’s an abbreviation «CDs» inside the abbreviation title:

~~~ HTML ~~~>
<abbr title="recordable CDs">CD-Rs</abbr> and <abbr title="recordable DVDs">DVD±Rs</abbr> are susceptible to literal bit-rot.
<~~~

Isn’t this wrong? No, because remember that the point of abbreviations are to expand one phrase into another. The user is assumed to already know what a CD is, it doesn’t have to be spelt out for them.¬
¬
This follows neatly into the next point: when and where to expand abbreviations at all…


Ⅱ. The ``title`` Attribute Is _Optional_ (#abbr-title)
============================================================================================================================
Oh man, this is so important. The misuse of the ``abbr`` element is because almost everybody is under the assumption that ``abbr`` elements _must_ have a ``title`` attribute, in fact— it’d seem pointless otherwise!

|	Your users do not need to know the definition of every single acronym and abbreviated technical term.
|	In fact, they don’t care. They don’t have to know what the «V» in DVD stands for if they know a DVD when
|	they see one.
|
|	Only title abbreviations that you expect people to read as the expanded form in their mind, or out aloud.
|
| Kroc Camen

An ``abbr`` element _without_ a ``title`` attribute should be used on any abbreviation / acronym that is written in all-capitals (unless you are providing a spoken alternative, like the «WYSIWYG» example from earlier), to communicate that the abbreviation is either unpronounceable as a word, or that it is capitalised—not for emphasis—but because each letter has an individual meaning. {E.g.|For example,}

~~~ HTML ~~~>
The <abbr>FBI</abbr> are like the British <abbr>MI5</abbr>.
<~~~


Ⅲ. Citations _are not_ Abbreviations (#abbr-cite)
============================================================================================================================
This one is very sneaky and can easily catch you out.

~~~ HTML ~~~>
BAD:	The site will be built using <abbr title="Hypertext Pre-Processor">PHP</abbr>.
<~~~

Firstly, this reads wrong; the abbreviation breaks the grammar. Secondly, remember that abbreviations are to communicate how things should be read, not to define terms.

But thirdly, it is not an abbreviation. It is not a section of the document that has been shortened or re-phrased by the author to fit their chosen grammar. It is not a personal rendering of words. The sentence is referring to a software product. This is a <citation (//www.whatwg.org/specs/web-apps/current-work/#the-cite)>.

~~~ HTML ~~~>
GOOD:	The site will be built using <cite>PHP</cite>.
<~~~

Even though a cited name can be an abbreviation of something else, the name seals that abbreviation and turns that name into a real word of sorts (a brand). Names that are already made from an abbreviation, can then even be abbreviated! (since they behave as normal words) For example “Mac OS X” is already an abbreviation of “Macintosh Operating System version Ten”, and people then often abbreviate further, calling it “OS X” or by referring to the version number / name “10.5 / Leopard”.


What counts as a citation? (#abbr-cite-what)
----------------------------------------------------------------------------------------------------------------------------
A citation represents the title of a work, where you are referring to it in the context of your sentence, or in passing. A work is defined as an intellectual human creation.

A work can be a _book_, a _poem_, a published piece of _writing_, a _piece of art_, a _website_, a _song_, a _film_, a _TV show_, a _game_ {&c.|et cetera} and also _software_.

However this does not include the following: _people’s names_, the name of a _ship_ or real products in general; such as a _packet of crisps_, a _stereo_ or _computer hardware_.


There are exceptions (#abbr-cite-except)
----------------------------------------------------------------------------------------------------------------------------
I won’t go into details, but there are exceptions here and there, that mostly lie around the context; whereby you are either referring to the citation itself, or the use of that work in a specific case - particularly with broadly used technologies like HTML, CSS and PHP.

~~~ HTML ~~~>
I am referring directly to the <cite>PHP</cite> language/technology.
My website’s <abbr>PHP</abbr> is small.
<~~~

That said, details like this will boil down to personal taste, and it’ll never really hurt to just stick to using one element or the other for all such instances, regardless.


Ⅳ. Abbreviations Should Be Meek (#abbr-meek)
============================================================================================================================
An abbreviation is merely anything that is read different from how it is written and vice-versa. It does not need to be in your face, Javascript-powered, “intelli-text”.


What if the reader does not know what a technical abbreviation / acronym means? (#abbr-unknown)
----------------------------------------------------------------------------------------------------------------------------
Isn’t the point of an ``abbr`` element so that these technical terms can be defined by hovering the mouse over the term?¬
¬
There’s two valid answers to this:

#	That’s what the <{``<dfn>``|definition} element (//www.whatwg.org/specs/web-apps/current-work/#the-dfn)> is for, and…
#	It is not your responsibility to be an encyclopædia.¬
	Being paranoid about your reader’s abilities is just going to make your life difficult

|	You, the author, only have to take the responsibility to know your audience and define those terms which you think
|	they won’t know, or that you may be newly introducing to them.
|
| Kroc Camen

If a user does not know a term, your website is not the only resource in existence where they can then find the definition! The user can easily google the term. In many browsers they can just right-click the word and choose to search the ’Web for it. On a Mac, there’s a system-wide integrated dictionary you can access in a number of ways. There is no end to the ways a user can find out what a term means if they need to.


How to style your abbreviations (#abbr-style)
----------------------------------------------------------------------------------------------------------------------------
The traditional way to style abbreviations is a grey dotted line, like so:

~~~ CSS ~~~>
abbr	{border-bottom: 1px solid #666;}
<~~~

However, this was under the previous model of using ``abbr`` as some kind of inline dictionary. Abbreviations are for the benefit of screen readers, search engines and enthusiasts like me. Generally, abbreviations shouldn’t be styled at all.

That said, abbreviations still do provide a useful service by allowing readers to uncover how something should be read. We need a subtle approach that doesn’t fill the user’s screen with grey dotted lines, but at the same time does allow them to discover where you’ve provided reading “hints”.

The method I’m using is to only show the grey-dotted underline when the user’s mouse is within the paragraph containing the abbreviations, so that when the user moves their mouse into the surrounding text, the abbreviations (with titles) will be marked, and the user can hover over them to then see the tooltip.

~~~ CSS ~~~>
*:hover>abbr[title]	{border-bottom: 1px dotted #666; cursor: help;}
<~~~

((Update: The above code only works with abbreviations directly within paragraphs, if the ``abbr`` element is wrapped in a link or any other kind of tag, the grey dotted line won’t appear until you hover directly over it. The new CSS below fixes this: _
(where «``section``» is the element/ID containing your blog posts)))

~~~ CSS ~~~>
/* first, the immediate descendants of the content area are set to highlight abbreviations on hover, but avoiding lists; as I don’t want *all* abbreviations highlighted when you hover on a root list… */
section>*:not(ol):not(ul):not(dl):hover abbr[title],
/* …only when hovering on each list-item */
 p:hover abbr[title], li:hover abbr[title], dl>*:hover abbr[title] {
	border-bottom: 1px dotted #666; cursor: help;
}
<~~~

							* * *

*I hope* this article provides with some practical guidance and enthusiasm.

If you spot any flaws in the HTML of my articles, please do contact me and let me know, I’ve got so many thousands of lines I’m sure to have made mistakes everywhere. Also you’re free to <e-mail me (mailto:kroc@camendesign.com)> if you’ve any questions about this article and using ``abbr``, ``cite`` and HTML5 in general.

Special thanks goes to Adam of <firsttube.com> for reviewing the article whilst it was being prepared and spotting a number of flaws.

</section>