Re: RFC 2119 terms, ALL CAPS vs lower case

[Abdussalam Baryun]

Hi

It is preferable to update RFC2119 to be more suitable for IETF RFCs
in the future, IMO importance of using CAPS is understood, but when to
use lower case (e.g. must, should, etc.) is not clear. Some use their
sensibility to determine when to use lower case. In the end we can
leave it for the editors to feedback on that when submitting, or use
different sentences. In summary, from some discussions, RFC2119 seems
not to be the best practice so far.

Abdussalam

+
--On Sunday, May 20, 2012 07:53 +0100 Brian E Carpenter
 wrote:

> 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,

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Yoav Nir]

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

> -BEGIN PGP SIGNED MESSAGE-
> Hash: SHA256
> 
> On 05/20/2012 12:41 PM, Stephane Bortzmeyer wrote:
>> On Wed, May 16, 2012 at 11:06:25AM -0400, Simon Perreault
>>  wrote a message of 12 lines which said:
>> 
 One dreams of a period in which precision and elegance were not 
 mutually exclusive properties.
>>> 
>>> 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  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

la lojban satci .ije la lojban na'e nolmle

Re: RFC 2119 terms, ALL CAPS vs lower case

[Marc Petit-Huguenin]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On 05/20/2012 12:41 PM, Stephane Bortzmeyer wrote:
> On Wed, May 16, 2012 at 11:06:25AM -0400, Simon Perreault
>  wrote a message of 12 lines which said:
> 
>>> One dreams of a period in which precision and elegance were not 
>>> mutually exclusive properties.
>> 
>> 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  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: m...@petit-huguenin.org
Professional email: petit...@acm.org
Blog: http://blog.marc.petit-huguenin.org
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.12 (GNU/Linux)

iQIcBAEBCAAGBQJPuVXnAAoJECnERZXWan7E4tEP/RmoX1ga8rxp9PdWgBKImiwu
HYrypdCvVndRLwrdnNiEBU0hx83gdOdFn6MhOImmVmY7LMwuL0sofkCI9Y4ZnN4G
X6yBHqji1aTbGHbliQK5p44pebqX7NKxtQa4msFCl+8BNQ6bezHmwK9CKyN7QMSc
zXaA8Y7wo0mlmgbPfCF93/cR3yXUEdKLOi3wZDwEP/jFX632cUS6n2am9mL/HZA9
qm8td0F0xRb/+oV0MMfzEb+MDDi2TptKDNDSXIqyCMsZ1qMyVUwVOCTUnJ7waxoX
dmHTZ5HhPFlOTY+aPYwSDzmqDfZa4jd1z6vUR5hZ2uLxLX6LD4/Bjc4W2E1yPWG+
BAZxGbwNchWwXlb1xzuCch4CVIXtuN7nGe3EPvNDLiWM50vSuFyOROsIaV1MgW0W
EVA0Vk68CvDu9O+OjCg83eDkFHi/OHloTqz0tx71xD5vtnPxrZWvR4hdIe/ffs4e
i/PKY2c0PItN9vA4hskDkoJoXQ1Drg91t9eoh4qJBulm4+YZ+Xv6SrmmnYJtzTzk
ezHeCzatkGB9FvXoyBkNnbZPLFDqgHuPDIdcV067x+r2Yqdywb04ECy/30Dy6HfH
BI//qYZEO3fbgbLYz7s8NpvuucP43OpsDIkUpp4p7CKss1LTVodiWd7aj5HdN8W2
QcmRb7nsKeR1jGigGIjR
=tiWK
-END PGP SIGNATURE-

Re: RFC 2119 terms, ALL CAPS vs lower case

[Stephane Bortzmeyer]

On Wed, May 16, 2012 at 11:06:25AM -0400,
 Simon Perreault  wrote 
 a message of 12 lines which said:

> >One dreams of a period in which precision and elegance were not
> >mutually exclusive properties.
> 
> 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  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.

