Subject: RFC 2119 terms, ALL CAPS vs lower case

From: Barry Leiba <[email-masked]>
Date: Wed, 16 May 2012 09:59:08 -0400

Some snippets from another discussion thread, in a galaxy far, far away:

Murray:
>>> Sections 1, 3-7: The "may" in a document citing RFC2119 ought to be
>>> "can" or such.

Ned:
>> This seems pretty silly to me. The entire point of capitalizing these
>> terms is so they aren't confused with conventional usage, freeing up
>> the regular forms for conventional use.

Murray:
> As Dave would have pointed out had I not beaten him to it, RFC2119
> doesn't actually say "MAY" is different from "may".  And I've been
> asked to deal with this in enough of my own drafts that now I bring
> it up when I see it.
>
> Barry has suggested, and I believe the IESG has allowed, that the
> RFC2119 boilerplate included in the document also say that the RFC2119
> meaning for each only applies when the word is in all-uppercase. 
 That
> allows the stuff you're talking about.
>
> We could further suggest that someone who feels so inclined propose a
> BCP draft to actually update RFC2119 accordingly.

In fact, RFC 2119 says that the normative keywords are "often 
capitalized", but doesn't require that they be.

As Murray says, my habit is to use this for 2119 boilerplate:

   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 [RFC2119] when they
   appear in ALL CAPS.  These words may also appear in this document in
   lower case as plain English words, absent their normative meanings.

This passes all nit checks, including those involving the eyes of the 
IESG, and I think it makes the situation absolutely clear.  We could, 
certainly, as Murray notes, update 2119 to require all caps in order to 
use the words as 2119 terms.

Alternatively, Tony and Dave had submitted this draft, now expired:
   http://tools.ietf.org/html/draft-hansen-nonkeywords-non2119
It suggests words such as "can" and "ought to" as substitutes, which is 
what Murray's original review was also suggesting.

The trouble with the first approach (using all caps as 2119 terms, and 
using the same words in lower case as normal English) isn't so much 
that someone might be confused later, but that during development and 
review we're not sure whether you meant to put the word in all caps, 
and just forgot.  No amount of documentation can avoid that question, 
and using "can" or "ought to" gets us away from the issue.

The trouble with the "non-normative synonyms" is that it makes document 
text awkward, by requiring us to artificially substitute less apt 
words, when "may" and "should", as English words, are exactly what we 
mean.

It's probably worth having a discussion of all of that, and seeing 
whether there's some possibility of developing a rough community 
consensus on what we might-could-maybe-oughta-should do.

Barry

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 May 2012 07:17:04 -0700

On 5/16/2012 6:59 AM, Barry Leiba wrote:
> IESG,

Computer Science has a long history of being quaint about the role of 
upper/lower case and then ignoring the problems caused by the 
distinctive interpretation it imposes.  It has never recovered from a 
couple of decades of having no upper case, and continues to treat the 
capability as worthy for semantic distinction, in contrast with natural 
usage.

it is ALso interesting to hear that the IETF's actual standards are not 
what is written in our documents but what is in our SUBMISSION testing 
code and the whims of personal interpretation (by the IESG).  There are 
faint echos of Through the Looking Glass, here.  Things mean whatever 
the IESG chooses to declare them to mean, not what the plain language in 
formally adopted documents say they mean.

This is not the sort of topic that should be artificial nor nuanced, nor 
should it encourage misunderstanding.  Case does not define meaning in 
normal language, why should it here?

It is not exactly an onerous task to use different vocabulary, to make 
sure there is no potential ambiguity for readers.  Relying solely on 
case to distinguish between normative vs. non-normative is, forgive me, 
really silly.

> using the same words in lower case as normal English) isn't so much that
> someone might be confused later,

It is certainly one of the troubles with it.

> but that during development and review
> we're not sure whether you meant to put the word in all caps, and just
> forgot. No amount of documentation can avoid that question, and using
> "can" or "ought to" gets us away from the issue.

And yes, this is certainly another trouble with it.

> text awkward, by requiring us to artificially substitute less apt words,
> when "may" and "should", as English words, are exactly what we mean.

Because, after all, technical specification language is already such 
elegant prose, maintaining that elegance is more important than robustly 
encoding the semantic of being normative in a way that avoids ambiguity?

I guess the underlying issue here is whether the rather essential burden 
of working to carefully discerning normativity is placed on the small 
range of authors of a specification or on the variable ocean of 
potential readers?

d/
-- 
  Dave Crocker
  Brandenburg InternetWorking
  bbiw.net

---

From: Randy Bush <[email-masked]>
Date: Wed, 16 May 2012 04:28:23 -1000

can != may

one is ability, the other permission

randy

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 May 2012 07:31:53 -0700

> one is ability, the other permission

When we were first taught English grammar, yes.  Today, not so much.

Actually pretty much never.  In modern usage, the distinction has been lost.

d/

---

From: Scott Kitterman <[email-masked]>
Date: Wed, 16 May 2012 10:34:19 -0400

> Actually pretty much never.  In modern usage, the distinction has been lost.

I must be ancient then as I still use this distinction (and similarly 
would/could).

