Subject: Re: RFC2119 Upper Case Syntax for rfc2460bis

From: Jen Linkova <[email-masked]>
Date: Tue, 3 Nov 2015 09:08:17 +0100

On Mon, Oct 26, 2015 at 8:55 PM, Bob Hinden <[email-masked]> wrote:
>>> Thanks.  I am not sure it needs to be in the actual RFC as it seems more to me about IETF procedures than IPv6.  It will definitely be in the write up when (if?) this goes to the IESG and that will be recored in the data-tracker for posterity.
>>
>> I would like to see it in the actual RFC, because the RFC series is a Publication, whereas the data-tracker is not.
>>
>> Put another way, I’m fairly confident that Posterity will be able to read RFC 2460 for the next millennium, even after it passes into the Historical category, and I’m much less confident that Posterity will be able to find the data-tracker after such a long time, much less query it for the entire history of the IETF. I’m not even very confident that all the public information stored in the data-tracker today will continue to be available next week, much less after a millennium.
>
> I am sure it will be fertile grounds to future IETF historians :-)
>
> Any other view on this?

To be honest, I do see value in using RFC2119 language for the
following reasons:

- I've been involved in at least two long and not very productive
discussions with developers when they were using 'it is not in capital
letters, so it is not real MUST' argument. I'm not sure there are
people which are (and will be) confused.
- while it is understandable why RFC2460 does not use RFC2119
language, it might be very confusing for readers to see an RFC
published in 2015 which is not using the language convention so
typical for other RFCs.
- RFC2119 clearly defines what all those terms mean. Not using RFC2119
language allow readers (especially if English is not their native
language) interpret the nuances rather freely. (is 'shall not' is
'must not' or 'should not'? 'yes, it says 'should' so we add it in the
next version of software' etc).

If there is a strong preference not to update the text with capital
letters and reference to RFC2119, maybe it make sense to put a note
saying 'lower case must/shall/should... are used as MUST/SHALL...
defined in RFC2119'?

-- 
SY, Jen Linkova aka Furry

---

From: Fernando Gont <[email-masked]>
Date: Tue, 3 Nov 2015 17:56:00 +0900

On 11/03/2015 05:08 PM, Jen Linkova wrote:
>>>> Thanks.  I am not sure it needs to be in the actual RFC as it
>>>> seems more to me about IETF procedures than IPv6.  It will
>>>> definitely be in the write up when (if?) this goes to the IESG
>>>> and that will be recored in the data-tracker for posterity.
>>> 
>>> I would like to see it in the actual RFC, because the RFC series
>>> is a Publication, whereas the data-tracker is not.
>>> 
>>> Put another way, I’m fairly confident that Posterity will be able
>>> to read RFC 2460 for the next millennium, even after it passes
>>> into the Historical category, and I’m much less confident that
>>> Posterity will be able to find the data-tracker after such a long
>>> time, much less query it for the entire history of the IETF. I’m
>>> not even very confident that all the public information stored in
>>> the data-tracker today will continue to be available next week,
>>> much less after a millennium.
>> 
> discussions with developers when they were using 'it is not in
> capital letters, so it is not real MUST' argument. I'm not sure there
> are people which are (and will be) confused. - while it is
> understandable why RFC2460 does not use RFC2119 language, it might be
> very confusing for readers to see an RFC published in 2015 which is
> not using the language convention so typical for other RFCs. -
> RFC2119 clearly defines what all those terms mean. Not using RFC2119 
> 'must not' or 'should not'? 'yes, it says 'should' so we add it in
> the next version of software' etc).

+1 to the above.

> saying 'lower case must/shall/should... are used as MUST/SHALL... 

I bet that will result in some use "must" or "should"s that are not
meant to be requirements to be considered as such... So... while
painful, I'd be game for using RFC2119 where appropriate.

Thanks!

Cheers,
-- 
Fernando Gont
SI6 Networks
e-mail: [email-masked]
PGP Fingerprint: 6666 31C6 D484 63B2 8FB1 E3C4 AE25 0D55 1D4E 7492

---

From: "Fred Baker (fred)" <[email-masked]>
Date: Tue, 3 Nov 2015 13:45:21 +0000

> On Oct 21, 2015, at 6:58 AM, Bob Hinden <[email-masked]> wrote:
> 
> Formally RFC2119 is not required to be used, nor does it require upper case language. It’s use is a SHOULD :-)

Speaking for myself, I understand the arguments you make against adjusting the text, but I think the difference from RFC 2119 has been unfortunate. I would rather see the document either reference 2119 and obey those meanings or find other words, in order to clear up the ambiguity present in the document as it stands.

---

From: Jen Linkova <[email-masked]>
Date: Tue, 3 Nov 2015 14:59:03 +0100

