

{	"date"		:	201008132033,
	"updated"	:	201008151353,
	"licence"	:	"cc-by",

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


*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 (//> ``<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 ~~~>

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 ~~~>


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 ~~~>

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 (//> 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 ~~~>

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

~~~ HTML ~~~>

(({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 (//>)_))

~~~ HTML ~~~>

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

The Citation Element (#cite)
I saved the worst ’till last. The <citation element (//> encompasses a large amount of terminology in common use:

|	an exhibition, a legal case report, etc). This can be a work that is being quoted or referenced in detail



~~~ HTML ~~~>
		on the back of his head, behind Christopher Robin.

But also applies when naming the title of a book.

~~~ HTML ~~~>


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~” (//>),

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.