Scott K

---

From: Edward Lewis <[email-masked]>
Date: Wed, 16 May 2012 10:36:44 -0400

At 9:59 -0400 5/16/12, Barry Leiba wrote:

>whether there's some possibility of developing a rough community consensus
>on what we might-could-maybe-oughta-should do.

What I've run into, a couple of times, in the past few years are 
customer documents, such as RFP (request for proposals) that ask 
about compliance with RFC documents.  In that role it doesn't really 
matter whether the RFC 2119 words are written one way or another, the 
pain is that RFCs generally do not define what it means to be 
compliant.

Granted the RFC series is not intended to be (all) requirements 
documents nor standards documents against which compliance can be 
judged.  I am not saying the RFC series is deficient in the role it 
is intended to play.  But if there is a discussion on the topic of 
the RFC 2119 words, I'd encourage giving thought to appeasing those 
that want documents against which compliance can be judged.

Perhaps a sub-series of RFC documents can be tagged for compliance 
applicability, written in way that testing of requirements is 
possible, and so on.  In such a sub-series, special-meaning words 
would matter.  In all other documents, all words would "revert" to 
their natural meanings.  E.g., SHOULD would be the same as "ought 
to", MUST would be the same as "it has to be" and so on.
-- 
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Edward Lewis
NeuStar                    You can leave a voice message at +1-571-434-5468

2012...time to reuse those 1984 calendars!

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 May 2012 07:38:10 -0700

