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

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

Received on Monday, 21 December 2009 23:31:12 UTC