Subject: Uppercase question for RFC2119 words

From: John Leslie <[email-masked]>
Date: Mon, 28 Mar 2016 09:28:59 -0400

NB this IMHO belongs on <[email-masked]>, and I'm directing Reply-To there

Barry Leiba <[email-masked]> wrote:
> Martin says:
> 
>>... while for some people, the difference between upper and lower case
>> is very strong, for others, it's not perceived that strongly. Examples
>> may include people whose native script doesn't make such a distinction
> 
> This has been brought up before.  I know Martin lives in such a
> country, so perhaps he has different data, but I have checked with my
> own Chinese colleagues, and they confirm that they *do* understand,
> notice, and pay attention to the difference in case when they're
> reading the documents.  (It's entirely possible that they're more
> prone to making case errors when they're writing, but that speaks to
> the "getting it right" part, which I always consider a problem --
> there are a great many wrong uses of 2119 key words that show up
> often, and some of those are, no doubt, due to authors writing
> "should" or "may" or "must" and thinking they ought to put that in
> upper case.)
> 
> John comments:
> 
>>>... It would be good if the relevant entity (I have copied the IESG
>>> and the RFC Editor, but somebody else may be in charge here)
>>
>> (indeed, the IESG may or may not be in charge here; but this is a
>> definite mine-field as we try to escape the ASCII straitjacket when
>> preparing RFCs)
> 
> I believe the IESG is *not* in charge here, other than to have
> different ADs pick at different things in our reviews.  I believe the
> community is in charge.

   I agree with Barry: the community should be in charge.

> The key point is the second sentence of the Abstract from RFC 2119:
> 
>    In many standards track documents several words are used to signify
>    the requirements in the specification.  These words are often
>    capitalized.

   Please note that an Abstract is never supposed to override the
document itself. (But I agree this is the source of the issue.)

> The problem here is that it's explanatory, not normative.  The
> explanation -- and the usage custom -- leads many of us to think we
> can use capitalization to make the distinction, while the fact that
> its not normative leads many of us to think that "should" means
> "SHOULD".

   I think Barry has it right; but I hope our readers don't confuse the
Abstract with the explanation in the body of the document.

> My suggestion is to write a tiny draft (I'm willing to be the editor
> of that) that updates 2119, which makes one of the following changes:
> 
> NEW -- alternative 1
>    In many standards track documents several words are used to signify
>    the requirements in the specification.  These words are often
>    capitalized, as shown below, but they have special, requirements
>    meanings regardless of capitalization.
> 
> NEW -- alternative 2
>    In many standards track documents several words are used to signify
>    the requirements in the specification.  These words have special,
>    requirements meanings only when they appear in ALL CAPITALS,
>    as shown below.

   Needless to say, I prefer alternative 2...

> The hard bit, of course, will be to determine which of those
> alternatives the community has rough consensus on.

   And for that determination, the IESG _is_ in charge.   

> Perhaps I will post an I-D when the pre-meeting fog lifts, and we can
> bash it out on the IETF discussion list.

   Actually, I suggest on-list discussion before that, and Barry posting
_after_ the plenary, when he has left the IESG (and returned to the
_actually_ important work of IESG scribing ;^)

   I know this is a religious-war; and I apologize in advance for not
being present in Buenos Aires to receive the in-person flamage.

   Nonetheless, I restate my opinion:

] IMHO, the intent (when 2119 was written), was to define new words
] using ASCII uppercase, not to redefine English words.  As evidence,
] I cite the three uses of lowercase "must", four uses of lowercase
] "should", and five uses of lowercase "may", which are a true challenge
] to interpret as 2119 keywords.

And I beg folks to respect the convention that an Abstract must not
_change_ the meaning of a document.

   (I'll wait for later to argue why I believe alternative 2 is a better
way to run a railroad...)

--
John Leslie <[email-masked]>

---

From: "Scott O. Bradner" <[email-masked]>
Date: Mon, 28 Mar 2016 09:57:58 -0400

> On Mar 28, 2016, at 9:28 AM, John Leslie <[email-masked]> wrote:
> 
> 

well, not quite - it was to make more consistent an existing practice

the use of capitalized words in IETF documents predates RFC 2119 by quite a bit - see,
for example, RFC 1023.  The use became codified by RFC 1122, where the definitions in 
RFC 2119 come from.

As an AD I became frustrated by the number of IDs I was reviewing that used upper case words
but did not include any statement of what the reader was to make of the fact that some words were 
capitalized.  I, and the rest of the IESG at the time, were returning the IDs requesting that the 
authors add some explanation.  The explanations that were added were , to say the least, 
inconsistent. After rather many of these I wrote what became RFC 2119 so that we would at
lets have a consistent explanation of the capitalized words that authors could use if they wanted to.  
There was some interaction on the list that resulted in what is now section 6 of RFC 2119 to
provide guidance on when to use the capitalized words

The wishy washy descriptive rather than proscriptive language in the abstract was because I,
the IESG and the community were not of one mind to say that the use of such capitalized
terms should be mandatory - quite a few people felt that the english language was at 
least good enough to convey  the writer’s intent without having to aggrandize specific words.
Thus the abstract basically was saying: if you want to use capitalized words here is a standard
way to say what they mean - as I recall some RFCs even after 2119 was published included
their own definitions for the capitalized terms because the authors thought they had better
definitions.

Scott

---

From: Barry Leiba <[email-masked]>
Date: Mon, 28 Mar 2016 10:09:51 -0400

> way to say what they mean

Ah.  Then perhaps the clarification needs to go a little further and
make this clear:
- We're defining specific terms that specifications can use.
- These terms are always capitalized when these definitions are used.
- You don't have to use them.  If you do, they're capitalized and
their meanings are as specified here.
- There are similar-looking English words that are not capitalized,
and they have their normal English meanings; this document has nothing
to do with them.