> I must be ancient then as I still use this distinction (and similarly

I try to too.  The issue isn't with those of us who generate the 
distinction but the masses that don't hear it and seem not to know of it.

This sort of change in language, across a few decades, seems to be 
extremely common.

d/

---

From: Randy Bush <[email-masked]>
Date: Wed, 16 May 2012 04:38:56 -1000

> I must be ancient then as I still use this distinction (and similarly 

yep.  let's stick to hacking our own documents, not the english
language.

further, quoting barry:

> and just forgot.

and when i say a field is 42 bits long, you don't know if i really meant
41.

just address the document, do not try to guess intent.  life is already
sufficiently complex.

randy

---

From: Randy Bush <[email-masked]>
Date: Wed, 16 May 2012 04:39:22 -1000

>    lower case as plain English words, absent their normative meanings.

i like this a lot

randy

---

From: "Adrian Farrel" <[email-masked]>
Date: Wed, 16 May 2012 15:44:27 +0100

How about...

    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 [RFC2119] when they
    appear in ALL CAPS.  These words may also appear in this document in
    lower case as plain English words, absent their normative meanings. Other
    words found in this document MAY also have their expected meanings. The
    term TROLL-BAIT is to be interpreted as described in [1].

[1] http://www.urbandictionary.com/define.php?term=TROLL%20BAIT

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 May 2012 07:54:13 -0700

>>     lower case as plain English words, absent their normative meanings.

So do I.  Rather than attend to likely misinterpretation by average 
readers, it relieves us from responsibilities for misunderstandings due 
to our choosing not to conform to normal language usage.

Making an artificial, formal distinction is far more productive than 
worrying about characteristics of typical readers.

d/

---

From: Andrew Sullivan <[email-masked]>
Date: Wed, 16 May 2012 10:56:55 -0400

On Wed, May 16, 2012 at 07:17:04AM -0700, Dave Crocker wrote:
> Case does not define meaning in normal language, why should it here?

That is false.  Consider these two passages:

    The King asked the Queen,
    and the Queen asked the dairy-maid …

vs

    The king asked the queen,
    and the queen asked the dairy-maid…

The King is not the kind and the Queen is not the queen, and you can
tell just by virtue of the initial capital letter (and though you
can't tell which king or queen, you can tell for sure which King and
which Queen.  The King has no current referent, rather like Russell's
present King of France, bald or otherwise).  What's more, you can tell
which dairy-maid in the first passage (by virtue of relation to the
Queen) but not in the second.

But your claim is actually a symptom of the disease you've diagnosed:
computers obliterated distinctions that are important in the writing
of natural languages, mostly because case transformation for ASCII was
a trivial task and treating these differences as meaningless saved
some work.  Many have stopped treating case as meaningful.

Since the task of written specification is to be as clear as possible,
I have to agree with your conclusion, despite disagreeing with the
premise: the lower case form of a protocol word will confuse people
too, and therefore we mustn't rely on case alone to carry the freight.
Use other words.

> elegant prose, maintaining that elegance is more important than
> robustly encoding the semantic of being normative in a way that
> avoids ambiguity?

One dreams of a period in which precision and elegance were not
mutually exclusive properties.

Best,

A

-- 
Andrew Sullivan
[email-masked]

---

From: Simon Perreault <[email-masked]>
Date: Wed, 16 May 2012 11:06:25 -0400

> mutually exclusive properties.

You mean when French was the dominant language?

Simon

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 May 2012 08:08:16 -0700

> some work.  Many have stopped treating case as meaningful.

ahh.  it's computerization THAT HAS COMPLETELY CHANged MeaNing.

gOOd to NO.

d/

---

From: Sam Hartman <[email-masked]>
Date: Wed, 16 May 2012 11:58:28 -0400

>>>>> "Adrian" == Adrian Farrel <[email-masked]> writes:

    Adrian> How about...  The key words "MUST", "MUST NOT", "REQUIRED",
    Adrian> "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",
    Adrian> "MAY", and "OPTIONAL" in this document are to be interpreted
    Adrian> as described in [RFC2119] when they appear in ALL CAPS.
    Adrian> These words may also appear in this document in lower case
    Adrian> as plain English words, absent their normative
    Adrian> meanings. Other words found in this document MAY also have
    Adrian> their expected meanings. The term TROLL-BAIT is to be
    Adrian> interpreted as described in [1].

I like this a lot with no sarcasm intended.
I'll note that  in my normal reading mode I  do not distinguish case,
but even so I find the ability to use may and should in RFC text without
the 2119 implications valuable.

Yes, you need to be careful. Yes, you should consider how your reader
might or might not notice the difference.  Consider though if you're
saying something like "an octet may contain a value between 0 and 255."
It's not really normative; it's a statement of fact. However, the world
will not really be made worse if someone checks the range of their octet
values.

---

From: Hector Santos <[email-masked]>
Date: Wed, 16 May 2012 13:48:10 -0400

+1

-- 
HLS

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 16 May 2012 11:53:33 -0600

> the 2119 implications valuable.

Your mileage may (or is that MAY?) vary, but to forestall confusion I've
settled on the practice of using "can" and "might" instead of lowercase
"may", "ought to" and "is suggested to" instead of lowercase "should",
and "needs to" or "has to" instead of lowercase "must" (etc.). I'm not
saying that anyone else SHOULD or MUST use that convention, but you
might consider it in your own spec-writing.

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Mary Barnes <[email-masked]>
Date: Wed, 16 May 2012 13:02:17 -0500

Peter,

I also try to follow the same practice after I got the suggestion for one
of my documents. The issue I see with the suggestion that "may" is not
normative whereas MAY is, is that it is not at all uncommon for folks to
typo and forget to make the "may" uppercase - that puts the burden on the
RFC editor to find those if others don't during IETF LC.  I also believe
that many times that "may" is used, it actually is better stated as "can"
and the same with "ought" for "should".

Mary.

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 16 May 2012 19:11:04 +0100

> On 5/16/12 9:58 AM, Sam Hartman wrote:

...
>> the 2119 implications valuable.

Agreed. But as a gen-art reviewer, I have several times had to ask
authors whether a particular lower case "may" was intended to be normative
or normal English. Authors must be fastidious about this.

> might consider it in your own spec-writing.

It is indeed very important not to use "may" when it's ambiguous.
"It may rain today" is fine; "you may leave now" is not (I can think
of three different meanings). In RFC2119-talk, "you MAY leave now"
only has one meaning.

   Brian

---

From: Ole Jacobsen <[email-masked]>
Date: Wed, 16 May 2012 11:26:02 -0700 (PDT)

And of course if we had a slightly richer publication format we could 
use, oh, say, underline, bold, italics and maybe even a special font 
for normative terms, but I guess I am dreaming decades ahead...

Ole

Ole J. Jacobsen
Editor and Publisher,  The Internet Protocol Journal
Cisco Systems
Tel: +1 408-527-8972   Mobile: +1 415-370-4628
E-mail: [email-masked]  URL: http://www.cisco.com/ipj
Skype: organdemo

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 16 May 2012 12:43:27 -0600

> for normative terms, but I guess I am dreaming decades ahead...

Although I too dream the impossible dream, I would prefer not to trust
in formatting to enforce the semantic distinction in this instance.

Peter

---

From: "Adrian Farrel" <[email-masked]>
Date: Wed, 16 May 2012 19:45:28 +0100

Remind me:
Is bold must more or less compelling that underlined must. And where does uppercase MUST fit in?

I fear the slightly richer publication format will give rise to a slightly more complex revision of RFC 2119.

Adrian

> -----Original Message-----
> From: Peter Saint-Andre [mailto:[email-masked]]
> Sent: 16 May 2012 19:43
> To: Ole Jacobsen
> Cc: Mary Barnes; [email-masked]; Sam Hartman; [email-masked]
> Subject: Re: RFC 2119 terms, ALL CAPS vs lower case
>

---

From: Ole Jacobsen <[email-masked]>
Date: Wed, 16 May 2012 11:46:24 -0700 (PDT)

Yeah, that's probably a safer approach. One could of course
imagine some kind of hybrid and parsing in the form of *very*
or /very/ explicit terms. Maybe this is orthogonal to the
other discussion we are having...

Ole

Ole J. Jacobsen

---

From: John C Klensin <[email-masked]>
Date: Wed, 16 May 2012 16:03:09 -0400

--On Wednesday, May 16, 2012 19:45 +0100 Adrian Farrel
<[email-masked]> wrote:

> I fear the slightly richer publication format will give rise
> to a slightly more complex revision of RFC 2119.

Let's try to remember that many of the comments/ requests for
alternate publication formats have been to make "display" more a
function of the devices being used.  Depending on type style
variations (style, size, font variations, underlining, etc.)
would pretty much defeat that particular claimed requirement.
As I take Sam's note to sort of point out, even the use of
uppercase to imply specific semantics can be problematic; we
should at least strive to not make things worse, IMO.

    john

---

From: Randy Bush <[email-masked]>
Date: Wed, 16 May 2012 10:10:02 -1000

> Authors must be fastidious about this.

s/this/documents/

> "It may rain today" is fine

iff you are talaya

randy

---

From: "Worley, Dale R (Dale)" <[email-masked]>
Date: Wed, 16 May 2012 16:10:24 -0400

> From: John C Klensin [[email-masked]]
> 
> > Remind me:

I'm looking forward to the normative use of <BLINK>...</BLINK>.

Dale

---

From: Dave Cridland <[email-masked]>
Date: Wed, 16 May 2012 21:29:40 +0100

> > Authors must be fastidious about this.

RFC 2119 §6 says:

   Imperatives of the type defined in this memo must be used with care
   and sparingly.  In particular, they MUST only be used where it is
   actually required for interoperation or to limit behavior which has
   potential for causing harm (e.g., limiting retransmisssions).  For
   example, they must not be used to try to impose a particular method
   on implementors where the method is not required for
   interoperability.

I note two things:

1) RFC 2119 also uses lower-case "must" and "may" throughout.

2) RFC 2119 also clearly states that using the terms too much will  
harm interoperability.

