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

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

<section>
# Me, Myself and I — or:¬Abbreviations, Definitions & Citations Revisited #

&__TOC__;

*In three years of writing these elements continue to confuse me.* Well, it’s not that they confuse me, but that I come across so many examples of their use that I always feel like a clear definition is right on the tip of my tongue but I can never grasp it clearly.

I started <~How To Use ``<abbr>`` In HTML5, _and_ In General~ (/code/using-abbr)> by admitting that I had to write it because I wasn’t clear myself on the optimum use of these elements. I now have to say that that article is also wrong and it’s time once again to explore my increased understanding.

The rules presented here are my own personal best practices designed to be easy to remember, implement and to serve practical purposes rather than markup for markup's sake. They are, in my opinion, the most elegant and clear guidelines on the use of these elements on the Internet.


The Abbreviation Element (#abbr)
============================================================================================================================
The HTML5 spec <defines (//www.whatwg.org/specs/web-apps/current-work/#the-abbr-element)> ``<abbr>`` as: «an abbreviation or acronym, optionally with its expansion. The title attribute may be used to provide an expansion of the abbreviation. The attribute, if specified, must contain an expansion of the abbreviation, and nothing else.»

Note carefully the wording “expansion”. Expansion, not definition. That means that the ``abbr`` element is ideal for expanding written forms into spoken forms, and this is how I recommend you use it.

~~~ HTML ~~~>
<abbr title="et cetera">etc.</abbr>
<~~~

Here we are not _defining_ what «etc.» means (“and the rest”), we are expanding it into its spoken form for readability.

Use of abbreviations should serve some practical purpose on the page, even if not visible. The biggest problem I ran into was using the ``abbr`` element for any and every initialism I came across, like “HTML”, “CSS”, “PHP” {&c.|et cetera} This only served to benefit OCD rather than readers. When you are using “``<abbr>HTML</abbr>``” what exactly are you saying? It says that this is an abbreviation of some sort but initialisms are not spoken in any other way than they are written, because the letters are capitalised it is already evident that that it is an abbreviation and should be read letter-by-letter. Therefore marking this up does not help authors, screen readers, browsers or users. It’s obsessive markup and nothing else.

For the sake of sanity and to provide simplicity that can be remembered and followed ``<abbr>`` should be used for one, and only one purpose: to provide a human-speakable form of any _phrase_ or text. Read your writing and anywhere the exact words you speak does not match what symbols appear on the page you need an ``abbr`` element.

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

Here, the expansion of TCO is not to define it for those not in the know, it is to shape the spoken form into a more natural and flowing style that is easier on the ears than “price exclamation mark equals tee see oh” and is how I would personally read this aloud to others who didn't have the text to hand.

What about abbreviations without titles? Where should they be used, if at all? Whilst I have told you to not use ``abbr`` for capitalised initialisms read letter by letter, there are initialisms that should be read as they are written--acronyms. "RAID" for example, despite being capitalised like "HTML" should not be read as "Arr aye eye dee". Because HTML5 removed ``<acronym>`` this is the only instance you should use ``abbr`` without a title to indicate to users and screen readers that the initialism should be pronounced rather than spelt out.

~~~ HTML ~~~>
GOOD:	<abbr>PAL</abbr>, not NTSC.
<~~~

Rules for using ``<abbr>`` (#abbr-rules)
----------------------------------------------------------------------------------------------------------------------------
1. (#abbr-1)	Do *not* use on initialisms that are spoken letter-by-letter. e.g. “HTML”, “CSS”, “PHP”

2. (#abbr-2)	Use when something is spoken differently from written _
		e.g. “$60/mo” is “``$60<abbr title=" per month">/mo</abbr>``”

3. (#abbr-3)	Only use ``abbr`` without a title on initialisms that should be pronounced as written rather than read out
		letter-by-letter, e.g. "``<abbr>RAID</abbr>``"

With these three rules you will save yourself writing more markup than is necessary and give your use of ``abbr`` a true purpose that encapsulates the human-spoken aspect of your writing.


The Definition Element (#dfn)
============================================================================================================================
The <{``dfn``|definition} element (//www.whatwg.org/specs/web-apps/current-work/#the-dfn-element)> is under used and ``abbr`` is commonly mistaken for it instead. ``abbr`` is not for defining what an initialism stands for. Don't ever do this:

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

If you worry that a term you have used is alien to your users and you should spell it out, use ``<dfn>`` instead.

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

(({NB:|Note:} "ASCII" is wrapped in an abbreviation element because it is an initialism that is pronounced as written, rather than spelt out (as per <``abbr`` rule 3 (#abbr-3)>). If we were defining "HTML" instead, this would not be the case.))

You don't have to restrict yourself to just initialisms when using ``dfn``, any term or phrase that needs explaining is candidate for ``dfn``. For example: ((_(<source (//www.acepilots.com/bard/ws_word_f.html)>)_))

~~~ HTML ~~~>
"My hounds are bred out of the Spartan kind, so <dfn title="flews: pendulous or overhanging lateral parts of the upper lip of dogs, especially prominent in hounds">flew'd</dfn>" [Shakespeare].
<~~~

That's literally all there is to it!

Rules for using ``<dfn>`` (#dfn-rules)
----------------------------------------------------------------------------------------------------------------------------
1. (#dfn-1)	The title of a ``dfn`` element is not part of the reading flow like ``abbr``, it is more like a glossary
		term--distinct and separate from the content

2. (#dfn-2)	Do not restrict yourself to just initialisms! Be helpful when terminology is being introduced for the first
		time or when context plays a key role in the meaning of terms


The Citation Element (#cite)
============================================================================================================================
I saved the worst ’till last. The <citation element (//www.whatwg.org/specs/web-apps/current-work/#the-cite-element)> encompasses a large amount of terminology in common use:

|	The cite element represents the title of a work (e.g. a book, a paper, an essay, a poem, a score, a song, a script,
|	a film, a TV show, a game, a sculpture, a painting, a theatre production, a play, an opera, a musical,
|	an exhibition, a legal case report, etc). This can be a work that is being quoted or referenced in detail
|	(i.e. a citation), or it can just be a work that is mentioned in passing.

In one article I might reference various pieces of software (an electronic ‘work’) such as Flash, QuickTime, Firefox, Safari and so on almost a hundred times. This is too much to be marking up every single time a noun that falls into these categories turns up. It really doesn’t distinguish any meaning to do that.

It gets confusing very quickly as to what counts as a citation and what doesn’t especially with digital works. After tiring of writing hundreds of inane cite elements and constantly struggling to classify what falls into the category or not, I decided that in order for citations to be meaningful in your writing they should be about _giving credit_. This is most evident when quoting something:

~~~ HTML ~~~>
<blockquote>
	<p>
		Here is Edward Bear, coming downstairs now, bump, bump, bump,
		on the back of his head, behind Christopher Robin.
	</p>
	<cite>Winnie-the-Pooh<cite>, A.A.Milne
</blockquote>
<~~~

But also applies when naming the title of a book.

~~~ HTML ~~~>
Buy your copy of <cite>The Lion, The Witch and The Wardrobe<cite> here.
<~~~

This is easy with physical things, but what about website names, titles of blog posts, software names?

The rules I have adopted are specifically to be simple enough to remember, not full of confusing edge cases and quandaries, and to provide clarity and purpose for using ``<cite>`` in the first place.

Rules for using ``<cite>`` (#cite-rules)
----------------------------------------------------------------------------------------------------------------------------
1. (#cite-1)	Use ``cite`` around only the following: the title of a book (including poems) or comic, the title of an
		online blog / article or document (e.g. <“~Mozilla Manifesto~” (//mozilla.org/about/manifesto.en.html)>),
		the title of a piece of art (including digital), film titles, song / album titles

2. (#cite-2)	Do not use ``cite`` around the name of software (that’s a rabbit-hole you don’t want to go into),
		website names, names of programming languages, computer games

3. (#cite-3)	Remember, above all, that ``cite`` is for _giving credit_


							* * *

*I am not an expert grammarian;* these rules are personal preferences born out of the tens of thousands of lines I have written on this website over the last three years. I have tried to take all the edge cases I have come across and hone the use of these elements down to clear and concise usage. In writing this article I have gone back and used search and replace to update my site to follow these rules and have removed _several thousand_ needless pieces of markup. From now on, these rules will guide me to use abbreviations, definitions and citations sparingly and in a meaningful way.

These rules do not represent the canon of HTML5 or the markup in general but are instead _practical_ guidelines to their usage. Feel free to adapt these rules to your own preferences around syntax, semantics and {{stoicism|“the endurance of pain or hardship without a display of feelings and without complaint”, i.e. RSI from typing too much markup!}}.

							* * *

*If you would like to write less markup,* perhaps consider using <ReMarkable (/code/remarkable)>, my shorthand syntax for writing articles that includes markup for `{abbr|abbreviations}`, `{{dfn|definitions}}` and `~citations~` as well as much more. You can view the <original markup for this article (/code/abbr_redux.rem)> as an example.

</section>