<!DOCTYPE html>
<!-- ========================================== kroc camen of camen design ============================================= -->
<title>code · Me, Myself and I — or: Abbreviations, Definitions &amp; Citations Revisited</title>
<link rel="stylesheet" type="text/css" href="/design/design.css" />
<meta name="viewport" content="width=device-width, maximum-scale=1.0, user-scalable=no" />
<link rel="alternate" type="application/rss+xml" href="/code/rss" title="Just code" />
<link rel="canonical" href="/code/abbr_redux" />
<!-- =================================================================================================================== -->
<header>
	<h1><a href="/" rel="index">
		Camen Design
	</a></h1>
	<nav><ul>
		<li><a href="/">all</a></li>
		<li><a href="/projects">projects</a></li>
		<li><a href="http://forum.camendesign.com">forum</a></li>
	</ul><ul>
		<li><a href="/quote/">quote</a></li>
		<li><a href="/writing/">writing</a></li>
		<li><a href="/blog/">blog</a></li>
		<li><a href="/photo/">photo</a></li>
		<li><a href="/code/" rel="tag">code</a></li>
		<li><a href="/art/">art</a></li>
		<li><a href="/link/">link</a></li>
		<li><a href="/poem/">poem</a></li>
		<li><a href="/audio/">audio</a></li>
	</ul><ul>
		<li><a href="/web-dev/">web-dev</a></li>
		<li><a href="/annoyances/">annoyances</a></li>
		<li><a href="/eve/">eve</a></li>
		<li><a href="/code-is-art/">code-is-art</a></li>
		<li><a href="/inspiration/">inspiration</a></li>
		<li><a href="/windows/">windows</a></li>
		<li><a href="/gift/">gift</a></li>
		<li><a href="/gaming/">gaming</a></li>
		<li><a href="/mac/">mac</a></li>
		<li><a href="/osnews/">osnews</a></li>
		<li><a href="/c64/">c64</a></li>
		<li><a href="/linux/">linux</a></li>
	</ul>
	<a rel="previous" href="/code/website_optimisation_measures">
		older article →
	</a><a rel="next" href="/code/remarkable">
		← newer article
	</a></nav>
</header>
<!-- =================================================================================================================== -->
<article><header>
	<!-- date published or updated -->
	<time pubdate datetime="2010-08-15T13:53:00+01:00">
		<sup>1:53<abbr>pm</abbr> • 2010</sup>
		<abbr title="August">Aug</abbr> 15
	</time>
	<!-- categories -->
	<ul>
		<li><a href="/code/abbr_redux" rel="bookmark tag">code</a></li>
		<li><a href="/code-is-art/abbr_redux">code-is-art</a></li>
		<li><a href="/web-dev/abbr_redux">web-dev</a></li>
	</ul>
	<!-- licence -->
	<small>
		<a rel="license" href="http://creativecommons.org/licenses/by/3.0/deed.en_GB">c</a>
		share + remix
	</small>
</header>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<section>
<h1>Me, Myself and I — or:<br />Abbreviations, Definitions &amp; Citations Revisited</h1>
<ol>
	<li>
		<a href="#abbr">The Abbreviation Element</a>
		<ol>
			<li><a href="#abbr-rules">Rules for Using <code>&lt;abbr&gt;</code></a></li>
		</ol>
	</li><li>
		<a href="#dfn">The Definition Element</a>
		<ol>
			<li><a href="#dfn-rules">Rules for Using <code>&lt;dfn&gt;</code></a></li>
		</ol>
	</li><li>
		<a href="#cite">The Citation Element</a>
		<ol>
			<li><a href="#cite-rules">Rules for Using <code>&lt;cite&gt;</code></a></li>
		</ol>
	</li>
</ol>
<p>
	<strong>In three years of writing these elements continue to confuse me.</strong> 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.
</p><p>
	I started <a href="/code/using-abbr"><cite>How To Use <code>&lt;abbr&gt;</code> In HTML5, <em>and</em> In
	General</cite></a> 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.
</p><p>
	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.
</p>


<h2 id="abbr">The Abbreviation Element</h2>
<p>
	The HTML5 spec
	<a href="http://www.whatwg.org/specs/web-apps/current-work/#the-abbr-element" rel="external">defines</a>
	<code>&lt;abbr&gt;</code> as: <q>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.</q>