The second is the one I feel we have violated much more, and caused  
much more damage, than any possible problem with the first.

Consider:

"An octet may contain 0-255".

This is most certainly not going to be helped if we say:

"An octet MAY contain 0-255".

We could either rephrase:

"An octet contains 0-255".

Or use a different awkward word - although up with this I will not  
put:

"An octet might contain 0-255" - or it might not?

But many requirements can be re-cast as statements of fact about  
valid protocol:

"The Foo octet MUST lie between 0 and 127 inclusive; that is, the  
highest bit MUST NOT be set."

As Pete Resnick, I think, once said, these terms are not just a stick  
to beat people with.

"A valid Foo octet lies between 0 and 127 inclusive; that is, the  
highest bit is never set."

That's just as clear, to me, and allows me to concentrate the MUST  
stick where I actually do want to stress a real problem, perhaps:

"Receivers of an invalid Foo octet - that is, one with the highest  
bit set - MUST emit the 'Invalid Foo' error, and therefore terminate  
the session immediately."

Overuse of RFC 2119 language reduces its utility.

Dave.
-- 
Dave Cridland - mailto:[email-masked] - xmpp:[email-masked]
  - acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/
  - http://dave.cridland.net/
Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade

---

From: Warren Kumari <[email-masked]>
Date: Wed, 16 May 2012 17:22:56 -0400

> I'm looking forward to the normative use of <BLINK>...</BLINK>.

Errr… would that be more or less strong then the non-<BLINK> version of a word?

Initially I'd think more, but on reflection it only visible for half the time, so I guess it is half as strong?!  ;-)

W

---

From: [email-masked]
Date: Wed, 16 May 2012 14:22:47 -0700 (PDT)

> i like this a lot

I agree. In fact I just incorporated it into the media types registration
update.

				Ned

---

From: Ralph Droms <[email-masked]>
Date: Wed, 16 May 2012 17:26:40 -0400

> I agree. In fact I just incorporated it into the media types registration

To be sure of meaning and help confusion avoidance, I would prefer that the key words not appear in the document in lower case and that authors use the suggested replacement words (or break out the thesaurus?).

- Ralph

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 May 2012 14:54:36 -0700

+1

and for the current thread, case is format...

>in formatting to enforce the semantic distinction in this instance.

/d

 via mobile

---

From: Jaap Akkerhuis <[email-masked]>
Date: Thu, 17 May 2012 00:01:46 +0200

Proper use should be <NORMATIVE>....</NORMATIVE>, how that is revealed to
the user is decided by the display system.

	jaap

---

From: Hector Santos <[email-masked]>
Date: Wed, 16 May 2012 19:00:12 -0400

+1

My view that this is more about the specific issues of documents and 
not just RFC2119 itself.  Sometimes it falls through the cracks. 
Sometimes a justification or argument is found to show the contrary of 
what is stated, especially when its uses lower cases or even terms 
like "choose."  Sometimes its just new conflicts of integrated 
documents where perhaps an augmented RFC attempts to reinforce what 
the base RFC may have lacked.

In my view, it will help if future I-D and RFC authors begin to have 
one new section called in chapter 1.0

   1.x - Minimum Compliancy Requirement Summary

Far too often documents have mixed functional and technical 
specifications, mixed normative and non-normative compliance semantics 
too spread out and peppered throughout the document making it harder 
to catch compliance level issues.

-- 
HLS

---

From: [email-masked]
Date: Wed, 16 May 2012 19:22:42 -0700 (PDT)

> To be sure of meaning and help confusion avoidance, I would prefer that the
> key words not appear in the document in lower case and that authors use the
> suggested replacement words (or break out the thesaurus?).