Re: RFC 2119 terms, ALL CAPS vs lower case

[Brian E Carpenter]

On 2012-05-20 17:29, John C Klensin wrote:
> 
> --On Sunday, May 20, 2012 07:53 +0100 Brian E Carpenter
>  wrote:
> 
>> 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,
> 
> I've been trying really hard to avoid this discussion, but I
> 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.

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

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

   Brian

> 
> john
> 
> 
> 
> 
> 
> 
> 

Re: RFC 2119 terms, ALL CAPS vs lower case

[John C Klensin]

--On Sunday, May 20, 2012 07:53 +0100 Brian E Carpenter
 wrote:

> 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,

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Hector Santos]

Brian E Carpenter wrote:

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.


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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Stephen Farrell]

On 05/20/2012 07:25 AM, Yaakov Stein wrote:
> 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.

Re: RFC 2119 terms, ALL CAPS vs lower case

[Bill McQuillan]

On Sat, 2012-05-19, Brian E Carpenter wrote:
> 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.

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:

   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.

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 

Re: RFC 2119 terms, ALL CAPS vs lower case

[Brian E Carpenter]

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

RE: RFC 2119 terms, ALL CAPS vs lower case

[Yaakov Stein]

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

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

> 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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Eliot Lear]

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?

Re: RFC 2119 terms, ALL CAPS vs lower case

[Ofer Inbar]

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Carsten Bormann]

On May 19, 2012, at 08:48, Brian E Carpenter wrote:

> Very seriously - after all that has been said on this thread, I see
> no reason to change anything. 

+1

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

Grüße, Carsten

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

> Very seriously - after all that has been said on this thread, I see
> 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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Brian E Carpenter]

On 2012-05-18 19:27, Randy Bush wrote:
>> 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?

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

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

randy

Re: RFC 2119 terms, ALL CAPS vs lower case

[Ralph Droms]

On May 18, 2012, at 2:40 PM 5/18/12, Randy Bush wrote:

>> Dave Crocker's suggestion would minimize the number of words taken out
>> of our vocabulary:
> 
> for a language other than english.
> 
>> In addition to "clear and concise" we need precision and avoidance of
>> ambiguity.
> 
> wonderful rofl.  thanks.  mind if i put that in my public quotes file?

Always happy to entertain, even if unintentionally...

- Ralph

> 
> randy

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

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

for a language other than english.

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

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

randy

Re: RFC 2119 terms, ALL CAPS vs lower case

[Ralph Droms]

On May 18, 2012, at 2:27 PM 5/18/12, Randy Bush wrote:

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

You are correct and point taken.  

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

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


> 
> randy

Re: RFC 2119 terms, ALL CAPS vs lower case

[ned+ietf]

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

And therefore explicitly disallowed by the erratum process.

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

A very emphatic +1.

Ned

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

> 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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Eric Rosen]

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Marshall Eubanks]

On Fri, May 18, 2012 at 12:41 PM, Ralph Droms  wrote:
>
> On May 16, 2012, at 10:22 PM 5/16/12, Ned Freed wrote:
>
>>
>>> On May 16, 2012, at 5:22 PM 5/16/12, ned+i...@mauve.mrochek.com wrote:
>>
>>  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.

> i like this a lot

 I agree. In fact I just incorporated it into the media types registration
 update.
>>
>>> 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.
>
> 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."

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

Regards
Marshall

>
> - Ralph
>
>>
>>                               Ned
>

Re: RFC 2119 terms, ALL CAPS vs lower case

[Ralph Droms]

On May 16, 2012, at 10:22 PM 5/16/12, Ned Freed wrote:

> 
>> On May 16, 2012, at 5:22 PM 5/16/12, ned+i...@mauve.mrochek.com wrote:
> 
>  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.
>>> 
 i like this a lot
>>> 
>>> I agree. In fact I just incorporated it into the media types registration
>>> update.
> 
>> 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.

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