</p><p>
	Note carefully the wording “expansion”. Expansion, not definition. That means that the <code>abbr</code>
	element is ideal for expanding written forms into spoken forms, and this is how I recommend you use it.
</p>

<pre><code>&lt;abbr title="et cetera"&gt;etc.&lt;/abbr&gt;</code></pre>

<p>
	Here we are not <em>defining</em> what <q>etc.</q> means (“and the rest”), we are expanding it into its spoken
	form for readability.
</p><p>
	Use of abbreviations should serve some practical purpose on the page, even if not visible. The biggest problem I ran
	into was using the <code>abbr</code> element for any and every initialism I came across, like “HTML”,
	“CSS”, “PHP” <abbr title="et cetera">&amp;c.</abbr> This only served to benefit OCD rather than readers.
	When you are using “<code>&lt;abbr&gt;HTML&lt;/abbr&gt;</code>” 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.
</p><p>
	For the sake of sanity and to provide simplicity that can be remembered and followed <code>&lt;abbr&gt;</code>
	should be used for one, and only one purpose: to provide a human-speakable form of any <em>phrase</em> or text. Read
	your writing and anywhere the exact words you speak does not match what symbols appear on the page you need an
	<code>abbr</code> element.
</p>

<pre><code>Price &lt;abbr title="does not equal"&gt;!=&lt;/abbr&gt; &lt;abbr title="total cost of ownership"&gt;TCO&lt;/abbr&gt;</code></pre>

<p>
	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.
</p><p>
	What about abbreviations without titles? Where should they be used, if at all? Whilst I have told you to not use
	<code>abbr</code> 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 <code>&lt;acronym&gt;</code> this is the only instance you should use
	<code>abbr</code> without a title to indicate to users and screen readers that the initialism should be pronounced
	rather than spelt out.
</p>

<pre><code>GOOD:	&lt;abbr&gt;PAL&lt;/abbr&gt;, not NTSC.</code></pre>


<h3 id="abbr-rules">Rules for Using <code>&lt;abbr&gt;</code></h3>
<ol>
	<li id="abbr-1">
		<p>
			Do <strong>not</strong> use on initialisms that are spoken letter-by-letter. e.g. “HTML”,
			“CSS”, “PHP”
		</p>
	</li><li id="abbr-2">
		<p>
			Use when something is spoken differently from written<br />
			e.g. “$60/mo” is “<code>$60&lt;abbr title=" per month"&gt;/mo&lt;/abbr&gt;</code>”
		</p>
	</li><li id="abbr-3">
		<p>
			Only use <code>abbr</code> without a title on initialisms that should be pronounced as written
			rather than read out letter-by-letter, e.g. “<code>&lt;abbr&gt;RAID&lt;/abbr&gt;</code>”
		</p>
	</li>
</ol>
<p>
	With these three rules you will save yourself writing more markup than is necessary and give your use of
	<code>abbr</code> a true purpose that encapsulates the human-spoken aspect of your writing.
</p>


<h2 id="dfn">The Definition Element</h2>
<p>
	The
	<a href="http://www.whatwg.org/specs/web-apps/current-work/#the-dfn-element" rel="external"><abbr title="definition"><code>dfn</code></abbr>
	element</a> is under used and <code>abbr</code> is commonly mistaken for it instead. <code>abbr</code> is not for
	defining what an initialism stands for. Don’t ever do this:
</p>

<pre><code>BAD:	I made some &lt;abbr title="American Standard Code for Information Interchange"&gt;ASCII&lt;/abbr&gt; art.</code></pre>

<p>
	If you worry that a term you have used is alien to your users and you should spell it out, use
	<code>&lt;dfn&gt;</code> instead.
</p>

<pre><code>GOOD:	I made some &lt;dfn title="American Standard Code for Information Interchange"&gt;&lt;abbr&gt;ASCII&lt;/abbr&gt;&lt;/dfn&gt; art.</code></pre>

<p>
	<small><abbr title="Note:">NB:</abbr> “ASCII” is wrapped in an abbreviation element because it is an initialism
	that is pronounced as written, rather than spelt out (as per <a href="#abbr-3"><code>abbr</code> rule 3</a>). If
	we were defining “HTML” instead, this would not be the case.</small>
</p><p>
	You don’t have to restrict yourself to just initialisms when using <code>dfn</code>, any term or phrase that
	needs explaining is candidate for <code>dfn</code>. For example:
	<small><em>(<a href="http://www.acepilots.com/bard/ws_word_f.html" rel="external">source</a>)</em></small>