Preferring it is one thing; I'm OK with that. Making it some sort of
hard-and-fast rule is another matter entirely. We have too many of those
as it is.

				Ned

---

From: Doug Barton <[email-masked]>
Date: Wed, 16 May 2012 23:18:32 -0700

> capitalized", but doesn't require that they be.

Standards should be written in such a way as to remove as much ambiguity
as possible, not show how clever we are. That allowance in 2119 was a
mistake, and the fact that people remain confused 15 years later is
clear evidence of that.

Normative use of the 2119 key words should always be capitalized.

And yes, "can" is about ability, "may" is about permission. Choosing to
add to the confusion about the simple English meaning of those words
doesn't make us look any more clever.

Doug

-- 
    If you're never wrong, you're not trying hard enough

---

From: t.p. <[email-masked]>
Date: Thu, 17 May 2012 09:11:09 +0100

----- Original Message -----
From: "Doug Barton" <[email-masked]>
To: <[email-masked]>
Cc: "Barry Leiba" <[email-masked]>
Sent: Thursday, May 17, 2012 7:18 AM
> doesn't make us look any more clever.

Yes, normative use should be capitalised and non-normative use should be
avoided, but there is also a distinction to be drawn between MAY and the
others.  Frequently, at or around WG Last Call, the question arises as
to the meaning of MAY, the conclusion often being that it is
meaningless; this MAY or MAY NOT be the case, so who cares, why bother?

MUST and SHOULD are quite different, they do have a force to them and
they are distinct.  SO while I would not comment on the use of 'may', I
would comment on the use of 'should' or 'must'; the latter confuse, the
former, who cares?

Tom Petch

---

From: Tony Finch <[email-masked]>
Date: Thu, 17 May 2012 11:54:06 +0100

>     and the queen asked the dairy-maid…

I really can't tell any difference between the two. The capitalization
here is just a conventional mark of respect (cf. God). Better examples:

Polish / polish
"I helped my uncle Jack off a horse"
Catholic / catholic
Conservative / conservative

In the latter two cases you often get disambiguating circumlocutions (such
as "conservative with a small c" in British political discussion) so even
if you can use case to make a distinction in meaning, it's usually too
subtle to rely on if you want to avoid "amusing" misinterpretations.

Tony.
-- 
f.anthony.n.finch  <[email-masked]>  http://dotat.at/
Humber, Thames: South or southwest 3 or 4, backing east 4 or 5 later. Slight
or moderate. Mainly fair. Mainly good.

---

From: Tony Finch <[email-masked]>
Date: Thu, 17 May 2012 11:56:31 +0100

> one is ability, the other permission

Right, and if you are giving some entity permission to do something in a
protocol spec, surely that ought to be written in normative terms.

Tony.
-- 
f.anthony.n.finch  <[email-masked]>  http://dotat.at/
FitzRoy: Cyclonic at times in far north, otherwise mainly westerly or
northwesterly 5 to 7, occasionally gale 8 in southeast at first, decreasing 4
or 5 later. Moderate or rough. Showers. Good.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 16:00:38 +0200

On 2012-05-16 22:29, Dave Cridland wrote:
> 2) RFC 2119 also clearly states that using the terms too much will harm
> interoperability.
>
> The second is the one I feel we have violated much more, and caused much
> more damage, than any possible problem with the first.
> ...

+100

---

From: "Lee Howard" <[email-masked]>
Date: Thu, 17 May 2012 13:19:07 -0400

> From: [email-masked] [mailto:[email-masked]] On Behalf Of
Dave Cridland
> "The Foo octet MUST lie between 0 and 127 inclusive; that is, the highest
bit MUST NOT
> be set."
> "A valid Foo octet lies between 0 and 127 inclusive; that is, the highest
bit is never set."

We do not improve clarity by making sentences harder to read.
We should avoid rfc2119 language where possible, to be clear, but not at the
expense of
clarity.

* Could be read as normative: "Always do this, unless you can explain why
you can't."

Lee

---

From: Hector Santos <[email-masked]>
Date: Fri, 18 May 2012 01:06:40 -0400

> We do not improve clarity by making sentences harder to read.

Or colorizing it.

> expense of clarity.

+1, I think this is more specific to documents and not RFC2119. I 
don't think we can generalize RFC2119.

-- 
HLS

---

From: Marshall Eubanks <[email-masked]>
Date: Fri, 18 May 2012 09:28:35 -0400

>> We do not improve clarity by making sentences harder to read.

I find this morning a message on the URN WG list
by Alfred Hines on RFC 6329, which has a new (AFAIK) convention on
normative language

3.  Conventions Used in This Document

   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 [RFC2119].

   The lowercase forms with an initial capital "Must", "Must Not",
   "Shall", "Shall Not", "Should", "Should Not", "May", and "Optional"
   in this document are to be interpreted in the sense defined in
   [RFC2119], but are used where the normative behavior is defined in
   documents published by SDOs other than the IETF.

I am not sure this is in the direction of greater clarity. Should
there be a need to
overlay different degrees of normativeness onto a text, XML would
probably be better bet.
Whether the previous sentence is normative or not is left as an
exercise for the reader.

Regards
Marshall