...and I'd like to add one more, because so many people think that
text isn't normative unless it has 2119 key words in all caps in it:

- Normative text doesn't require the use of these key words.  They're
used for clarity and consistency when you want that, but lots of
normative text doesn't need to use them, and doesn't use them.

Barry

---

From: "Scott O. Bradner" <[email-masked]>
Date: Mon, 28 Mar 2016 10:13:09 -0400

one minor tweak

> On Mar 28, 2016, at 10:09 AM, Barry Leiba <[email-masked]> wrote:
> 

these definitions are only meaningful if the words are capitalized

---

From: John C Klensin <[email-masked]>
Date: Mon, 28 Mar 2016 14:23:38 -0400

Yes.  +1.  About time and long overdue.

    john

--On Monday, March 28, 2016 10:09 -0400 Barry Leiba
<[email-masked]> wrote:

> Ah.  Then perhaps the clarification needs to go a little
> further and make this clear:
> - These terms are always capitalized when these definitions
> are used. - You don't have to use them.  If you do, they're
> capitalized and their meanings are as specified here.
> - There are similar-looking English words that are not
> capitalized, and they have their normal English meanings; this
> document has nothing to do with them.
> 
> ...and I'd like to add one more, because so many people think
> that text isn't normative unless it has 2119 key words in all
> caps in it:
> 
> - Normative text doesn't require the use of these key words.
> They're used for clarity and consistency when you want that,
> but lots of normative text doesn't need to use them, and
> doesn't use them.

---

From: Barry Leiba <[email-masked]>
Date: Mon, 28 Mar 2016 15:09:53 -0400

> one minor tweak

A fine tweak.  I'll write it up and pass it to a few people before I
post the I-D.

I'd rather do it as an update to 2119, rather than a complete
revision, even though 2119 is so short, for two reasons:

1. I don't want to get into arguments about other changes.

2. I don't want to make 2119 obsolete: there's value in continuing to
refer to it with that RFC number.

Barry

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 29 Mar 2016 08:58:09 +1300

There are times when I think RFC2119 was a really bad idea, despite it having
become probably the most frequently cited RFC (inside and outside the IETF).
It seems to create as much confusion as it avoids.

There are four words whose RFC2119 meaning is different from the dictionary
meaning: should, recommended, may and optional. Having special typography
for them is useful, because it signals the RFC2119 meanings. But if a spec
uses, for example, a mixture of SHOULD and should, who knows what the authors
intended? To that extent, the proposed clarification is helpful.

The other words (must, shall, required, not) mean what they always mean.
The only argument for upper-casing them is aesthetic symmetry. If a spec
uses alternatives like mandatory, necessary or forbidden, they are just as
powerful.

So
> these definitions are only meaningful if the words are capitalized
can be applied to should, recommended, may and optional if we want,
but strictly doesn't apply to must, shall, required, not, mandatory,
necessary, forbidden, need, or any other such words.

Where we can get into real trouble is if a spec contains should, recommended,
may and optional *plus* other non-categorical (fuzzy) words like ought,
encourage, suggest, can, might, allowed, permit (and I did not pull those
words out of the air, but out of draft-hansen-nonkeywords-non2119). What do
they mean? It can be very unclear. If a node receives a message containing
an element covered in the spec by "allowed" instead of "OPTIONAL", is the
receiver supposed to interoperate or to reject the message?

If we are issuing guidance, it should probably include a specific warning
to use any such fuzzy words with extreme care.

   Brian

---

From: Eric Gray <[email-masked]>
Date: Mon, 28 Mar 2016 20:27:15 +0000

Brian,

	 I agree with most of what you say.  My impression has been that many times the use of some 
of the fuzzier words stems from the fact that the author(s) have occasionally forgotten that they are 
writing a specification, and not a bit of literary prose.

	Using variation in wording does not make a specification more readable, as it might a piece of
literature.  It makes it less readable, even if it might make it a less boring read.

	I am not certain that making a specification exciting enough to keep the average reader awake is 
a goal.

	One area where I do slightly disagree is in your characterization of the use of must verses MUST,
and similar words.  The English usage of the word "must" can vary slightly from the normative use of the 
word "MUST."

	As an example - in the statement "what goes up, must come down" - the word "must" is almost 
certainly meant to reflect a fact of nature, as opposed to an implementation choice that is needed if we
want to have interoperable implementations of a specification. 

	If you could throw a ball into the air, and it just hung there, I'm not sure we should refer to it as
"non-compliant."  :-)

	Also, a statement along the lines of "electronic equipment MUST have a power source of some 
sort" is not particularly useful for interoperability - even though it seems likely to be true.

	Nor do I think we would want an implementation that did not have this limitation to be deemed
non-compliant.

	There are similar uses for "need" for instance.  And - while I cannot think of an example at the 
moment - I am not prepared to bet the farm that there are no such similar uses for "required."  Maybe
this might be the case for a legal requirement that has nothing to do with compatible implementation?

	In any case, it is occasionally necessary to use these terms in an explanatory sense, having not 
very much to do with specification of normative behavior.  The good news is that most of us can tell if
the meaning is explanatory, verses normative.

--
Eric

-----Original Message-----
From: ietf [mailto:[email-masked]] On Behalf Of Brian E Carpenter
Sent: Monday, March 28, 2016 3:58 PM
To: Scott O. Bradner; Barry Leiba
Cc: Heather Flanagan (RFC Series Editor); [email-masked]; IETF discussion list; IESG
Subject: Fuzzy words [was Uppercase question for RFC2119 words]

