When we think about HTML semantics in 2014, we’re all pretty satisfied with the marks we’ve made.
There is section
, header
, aside
, footer
, main
, and even menu
!
We’ve got everything we need right? Then why are we still doing things like this?
<body class="article">
<div class="content">
Being guilty of this at times while laziness or deadlines got the better of me, I decided to reacquiant myself with the intended uses of our trusty markup standard. What better place to start than the old standby, the div tag. Right away, I saw the note in the spec:
Authors are strongly encouraged to view the div element as an element of last resort, for when no other element is suitable. Use of more appropriate elements instead of the div element leads to better accessibility for readers and easier maintainability for authors.
Off to an agreeably good start, I decided to keep skipping around, and see what
other declarations supported my opinions. Remember thehr
element? Well, it
turns out it’s not just for drawing a chiseled, beveled, or embossed border in
the middle of your screen. It’s actuallyvery semantic.
The hr element represents a paragraph-level thematic break, e.g. a scene change in a story, or a transition to another topic within a section of a reference book.
Whoa. I was really intruiged at this point. I had to learn more! What other assumptions was I using to justify my markup?
How about the humble paragraph element?
The p element should not be used when a more specific element is more appropriate. The following example is technically correct:
<section> <p>Last modified: 2001-04-23</p> <p>Author: fred@example.com</p> </section>
However, it would be better marked-up as:
<section> <footer>Last modified: 2001-04-23</footer> <address>Author: fred@example.com</address> </section>
Or:
<section> <footer> <p>Last modified: 2001-04-23</p> <address>Author: fred@example.com</address> </footer> </section>
Ok, less impressive, but the more appropriate applications of the footer
and
address
tags is cool. Thinking I knew all there was to know about paragraph
semantics, I saw this note in the spec.
The solution is to realise that a paragraph, in HTML terms, is not a logical concept, but a structural one. In the fantastic example [below], there are actually five paragraphs as defined by this specification: one before the list, one for each bullet, and one after the list.
<p>For instance, this fantastic sentence has bullets relating to</p>
<ul><li>wizards,
<li>faster-than-light travel, and
<li>telepathy,</ul>
<p>and is further discussed below.</p>
In other words, “there is no spoon”.
The HTML5 Document Outline, that allows for multiple h1-h6
tags based on
sectioning roots,does not exist.
Is a concept that lives in the HTML specification, but is essentially a fiction in the real world. It is a fiction because user agents have not implemented it and there is no indication that any will. - Steve Faulkner
To be honest, it’s kind of a relief to hear this, because I never felt
comfortable or totally grasped the concept of multipleh1
or h2
elements on
a page. It quickly became unweildy when trying to remember which elements began
a new section context, and how many header elements I’d already used.
Cheers for keeping things simple.
As I’m currently doing research on developer documentation, I thought I’d
look intopre
and code
tags, to be sure I was using them correctly. code
for inline references, like in this paragraph, andpre
for longer,
blockquote
-style code embeds.
Well, those assumptions are mostly true, but as we’ve seen, there is usually
a better, more meaningful element to use. What I found was another pair of
elements that were specifically created for code documentation,kbd
and
samp
. Why these tags are so special to me is that they solve 2 problems:
-
I can now use a semantic element to distinguish between code that the user should enter (
kbd
) and code that a machine outputs (samp
). -
I now have 2 separate CSS hooks to use to help visually distinguish these two pieces of information in documentation.
I’d never seen those applied to documentation markup before, but now I can’t imagine not using them.
If we want to get really descriptive, there are a couple more elements we can leverage for both machine and human-readable code markup.
The var
tag can be used for marking up variables in code, and the
data
element is used to delineate pure data, such as the values needed
in tabular information.
You might be asking what the data
element offers over data-*
attributes.
With thedata
element’s value
attribute present, browsers will someday be
able to use it with thesortable
attribute of the table
element to
provide a mechanism for authors and users tosort tables.
Note: Browser support for the table sorting model very hard to come by, and
I've yet to see a working example. Plus, the HTML 5.1 DOM API spec on it is kind
of a mess, but when it does make it into in the wild, make sure you add the
aria-sort
role to the appropriate table header element. (Thanks to
Ray Camden for shedding some light.)
Another highly useful element in code documentation semantics is the figure
element, and it can be used for much more than screenshots.
The figure element represents some flow content, optionally with a caption, that is self-contained (like a complete sentence) and is typically referenced as a single unit from the main flow of the document.
Notice nothing about images specifically was mentioned. The spec then goes on
to demo a code snippet marked up with figure
.
<p>In <a href="#l4">listing</a> we see the primary core interface
> API declaration.</p>
<figure id="l4">
<figcaption>Listing 4. The primary core interface API declaration.</figcaption>
interface PrimaryCore {
boolean verifyDataLine();
void sendData(in sequence<byte> data);
void initSelfDestruct();
}
</figure>
<p>The API is designed to use UTF-8.</p>
Wow, that totally makes sense, doesn’t it? Think about how many books you’ ve read that havethis little figure element off to the side to point out a detail about a code snippet.
My favorite HTML element, and in my opinion, the most underrated element in the
spec, is the decription list
(dl
). It’s intended for marking up name-value pairs of content. This
could apply to anything from a list of services offered and their accompanying
descriptions, to a simple ‘previous article/next article’ component, like the
one at the bottom of every article on my blog here. It’s perfect for documenting
a page’s edit history, causes and effects, or, surprisingly, any list data that
needs a group heading. I had no idea before reading the spec, but it’s entirely
valid to have onedt
(decription term) and multiple dd
s (description
definitions). Here’s a great example from the spec, marking up variations in
spelling across the English language, though the definition is the same.
<dl>
<dt lang="en-US"> <dfn>color</dfn> </dt>
<dt lang="en-GB"> <dfn>colour</dfn> </dt>
<dd> A sensation which (in humans) derives from the ability of
the fine structure of the eye to distinguish three differently
filtered analyses of a view. </dd>
</dl>
Astute readers and fellow HTML nerds may be wondering about the rarely-seen
dfn
element and where it fits into the semantic uses of description
lists. Adfn
is the element the spec describes as: “the defining instance of
a term”. In combination with theabbr
and a
elements, one can provide a
really nice UX for finding the first instance of a definiton. See this example
from the spec:
In the following fragment, the term “Garage Door Opener” is first defined in the first paragraph, then used in the second. In both cases, its abbreviation is what is actually displayed.
<p>The <dfn><abbr title="Garage Door Opener">GDO</abbr></dfn>
is a device that allows off-world teams to open the iris.</p>
<!-- ... later in the document: -->
<p>Teal'c activated his <abbr title="Garage Door Opener">GDO</abbr>
and so Hammond ordered the iris to be opened.</p>
With the addition of an a element, the reference can be made explicit:
<p>The <dfn id=gdo><abbr title="Garage Door Opener">GDO</abbr></dfn>
is a device that allows off-world teams to open the iris.</p>
<!-- ... later in the document: -->
<p>Teal'c activated his <a href=#gdo><abbr title="Garage Door Opener">GDO</abbr></a>
and so Hammond ordered the iris to be opened.</p>
If you’ve ever read an ebook that has footnote or index functionality, this is exactly the same idea.
While there is still work to be done on the available semantics and appropriate uses of markup, it’s nice to know that we have more to work with than we sometimes allow ourselves to believe.
In my next post, we’ll dive deeper into the HTML of tomorrow, and what it would look like if it were designed today.