> +1, I think this is more specific to documents and not RFC2119. I don't
> think we can generalize RFC2119.
>
>
> --
> HLS
>
>

---

From: [email-masked]
Date: Fri, 18 May 2012 08:14:34 -0700 (PDT)

> Whether the previous sentence is normative or not is left as an

By my count, there are also two lower case "must"s and six lower case "should"s
in there. In a document with compliance language this complex, those SHOULD
have been eliminated.

Be that as it may, this is asking more of the convention that it realistically
can be expected to deliver. I don't know the circumstances behind this
document - maybe there was no alternative - but the right thing IMO is to
try and avoid having to do anything like this.

				Ned

---

From: Ralph Droms <[email-masked]>
Date: Fri, 18 May 2012 12:41:11 -0400

> hard-and-fast rule is another matter entirely. We have too many of those

Well, here's another example of imprecision in the written word.  What I meant is that my preference would be a requirement that RFC 2119 key words not appear in lower case at all.

Seems to me that precision of meaning overrides graceful use of the language.  Making the requirement something like "RFC 2119 key words SHOULD NOT appear in lower case unless the lower case usage is clearly non-normative" means we have to think a lot harder about some details and (AD hat and reading glasses firmly in place) we have enough details to think about already.  So, I recommend an errata to RFC 2119: "These words MUST NOT appear in a document in lower case."

- Ralph

---

From: Marshall Eubanks <[email-masked]>
Date: Fri, 18 May 2012 13:04:11 -0400

> Seems to me that precision of meaning overrides graceful use of the language.  Making the requirement something like "RFC 2119 key words SHOULD NOT appear in lower case unless the lower case usage…

...except in a direct quote of another document.

Regards
Marshall

---

From: Eric Rosen <[email-masked]>
Date: Fri, 18 May 2012 14:23:42 -0400

> So, I recommend an errata to RFC 2119: "These words MUST NOT appear in a
> document in lower case."

I'm glad you said "I recommend" instead of "I have recommended", as the
latter would violate the recommended (oh dear) rule.

This RECOMMENDED rule would also imply that documents can no longer be
published during the month of May, as otherwise the date line would put the
document out of compliance with this erratum.

Also, it would no longer be possible for the references to list any document
that was published in the month of May.  I suppose we could make it a rule
that the month of May be referred to as "the month between April and June".

Of course, you didn't say that the reserved words muSt nOt appear in mixed
case, so mAybe that will become a workaround.

> Seems to me that precision of meaning overrides graceful use of the
> language.

Many IETF specs lack the desirable degree of precision, but the use of the
"reserved words" in capitalized or uncapitalized form just is not that big a
contributor to the imprecision.  Failure to properly specify all the actions
in all the possible state/event combinations is a much bigger source of
confusion than failure to capitalize "must" (I mean failure to capitalize
"MUST").  I don't know why so much attention is being given to something
that is NOT going to improve the quality of the specs by any appreciable
amount.

---

From: Randy Bush <[email-masked]>
Date: Sat, 19 May 2012 03:27:17 +0900

> I recommend an errata to RFC 2119: "These words MUST NOT appear in a
> document in lower case."

first, that is not an erratum, it is a non-trivial semantic change.

second, do we not already have enough problems being clear and concise
without removing common words from our language?

randy

---

From: [email-masked]
Date: Fri, 18 May 2012 11:32:56 -0700 (PDT)

> first, that is not an erratum, it is a non-trivial semantic change.

And therefore explicitly disallowed by the erratum process.

> without removing common words from our language?

A very emphatic +1.

				Ned

---

From: Ralph Droms <[email-masked]>
Date: Fri, 18 May 2012 14:35:47 -0400

> first, that is not an erratum, it is a non-trivial semantic change.

You are correct and point taken.  

Dave Crocker's suggestion would minimize the number of words taken out of our vocabulary:

> I'd be inclined to change 2119 to reserve only Must, Should and May, independent of case and for no other use, and release the other terms.

In addition to "clear and concise" we need precision and avoidance of ambiguity.

- Ralph

---

From: Randy Bush <[email-masked]>
Date: Sat, 19 May 2012 03:40:13 +0900

> Dave Crocker's suggestion would minimize the number of words taken out

for a language other than english.

> In addition to "clear and concise" we need precision and avoidance of

wonderful rofl.  thanks.  mind if i put that in my public quotes file?

randy

---

From: Ralph Droms <[email-masked]>
Date: Fri, 18 May 2012 15:59:20 -0400

> wonderful rofl.  thanks.  mind if i put that in my public quotes file?

Always happy to entertain, even if unintentionally...

- Ralph

---

From: Randy Bush <[email-masked]>
Date: Sat, 19 May 2012 07:54:55 +0900

my wife says the purpose of tourists (we in japan) is to amuse the
natives

randy

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 19 May 2012 07:48:44 +0100

> without removing common words from our language?

May I say "+1"?

Very seriously - after all that has been said on this thread, I see
no reason to change anything. Authors and the RFC Editor can create
unambiguous language with a bit of thought. There is an erratum
in 2119 ("NOT RECOMMENDED" is not mentioned in the recommended
boilerplate) but we know how to deal with that.

