[rfc-i] Is there a use case for 2119 keyword markup?

"Martin J. Dürst" duerst at it.aoyama.ac.jp
Mon Jun 23 01:51:20 PDT 2014


(Sorry for being late to this thread :-). Here's another example of 
using 2119 keyword markup, just for your reference:

http://www.w3.org/TR/charmod/
(Character Model for the World Wide Web 1.0: Fundamentals)

See in particular http://www.w3.org/TR/charmod/#sec-Checklist.

This is the HTML output of some XML source that I should be able to dig 
up if anybody is interested. It marks up RFC 2119 keywords, but goes 
further along what Larry has proposed and marks up the sentences 
(conformance criteria) and also collects them in an appendix.

It also categorizes the requirements by whether they apply to spec(s) 
(writers), to implementations, or to content. That's rather specific to 
the architectural nature of this spec. The numbers aren't autogenerated 
(and not consecutive), because we didn't want the numbers to move around.

In hindsight, we probably went a bit too far, but if it has helped an 
reader in any way, then I hope it was time well spent. It also helped us 
a lot to get clarity on what we meant, which was particularly difficult 
and important for this subject matter.

Regards,   Martin.

On 2014/06/19 13:05, Tony Hansen wrote:
> On 6/18/14, 4:50 PM, Heather Flanagan (RFC Series Editor) wrote:
>> Hello rfc-interest,
>>
>> A question came up recently regarding whether there were any serious use
>> cases around semantically marking up RFC 2119 keywords (when used _as_
>> keywords) in the new format.
>>
>> In the HTML draft, it says:
>> 3.3.1.  Requirement Keywords
>>
>>     The RFC2119 keywords in the document will be set off with special
>>     markup.  They are surrounded with a <span> element containing the CSS
>>     class rfc2119.  For example:
>>
>>     They <span class='rfc2119'>MUST</span> be surrounded
>>
>> For this to happen, we need to add something to the XML vocabulary as
>> well.  Does anyone have a use case where this kind of markup would be
>> useful, or is it just a "nice to have, because we can, but not if it
>> increases the overall cost of creating RFCs"?
>
> I'll give an example of where markup of 2119 keywords has been used
> successfully:
>
> The HTTPbis documents that were recently published were written in a
> slight variant of the V2 xml2rfc language. If you take a look at
> http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p1-messaging-26.xml
> you'll find a series of  entity definitions at the top:
>
>    <!ENTITY MAY "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>MAY</bcp14>">
>    <!ENTITY MUST "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>MUST</bcp14>">
>    <!ENTITY MUST-NOT "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>MUST NOT</bcp14>">
>    <!ENTITY OPTIONAL "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>OPTIONAL</bcp14>">
>    <!ENTITY RECOMMENDED "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>RECOMMENDED</bcp14>">
>    <!ENTITY REQUIRED "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>REQUIRED</bcp14>">
>    <!ENTITY SHALL "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>SHALL</bcp14>">
>    <!ENTITY SHALL-NOT "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>SHALL NOT</bcp14>">
>    <!ENTITY SHOULD "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>SHOULD</bcp14>">
>    <!ENTITY SHOULD-NOT "<bcp14
> xmlns='http://purl.org/net/xml2rfc/ext'>SHOULD NOT</bcp14>">
>
> Then within the document, the entities &MAY;, &MUST;, etc. are used
> wherever the 2119 keywords should be used.
>
> If you look at the author's HTML version of that spec,
> http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p1-messaging-26.html, you'll
> see that the <bcp14/> extension has rendered the keywords in SMALL CAPS,
> which is slightly different than the surrounding text, just enough so
> it's obvious that these are the keywords and yet not so much different.
>
> One of the items that is being discussed for the HTML rendering of RFCs
> is the ability to replace the CSS with your own CSS. Having the keywords
> marked up semantically allows the keywords to be displayed in various
> different ways, depending on which CSS has been used. This would allow
> us to have tools that help highlight where the 2119-keyed requirements
> are located, and otherwise get out of the way. But it DOES require
> having the semantic information available within the XML.
>
>      Tony Hansen
>
>
>
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>


More information about the rfc-interest mailing list