Fun With Keyword Markup

Jere Käpyaho

The keywords defined in RFC 2119 are often used in specifications to indicate the normativity of requirements to the implementation. It seems useful to mark them up semantically so that it becomes easier to harvest sentences in the specification that contain mandatory or optional requirements.

This article looks at ways of presenting the keyword markup in HTML using CSS styles, and augmenting the presentation using JavaScript and the DOM.

Basic Keyword Markup and Styling

Since HTML does not have a dedicated element for RFC 2119 keywords, an easy replacement is to mark them up with a harmless inline element like <span>, which does not change the presentation in any way unless explicitly requested, using a CSS stylesheet. Of course, a <span> element has multiple uses, so it seems sensible to distinguish between RFC 2119 keyword spans from other spans by using the class attribute.

The markup for keywords could be as simple as:

<span class="keyword">MUST</span>

It then becomes easy to assign a presentation the keywords using a CSS style rule, such as:

.keyword {
    text-transform: uppercase;
    font-weight: bold;
}

Using .keyword instead of span.keyword as the selector is almost a matter of preference, but it is slightly more flexible. Note that the presentation could be anything you like. Here the text is transformed into uppercase, just in case [sic] you forgot to write it in ALL CAPS as it is generally done.

Using a style rule beats manual markup as <strong> or even (shudder) <b>. You can change the presentation at any time by simply changing the style rule.

The Standard Keyword Meanings

If you use the RFC 2119 keywords as they are explained in, well, RFC 2119, you should include the following boilerplate text (again, from RFC 2119) in your specification text:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Of course, you should also mark up the keywords in the boilerplate text with the keyword markup described above, so that they get the same presentation as their actual occurrences. It often helps to distinguish them from the normal uses of these words, although the most unambiguous way is to write the text so that these "loaded" words only appear in their RFC 2119 meaning. It takes some practice, but it can be achieved. In this document I have actually included a style rule exactly as the one found above, and I have marked up the keywords in the boilerplate text with the span elements.

The meanings of the RFC 2119 keywords are very clearly stated in the RFC text itself, but unless you have memorized them, you will need to check back with the RFC text very often. Since the meanings are not expected to change overnight, you might as well copy them into your document (some may find this objectionable, but let's see how this turns out first).

• This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
• This phrase, or the phrase "SHALL NOT", mean that the definition is an absolute prohibition of the specification.
• This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
• This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
• This word, or the adjective "OPTIONAL", mean that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)

(The keyword legends are actually in this document, right before this paragraph inside a <ul> element, but they are not displayed.) However, if you just slap them somewhere, you will have to go back and forth in your document, between the keyword occurrence and its explanation. Wouldn't it be nice if you could see the meaning of the keyword right there on the spot? Maybe that could be arranged with the help of JavaScript and the DOM.

Little JavaScript Helpers

A well-known use of JavaScript is to manipulate the contents of the document and its visibility using the Document Object Model (DOM). It turns out we can do tricks with the <span> elements and make them adopt the legends automatically.

The first thing we can try is to assign title attributes to the span elements and use the keyword legends as the value. Most browsers present the title attribute as a "tooltip" that hovers above the element for some system-determined time. It is not an ideal solution, as the tooltip could go away before the user has had time to read the whole legend, but it is a start. You may already have parked your pointer on one of the keywords, and if your browser renders the title element as a tooltip, you have seen one. Let's see how it was done.

NOTE: This is a work in progress! It is not finished yet!