A strong argument against updating RFC 2119 is the fact that it's
one of the most cited RFCs *outside* the RFC series. Several other
SDOs commonly cite RFC 2119 and use its terminology. If it was
a protocol, we'd be proud of its success, but that makes changing
it a source of unintended consequences.

   Brian

---

From: Randy Bush <[email-masked]>
Date: Sat, 19 May 2012 15:54:26 +0900

> no reason to change anything.

the discussion has incited me to change the boiler plate which i will
use henceforth

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to
   be interpreted as described in RFC 2119 [RFC2119] only when they
   appear in all upper case.  They may also appear in lower or mixed
   case as English words, without any normative meaning.

randy

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 19 May 2012 09:28:12 +0200

+1

This is one of those issues that is best addressed by *awareness*, not by new rules.

Grüße, Carsten

---

From: Ofer Inbar <[email-masked]>
Date: Sat, 19 May 2012 15:39:04 -0400

As a reader of RFCs, I've come to expect that 2119 words are always
capitalized, and that when the same words appear in lowercase or mixed
case they're not being used in the 2119 sense.  This seems to be a de
facto standard, even though 2119 doesn't require it.  I'm in favor of
continuing with this standard since I think most readers of RFCs have
grown to expect it, but there doesn't seem to be a need to make any
change.

Two things I like:

 - Randy's new suggested boilerplate

 - Avoiding using 2119-like words in lowercase when other wording
 would work equally well, at the author's discretion.  That seems
 like a reasonable practice, but trying to define and enforce it
 would be far too much trouble and have silly unintended consequences.

So perhaps if Randy's new suggested boilerplate could be added as an
erratum to 2119, clearly labeled an optional suggestion, I think that
might be useful.  But don't change the rules.  2119 works well as is IMO.
  -- Cos

---

From: Eliot Lear <[email-masked]>
Date: Sat, 19 May 2012 22:19:36 +0200

On 5/16/12 3:59 PM, Barry Leiba wrote:
>
> It's probably worth having a discussion of all of that

Did you envision THIS much discussion?

---

From: Randy Bush <[email-masked]>
Date: Sun, 20 May 2012 06:45:28 +0900

> So perhaps if Randy's new suggested boilerplate could be added as
> an erratum to 2119

yikes!  i did not intend that.  and i think folk need to look up
'erratum', think trivial bug fix.  this would be a change.  and i do
not have the hubris to change sob's immortal words :)

i think the practical problem my text may hit is id-nits and id nit
pickers.  two friends have warned me that i may have fun getting a
draft through the iesg with it, and that i can look forward to
silliness.  my read of the iesg is that they have been taking a
higher road these years.  but we'll see.

randy

---

From: Yaakov Stein <[email-masked]>
Date: Sun, 20 May 2012 06:25:52 +0000

> for normative terms, but I guess I am dreaming decades ahead...

I was waiting to see if someone was going to bring this up.

In Roman law, the way you capitalized something in a document could have significant consequences,
for example, incorrect use of Capitis Diminutio could change you from a free person into a slave!

OTOH, the Uniform Commercial Code requires certain terms be rendered "conspicuous",
which may be accomplished though capitalization, or using bold face, or a larger font, or contrasting color, etc.

The intervening 2000 years enabled the UCC to exploit more modern typesetting technologies.

But the IETF is still living in Roman times.

Y(J)S

---

From: Brian E Carpenter <[email-masked]>
Date: Sun, 20 May 2012 07:53:54 +0100

On 2012-05-19 20:39, Ofer Inbar wrote:
...

>  But don't change the rules.  2119 works well as is IMO.

Just to be clear about the current rules, 2119 makes it clear that
upper case keywords are optional ("These words are often capitalized").
Indeed, numerous standards track documents don't use them.

    Brian

---

From: Bill McQuillan <[email-masked]>
Date: Sun, 20 May 2012 00:39:46 -0700

> Indeed, numerous standards track documents don't use them.

I do not agree that 2119 is "clear" on this topic. I read the
beginning of the first paragraph of the Abstract as:

Some background motivation:

  In many standards track documents several words are used to
  signify the requirements in the specification. These words are
  often capitalized.

A new proposal:

  This document defines these words as they should be interpreted
  in IETF documents.

Thus, it is defining a new, unified convention for documenting 
requirements language.

And then the boilerplate shows all of the requirement words in 
uppercase, obviously convincing a lot of people that the new 
standard is to use them in uppercase when their meaning is 
normative.

As one example, in section 6 the text reads:

   potential for causing harm (e.g., limiting retransmisssions)  For

There is one instance of "MUST" and two of "must" in this 
paragraph. I would observe that the "MUST" is used to define a 
requirement upon RFC texts, but the two "must"s are used to 
try to affect the motivation of the humans writing the RFC texts.

There are examples elsewhere in 2119 of the use of these words in
lowercase that seem NOT be used in a normative way.

If anything I would evaluate the evidence to indicate that the 
distinction of case *was intended* to be meaningful.

-- 
Bill McQuillan <[email-masked]>

---