> 
>   Ned

Re: RFC 2119 terms, ALL CAPS vs lower case

[ned+ietf]

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

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Marshall Eubanks]

On Fri, May 18, 2012 at 1:06 AM, Hector Santos  wrote:
> Lee Howard wrote:
>>
>>
>>> -Original Message-
>>> From: ietf-boun...@ietf.org [mailto:ietf-boun...@ietf.org] On Behalf Of
>>
>> Dave Cridland
>>>
>>> Consider:
>>>
>>> "An octet may contain 0-255".
>>> "An octet contains 0-255".
>>> "An octet might contain 0-255" - or it might not?
>>> "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.
>
>
> Or colorizing it.

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


>
>
>> We should avoid rfc2119 language where possible, to be clear, but not at
>> the
>> expense of clarity.
>
>
> +1, I think this is more specific to documents and not RFC2119. I don't
> think we can generalize RFC2119.
>
>
> --
> HLS
>
>

Re: RFC 2119 terms, ALL CAPS vs lower case

[Hector Santos]

Lee Howard wrote:



-Original Message-
From: ietf-boun...@ietf.org [mailto:ietf-boun...@ietf.org] On Behalf Of

Dave Cridland

Consider:

"An octet may contain 0-255".
"An octet contains 0-255".
"An octet might contain 0-255" - or it might not?
"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.


Or colorizing it.


We should avoid rfc2119 language where possible, to be clear, but not at the
expense of clarity.


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



--
HLS

RE: RFC 2119 terms, ALL CAPS vs lower case

[Lee Howard]

> -Original Message-
> From: ietf-boun...@ietf.org [mailto:ietf-boun...@ietf.org] On Behalf Of
Dave Cridland
> Consider:
> 
> "An octet may contain 0-255".
> "An octet contains 0-255".
> "An octet might contain 0-255" - or it might not?
> "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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Julian Reschke]

On 2012-05-16 22:29, Dave Cridland wrote:

On Wed May 16 21:10:02 2012, Randy Bush wrote:

> Authors must be fastidious about this.

s/this/documents/


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


+100

Re: RFC 2119 terms, ALL CAPS vs lower case

[Tony Finch]

Randy Bush  wrote:

> can != may
>
> 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.finchhttp://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.

Re: RFC 2119 terms, ALL CAPS vs lower case

[Tony Finch]

Andrew Sullivan  wrote:
> 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…

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.finchhttp://dotat.at/
Humber, Thames: South or southwest 3 or 4, backing east 4 or 5 later. Slight
or moderate. Mainly fair. Mainly good.

Re: RFC 2119 terms, ALL CAPS vs lower case

[t . p .]

- Original Message -
From: "Doug Barton" 
To: 
Cc: "Barry Leiba" 
Sent: Thursday, May 17, 2012 7:18 AM
> On 05/16/2012 06:59, Barry Leiba wrote:
> > In fact, RFC 2119 says that the normative keywords are "often
> > 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.

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

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Doug Barton]

On 05/16/2012 06:59, Barry Leiba wrote:
> In fact, RFC 2119 says that the normative keywords are "often
> 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

Re: RFC 2119 terms, ALL CAPS vs lower case

[ned+ietf]

> On May 16, 2012, at 5:22 PM 5/16/12, ned+i...@mauve.mrochek.com wrote:

> >>>   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.
> >
> >> i like this a lot
> >
> > I agree. In fact I just incorporated it into the media types registration
> > update.

> 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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Hector Santos]

+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


Brian E Carpenter wrote:

On 2012-05-16 18:53, Peter Saint-Andre wrote:

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


...

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.


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.


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.


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.

Re: RFC 2119 terms, ALL CAPS vs lower case

[Jaap Akkerhuis]

I'm looking forward to the normative use of 

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

jaap

Re: RFC 2119 terms, ALL CAPS vs lower case