So

   Brian

---

From: Barry Leiba <[email-masked]>
Date: Mon, 28 Mar 2016 16:30:36 -0400

Brian, I think your note goes to how important it is to write clearly
and to get a lot of eyes on it before we publish it.  Well-written
documents, with or without 2119 key words, and with or without
lower-case look-alikes, can still be clear.  Fuzzily written documents
will be fuzzy.

> receiver supposed to interoperate or to reject the message?

Well, this is where 2119 advises that we *use* the key words when
interoperability is at stake.  It's fine to be fuzzy when it doesn't
matter, though even then, I'd argue for more explanation:

   Every frobotz MUST contain a valid bleeg.  The glorp field in the
   frobotz is an unsigned integer that is normally between 0 and 666,
   inclusive.  Values greater than 666 are allowed, but recipients
   using older software might not be able to handle such values.
...
   When processing a frobotz that does not meet the requirements in
   section 3.1.4, it is permissible to reject the frobotz outright, or to
   attempt to process the parts of it that make sense; the choice is
   an implementation decision.  However, any frobotz that does not
   contain a valid bleeg MUST be rejected.

That sort of thing.

Barry

---

From: "John Levine" <[email-masked]>
Date: 28 Mar 2016 20:55:08 -0000

>>> normative text doesn't need to use them, and doesn't use them.

So you're saying that normative text MAY use key words?  Or it SHOULD
use key words?

Signed,
Confused

---

From: David Farmer <[email-masked]>
Date: Mon, 28 Mar 2016 17:04:58 -0500

> So you're saying that normative text MAY use key words?  Or it SHOULD

Personally, I believe normative text SHOULD use the capitalized keywords.
However, I'm worried we only really have consensus for MAY.

Additionally, It would also be useful to provide a recommendation regarding
advancing specification to Internet Standard (RFC6410), is adherence to
RFC2119 an important issue in that regard?  And, are capitalized keywords
more or less important than the overall stability of the text in that
process. Put more directly, should specifications be updated with
capitalized keywords as part of that process?  Or, is it more important to
keep the text the same?

Even if there isn't a consensus for SHOULD, I think clearly stating the
consensus is only MAY would be helpful and might short circuit some
unnecessary discsion.

Thanks

-- 
===============================================
David Farmer               Email:[email-masked]
Networking & Telecommunication Services
Office of Information Technology
University of Minnesota
2218 University Ave SE        Phone: 612-626-0815
Minneapolis, MN 55414-3029   Cell: 612-812-9952
===============================================

---

From: Dick Franks <[email-masked]>
Date: Tue, 29 Mar 2016 00:01:51 +0100

> Personally, I believe normative text SHOULD use the capitalized keywords.
Your opinion

>   However, I'm worried we only really have consensus for MAY.
Many others' opinion.

if (SHOULD) {

> RFC2119 an important issue in that regard?
>
No

>   And, are capitalized keywords more or less important than the overall
> stability of the text in that process.
>
Less

> Put more directly, should specifications be updated with capitalized
> keywords as part of that process?
>
No

>   Or, is it more important to keep the text the same?
>
Yes

} else {

> RFC2119 an important issue in that regard?
>
No

>   And, are capitalized keywords more or less important than the overall
> stability of the text in that process.
>
Less

> Put more directly, should specifications be updated with capitalized
> keywords as part of that process?
>
No

>   Or, is it more important to keep the text the same?
>
Yes

... I think clearly stating the consensus is only MAY would be helpful and
> might short circuit some unnecessary [discussion].
>
Irrelevant

}

As the man said, natural language usage MAY be used, even others think it
SHOULD NOT.

---

From: Tony Finch <[email-masked]>
Date: Tue, 29 Mar 2016 11:57:57 +0100

Brian E Carpenter <[email-masked]> wrote:

> But if a spec uses, for example, a mixture of SHOULD and should, who
> knows what the authors intended? To that extent, the proposed
> clarification is helpful.

I think if a document uses RFC 2119 keywords then it ought to avoid
non-capitalized uses of the keywords, e.g. by replacing "should" with
"ought to" or other rephrasings.

Tony.
-- 
f.anthony.n.finch  <[email-masked]>  http://dotat.at/  -  I xn--zr8h punycode
Rockall, Malin: Cyclonic 4 or 5, becoming west 5 or 6 later. Moderate or
rough, occasionally very rough in south Rockall. Showers. Good.

---

From: Scott Bradner <[email-masked]>
Date: Tue, 29 Mar 2016 07:27:13 -0400

fwiw - seems to me that the basic idea that MUST and must are the same is wrong and will lead to 
even more confusion

imo - any clarification should (not SHOULD - i.e. the english language) say
	1/ some authors capitalize some words for emphasis and clarity
	2/ there is no requirement to use capitalized words 
	2/ when capitalized words are used RFC 2119 says what the capitalized words mean
	3/ non capitalized words are interpreted using normal English 

Scott

> On Mar 28, 2016, at 4:30 PM, Barry Leiba <[email-masked]> wrote:
>

---

From: Loa Andersson <[email-masked]>
Date: Tue, 29 Mar 2016 19:29:56 +0800

2nd in motion

/Loa

---

From: Randy Bush <[email-masked]>
Date: Tue, 29 Mar 2016 08:48:07 -0300

[ i hate being drawn into yet more process omphaloskepsis, but this is
  painful ]

> fwiw - seems to me that the basic idea that MUST and must are the same
> is wrong and will lead to even more confusion
> 

yes, please.  please, let's not invent new semantics.

randy

---

From: John C Klensin <[email-masked]>
Date: Tue, 29 Mar 2016 07:57:54 -0400

