Subject: Re: [apps-review] [apps-discuss] Review of draft-ietf-eai-rfc5337bis-dsn-1

From: Eliot Lear <[email-masked]>
Date: Sun, 12 Dec 2010 17:40:58 +0100

I wrote:

On 12/7/10 8:07 AM, Eliot Lear wrote:
> I have been selected as the Applications Area Review Team reviewer for
> this draft (for background on apps-review, please see
> http://www.apps.ietf.org/content/applications-area-review-team).
> Please resolve these comments along with any other Last Call comments
> you may receive. Please wait for direction from your document shepherd
> or AD before posting a new version of the draft.
>
> Document: draft-ietf-eai-rfc5337bis-01
> Title: Internationalized Delivery Status and Disposition Notifications
> Reviewer: Eliot Lear
> Review Date: 7 Dec 2010
>

...

> More importantly, the specification makes use of the =/ operator  from
> RFC 5234, but for constructs that it does not control.  I don't know
> if this was the original intent or not, but I am a little concerned
> that use of =/ in a construct that is not wholly controlled by a
> single specification is asking for confusion later.  This is an
> optional specification, right?

After discussing this a bit with Dave Crocker, perhaps this problem is
all in my head.  Therefore, I recommend no change to the spec on this point.

Eliot

---

From: Dave CROCKER <[email-masked]>
Date: Sun, 12 Dec 2010 09:16:35 -0800

On 12/12/2010 8:40 AM, Eliot Lear wrote:
>> More importantly, the specification makes use of the =/ operator  from RFC
>> 5234, but for constructs that it does not control.  I don't know if this was
>> the original intent or not, but I am a little concerned that use of =/ in a
>> construct that is not wholly controlled by a single specification is asking
>> for confusion later.  This is an optional specification, right?
>
> After discussing this a bit with Dave Crocker, perhaps this problem is all in my
> head.  Therefore, I recommend no change to the spec on this point.

While I believe the current specification's use of =/ is not only legal but that 
it is in fact exactly the sort of use that was intended, I also note that it's a 
pretty unusual ABNF construct and that it might invite some confusion. 
Cross-referencing a rule from another specification strikes me as a big deal and 
that it's worth helping the reader as much as possible.

So I suggest having a citation for the original version of the rule be included 
in a comment associated with the new rule.

For example:

      generic-address =/ utf-8-enc-addr
                        ; updates Section 3.2.3 of [RFC3798]

d/

-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: Eliot Lear <[email-masked]>
Date: Sun, 12 Dec 2010 22:59:33 +0100

On 12/12/10 10:48 PM, Lyndon Nerenberg (VE6BBM/VE7TFX) wrote:
> The base IMAP RFC (3501) made this construct easy and (I think)
> relatively obvious.  YMMV.  If a grammar extension is globally
> applicable to a parent specification, I think the subject document
> reads easier if the extension is called out at the top of the grammar,
> rather than littering each ABNF element with a callout comment.  The
> alternatives can get very noisy, especially if there is multiple
> inheritance involved.

I take your point but then if you are calling out multiple
specifications someone has to go on a fishing expedition to understand
perhaps the single definition they want out of a specification.

Eliot

---

From: "Lyndon Nerenberg (VE6BBM/VE7TFX)" <[email-masked]>
Date: Sun, 12 Dec 2010 13:48:48 -0800

>                         ; updates Section 3.2.3 of [RFC3798]

FWIW, this is what I did for IMAP Binary (3516); it doesn't seem to have
caused any confusion:

  7.  Formal Protocol Syntax

   The following syntax specification uses the augmented Backus-Naur
   Form (ABNF) notation as used in [ABNF], and incorporates by reference
   the Core Rules defined in that document.

   This syntax augments the grammar specified in [IMAP4rev1].

   append         =/  "APPEND" SP mailbox [SP flag-list]
                      [SP date-time] SP literal8

   fetch-att      =/  "BINARY" [".PEEK"] section-binary [partial]
                      / "BINARY.SIZE" section-binary

   literal8       =   "~{" number "}" CRLF *OCTET
                      ; <number> represents the number of OCTETs
                      ; in the response string.

   msg-att-static =/  "BINARY" section-binary SP (nstring / literal8)
                      / "BINARY.SIZE" section-binary SP number

   partial        =   "<" number "." nz-number ">"

   resp-text-code =/  "UNKNOWN-CTE"

   section-binary =   "[" [section-part] "]"

--lyndon

---

From: Dave CROCKER <[email-masked]>
Date: Mon, 13 Dec 2010 10:01:29 -0800

On 12/12/2010 1:59 PM, Eliot Lear wrote:
>> applicable to a parent specification,
...
> perhaps the single definition they want out of a specification.

+1

I'm sympathetic to the desire to be "efficient" in writing this stuff, but 
specifications need to be very clear and very unambiguous.  Anything that 
requires extra searching by the reader is a big negative in specification writing.

There are different way of satisfying this requirement (that is, avoiding the 
searching or confusion.)  As long as there is almost no change a reader can miss 
that it's an externally-defined rule nor miss the citation to the external 
specification for that rule, then it ought to be acceptable.

The per-rule citation approach that I've suggested is by far the safest, but yes 
there are certainly situations where other approaches will work.

d/

-- 

   Dave Crocker