Subject: [apps-discuss] Apps-team review of draft-gellens-mime-bucket-bis-03

From: S Moonesamy <[email-masked]>
Date: Sat, 16 Apr 2011 06:43:30 -0700

Hello,

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-gellens-mime-bucket-bis-03
Reviewer: S. Moonesamy
Review Date: April 16, 2011
IETF Last Call Date: Unknown
IESG Telechat Date: Unknown

Summary:

This draft is almost ready for publication as a Proposed Standard but 
has a few nits that should be fixed before publication.

The Codecs Parameter for "Bucket" Media Types was specified in RFC 
4281.  This draft specifies the Codecs and Profiles Parameters for 
"Bucket" Media Types.  As it is a significant change from RFC 4281, 
it does not fit the requirements specified in RFC 2026 for Draft 
Standard.  Please refer to RFC 5657 for additional information about 
how to advance a protocol to Draft Standard.

Please note that I have not read ISO/IEC 14496-15:2010, a normative 
reference, as it is not freely available.

Major Issues:

None

Minor Issues:

None

Nits:

draft-gellens-mime-bucket-bis-03 obsoletes RFC 4281 but there is no 
mention of that in the Abstract Section or the rest of the document.

In Section 3.1:

   "An element MAY include an octet that must be encoded in order to
    comply with [RFC2045]"

I suggest capitalizing the "must" as key words are capitalized in 
that sentence.

   "Note that, when the [RFC2231] form is used, the percent
    sign, asterisk, and single quote characters have special meaning and
    so must themselves be encoded."

I suggest capitalizing the "must".

In Section 4.2:

   "An element MAY include an octet that must be encoded in order to
    comply with [RFC2045]"

I suggest capitalizing the "must".

   "Note that, when the [RFC2231] form is used,
    the percent sign, asterisk, and single quote characters have special
    meaning and so must themselves be encoded."

I suggest capitalizing the "must".

Regards,
S. Moonesamy

---

From: Randall Gellens <[email-masked]>
Date: Sun, 17 Apr 2011 10:34:07 -0700

Hi sm,

Thanks for the helpful review.  I appreciate it.

All: Please see below for my thoughts:

At 6:43 AM -0700 4/16/11, S Moonesamy wrote:

>  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.
>
>  This draft is almost ready for publication as a Proposed Standard 
> but has a few nits that should be fixed before publication.
>
> Standard.  Please refer to RFC 5657 for additional information 
> about how to advance a protocol to Draft Standard.
>

