Subject: RFC2119 keywords

From: Marc Blanchet <[email-masked]>
Date: Wed, 02 Feb 2011 09:12:33 -0500

Hello,
  almost all drafts copy the following 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 ...
"
and also add a reference to RFC2119.

Instead of copying all the time, and given that everybody knows this 
stuff, why don't we instead put this text or reference it in the 
document boilerplate generated by xml2rfc or else?

Marc.
-- 
=========
IPv6 book: Migrating to IPv6, Wiley. http://www.ipv6book.ca
Stun/Turn server for VoIP NAT-FW traversal: http://numb.viagenie.ca
DTN Implementation: http://postellation.viagenie.ca
NAT64-DNS64 Opensource: http://ecdysis.viagenie.ca

---

From: Andrew Sullivan <[email-masked]>
Date: Wed, 2 Feb 2011 10:31:17 -0500

> document boilerplate generated by xml2rfc or else?

For xml2rfc, I think a directive would be needed.  It shouldn't be in
every draft -- there are drafts that don't have it or, more often,
include it and don't actually use any of the keywords.

A

-- 
Andrew Sullivan
[email-masked]
Shinkuro, Inc.

---

From: "Richard L. Barnes" <[email-masked]>
Date: Wed, 2 Feb 2011 10:35:35 -0500

You could also define an entity in the DTD, assuming that the reference would be in the <references>.

<!ENTITY rfc2119 '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 in RFC 2119 <xref target="RFC2119"></xref>.'>

<section title="Terminology">
&rfc2119;
</section>

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 02 Feb 2011 11:50:58 -0500

> include it and don't actually use any of the keywords.

Maybe a directive that says, in effect, "include that boilerplate and 
reference *if* any of those words appear in the document".

	Thanks,
	Paul

---

From: "David Harrington" <[email-masked]>
Date: Wed, 2 Feb 2011 12:19:25 -0500

I think this is better handled by the human editor, using a directive.
It only needs to be added once per document.

dbh 

> -----Original Message-----
> From: [email-masked] 
> [mailto:[email-masked]] On Behalf Of Paul Kyzivat
> Sent: Wednesday, February 02, 2011 11:51 AM
> To: [email-masked]
> Subject: Re: RFC2119 keywords
> 
> 
>

---

From: [email-masked] (Scott O. Bradner)
Date: Wed, 2 Feb 2011 12:22:28 -0500 (EST)

> reference *if* any of those words appear in the document".

case sensitive (not included for "must" but included if "MUST")

Scott

---

From: Joe Touch <[email-masked]>
Date: Wed, 02 Feb 2011 09:45:16 -0800

> case sensitive (not included for "must" but included if "MUST")

Hi, Scott (et al.),

FWIW, the text I've been using for a while in the .doc template is as 
follows, to avoid the lowercase being misinterpreted as 2119-related:

----
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 [RFC2119].
In this document, these words will appear with that interpretation 
only when in ALL CAPS. Lower case uses of these words are not to be 
interpreted as carrying RFC-2119 significance.
----

I also include the following convention to help people actually find 
such keyword statements, which I try very hard to list as single 
bullets, rather than in running text:

----
In this document, the characters ">>" preceding an indented line(s) 
indicates a compliance requirement statement using the key words 
listed above. This convention aids reviewers in quickly identifying   or 
finding the explicit compliance requirements of this RFC.
----

Joe

---

From: [email-masked] (Scott O. Bradner)
Date: Wed, 2 Feb 2011 12:46:40 -0500 (EST)

> interpreted as carrying RFC-2119 significance.

agree - done that myself

---

From: Loa Andersson <[email-masked]>
Date: Wed, 02 Feb 2011 18:51:00 +0100

"MUST NOT" and "must not" is OK, but "MUST not" is not

/Loa

---

From: Joe Touch <[email-masked]>
Date: Wed, 02 Feb 2011 09:57:21 -0800

FWIW, I prefer that use of 2119 language is deliberate, so "must not" 
doesn't carry any particular importance to me - which is why I use the 
sentence below to be very clear on that point.

I can add "Lower case and mixed case uses of these words..." to handle 
the case you raise, if needed.

Joe

---

From: Olafur Gudmundsson <[email-masked]>
Date: Wed, 02 Feb 2011 13:02:09 -0500

> document boilerplate generated by xml2rfc or else?

Related question, is there a reason to list the words that do not
appear in the document?
To me the list in each document should only reflect the words used.
I would like xml2rfc generate this just like table of contents.
To accomplish this we may need to use something like &MUST each time we 
want to use a 2119 word.
A further advantage of this is when/if we move from TXT as the output
we can have the 2119 MUST show up differently than plain MUST.

	Olafur

---

From: [email-masked] (Scott O. Bradner)
Date: Wed, 2 Feb 2011 13:03:54 -0500 (EST)

> Related question, is there a reason to list the words that do not

(as the author of 2119) - no
but the suggested wording in 2119 is inclusive

Scott

---

From: "Dan Wing" <[email-masked]>
Date: Wed, 2 Feb 2011 10:06:26 -0800

> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of Marc Blanchet
> Sent: Wednesday, February 02, 2011 6:13 AM
> To: Working Group Chairs
> Subject: RFC2119 keywords
> 
> Hello,

That text is missing the "NOT RECOMMENDED" keyword.  See
http://www.rfc-editor.org/errata_search.php?eid=499

-d

---

From: [email-masked] (Scott O. Bradner)
Date: Wed, 2 Feb 2011 13:07:31 -0500 (EST)

> That text is missing the "NOT RECOMMENDED" keyword. 

correct - you can not imagine how many times I've been told that :-)

Scott

---

From: "Dan Wing" <[email-masked]>
Date: Wed, 2 Feb 2011 10:24:18 -0800

> Behalf Of Scott O. Bradner
> Sent: Wednesday, February 02, 2011 10:08 AM
> To: [email-masked]; [email-masked]; [email-masked]
> Subject: RE: RFC2119 keywords
> 

:-)

-d

---

From: John C Klensin <[email-masked]>
Date: Wed, 02 Feb 2011 13:35:44 -0500

--On Wednesday, February 02, 2011 10:31 -0500 Andrew Sullivan
<[email-masked]> wrote:

>> Instead of copying all the time, and given that everybody
>> knows this   stuff, why don't we instead put this text or
>> reference it in the   document boilerplate generated by
>> xml2rfc or else?
> 
> For xml2rfc, I think a directive would be needed.  It
> shouldn't be in every draft -- there are drafts that don't
> have it or, more often, include it and don't actually use any
> of the keywords.

The added advantage of doing something directive-like is that,
despite widely-adopted habits, pushback from nits checkers,
etc., the use of those definitions for those terms is still not
mandatory.

   john

---

From: Adam Roach <[email-masked]>
Date: Wed, 02 Feb 2011 13:27:50 -0600

> (as the author of 2119) - no

The i-d submission tool recently started complaining if you don't use 
the exact, EXACT 2119 language. I had a tailored version of that text 
that only mentioned the actual terms used in the document, and i-d 
submission refused to let it go through.

So Scott's "no" is more philosophical than real. As a practical matter, 
it seems the tools are forcing the answer to be "yes."

/a

---

From: [email-masked] (Scott O. Bradner)
Date: Wed, 2 Feb 2011 14:29:09 -0500 (EST)

> So Scott's "no" is more philosophical than real.

correct

it is my opinion of how things should work

Scott

---

From: John C Klensin <[email-masked]>
Date: Wed, 02 Feb 2011 15:16:14 -0500

--On Wednesday, February 02, 2011 13:27 -0600 Adam Roach
<[email-masked]> wrote:

>>> Related question, is there a reason to list the words that
>>> do not appear in the document?
> The i-d submission tool recently started complaining if you
> don't use the exact, EXACT 2119 language. I had a tailored
> version of that text that only mentioned the actual terms used
> in the document, and i-d submission refused to let it go
> through.
> 
> So Scott's "no" is more philosophical than real. As a
> practical matter, it seems the tools are forcing the answer to
> be "yes."

If anyone cares enough, there should probably be forceful
pushback on any provisions of those tools that enforce rules
that derive neither from from formal community consensus nor
from IESG statements to which the community had an opportunity
to object.  Especially for I-Ds, flexibility for authors to make
sensible decisions is really an important asset.

That said, I have personally have other windmills with which to
do battle and am perfectly welcome to do manual submissions if
the tools get in my way.

    john

---

From: James Carlson <[email-masked]>
Date: Wed, 02 Feb 2011 17:37:07 -0500

> sensible decisions is really an important asset.

For what it's worth (and it may not be much, as we're really talking
about minutiae here), I happen to like the insistence on the exact 2119
wording.  Having exactly the same wording in each document means that I
don't have to refer back to some author's quirky definition of the
keywords when reading a document.  If I encounter "RECOMMENDED," it
means the same thing everywhere, and I don't have to go check whether
this particular author happened to elide it from the list or (worse)
gave it different meaning.

The only way to go one better would be to remove this and other silly
boilerplate from all RFCs, and simply have a single "#include" for all
of it.  But that's obviously "impossible" in a world of laws and
regulations.  :-/

-- 
James Carlson         42.703N 71.076W         <[email-masked]>

---

From: Andrew Sullivan <[email-masked]>
Date: Wed, 2 Feb 2011 17:51:10 -0500

> sensible decisions is really an important asset.

Since this is now actually kind of back on topic for wgchairs, that
was the reason I replied in the first place, and it's tightly linked
to my usual complaint that the idnits process is about form, not
content.

I think as WG chairs, we ought to be concerned that process rules and
bureaucratic efficiency are gradually encroaching on the ability to
get work done easily and swiftly.  I find it not a little ironic that
old-fashioned tools like *roff -- or just an Emacs formatting
template, for all that -- are increasingly putting out formally
correct but idnits-rejected drafts because the tools are being tested
not against a spec, but against an implementation.  Given our usual
rules for protocols, that says something very bad about where our
values really lie.  I personally find xml2rfc easier to use than the
alternatives (although still much harder than, say, a well-designed
LaTeX style); but I see no reason why I need repeatedly to explain to
people who have been producing RFCs for 25 years why their template
suddenly doesn't work even though they have all the right boilerplate.