[Dave Crocker]

+1

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

Peter Saint-Andre  wrote:

>On 5/16/12 12:26 PM, Ole Jacobsen wrote:
>> 
>> 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...
>
>Although I too dream the impossible dream, I would prefer not to trust
>in formatting to enforce the semantic distinction in this instance.
>
>Peter


/d
--
 Dave Crocker
 Brandenburg InternetWorking
 bbiw.net

 via mobile

Re: RFC 2119 terms, ALL CAPS vs lower case

[Ralph Droms]

On May 16, 2012, at 5:22 PM 5/16/12, ned+i...@mauve.mrochek.com wrote:

>>>   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.
> 
>> i like this a lot
> 
> I agree. In fact I just incorporated it into the media types registration
> update.

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

> 
>   Ned

Re: RFC 2119 terms, ALL CAPS vs lower case

[ned+ietf]

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

> i like this a lot

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

Ned

Re: [IETF] RE: RFC 2119 terms, ALL CAPS vs lower case

[Warren Kumari]

On May 16, 2012, at 4:10 PM, Worley, Dale R (Dale) wrote:

>> From: John C Klensin [john-i...@jck.com]
>> 
>>> 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.
>> 
>> 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.
> 
> I'm looking forward to the normative use of 

Errr… would that be more or less strong then the non- 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

> 
> Dale
> 

Re: RFC 2119 terms, ALL CAPS vs lower case

[Dave Cridland]

On Wed May 16 21:10:02 2012, Randy Bush wrote:

> Authors must be fastidious about this.

s/this/documents/


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:d...@cridland.net - xmpp:d...@dave.cridland.net
 - acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/
 - http://dave.cridland.net/
Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade

RE: RFC 2119 terms, ALL CAPS vs lower case

[Worley, Dale R (Dale)]

> From: John C Klensin [john-i...@jck.com]
> 
> > 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.
> 
> 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.

I'm looking forward to the normative use of 

Dale

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

> Authors must be fastidious about this.

s/this/documents/

> "It may rain today" is fine

iff you are talaya

randy

RE: RFC 2119 terms, ALL CAPS vs lower case

[John C Klensin]

--On Wednesday, May 16, 2012 19:45 +0100 Adrian Farrel
 wrote:

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

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Ole Jacobsen]

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
Editor and Publisher,  The Internet Protocol Journal
Cisco Systems
Tel: +1 408-527-8972   Mobile: +1 415-370-4628
E-mail: o...@cisco.com  URL: http://www.cisco.com/ipj
Skype: organdemo


On Wed, 16 May 2012, Peter Saint-Andre wrote:

> On 5/16/12 12:26 PM, Ole Jacobsen wrote:
> > 
> > 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...
> 
> Although I too dream the impossible dream, I would prefer not to trust
> in formatting to enforce the semantic distinction in this instance.
> 
> Peter
> 

RE: RFC 2119 terms, ALL CAPS vs lower case

[Adrian Farrel]

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:stpe...@stpeter.im]
> Sent: 16 May 2012 19:43
> To: Ole Jacobsen
> Cc: Mary Barnes; adr...@olddog.co.uk; Sam Hartman; ietf@ietf.org
> Subject: Re: RFC 2119 terms, ALL CAPS vs lower case
> 
> On 5/16/12 12:26 PM, Ole Jacobsen wrote:
> >
> > 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...
> 
> Although I too dream the impossible dream, I would prefer not to trust
> in formatting to enforce the semantic distinction in this instance.
> 
> Peter

Re: RFC 2119 terms, ALL CAPS vs lower case

[Peter Saint-Andre]

On 5/16/12 12:26 PM, Ole Jacobsen wrote:
> 
> 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...

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

Peter

Re: RFC 2119 terms, ALL CAPS vs lower case

[Ole Jacobsen]

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: o...@cisco.com  URL: http://www.cisco.com/ipj
Skype: organdemo

