Theresa O’Connor

Revisiting RFC 2119 markup

Earlier this month, I proposed some HTML for marking up RFC 2119’s language for expressing requirement levels. In reply, Tantek recently pointed me at the relevant section of the W3C’s manual of style, in which they lay out how the W3C marks these terms out:

<em title="MUST in RFC 2119 context"
       class="RFC2119">MUST</em>

.RFC2119 {
  text-transform: lowercase;
  font-style: italic;
}

There are several differences between this approach and mine. The first difference to note is the use of <em> and not <strong>.

I chose to use <strong> because I remembered that the current HTML 5 draft drew a distinction between “emphasis” and “importance,” and that the draft has <em> increase the emphasis of its content, while <strong> increases the importance. It seemed to me that normative text is more important than the other kinds of text in a specification, so <strong> seemed a natural fit.

Of course, I hadn’t actually gone back to read the relevant sections of the HTML 5 draft. Had I, I would have chosen differently. Here’s what HTML 5 has to say about emphasis and importance (emphasis—and importance—mine):

Changing the importance of a piece of text with the strong element does not change the meaning of the sentence.

The placement of emphasis changes the meaning of the sentence. The [em] element thus forms an integral part of the content. The precise way in which emphasis is used in this way depends on the language.

So the distinction HTML 5 draws makes it clear that <em> is preferable in this case: the whole point of using “RFC 2119 ‘should’” instead of “ordinary English ‘should’” is precisely to change the meaning of the sentence.

So I recommend the use of <em> to mark up the use of RFC 2119 words in text.

The second difference to note is that W3C says to make them UPPERCASE, and to downcase them with CSS. This has the advantage that text-mode browsers, and browsers not supporting CSS, display RFC 2119 terms in uppercase, which is customary and helps to distinguish “RFC 2119 ‘should’” from “ordinary English ‘should.’”

Nevertheless, I suspect constantly writing these things in uppercase may be too high a burden to place on authors, and might harm readability. For instance, the current HTML 5 draft does not place RFC 2119 terms into uppercase. That being said, the class name RFC2119 works well as a way of marking the use of these words, so I’m adopting it as well.

Note that the RFC2119 class name is orthogonal to my defined class nameRFC2119 is specific to the use of RFC 2119 terminology, whereas defined is a general tool, for whenever you use a term defined with <dfn> elsewhere on the page. So I’m using both class names.

The final difference is the @title W3C places on the <em>. I think this is a pretty good idea, but might be overly burdensome on authors. Personally, I don’t expect to use it regularly. If your authoring environment automates this sort of thing, like the microformats wiki’s templates for this, great—@title away!