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

From: Eliot Lear <[email-masked]>
Date: Tue, 07 Dec 2010 08:07:27 +0100

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

Summary:

This draft is almost ready for publication but has a few *minor* issues
that should be considered prior to publication.  Great job!

Major Issues:  none.  Cool!

Minor Issues:

The document does not state clearly what the differences between this
specification and RFC5337.  Doing so could speed adoption of this
specification.  As some of the changes seem subtle, such an addition
would be particularly welcome.

ABNF:  Courtesy of Bill Fenner's ABNF checker, there are several changes
that could be made for clarity:

Upper-casify hex (e.g., 2a->2A) [throughout]
Combine "Diagnostic-Code" ":" -> ""Diagnostic-Code:"
Combine "Localized-Diagnostic" ":" -> ""Localized-Diagnostic:"
Combine "Failure" ":" -> "Failure:"
Combine "Warning" ":" -> "Warning:"

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?

Finally, in the beginning of the document you discuss whether or not to
create a new registration, and indicate that the working group chose not
to create a new registration. I can easily imagine good reasoning for
this, but perhaps you might elaborate in descriptive language the nature
of the choice and why you chose one way rather than the other,
especially in light of what may seem like a contrary decision in 5336bis.

Regards,

Eliot

---

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

I wrote:

> Title: Internationalized Delivery Status and Disposition Notifications

...

> 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: "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] "]"

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.

--lyndon

---

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

> alternatives can get very noisy, especially if there is multiple

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