On Tue, Nov 3, 2015 at 9:56 AM, Fernando Gont <[email-masked]> wrote:
> meant to be requirements to be considered as such...

Wait, what? all "must" are equal, but some "must" are more equal than others?
If there are 'must' which are actually MUST and there are 'must' which
are not MUST - how can we tell one from the other?
How can we expect any interoperability?

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 4 Nov 2015 10:34:23 +1300

> How can we expect any interoperability?

I have a much bigger problem (as a Gen-ART reviewer) when I read a draft
in an area I don't know well, if the document cites RFC 2119 and I find an
instance of lower-case 'must', or even worse, lower-case 'may' used when the
writer might actually mean 'might'. Then I really cannot decide whether the
text guarantees interoperability. The presence of 'MUST' and 'MAY' elsewhere
in the draft really doesn't help with that.

What I suggest is that when all the other work on this draft is done, we
all review it carefully for ambiguity, and where we find ambiguity, we fix
it. After that we could have a sensible discussion whether s/must/MUST/ etc
would add any value.

   Brian

    Brian

---

From: t.petch <[email-masked]>
Date: Wed, 4 Nov 2015 10:17:55 +0000

----- Original Message -----
From: "Jen Linkova" <[email-masked]>
To: "Fernando Gont" <[email-masked]>
Cc: "IPv6 List" <[email-masked]>; "Bob Hinden" <[email-masked]>
Sent: Tuesday, November 03, 2015 1:59 PM
> How can we expect any interoperability?

Yup and yup.  I looked and saw some 70 'should' or 'must' in this I-D
and believe that turning them into 'SHOULD' and 'MUST' will indeed
provoke discussion about some of them; and yes, I see that as a
necessary part of turning this into a Standard.  I have seen the use of
'must' raise discussions on a number of occasions, usually at IESG
Review or IETF Last Call, and think that they are best resolved within
the WG.

Tom Petch

> --------------------------------------------------------------------
> IETF IPv6 working group mailing list
> [email-masked]
> Administrative Requests: https://www.ietf.org/mailman/listinfo/ipv6
> --------------------------------------------------------------------

---

From: "George, Wes" <[email-masked]>
Date: Wed, 4 Nov 2015 23:11:51 +0000

On 10/26/15, 8:59 PM, "ipv6 on behalf of Brian E Carpenter"
<[email-masked] on behalf of [email-masked]> wrote:

>if we read the
>text critically for ambiguity we should be OK. In a sense, the upper case
>usage
>is just a lazy writing technique.
>
>I think it's a sad day if we have to write "In this document, English
>words written
>in lower case mean what they say, without resorting to SHOUTING." In
>other words,
>I take James' point but I don't know how to express it without absurdity.

WG] Sorry Brian, the ship has already sailed on that, and calling it lazy
really doesn't help the discussion. Much like many other colloquial abuses
of language that are initially unacceptable but gradually become
acceptable to everyone but grammarians due to common and widespread
adoption, a large part of the IETF authorship has been using the mental
and textual shortand "CAPS=NORMATIVE, lowercase=conversational" for long
enough now without anyone making a fuss that it's becoming a de facto
standard. It is also a nuance lost on a large portion of the readership,
because they don't see all of 2119 before reading a document. They read
the boilerplate at the top of the document they're reading, which only
uses CAPS:
"Requirements Language

   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"

But independent of caps/no caps, I think it's far more important to make
the normative language in 2460 unambiguously compliant with 2119 than it
is to preserve the original text. Since you are incorporating post-2119
text anyway, I think you MUST change the original text where appropriate
for consistency's sake. This group should be perfectly capable of using
language to make things clear without breaking interoperability,
especially since many of the folks involved in the original document can
help us with interpretation of intent where the original document is, dare
I say it, unclear.
A good standard isn't ambiguous. We have too many ESL authors and readers,
and readers not steeped in IETF tradition to rely on subtle context for
clues as to which things are normative in the original text and which are
not.
Further, the entire point behind taking the extra effort to incorporate
updates and errata is to consolidate the updates that have happened since
the original standard was written. We want an easier to underatand and
implement standard (one not spread across many subtending documents, where
the union of them is not always completely clear). Part of the necessary
updates is due to the fact that since the document was written, we have a
defined set of standardized normative keywords, and a commonly accepted
format for them (uppercase). This document should conform, because the
idea is to have a document that represents the state of the art when it
was published. This update before promotion to full standard is the
closest thing IETF has to a living document, and the result will be worth
the effort. This is like the building code - if you open the wall to
renovate, you have to bring what you find inside up to compliance with the
current code.

Wes George

________________________________