From: Stephen Farrell <[email-masked]>
Date: Sun, 20 May 2012 11:29:09 +0100

> But the IETF is still living in Roman times.

If you want a discussion as to whether we should live
in Times Roman, that'd be best on the rfc editor list.
(Sorry, couldn't resist;-)

S.

---

From: Hector Santos <[email-masked]>
Date: Sun, 20 May 2012 10:40:15 -0400

> Indeed, numerous standards track documents don't use them.

Curious, does any "fixes" of 2119, will fix a document or set of 
documents?  automatically, unchanged?

It just seems that the docs themselves need the fixing and desires to 
change meanings in 2119 is to correct past mistakes or perhaps 
intentional relaxations wanting to be stronger today.

Here is one example where a conflict is often raised that "Local 
Policy" Rules.

    The Checking Software can choose between A or B.
    It is RECOMMENDED that C is used.

A is not defined, B has 2119 language.  However, although it is not 
written, C is only possible if A is used.  B preempts, short-circuits C.

A possible correction would based on Implementation vs Deployment, two 
different readers getting the same understanding:

    The Implementation MUST offer A and B and C.
    The Deployment CAN choose between A or B.
    The Deployment SHOULD use C when the Deployment uses A.

I would use a MUST in the last one, but that will change the original 
RECOMMENDED spec item.

-- 
HLS

---

From: John C Klensin <[email-masked]>
Date: Sun, 20 May 2012 12:29:27 -0400

--On Sunday, May 20, 2012 07:53 +0100 Brian E Carpenter
<[email-masked]> wrote:

> Just to be clear about the current rules, 2119 makes it clear
> that upper case keywords are optional ("These words are often
> capitalized"). Indeed, numerous standards track documents
> don't use them.

Brian,

I've been trying really hard to avoid this discussion, but I
think the above is misleading.

In recent years, various IESG members have insisted that any
IETF Track document that contains anything approximating
conformance language include the 2119 reference and whatever the
strict interpretation of the week is about caps, etc.  As Randy
suggests, there have been signs of more nuance in the last IESG
or two, but...

The same problem applies to the other issue with 2119, which is
that we have history for at least two different interpretations
of those words, the ones in 2119 that are interpreted as
"necessary for interoperability" and the ones in, e.g.,
1122/1123 (Section 1.3.2 in the latter) which are "requirements
of the specification" without binding those requirements to a
particular reason.  From my point of view, the other difficulty
with treating 2119 like Received Wisdom and a set of absolute
requirements is that the interoperability criterion often makes
no sense for what are perfectly reasonable requirements.  As an
example drawn from 1123, a specification might reasonably say
"this option MUST be configurable" because it is necessary to
make things work in a plausible way even if that statement
cannot be explicitly linked to "won't interoperate unless it
does".   But again, in recent years, some IESG members (and
others) have insisted that only the 2119 definitions are
permitted.

The combination of the two is known in some quarters as writing
technically poor or deficient specs in the interest of clear
conformance to procedures.  At least historically, that was a
trap the IETF tried to avoid.

    john

---

From: Brian E Carpenter <[email-masked]>
Date: Sun, 20 May 2012 19:00:13 +0100

> think the above is misleading.

My personal preference is to use RFC 2119, but if the IESG made
that into a rule without community consensus, I think it would
be wrong.

> trap the IETF tried to avoid.

Yes, it would be sad if the IETF were no longer to allow itself to
apply common sense rather than rules.

   Brian

---

From: Stephane Bortzmeyer <[email-masked]>
Date: Sun, 20 May 2012 21:41:40 +0200

On Wed, May 16, 2012 at 11:06:25AM -0400,
 Simon Perreault <[email-masked]> wrote 

> You mean when French was the dominant language?

Nice troll. Let me amend it: we now have languages which were
conceived for writing precisely what you mean (not too much ambiguity,
not too little). Lojban <http://en.wikipedia.org/wiki/Lojban> is the
best known. I do not expect IETF to adopt it for RFCs (despite the
imperfections of English) but I regret it. This would give me the push
I need to really learn Lojban.

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Sun, 20 May 2012 13:36:58 -0700

On 05/20/2012 12:41 PM, Stephane Bortzmeyer wrote:
> On Wed, May 16, 2012 at 11:06:25AM -0400, Simon Perreault
> <[email-masked]> wrote a message of 12 lines which said:
> 
> Nice troll. Let me amend it: we now have languages which were conceived for
> writing precisely what you mean (not too much ambiguity, not too little).
> Lojban <http://en.wikipedia.org/wiki/Lojban> is the best known. I do not
> expect IETF to adopt it for RFCs (despite the imperfections of English) but
> I regret it. This would give me the push I need to really learn Lojban.
> 

Su'i pa

- -- 
Marc Petit-Huguenin
Personal email: [email-masked]
Professional email: [email-masked]
Blog: http://blog.marc.petit-huguenin.org

---

From: Yoav Nir <[email-masked]>
Date: Mon, 21 May 2012 01:44:25 +0300

On May 20, 2012, at 11:36 PM, Marc Petit-Huguenin wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
> 

la lojban satci .ije la lojban na'e nolmle