There is a document header for it, but I agree that for clarify, 
there should be a statement to this effect in the text.  My 
suggestion is to add text at the end of the second paragraph of the 
Abstract (which starts 'This document specifies two parameters, 
"codecs" and "profiles"'.  The new text can say something along the 
lines of 'RFC 4281 added the "codecs" parameter, which this document 
retains in a backwards compatible manor; the "profiles" parameter is 
added by this document.'

I think this makes the situation clear to those readers who aren't 
familiar with RFC 4281

>  I suggest capitalizing the "must" as key words are capitalized in 

This is a little tricky, because the "MAY include" in normative in 
this document (this document is imposing the rule) while the "must be 
encoded in order to comply" is descriptive; it describes the octet to 
which the rest of the clause applies.  I think simply capitalizing 
the "must" in this instance would make the text less clear.   What 
would people (especially my other authors) think about using wording 
such as:

     An element MAY include an octet that [RFC2045] REQUIRES to be

>  I suggest capitalizing the "must".

I agree.

>  I suggest capitalizing the "must".

I suggest using the wording from above:

     An element MAY include an octet that [RFC2045] REQUIRES to be

>  I suggest capitalizing the "must".

I agree.

-- 
Randall Gellens
Opinions are personal;    facts are suspect;    I speak for myself only
-------------- Randomly selected tag: ---------------
He who would travel happily must travel light.  --Antoine St. Exuperey

---

From: Randall Gellens <[email-masked]>
Date: Mon, 18 Apr 2011 12:06:35 -0700

At 11:36 AM -0700 4/18/11, David Singer wrote:

>  On Apr 17, 2011, at 10:34 , Randall Gellens wrote:
>
>>  Hi sm,
>>
>  I also appreciate it.  Thanks
>
>>
>>>  I have been selected as the Applications Area Review Team 
>>> reviewer for this draft (for background on apps-review, please 
>>> see 
>>>  The Codecs Parameter for "Bucket" Media Types was specified in 
>>> RFC 4281.  This draft specifies the Codecs and Profiles 
>>> Parameters for "Bucket" Media Types.  As it is a significant 
>>> change from RFC 4281, it does not fit the requirements specified 
>>> in RFC 2026 for Draft Standard.  Please refer to RFC 5657 for 
>>> additional information about how to advance a protocol to Draft 
>>> Standard.
>>>
>>>  Please note that I have not read ISO/IEC 14496-15:2010, a 
>>> normative reference, as it is not freely available.
>>>
>>>  Major Issues:
>>>
>>>  None
>>>
>>>  Minor Issues:
>>>
>>>  None
>>>
>>>  Nits:
>>>
>>>  draft-gellens-mime-bucket-bis-03 obsoletes RFC 4281 but there is 
>>> no mention of that in the Abstract Section or the rest of the 
>>> document.
>>
>> suggestion is to add text at the end of the second paragraph of 
>> the Abstract (which starts 'This document specifies two 
>> parameters, "codecs" and "profiles"'.  The new text can say 
>> something along the lines of 'RFC 4281 added the "codecs" 
>> parameter, which this document retains in a backwards compatible 
>> manor; the "profiles" parameter is added by this document.'
>
>  and makes other clarifications to the use of the codecs parameter.
>
>>
>  OK, I wasn't sure whether such textual backwards-pointers were even 
> allowed.  Now I know that they are encouraged.
>
>>
>>>
>>>  In Section 3.1:
>>>
>> this document (this document is imposing the rule) while the "must 
>> be encoded in order to comply" is descriptive; it describes the 
>> octet to which the rest of the clause applies.  I think simply 
>> capitalizing the "must" in this instance would make the text less 
>> clear.   What would people (especially my other authors) think 
>> about using wording such as:
>>
>  I agree, I think it best if capitalized verbs are used for 
> requirements expressed in the document. So I would not capitalize 
> 'requires' in this case, but it's OK by me.

Dave made my point, which is that it can be confusing when normative 
directives are used for informative purposes.  One approach I try to 
use is to reword to be descriptive, but it's hard in this case.  I 
think "requires" can be written lower case here.

>  Existing text from 4281.  Can I have  MUST in a 'Note' sentence? 
> Most bodies don't allow that.  I think that the 'Note that,' should 
> go:
>  When the [RFC2231] form is used, the percent
>     so MUST themselves be encoded.

I've used MUST in notes before; I think it's fine here.

>
>  Similarly below....
>
>  New suggested text (not yet uploaded, as per intsructions)
>
>
>  Attachment converted: TiLand:draft-gellens-mime-#29C6465.txt 
> (TEXT/R*ch) (029C6465)
>
>>
>>>
>>>  In Section 4.2:
>>>
>  David Singer
>  Multimedia and Software Standards, Apple Inc.

-------------- Randomly selected tag: ---------------
The trouble with the world is not that people know too little, but
that they know so many things that ain't so.
--Mark Twain

---

From: S Moonesamy <[email-masked]>
Date: Mon, 18 Apr 2011 23:59:55 -0700

Hi Randy,

I removed the IESG from the Cc as the Apps Area ADs read the 
apps-discuss mailing list and can provide feedback to the IESG.

>retains in a backwards compatible manor; the "profiles" parameter is 

I noticed the document header.  As this is an editorial nit, feel 
free to ignore the comment.  Section 4.1.1 of the RFC Style Guide 
mentions that "Authors often also include a statement in the Abstract 
and/or Introduction sections".   That is flagged as a "should" by 
ID-nits by the way.  Your above comment sums up the changes in this draft.

You could also have:

    This document specifies two parameters, "codecs" and "profiles", which are
    used with various MIME types or type/subtype combinations to allow for
    unambiguous specification of the codecs and/or profiles  employed by the
    media formats contained within.  This document obsoletes RFC 4281 and
    retains the "codecs" parameter in a backwards compatible manner; the.

"profiles" parameter is added by this document.
>I think this makes the situation clear to those readers who aren't 

Yes.

>clear.   What would people (especially my other authors) think about 
>using wording such as:

Thanks for explaining the subtlety of the "must".

>     encoded.  In this case, [RFC2231] is used:

Ok.

>     encoded.  In this case, [RFC2231] is used:

Ok.

Best regards,
S. Moonesamy

---

From: S Moonesamy <[email-masked]>
Date: Tue, 19 Apr 2011 00:41:30 -0700

Hi David,
>'requires' in this case, but it's OK by me.

Randy commented on this in another message.  The "requires" should be 
clear enough.

>Existing text from 4281.  Can I have  MUST in a 'Note' 
>sentence?  Most bodies don't allow that.  I think that the 'Note 
>that,' should go:

I have seen "MUST" used in "Note" sentences in other RFCs.  You 
already had similar text in the RFC published in 2005.  As it hasn't 
been a problem, I don't see why it should be a problem now.

By the way, I gave an "almost ready for publication" rating as the 
document state is "Publication Requested" and the authors already 
know how to address editorial nits.

Regards,
S. Moonesamy

---

From: David Singer <[email-masked]>
Date: Mon, 18 Apr 2011 11:36:17 -0700

>> 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.
>> 
>> This draft is almost ready for publication as a Proposed Standard but has a few nits that should be fixed before publication.
>> 
>> The Codecs Parameter for "Bucket" Media Types was specified in RFC 4281.  This draft specifies the Codecs and Profiles Parameters for "Bucket" Media Types.  As it is a significant change from RFC 4281, it does not fit the requirements specified in RFC 2026 for Draft Standard.  Please refer to RFC 5657 for additional information about how to advance a protocol to Draft Standard.
>> 
>> Please note that I have not read ISO/IEC 14496-15:2010, a normative reference, as it is not freely available.
>> 
>> Major Issues:
>> 
>> None
>> 
>> Minor Issues:
>> 
>> None
>> 
>> Nits:
>> 
>> draft-gellens-mime-bucket-bis-03 obsoletes RFC 4281 but there is no mention of that in the Abstract Section or the rest of the document.
> 
> There is a document header for it, but I agree that for clarify, there should be a statement to this effect in the text.  My suggestion is to add text at the end of the second paragraph of the Abstract (which starts 'This document specifies two parameters, "codecs" and "profiles"'.  The new text can say something along the lines of 'RFC 4281 added the "codecs" parameter, which this document retains in a backwards compatible manor; the "profiles" parameter is added by this document.'

> 
> I think this makes the situation clear to those readers who aren't familiar with RFC 4281

OK, I wasn't sure whether such textual backwards-pointers were even allowed.  Now I know that they are encouraged.

>> I suggest capitalizing the "must" as key words are capitalized in that sentence.
> 
> This is a little tricky, because the "MAY include" in normative in this document (this document is imposing the rule) while the "must be encoded in order to comply" is descriptive; it describes the octet to which the rest of the clause applies.  I think simply capitalizing the "must" in this instance would make the text less clear.   What would people (especially my other authors) think about using wording such as:
> 

I agree, I think it best if capitalized verbs are used for requirements expressed in the document. So I would not capitalize 'requires' in this case, but it's OK by me.

>> I suggest capitalizing the "must".

Existing text from 4281.  Can I have  MUST in a 'Note' sentence?  Most bodies don't allow that.  I think that the 'Note that,' should go:
When the [RFC2231] form is used, the percent
   sign, asterisk, and single quote characters have special meaning and
   so MUST themselves be encoded.

Similarly below....

David Singer

---

From: David Singer <[email-masked]>
Date: Thu, 21 Apr 2011 17:47:27 -0700

OK

I put back the "Note that"

On Apr 19, 2011, at 0:41 , S Moonesamy wrote:

> Randy commented on this in another message.  The "requires" should be clear enough.
> 
> I have seen "MUST" used in "Note" sentences in other RFCs.  You already had similar text in the RFC published in 2005.  As it hasn't been a problem, I don't see why it should be a problem now.
> 
> By the way, I gave an "almost ready for publication" rating as the document state is "Publication Requested" and the authors already know how to address editorial nits.
> 
> Regards,
> S. Moonesamy 

David Singer