--On Tuesday, March 29, 2016 07:27 -0400 Scott Bradner
<[email-masked]> wrote:

> fwiw - seems to me that the basic idea that MUST and must are
> the same is wrong and will lead to  even more confusion
> 
>  2/ when capitalized words are used RFC
> 2119 says what the capitalized words mean 

Agreed, if your second #2 is modified to read "when capitalized
words are used and RFC 2119 is explicitly and normatively
referenced, RFC 2119 says what the capitalized words mean".   In
other words, there is no universal applicability of 2119 -- if I
write a document that says "where this document says 'MUST', it
means you should (sic) do it if you find it convenient". that
might well be editorially dumb, but 2119 has nothing to do with
it, nor does it prevent such a definition.

   john

---

From: Scott Bradner <[email-masked]>
Date: Tue, 29 Mar 2016 08:06:39 -0400

agreed

Scott

> On Mar 29, 2016, at 7:57 AM, John C Klensin <[email-masked]> wrote:
> 
> 
>

---

From: "Ben Campbell" <[email-masked]>
Date: Tue, 29 Mar 2016 08:30:00 -0500

> 	3/ non capitalized words are interpreted using normal English

I agree heartily, especially with 3. As it is, we often get tortured 
language where people try to avoid such words in text. That makes the 
writing hard, and the reading even harder.

Ben.

---

From: Dave Cridland <[email-masked]>
Date: Tue, 29 Mar 2016 14:46:21 +0100

> it, nor does it prevent such a definition.
Agreed, but we should (ought to, probably wish to, etc) consider a
replacement for the following:

      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.

Perhaps simply:

      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 when capitalised.

---

From: John C Klensin <[email-masked]>
Date: Tue, 29 Mar 2016 09:52:55 -0400

--On Tuesday, March 29, 2016 14:46 +0100 Dave Cridland
<[email-masked]> wrote:

> Perhaps simply:
> 
>       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 when capitalised.

I think that is an improvement even if I have some doubts that
it will make much difference.  The difference should, IMO, pivot
on whether 2119 is normatively referenced as a source of those
definitions.

    john

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 29 Mar 2016 07:18:32 -0700

> to use any such fuzzy words with extreme care.

I've been watching this thread and am thrilled to see these
clarifications coming through. Changes to RFC 2219 are a community
decision, not an RFC Editor decision, but the RFC Editor definitely
appreciates consistency and clarity!

-Heather

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Tue, 29 Mar 2016 15:26:23 +0000

I also feel that a modified version of the RFC 2119 statement should be defined and specified in a small RFC.

I like Dave's addition, but also think adding the word "only" is worth doing:

      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 only when capitalised.

Leaving out the "only" still leaves the statement (slightly) ambiguous; it's the same as the difference between "if" and "if and only if".

- Tony Hansen

From: ietf <[email-masked]<mailto:[email-masked]>> on behalf of Dave Cridland <[email-masked]<mailto:[email-masked]>>
Date: Tuesday, March 29, 2016 at 9:46 AM
To: John C Klensin <[email-masked]<mailto:[email-masked]>>
Cc: IETF discussion list <[email-masked]<mailto:[email-masked]>>, "Heather Flanagan (RFC Series Editor)" <[email-masked]<mailto:[email-masked]>>, "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>, IESG <[email-masked]<mailto:[email-masked]>>, Barry Leiba <[email-masked]<mailto:[email-masked]>>
Subject: Re: Fuzzy words [was Uppercase question for RFC2119 words]

. . .
Agreed, but we should (ought to, probably wish to, etc) consider a replacement for the following:

Perhaps simply:

---

From: John C Klensin <[email-masked]>
Date: Tue, 29 Mar 2016 12:34:22 -0400

--On Tuesday, March 29, 2016 08:58 +1300 Brian E Carpenter
<[email-masked]> wrote:

>...
> The other words (must, shall, required, not) mean what they
> always mean. The only argument for upper-casing them is
> aesthetic symmetry. If a spec uses alternatives like
> mandatory, necessary or forbidden, they are just as powerful.
>...

Actually, when 2119 is referenced, Section 6 attaches particular
interoperability semantics to MUST, SHALL, etc., that are not
part of the plain-English meaning of those words.  Section 6
seems to be ignored most of the time but cited when it supports
an axe someone wants to grind about use of conformance language.

    john

---

From: Dave Cridland <[email-masked]>
Date: Tue, 29 Mar 2016 17:36:12 +0100

On 29 March 2016 at 16:26, HANSEN, TONY L <[email-masked]> wrote:

> Leaving out the "only" still leaves the statement (slightly) ambiguous;
> it's the same as the difference between "if" and "if and only if".
>
>
I agree that's an improvement.

> - Tony Hansen
>
> From: ietf <[email-masked]> on behalf of Dave Cridland <
> [email-masked]>
> To: John C Klensin <[email-masked]>
> Cc: IETF discussion list <[email-masked]>, "Heather Flanagan (RFC Series
> Editor)" <[email-masked]>, "[email-masked]" <[email-masked]>, IESG <
> [email-masked]>, Barry Leiba <[email-masked]>

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Tue, 29 Mar 2016 18:11:31 +0000

>"ought to" or other rephrasings.

Cue reference to "draft-hansen-nonkeywords-non2119" :-)

	Tony Hansen

---

From: John C Klensin <[email-masked]>
Date: Tue, 29 Mar 2016 16:03:14 -0400

--On Tuesday, March 29, 2016 18:11 +0000 "HANSEN, TONY L"
<[email-masked]> wrote:

> On 3/29/16, 6:57 AM, "ietf on behalf of Tony Finch"
> <[email-masked] on behalf of [email-masked]> wrote:
> 
> 
>>> But if a spec uses, for example, a mixture of SHOULD and
>>> should, who knows what the authors intended? To that extent,
>>> the proposed clarification is helpful.
>> 
>> I think if a document uses RFC 2119 keywords then it ought to
>> avoid non-capitalized uses of the keywords, e.g. by replacing
>> "should" with "ought to" or other rephrasings.
>> 
>> Tony.
> 

Tony (and Tony), it seems to me that raises a fundamental issue
in editorial philosophy and style as well as some human factors
issues... the latter especially for readers who have to
translate (if only in their heads) between English and whatever
language they "think in".  I just don't know whether it is
possible to fix/adjust 2119 without resolving it.

There are, I think, two almost-separate problems.  The first is
that 2119, presumably in the interest of smooth and elegant
writing and phrasing, defined and therefore preempted not only
MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, but several of the
obvious synonyms.  Had it not done that, it would have been
possible to say "for IETF purposes, these are not synonyms,
their meanings are different, and upper-case is just a
convenience for emphasis".  But those obvious synonyms are gone
too, so that avoiding the non-normative versions of the terms
requires some rather awkward circumlocutions as, IMO,  some of
the recommendations of draft-hansen-nonkeywords-non2119 rather
painfully illustrates.  

If you want to understand how painful, pick a non-English
language with with you or one of your colleagues is familiar, a
language that is not closely related to English in vocabulary
and semantics (i.e., not either a Germanic or a Romance
language), and then toss the text of a standard with the terms
recommended in your I-D mechanically substituted for the
normative 2119 terms into the widely-available automatic
translation tool of your choice.  I've tried an experiment or
two like that; the results were, IMO, appalling but YMMD.

So I just don't see that as a viable solution unless you want to
make writing clear I-Ds really difficult (and Heather and the
Production Center are willing to let those awkward constructions
make it into RFCs).

Again, this is partially a philosophical disagreement, so I
recognize that there are other points of view.

best,
    john

---

From: Eliot Lear <[email-masked]>
Date: Tue, 29 Mar 2016 22:43:53 +0200

> receiver supposed to interoperate or to reject the message?

Yes, this.  There seems to be a sort of MUSTSHOULDMAYphobia.  The
contortions some people will go through to avoid the words when that is
what they mean is, at times, hilarious; but at other times harmful to
interoperability.

Eliot

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 30 Mar 2016 12:39:10 +1300

On 30/03/2016 00:27, Scott Bradner wrote:
> fwiw - seems to me that the basic idea that MUST and must are the same is wrong

I disagree, specifically for MUST, SHALL, REQUIRED and NOT. RFC2119
doesn't change their meanings, because their meanings are categorical
anyway. It's absolutely appropriate that RFC 2119 states their meanings,
but they aren't ambiguous.

> and will lead to

That is a change, because 2119 does not say point 3/. I'm not saying
it's a bad change, but it really is a change, affecting SHOULD and MAY
in particular.

Honestly I don't think any of this will change the questions I sometimes
have for authors, basically
"Should that 'should' be 'SHOULD'?"
"Should that 'may/MAY' be 'might'?"

   Brian

---

From: "Scott O. Bradner" <[email-masked]>
Date: Tue, 29 Mar 2016 19:43:01 -0400

yup - it is a change, one that might help against the people that say 2119 MUST be used all the time
but it will not address the examples you cite

Scott

> On Mar 29, 2016, at 7:39 PM, Brian E Carpenter <[email-masked]> wrote:
>

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 30 Mar 2016 12:52:39 +1300

> I agree that's an improvement.