</p>

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

<p>
	That’s literally all there is to it!
</p>


<h3 id="dfn-rules">Rules for Using <code>&lt;dfn&gt;</code></h3>
<ol>
	<li id="dfn-1">
		<p>
			The title of a <code>dfn</code> element is not part of the reading flow like <code>abbr</code>,
			it is more like a glossary term—distinct and separate from the content
		</p>
	</li><li id="dfn-2">
		<p>
			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
		</p>
	</li>
</ol>


<h2 id="cite">The Citation Element</h2>
<p>
	I saved the worst ’till last. The
	<a href="http://www.whatwg.org/specs/web-apps/current-work/#the-cite-element" rel="external">citation element</a>
	encompasses a large amount of terminology in common use:
</p>
<blockquote>
	<p>
		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.
	</p>
</blockquote>
<p>
	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.
</p><p>
	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
	<em>giving credit</em>. This is most evident when quoting something:
</p>

<pre><code>&lt;blockquote&gt;
	&lt;p&gt;
		Here is Edward Bear, coming downstairs now, bump, bump, bump,
		on the back of his head, behind Christopher Robin.
	&lt;/p&gt;
	&lt;cite&gt;Winnie-the-Pooh&lt;cite&gt;, A.A.Milne
&lt;/blockquote&gt;</code></pre>

<p>
	But also applies when naming the title of a book.
</p>

<pre><code>Buy your copy of &lt;cite&gt;The Lion, The Witch and The Wardrobe&lt;cite&gt; here.</code></pre>

<p>
	This is easy with physical things, but what about website names, titles of blog posts, software names?
</p><p>
	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 <code>&lt;cite&gt;</code> in the first place.
</p>


<h3 id="cite-rules">Rules for Using <code>&lt;cite&gt;</code></h3>
<ol>
	<li id="cite-1">
		<p>
			Use <code>cite</code> around only the following: the title of a book (including poems) or comic,
			the title of an online blog / article or document (e.g.
			<a href="http://mozilla.org/about/manifesto.en.html" rel="external">“<cite>Mozilla
			Manifesto</cite>”</a>), the title of a piece of art (including digital), film titles, song /
			album titles
		</p>
	</li><li id="cite-2">
		<p>
			Do not use <code>cite</code> 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
		</p>
	</li><li id="cite-3">
		<p>Remember, above all, that <code>cite</code> is for <em>giving credit</em></p>
	</li>
</ol>

<hr />

<p>
	<strong>I am not an expert grammarian;</strong> 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 <em>several
	thousand</em> needless pieces of markup. From now on, these rules will guide me to use abbreviations, definitions
	and citations sparingly and in a meaningful way.
</p><p>
	These rules do not represent the canon of HTML5 or the markup in general but are instead <em>practical</em>
	guidelines to their usage. Feel free to adapt these rules to your own preferences around syntax, semantics and
	<dfn title="“the endurance of pain or hardship without a display of feelings and without complaint”, i.e. RSI from typing too much markup!">stoicism</dfn>.
</p>

<hr />

<p>
	<strong>If you would like to write less markup,</strong> perhaps consider using
	<a href="/code/remarkable">ReMarkable</a>, my shorthand syntax for writing articles that includes markup for
	<samp>{abbr|abbreviations}</samp>, <samp>{{dfn|definitions}}</samp> and <samp>~citations~</samp> as well as much
	more. You can view the <a href="/code/abbr_redux.rem">original markup for this article</a> as an example.
</p>
</section>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
</article>
<footer>
	<nav><a href="http://forum.camendesign.com">‹ Discuss this in the Forum ›</a></nav>
		
	<a href="mailto:kroc@camendesign.com">kroc@camendesign.com</a>
	<nav>view-source:
		<a href="/code/abbr_redux.rem">Rem</a> •
		<a href="/code/abbr_redux.html">HTML</a> •
		<a href="/design/">CSS</a> •
		<a href="/.system/">PHP</a> •
		<a href="/.htaccess">.htaccess</a>
	</nav>
	<form method="get" action="https://duckduckgo.com">
		<input type="hidden" name="sites" value="camendesign.com" />
		<input type="search" name="q" placeholder="search…" />
		<input type="submit" value="Go" />
	</form>
</footer>
<!-- =================================================================================================== code is art === -->