Re: RFC 2119 terms, ALL CAPS vs lower case

[Brian E Carpenter]

On 2012-05-16 18:53, Peter Saint-Andre wrote:
> On 5/16/12 9:58 AM, Sam Hartman wrote:

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

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.

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

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Mary Barnes]

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.

On Wed, May 16, 2012 at 12:53 PM, Peter Saint-Andre wrote:

> On 5/16/12 9:58 AM, Sam Hartman wrote:
> >> "Adrian" == Adrian Farrel  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.
>
> 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/
>
>
>

Re: RFC 2119 terms, ALL CAPS vs lower case

[Peter Saint-Andre]

On 5/16/12 9:58 AM, Sam Hartman wrote:
>> "Adrian" == Adrian Farrel  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.

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/

Re: RFC 2119 terms, ALL CAPS vs lower case

[Hector Santos]

+1

Randy Bush wrote:

can != may

one is ability, the other permission

randy




--
HLS

Re: RFC 2119 terms, ALL CAPS vs lower case

[Sam Hartman]

> "Adrian" == Adrian Farrel  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.

Re: RFC 2119 terms, ALL CAPS vs lower case

[Dave Crocker]

On 5/16/2012 7:56 AM, Andrew Sullivan wrote:

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.



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

gOOd to NO.

d/
--
 Dave Crocker
 Brandenburg InternetWorking
 bbiw.net

Re: RFC 2119 terms, ALL CAPS vs lower case

[Simon Perreault]

On 2012-05-16 10:56, Andrew Sullivan wrote:

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?


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


You mean when French was the dominant language?

Simon

Re: RFC 2119 terms, ALL CAPS vs lower case

[Andrew Sullivan]

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.

> 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?

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

Best,

A

-- 
Andrew Sullivan
a...@anvilwalrusden.com

Re: RFC 2119 terms, ALL CAPS vs lower case

[Dave Crocker]

On 5/16/2012 7:39 AM, Randy Bush wrote:

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.


i like this a lot



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/

--
 Dave Crocker
 Brandenburg InternetWorking
 bbiw.net

RE: RFC 2119 terms, ALL CAPS vs lower case

[Adrian Farrel]

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

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

i like this a lot

randy

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

>>> can != may
>>> 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.
> I must be ancient then as I still use this distinction (and similarly 
> would/could).

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

further, quoting barry:

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

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

Re: RFC 2119 terms, ALL CAPS vs lower case

[Dave Crocker]

On 5/16/2012 7:34 AM, Scott Kitterman wrote:

On Wednesday, May 16, 2012 07:31:53 AM Dave Crocker wrote:

On 5/16/2012 7:28 AM, Randy Bush wrote:

can != may

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.


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



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/

--
 Dave Crocker
 Brandenburg InternetWorking
 bbiw.net

Re: RFC 2119 terms, ALL CAPS vs lower case

[Edward Lewis]

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


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.


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
NeuStarYou can leave a voice message at +1-571-434-5468

2012...time to reuse those 1984 calendars!

Re: RFC 2119 terms, ALL CAPS vs lower case

[Scott Kitterman]

On Wednesday, May 16, 2012 07:31:53 AM Dave Crocker wrote:
> On 5/16/2012 7:28 AM, Randy Bush wrote:
> > can != may
> > 
> > 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.

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

Scott K

Re: RFC 2119 terms, ALL CAPS vs lower case

[Dave Crocker]

On 5/16/2012 7:28 AM, Randy Bush wrote:

can != may

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/
--
 Dave Crocker
 Brandenburg InternetWorking
 bbiw.net

Re: RFC 2119 terms, ALL CAPS vs lower case

[Randy Bush]

can != may

one is ability, the other permission

randy

Re: RFC 2119 terms, ALL CAPS vs lower case

[Dave Crocker]

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

This passes all nit checks, including those involving the eyes of the
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.




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,


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.



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.


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