This E-mail and any of its attachments may contain Time Warner Cable proprietary information, which is privileged, confidential, or subject to copyright belonging to Time Warner Cable. This E-mail is intended solely for the use of the individual or entity to which it is addressed. If you are not the intended recipient of this E-mail, you are hereby notified that any dissemination, distribution, copying, or action taken in relation to the contents of and attachments to this E-mail is strictly prohibited and may be unlawful. If you have received this E-mail in error, please notify the sender immediately and permanently delete the original and any copy of this E-mail and any printout.

---

From: Lorenzo Colitti <[email-masked]>
Date: Thu, 5 Nov 2015 09:13:57 +0900

On Thu, Nov 5, 2015 at 8:11 AM, George, Wes <[email-masked]>
wrote:

> This group should be perfectly capable of using
> A good standard isn't ambiguous.
>

What he said.

---

From: James Woodyatt <[email-masked]>
Date: Thu, 5 Nov 2015 09:58:37 +0900

On Oct 27, 2015, at 04:55, Bob Hinden <[email-masked]> wrote:
> On Oct 26, 2015, at 11:24 AM, james woodyatt <[email-masked]> wrote:
>> On Oct 26, 2015, at 08:58, Bob Hinden <[email-masked]> wrote:
>>> 

Yes, my view is contrary to Lee Howard’s view (expressed at the microphone yesterday) respecting the readability of specifications using upper-case RFC 2119 keywords. In my experience, the diligent use of upper-case keywords greatly facilitates the work of visually scanning the text of a document for the normative requirements scattered amid the typical soup of informative prose.

Whenever I discover that a document that cites RFC 2119 does not diligently capitalize all the keywords it surprises and disappoints me. Yes, I’m probably using a document reader application with an automatic text search function, and I can use that if necessary, but sometimes— sometimes— I’m not. I might be using hard copy on paper, and let’s remember we still use a US-ASCII plain test as an archival format because hard copy on paper.

This is why I generally sympathize with those who would prefer to convert all the RFC 2119 keywords to upper case.

If we decide to diverge from the recommended capitalization strategy for RFC 2119 keywords then I want an explicit informative note to that effect for the reasons previously mentioned by Jen Linkova. I too have had more experiences than I would like to recall dealing with people who don’t have a pedantic standards lawyer’s understanding of the technical bits of RFC 2119 and who mistakenly think that only the upper case instances of the keywords denote normative text.

That’s why having a note right there in RFC 2460bis that explains the divergence from the recommended capitalization strategy is an acceptable compromise to me.

—james

---

From: Fernando Gont <[email-masked]>
Date: Thu, 5 Nov 2015 16:18:47 +0900

On 11/05/2015 09:58 AM, James Woodyatt wrote:
> Yes, my view is contrary to Lee Howard’s view (expressed at the
> microphone yesterday) respecting the readability of specifications
> using upper-case RFC 2119 keywords. In my experience, the diligent
> use of upper-case keywords greatly facilitates the work of visually
> scanning the text of a document for the normative requirements
> scattered amid the typical soup of informative prose.

+1

---

From: Bob Hinden <[email-masked]>
Date: Thu, 5 Nov 2015 18:55:36 +0900

James,

> That’s why having a note right there in RFC 2460bis that explains the divergence from the recommended capitalization strategy is an acceptable compromise to me.

While I am not against adding text to clarify how the language is used in these drafts, but please show where it says that capitalization is required or even recommended?  It doesn’t say that in RFC2119.

Bob

---

From: David Farmer <[email-masked]>
Date: Fri, 6 Nov 2015 15:48:15 -0600

> While I am not against adding text to clarify how the language is used in these drafts, but please show where it says that capitalization is required or even recommended?  It doesn’t say that in RF…

There is nothing that explicitly says it.  I think because the suggested 
boiler within RFC2119 used ALL-CAPS to add emphasis to the quoted 
keywords, it has become a common practice, and one might even call it de 
facto IETF style to use All-CAPS to add emphasis to normative uses of 
RFC2119 keywords.

Personally, I think as this is a style issue, and it SHOULD be well 
within the editorial discretion of the author.  And, I'd really prefer 
we not do something like update RFC2119 to make it mandatory, but we could.

That said, if I were the author of this, given the importance and 
expected longevity of this, I would probably update the RFC2119 key 
words to use ALL-CAPS.  But I'm with James, "having a note right there 
in RFC 2460bis that explains the divergence from the [expected] 
capitalization strategy is an acceptable compromise".   James originally 
call it "the recommend capitalization strategy", I think it is more 
accurate to call it "the expected capitalization strategy".

Finally, I would strongly object to the idea of leaving all the keywords 
lowercase, and omitting the RFC2119 boilerplate and reference or other 
similar note.  But you agreed to provide such a note.  So, once we see 
the proposed text I expect we can quickly finish this.

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