Subject: re: suggestions for examples and explication wrt ABNF and header fields in draft-ietf-httpbis-p1

From: =JeffH <[email-masked]>
Date: Wed, 23 Dec 2009 13:16:20 -0800

I have some further suggestions wrt draft-ietf-httpbis-p1 section "1.2.2. 
Basic Rules".

HTH,

=JeffH
------

In Section 1.2.2 Basic Rules...

 >    Many HTTP/1.1 header field values consist of words separated by
                                                   ^^^^^
                                                   tokens

 >    whitespace or special characters.  These special characters MUST be
 >    in a quoted string to be used within a parameter value (as defined in
 >    Section 6.2).

The "special characters" aren't mentioned anywhere in draft-ietf-httpbis-p* 
spec set other than the above, nor are they defined in ABNF. Inspection of 
draft-ietf-httpbis-p1 and RFC2616 reveals that the "special characters" are 
what RFC2616 defined (using ABNF) as "separators". This is additionally 
confused in that the below tchar rule directly follows the above paragraph, and 
it takes a few moments to figure out that the below _are not_ the "special 
characters" (and it takes even more time to determine that the "special 
characters" aren't explicitly defined in draft-ietf-httpbis-p*).

 >      tchar          = "!" / "#" / "$" / "%" / "&" / "'" / "*"
 >                     / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
 >                     / DIGIT / ALPHA
 >
 >      token          = 1*tchar

I suggest rewriting the above paragraph as below, also explicitly including the 
"separators" ABNF from RFC2616 (tho remove the SP and HT from it), and list the 
"token" rule before the "tchar" rule, such that it reads...

    Many HTTP/1.1 header field values consist of tokens separated by
    whitespace (OWS or RWS as appropriate) or separators.  These
    separators, as well as whitespace, MUST be in a quoted string
    to be used within a parameter value (as defined in Section 6.2).

      separators     = "(" | ")" | "<" | ">" | "@"
                     | "," | ";" | ":" | "\" | <">
                     | "/" | "[" | "]" | "?" | "="
                     | "{" | "}"

      token          = 1*tchar

      tchar          = "!" / "#" / "$" / "%" / "&" / "'" / "*"
                     / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
                     / DIGIT / ALPHA

---
end

---

From: =JeffH <[email-masked]>
Date: Tue, 29 Dec 2009 15:00:52 -0800

> Ok, except I think the reference needs to go to 1.2.2.

ah, yes.

 > I agree that examples are needed for everyone not familiar with the
 > history of this. That being said, I have re-arranged stuff so that the
 > valid examples include empty elements,

oh, ok, looks good.

 > and I also added examples for
 > invalid values.

good idea.

 > I'd like to avoid enumerating these; the set may change after all... SO
 > I have simply added an explanation of the "obs-" prefix to 1.2.

ok, looks fine.

thanks,

=JeffH

ps: also, there's my follow-on comment wrt section "1.2.2. Basic Rules" and 
"special characters"