W3C home > Mailing lists > Public > www-qa@w3.org > August 2003

Re: how should RFC 2119 text be rendered?

From: Dominique HazaŽl-Massieux <dom@w3.org>
Date: 18 Aug 2003 17:44:31 +0200
To: pat hayes <phayes@ihmc.us>
Cc: www-qa@w3.org, lesch@w3.org
Message-Id: <1061221472.4430.19.camel@stratustier>
(sorry for the long delay to this reply, I meant to reply a long time
ago).

Le jeu 12/06/2003 ŗ 21:52, pat hayes a ťcrit :
> I have a style question regarding how best to render RFC2119 meanings 
> in HTML documents.
> 
> http://www.w3.org/TR/2003/WD-qaframe-spec-20030210/ section 1.6 says:
> "The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY ", and "OPTIONAL" will be 
> used as defined in RFC 2119 [RFC2119] . When used with the normative 
> RFC2119 meanings, they will be all uppercase. Occurrences of these 
> words in lowercase comprise normal prose usage, with no normative 
> implications. "

Note that this only concerns the usage of RFC keywords in specGL, not
the usage mandated by specGL for other specifications. The relevant part
for the latter says:
"""
Checkpoint 13.1. Use conformance key words.
Conformance requirements: the specification MUST use RFC 2119 keywords
to denote whether or not requirements are mandatory, optional, or
suggested.
Rationale: Using these keywords helps to identify the testable
statements in a specification.
"""
http://www.w3.org/TR/2003/WD-qaframe-spec-20030210/#Ck-use-keywords

It does not insist on uppercase/lowercase.

> I would normally understand this to mean that these keywords should 
> appear in a document in visible uppercase. However, section 9.7 of 
> http://www.w3.org/Guide/pubrules  says:

It's actually the Manual of Style [1], not the pubrules. Note that the
Manual of Style is only a set of guidelines, it's not enforced (nor is
SpecGL, at least as of today).

> and the recommended styling removes the uppercase from the view of 
> the document as seen in most browsers, so it is impossible for a 
> reader to see whether the word is being used normatively or normally 
> (with emphasis).

The idea is that the emphasis indicates the normativity of the words.
And the key here is that if you use RFC keywords that way, you will have
a section of your document that declares it using the same markup, and
hence the same aspect. Note that the uppercase choice in RFC 2119 is
related to the regular format of RFC as text/plain, where HTML has much
more possibilities of expressivity.

> So, which is it? MAY what the reader sees on their screen look like 
> lowercase italic, or MUST it look like uppercase Roman?

It MAY look like lowercase italic, provided that you declare it that way
(in my understanding). FWIW, the QA WG didn't have any strong consensus
toward one solution or the other.

Dom

[1] http://www.w3.org/2001/06/manual/#RFC
-- 
Dominique HazaŽl-Massieux - http://www.w3.org/People/Dom/
W3C/ERCIM
mailto:dom@w3.org

Received on Monday, 18 August 2003 11:44:33 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Sunday, 6 December 2009 12:14:00 GMT