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

From: =JeffH <[email-masked]>
Date: Mon, 21 Dec 2009 15:30:51 -0800

Hi, below are some modest suggestions for sections 1.2.1, 1.2.2, and 3.2 in 
draft-ietf-httpbis-p1-messaging-08 wrt the description of the ABNF rules and 
header fields. I believe adding such examples and prose will help one to figure 
things out more easily. I went through such an exercise last week (I based a 
new version of the Strict-Transport-Security header field on httpbis grammar), 
and it would have been somewhat easier if httpbis-p1 contained the below 
enhancements.

thanks, HTH,

=JeffH
------

[composed for a fixed-pitch font]

in draft-ietf-httpbis-p1-messaging-08:
-------------------------------------

It would be helpful if there were some examples inserted into the below 
subsection, as well as enhancing the first two paragraphs..

 > 1.2.1.  ABNF Extension: #rule
 >
 >    One extension to the ABNF rules of [RFC5234] is used to improve
 >    readability.

replace above para:

      The #rule extension to the ABNF rules of [RFC5234] is used to
      improve readability.

 >    A construct "#" is defined, similar to "*", for defining lists of
                                                              ^
                                                         comma-delimited

 >    elements.  The full form is "<n>#<m>element" indicating at least <n>
 >    and at most <m> elements, each separated by a single comma (",") and
 >    optional whitespace (OWS).
                              ^
                      see Section 3.2

 >
 >    Thus,
 >
 >      1#element => element *( OWS "," OWS element )
 >
 >    and:
 >
 >      #element => [ 1#element ]
 >
 >    and for n >= 1 and m > 1:
 >
 >      <n>#<m>element => element <n-1>*<m-1>( OWS "," OWS element )

insert:

      For example, given these ABNF productions:

         example-list = 1#example-list-elmt

         example-list-elmt = token  ; see Section 3.2

      Then these are legitimate values for example-list (not including
      the double quotes, which are present for delimitation only):

         "foo,bar"

         " foo ,bar"

         "  foo , bar,charlie   "

         "foo ,bar,   charlie "

         etc.

 >    For compatibility with legacy list rules, recipients SHOULD accept
 >    empty list elements.  In other words, consumers would follow the list
 >    productions:
 >
 >      #element => [ ( "," / element ) *( OWS "," [ OWS element ] ) ]
 >
 >      1#element => *( "," OWS ) element *( OWS "," [ OWS element ] )
 >
 >    Appendix C shows the collected ABNF, with the list rules expanded as
 >    explained above.

insert:

      For example, given the  example-list ABNF production above, these
      are also legitimate values for example-list (again, (not including
      the double quotes, which are present for delimitation only):

         "foo,bar,"

         ",,,,foo,,,,,bar,,,,,,"

         ",foo,bar"

         etc.

A suggested prose enhancement for "1.2.2.  Basic Rules"..

 >
 > 1.2.2.  Basic Rules
 >
 >    HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all
 >    protocol elements except the entity-body (see Appendix A for tolerant
 >    applications).  The end-of-line marker within an entity-body is
 >    defined by its associated media type, as described in Section 2.3 of
 >    [Part3].
 >
 >    This specification uses three rules to denote the use of linear
 >    whitespace: OWS (optional whitespace), RWS (required whitespace), and
 >    BWS ("bad" whitespace).

insert new para:

      This specification also uses the ABNF rule name prefix "obs-" to
      denote "obsolete" grammar rules that appear for historical reasons:
      obs-fold, obs-text, and obs-date. Please refer to section 3.2 for
      further information concerning the first two, and section 6.1 for
      obs-date.

 >    The OWS rule is used where zero or more linear whitespace characters
 >    ...

WRT "3.2    Header Fields"..

 > 3.2.  Header Fields
 >
 >    Each HTTP header field consists of a case-insensitive field name
 >    followed by a colon (":"), optional whitespace, and the field value.
 >
 >      header-field   = field-name ":" OWS [ field-value ] OWS
 >      field-name     = token
 >      field-value    = *( field-content / OWS )
 >      field-content  = *( WSP / VCHAR / obs-text )
 >
 >    No whitespace is allowed between the header field name and colon.
 >    For security reasons, any request message received containing such
 >    whitespace MUST be rejected with a response code of 400 (Bad
 >    Request).  A proxy MUST remove any such whitespace from a response
 >    message before forwarding the message downstream.
 >
 >    A field value MAY be preceded by optional whitespace (OWS); a single
 >    SP is preferred.  The field value does not include any leading or
 >    trailing white space: OWS occurring before the first non-whitespace
 >    character of the field value or after the last non-whitespace
 >    character of the field value is ignored and SHOULD be removed without
 >    changing the meaning of the header field.

I suggest adding, right here after the above paragraph, some example header 
fields. At least one should feature comma-separated field-values. e.g.

      example-header1: foo

      example-header2:foo

      example-header3: foo=bar,barfoo;attrib,charlie

      etc.

---
end

---

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Dec 2009 15:59:44 +0100

=JeffH wrote:
> Hi, below are some modest suggestions for sections 1.2.1, 1.2.2, and 3.2 
> in draft-ietf-httpbis-p1-messaging-08 wrt the description of the ABNF 
> rules and header fields. I believe adding such examples and prose will 
> help one to figure things out more easily. I went through such an 
> exercise last week (I based a new version of the 
> Strict-Transport-Security header field on httpbis grammar), and it would 
> have been somewhat easier if httpbis-p1 contained the below enhancements.
> 
> thanks, HTH,
> 
> =JeffH
> ------

Thanks Jeff,

> in draft-ietf-httpbis-p1-messaging-08:

Ok.

>  >    optional whitespace (OWS).

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

>      the double quotes, which are present for delimitation only):

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, and I also added examples for 
invalid values. (See below).

>      further information concerning the first two, and section 6.1 for

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.

> I suggest adding, right here after the above paragraph, some example 
> header fields. At least one should feature comma-separated field-values. 
> e.g.
> 
> 
>      example-header1: foo
> 
>      example-header2:foo
> 

...I will look at this later on.

I just committed <http://tools.ietf.org/wg/httpbis/trac/changeset/738>.

1.2 and 1.2.1 now read:

-- snip --
1.2.  Syntax Notation

    This specification uses the Augmented Backus-Naur Form (ABNF)
    notation of [RFC5234].

    The following core rules are included by reference, as defined in
    [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF
    (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote),
    HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit
    sequence of data), SP (space), VCHAR (any visible [USASCII]
    character), and WSP (whitespace).

    As a syntactical convention, ABNF rule names prefixed with "obs-"
    denote "obsolete" grammar rules that appear for historical reasons.

    The #rule extension to the ABNF rules of [RFC5234] is used to improve
    readability.

    A construct "#" is defined, similar to "*", for defining comma-
    delimited lists of elements.  The full form is "<n>#<m>element"
    indicating at least <n> and at most <m> elements, each separated by a
    single comma (",") and optional whitespace (OWS, Section 1.2.2).

    Thus,

    and:

    Note that empty elements do not contribute to the count of elements
    present, though.

      example-list      = 1#example-list-elmt
      example-list-elmt = token ; see Section 1.2.2

    Then these are valid values for example-list (not including the
    double quotes, which are present for delimitation only):

      "foo,bar"
      " foo ,bar,"
      "  foo , ,bar,charlie   "
      "foo ,bar,   charlie "

    But these values would be invalid, as at least one non-empty element
    is required:

      ""
      ","
      ",   ,"

-- snip --

Feedback appreciated,

Julian