I think it's a significant improvement, despite my other comments. However,
we should also insert "NOT RECOMMENDED" (see the erratum #499 on 2119).

    Brian

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 30 Mar 2016 12:46:51 +1300

> an axe someone wants to grind about use of conformance language.

My claim is that even section 6 does *not* change the meanings
of the categorical words in a spec. If it says that something
must or must not happen, either the statement is redundant or
it is essential for interoperability, whether it's written
in upper case Courier New or in runes.

But it doesn't matter. It's the SHOULDs and MAYs that require
precision in their use.

      Brian

---

From: Dave Cridland <[email-masked]>
Date: Wed, 30 Mar 2016 08:24:53 +0100

> in upper case Courier New or in runes.
I should think you must realise that shall not always be the case.

---

From: Adam Roach <[email-masked]>
Date: Wed, 30 Mar 2016 09:09:55 -0500

> - We're defining specific terms that specifications can use.

+1

> - These terms are always capitalized when these definitions are used.

+1

> their meanings are as specified here.

+1

> and they have their normal English meanings; this document has nothing

Yes. This. This, this, this, a million times, this. If we published a 
document that said only this, it would be a huge net win for the community.

> normative text doesn't need to use them, and doesn't use them.

+1

If there's anything I can do to help, Barry, please reach out to me.

/a

---

From: Dave Crocker <[email-masked]>
Date: Wed, 30 Mar 2016 07:34:26 -0700

> document that said only this, it would be a huge net win for the community.

Assuming that merely documenting this explicitly is sufficient, perhaps.

That such a rule differs from natural English -- which does not 
typically alter semantics based on case -- and that most readers of RFCs 
will not have such detailed knowledge of RFC2119 nor read RFCs with the 
care such a rule demands, my question BARRY and adam and EveryOne Else, 
is what makes anyone think that such a rule must (MUST?) ensure proper 
reading of RFCs so as to distinguish between normative portions and 
advisory portions?

It's worth distinguishing between rules that make the writers more 
comfortable, from rules that aid the reading efficacy in practical terms.

d/

-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: Adam Roach <[email-masked]>
Date: Wed, 30 Mar 2016 09:46:27 -0500

> comfortable, from rules that aid the reading efficacy in practical terms. 

Forcing implementors to read through the linguistic contortions authors 
make to avoid using perfectly good English words doesn't do them any 
favors. This odd game of charades -- "one syllable... sounds like... 
desk? wood?" -- does not aid clarity. Much the opposite.

/a

---

From: Eliot Lear <[email-masked]>
Date: Wed, 30 Mar 2016 16:52:47 +0200

On 3/30/16 4:46 PM, Adam Roach wrote:
> Forcing implementors to read through the linguistic contortions
> authors make to avoid using perfectly good English words doesn't do
> them any favors. This odd game of charades -- "one syllable... sounds
> like... desk? wood?" -- does not aid clarity. Much the opposite.

Ok.  But neither should authors and editors be afraid of 2119.  Those
definitions are there to help both the reader and the writer, so that
intent is clear.

Eliot

---

From: Lee Howard <[email-masked]>
Date: Wed, 30 Mar 2016 10:54:43 +0100

On 3/28/16, 3:09 PM, "ietf on behalf of Barry Leiba"
<[email-masked] on behalf of [email-masked]> wrote:

>> least good enough to convey  the writer¹s intent without having to
>>aggrandize specific words.

³can² = ³MAY²?

>- These terms are always capitalized when these definitions are used.

³are always² = ³MUST²?

>and they have their normal English meanings; this document has nothing

Gee, I thought rfc2119 was to say, ³These words have their normal English
meanings.²

>normative text doesn't need to use them, and doesn't use them.

I like rfc2119 for specifying protocols, because it very clearly describes
what MUST be implemented for interoperability to work, what SHOULD be done
for it to work well or as expected, and what MAY also be included.
However, I run into lots of cases with documents that are not intended for
Standards Track where people tell me I¹m not allowed to use the English
language because the IETF has defined it otherwise.[1]

I love the English language. It has a beautiful irregularity and dynamism
that gives it a richness rare among other languages. Romance languages
have grace, Mandarin has a melody, Japanese has an appealing order, German
has flexibility, but English is a strong mutt.

Let us not define jargon such that we raise barriers to contributing or
comprehending internet-drafts. The words ³should,² ³may,² and ³must² are
natural English. When necessary for normative protocol language, we should
[2] specify that we mean them in their rfc2119 sense, and may [3]
capitalize them. In the absence of text saying ³I mean rfc2119,² they have
natural English language meanings.

Lee

[1] To say nothing of rfc6919
[2] rfc2219 MUST
[3] rfc2119 MAY

---

From: "Ben Campbell" <[email-masked]>
Date: Wed, 30 Mar 2016 09:55:50 -0500

> like... desk? wood?" -- does not aid clarity. Much the opposite.

+1. Especially having grown up in the border between the US south and 
southwest, where "ought" was a considerably more loaded term than 
"should" (and  was primarily used by grandparents to lecture children).

---

From: Warren Kumari <[email-masked]>
Date: Wed, 30 Mar 2016 15:32:37 +0000

> for it to work well or as expected, and what MAY also be included.

So, sometimes MUST is too strong, and SHOULD is too weak. Lucking, back in
2012, Ron Bonica and I solved this critical issue, by allowing you much
more granularity in RFC2119 language.

http://www.rfc-editor.org/pipermail/rfc-interest/2012-March/002990.html

We thought it was really cool, but unfortunately, when trying to send it to
RFC Editor my mailer's autocomplete autocompleted to RFC Interest instead
:-(
W

---

From: Dave Cridland <[email-masked]>
Date: Wed, 30 Mar 2016 17:32:07 +0100

On 30 March 2016 at 15:34, Dave Crocker <[email-masked]> wrote:

> That such a rule differs from natural English -- which does not typically
> alter semantics based on case -- and that most readers of RFCs will not
> have such detailed knowledge of RFC2119 nor read RFCs with the care such a
> rule demands, my question BARRY and adam and EveryOne Else, is what makes
> anyone think that such a rule must (MUST?) ensure proper reading of RFCs so
> as to distinguish between normative portions and advisory portions?
>
>
Sorry, I think that's nonsense. RFC 2119 and its capitalized keywords are
well known to anyone reading any specifications, these days. I think we can
actually assume a priori knowledge of RFC 2119, for the most part. What I
think would be far more surprising is this notion that the keywords, noted
and referenced in capitals, also have the same precise meaning and force
when written normally.

I'd note that in typical technical books, different typefaces are often
used to indicate verbatim commands or code, placeholders, etc - the
practise of using typographical conventions not normally found in written
English in technical literature is not only extremely prevalent, but in
this case in particular this is the assumption of the vast majority of
those likely to read it.

If you don't believe me, go look at a XEP, or a PEP, or a W3C-TR, or any of
hundreds of ad-hoc specifications from community efforts to proprietary
HTTP APIs - they all use RFC 2119 language, often without even bothering to
cite the document.

That's not to say that when reviewing a document, a lower-case "must" might
not be better as a "MUST" - but I don't see it as any different to a
similarly lower case "ought" being phrased better as a "SHOULD" if that's
really what was meant. The keywords exist to enhance clarity - but nothing
more. A mandatory requirement can be expressed without the "M" word. We can
mention that not implementing a feature causes interoperability issues
without using the "S" word. Knowing that we may read such text does not
make it "OPTIONAL".

Finally, I'd note in passing that "bill" and "Bill", "will" and "Will",
"heather" and "Heather", all have different semantics based on case - not
that this is particular relevant.

---

From: Adam Roach <[email-masked]>
Date: Wed, 30 Mar 2016 11:52:17 -0500

On 3/30/16 11:32, Dave Cridland wrote:
> Finally, I'd note in passing that "bill" and "Bill", "will" and 
> "Will", "heather" and "Heather", all have different semantics based on 
> case - not that this is particular relevant.

It's actually quite relevant, since it shows that we already have 
significant cases in which merely changing letter case can alter meaning 
nontrivially. There's a somewhat bawdy example of this that you can find 
by typing "capitalization matters" into Google Image Search. (Probably 
not safe to do in many workplaces).

It kind of takes the wind out of arguments that people will miss the 
difference between letter cases.

/a

---

From: Dave Crocker <[email-masked]>
Date: Wed, 30 Mar 2016 10:03:49 -0700

On 3/30/2016 9:52 AM, Adam Roach wrote:
> nontrivially.

Except that the assertion that case alters meeting is wrong.  The 
examples given were wrong, adam.

d/

-- 

   Dave Crocker

---

From: John C Klensin <[email-masked]>
Date: Wed, 30 Mar 2016 13:07:06 -0400

--On Wednesday, March 30, 2016 07:34 -0700 Dave Crocker
<[email-masked]> wrote:

> That such a rule differs from natural English -- which does
> not typically alter semantics based on case -- and that most
> readers of RFCs will not have such detailed knowledge of
> RFC2119 nor read RFCs with the care such a rule demands, my
> question BARRY and adam and EveryOne Else, is what makes
> anyone think that such a rule must (MUST?) ensure proper
> reading of RFCs so as to distinguish between normative
> portions and advisory portions?

Dave, I'd suggest that technical (and, btw, legal) documents
define words to have local meanings in the context of that
document all the time, and that caps, boldface, italics, and
capital letters are commonly viewed as doing a favor to the
reader.  Usually that is done for slightly-unusual terms, rather
than words that are in common use, but that doesn't really
change the situation especially because, for most practical
cases, the difference between 2119-MUST and ordinary-must is
fairly slight.    I've explained elsewhere why I don't believe
the use of convoluted and forced language to avoid using words
like "must" is not a satisfactory solution, YMMD on that point
(and, I presume, does).

> It's worth distinguishing between rules that make the writers
> more comfortable, from rules that aid the reading efficacy in
> practical terms.

Sure.   But the convoluted sentences proposed by some
alternatives are likely to improve the situation for neither
group.

It seems to me that we may be asking the wrong questions.  To
review and consolidate two things that others have mentioned,
there are almost separate issues about (i) the difference
between normative and non-normative language and (ii) the
difference between interoperability requirements and conformance
requirements.

For the first, I don't think expecting people to do detective
work based on whether or not certain words (capitalized or not)
appear in a sentence of paragraph.  If we don't think our
documents are clear enough about it, the solution probably lies
in what some other standards bodies have done for years: be
really clear about whether the default is normative or
non-normative and then specifically identify every section or
paragraph that is the other.  That approach is sometimes tedious
for both authors and readers but is efficacious for readers and
does not allow misunderstandings.  

On the other hand, while the problem is easy to identify and
worry about, in watching IETF documents over the years, I've
rarely seen examples that represent real problems in practice.
The only major exceptions occur when the same information is
presented in two ways.  For example, when an ABNF description of
syntax and a prose description both appear in the same document
and do not turn out to be 100% consistent, it might be helpful
to have clear language that says "that is the one to believe if
there is any doubt", but we've often done that without having to
resort to "normative" and "non-normative" section labeling.

For the second, 2119 made a shift from the conformance language
of, e.g., RFC 1122 and 1123, to interoperability language.  In
retrospect, I think the implications of that change (quite
unintentionally, AFAICT) snuck by the community and perhaps have
never been adequately appreciated.  In many cases, there is no
practical difference but, it is sometimes important.  If that is
really our problem today --and a number of comments on these
threads suggest that it is -- then we aren't going to solve it
by discussing whether some words are written in upper case.  The
solution to that one probably lies in a 2119bis that provides
two sets of definitions (or at least explanations) and requires
each invoking document to call out which it is using.

best,
    john

---

From: Pat Thaler <[email-masked]>
Date: Wed, 30 Mar 2016 10:12:36 -0700

"must" has multiple meanings - it can indicate a requirement but it also
can be used to state the inevitable: e.g., "What goes up must come down."

Though in general, I'm not a fan of writing in all caps, "MUST" removes the
ambiguity indicating that it is to be understood as defined, rather than
having its regular English meaning.

All caps for the words also helps the requirement statements stand out when
scanning through a document.

On Wed, Mar 30, 2016 at 9:52 AM, Adam Roach <[email-masked]> wrote:

> nontrivially. There's a somewhat bawdy example of this that you can find by
> typing "capitalization matters" into Google Image Search. (Probably not
> safe to do in many workplaces).
>

---

From: Ole Jacobsen <[email-masked]>
Date: Wed, 30 Mar 2016 10:24:53 -0700 (PDT)

+1

A few years ago I stayed in a B&B in England. The owner asked me: "Do 
you require toast in the morning?" This particular use of "require"
is not commonly used in the US (at least not on the West Coast) unless
toast is some kind of medical substance.

All of which goes to show that words have different meaning and also 
different USAGE, often location-based.

Ole

---

From: Barry Leiba <[email-masked]>
Date: Wed, 30 Mar 2016 13:59:29 -0400

>> alter semantics based on case -- and that most readers of RFCs will not have
>> such detailed knowledge of RFC2119 nor read RFCs with the care such a rule
>> demands, my question BARRY and adam and EveryOne Else, is what makes anyone
>> think that such a rule must (MUST?) ensure proper reading of RFCs so as to
>> distinguish between normative portions and advisory portions?
>

I agree with the first and third sentences of what Dave Cridland said,
but I think we have to be a little careful about the second.  What I
think we can assume is an a priori knowledge of some of what 2119
says: that there are these capitalized key words that have special
meanings.  But it's quite clear from reviewing a lot of documents (one
of the fun things one gets to do as AD) that many writers do not know
how 2119 actually defines those.  I see significant misunderstandings
about "SHOULD" and "MAY" all the time, examples of which I can give
you if you like.  And one of my favourites is when someone used
"RECOMMENDED", I questioned it in a comment, and the response was,
"Yes, maybe we should switch that to 'SHOULD'."

As a complete side thing, I wonder how this all seems to
German-speakers, as German uses initial caps for all nouns.  I wonder
if anyone even notices if someone fails to do that.  I wonder if it
becomes puzzling, perhaps in some instances.

Barry

---

From: Stephan Wenger <[email-masked]>
Date: Wed, 30 Mar 2016 18:47:18 +0000

Hi Barry,

On 3/30/16, 10:59, "ietf on behalf of Barry Leiba" <[email-masked] on behalf of [email-masked]> wrote:
[...]

>becomes puzzling, perhaps in some instances.

German native speaker here.

Indeed, in German the first letter of a noun is capitalized, and indeed there are a very few examples where a noun and a (non-capitalized but otherwise spelled identically) non-noun have meanings that are not intuitively distinguishable.  One example is the plural noun “Spinnen” (spiders), and the verb “spinnen” (to spin/yarn and also to be bonkers :-)

There may even be a handful of cases (in all books of a sizable library) where that situation could lead to confusion when considering the context.  That would typically be slang language.  However, the amount of confusion is probably less than it would be in English, given the examples some folks provided here.

Except for acronyms, all-caps is a no-no in German, even for things like last names.

Stephan

---

From: Dave Cridland <[email-masked]>
Date: Wed, 30 Mar 2016 20:00:37 +0100

On 30 March 2016 at 18:59, Barry Leiba <[email-masked]> wrote:

> typically
> have
For future reference, I tend not to zero-index my sentences. ;-)