A

-- 
Andrew Sullivan
[email-masked]
Shinkuro, Inc.

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Thu, 03 Feb 2011 00:53:25 -0500

On Wed, 2011-02-02 at 17:51 -0500, Andrew Sullivan wrote:

> I find it not a little ironic that
> not against a spec, but against an implementation. 

Unfortunately, it's impossible to test against a spec.  Unless the spec
is written in some formal language, in which case you've simply reduced
the problem to verifying the "spec" does as intended.

What is possible is to test against a test suite.  I don't have any
special knowledge here, but I suspect that tools like idnits _do_ get
tested against a test suite, but that the test cases primarily
concentrate on discovering false accepts rather than false rejects.  It
might be useful to produce some test cases which are prone to being
falsely rejected for some reason.  Perhaps this could even be done
semi-automatically, by collecting documents which were rejected but
later discovered to be valid.

Perhaps it would also be useful for the submission process to be less
strict.  Certainly it is necessary to check the legal boilerplate, but
many of our current requirements, such as correct use of RFC2119, are
things that should be enforced late in the development lifecycle, not
during I-D submission while someone is trying to get a -00 in before the
deadline.

-- Jeff

---

From: John C Klensin <[email-masked]>
Date: Thu, 03 Feb 2011 09:09:13 -0500

FWIW, +1

--On Wednesday, February 02, 2011 17:51 -0500 Andrew Sullivan
<[email-masked]> wrote:

> Since this is now actually kind of back on topic for wgchairs,
> that was the reason I replied in the first place, and it's
> tightly linked to my usual complaint that the idnits process
> is about form, not content.
> 
> I think as WG chairs, we ought to be concerned that process
> rules and bureaucratic efficiency are gradually encroaching on
> the ability to get work done easily and swiftly.  I find it
> not a little ironic that old-fashioned tools like *roff -- or
> just an Emacs formatting template, for all that -- are
> increasingly putting out formally correct but idnits-rejected
> drafts because the tools are being tested not against a spec,
> but against an implementation.  Given our usual rules for
> protocols, that says something very bad about where our values
> really lie.  I personally find xml2rfc easier to use than the
> alternatives (although still much harder than, say, a
> well-designed LaTeX style); but I see no reason why I need
> repeatedly to explain to people who have been producing RFCs
> for 25 years why their template suddenly doesn't work even
> though they have all the right boilerplate.

---

From: John C Klensin <[email-masked]>
Date: Thu, 03 Feb 2011 09:28:14 -0500

--On Wednesday, February 02, 2011 17:37 -0500 James Carlson
<[email-masked]> wrote:

> For what it's worth (and it may not be much, as we're really
> talking about minutiae here), I happen to like the insistence
> on the exact 2119 wording.  Having exactly the same wording in
> each document means that I don't have to refer back to some
> author's quirky definition of the keywords when reading a
> document.  If I encounter "RECOMMENDED," it means the same
> thing everywhere, and I don't have to go check whether this
> particular author happened to elide it from the list or (worse)

Again fwiw, it has gotten to be the case that any attempt to use
non-2119 definitions gets a lot of pushback from the IESG (and,
when anyone notices, the broader community).  I don't see that
as a problem as long as the pushback comes from the sort of
motivation you suggest -- that it is normally better if everyone
uses the same terms to mean the same thing and that doing
otherwise should require a significant reason and significant
justification.

However, there are situations in which the 2119 definitions are
actually a poor match for what is intended.    In my personal
experience, those definitions usually well matched to protocol
specifications ("Technical Specifications" in 2026-speak) but
sometimes less well matched to Applicability Statements or even
BCPs.  Giving up on the flexibility to convince the community
that different definitions are appropriate and doing so in the
interest of mindless consistency, or as Andrew put it, process
rules and bureaucratic efficiency, seems to me to be a really
poor idea.

    john

---

From: [email-masked] (Scott O. Bradner)
Date: Thu, 3 Feb 2011 09:34:12 -0500 (EST)

I agree with John that 2119 is not a good match for non-technical
documents - that said, one can (and I have) added text to say how to
do a match - see e.g., RFC 2418

  RFC 2119 defines the use of these key words to help make the intent 
  of standards track documents as clear as possible.  The same key words 
  are used in this document to help smooth WG operation and reduce the chance
  for confusion about the processes.

not an ideal match but a way to explain

Scott

---

From: Tom Yu <[email-masked]>
Date: Fri, 04 Feb 2011 16:06:52 -0500

Adam Roach <[email-masked]> writes:

> So Scott's "no" is more philosophical than real. As a practical
> matter, it seems the tools are forcing the answer to be "yes."
>
> /a

Tools forcing the exact list from RFC 2119 would be a problem in
documents including ASN.1 syntax, because the all-caps "OPTIONAL" has
a specific non-2119 meaning in ASN.1.