- From: Julian Reschke <julian.reschke@gmx.de>
- Date: Tue, 29 Dec 2009 15:59:44 +0100
- To: =JeffH <Jeff.Hodges@KingsMountain.com>
- CC: IETF HTTP WG <ietf-http-wg@w3.org>
=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,
comments in-line...:
> [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.
Ok.
>
> > 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
Ok, except I think the reference needs to go to 1.2.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.
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).
> 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.
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.
> > 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.
...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.
1.2.1. ABNF Extension: #rule
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,
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 )
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 ] )
Note that empty elements do not contribute to the count of elements
present, though.
For example, given these ABNF productions:
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:
""
","
", ,"
Appendix C shows the collected ABNF, with the list rules expanded as
explained above.
-- snip --
Feedback appreciated,
Julian
Received on Tuesday, 29 December 2009 15:00:30 UTC