I think that MUST/SHOULD/MAY (the former two tempered by NOT) are
well-understood, although the strength of SHOULD is usually underestimated.
OPTIONAL is probably obvious enough (though its implications may not be),
and SHALL/RECOMMENDED are uncommon enough that they're probably not
understood nearly as well.

---

From: Mark Andrews <[email-masked]>
Date: Thu, 31 Mar 2016 06:19:26 +1100

> different USAGE, often location-based.

"table" can mean "to put aside" or to "make the focus of discussion"
or can be the actual physical item.

-- 
Mark Andrews, ISC
1 Seymour St., Dundas Valley, NSW 2117, Australia
PHONE: +61 2 9871 4742                 INTERNET: [email-masked]

---

From: "Drage, Keith (Nokia - GB)" <[email-masked]>
Date: Wed, 30 Mar 2016 19:28:39 +0000

This discussion seems to have started because rtcweb produced a document where the status (BCP, informative or standards track) was not clear and I could not even work it out from the use of pseudo normative language.

I would note that the meaning of even lower case “must” has to be clear, and in my view there is frequently an important distinction between “is obliged to” and “is expected to”, and even “should do”, all of which appear to be allowed by the Webster definition. Further, in the Oxford definition, only the first of these seems to be meant, so there is potentially an Atlantic divide here.

Further, when I have questioned in the past what some author has meant by using “must”, we frequently end up understanding that it was not meant at all. Sometimes it is hiding a somewhat differently phrased “MUST” requirement.

I could make similar arguments for other modal auxiliarys.

My other arguments for avoiding lower case versions are that other standards organizations (with one exception) do use lower case versions to explicitly define requirements, and the distinction of a usage within IETF is not necessarily understood, and secondly that it is far too easy for an editor with the misapplication of a single keypress to convert the case of a word.

Regards

Keith

From: rtcweb [mailto:[email-masked]] On Behalf Of EXT Dave Cridland
Sent: 30 March 2016 20:01
To: Barry Leiba
Cc: IETF discussion list; Heather Flanagan (RFC Series Editor); [email-masked]; IESG; Scott O. Bradner; Dave Crocker
Subject: Re: [rtcweb] Uppercase question for RFC2119 words

I think that MUST/SHOULD/MAY (the former two tempered by NOT) are well-understood, although the strength of SHOULD is usually underestimated. OPTIONAL is probably obvious enough (though its implications may not be), and SHALL/RECOMMENDED are uncommon enough that they're probably not understood nearly as well.

Barry

---

From: "Drage, Keith (Nokia - GB)" <[email-masked]>
Date: Wed, 30 Mar 2016 19:37:29 +0000

Irrespective of the rest of this discussion, a reviewer should always address every upper and lower case usage of such verbs and ensure they are appropriate, because that is the place most mistakes are made in being absolutely precise as to meaning.

Keith

From: rtcweb [mailto:[email-masked]] On Behalf Of EXT Dave Cridland
Sent: 30 March 2016 08:25
To: Brian E Carpenter
Cc: IETF discussion list; Heather Flanagan (RFC Series Editor); [email-masked]; IESG; John C Klensin; Barry Leiba; Scott O. Bradner
Subject: Re: [rtcweb] Fuzzy words [was Uppercase question for RFC2119 words]

On 30 March 2016 at 00:46, Brian E Carpenter <[email-masked]<mailto:[email-masked]>> wrote:
On 30/03/2016 05:34, John C Klensin wrote:
> <[email-masked]<mailto:[email-masked]>> wrote:
>
>> ...

      Brian