Multiple definitions of the same ABNF rule potentially confusing

[cakoose]

In RFC 7230, Section 7, there are two definitions for "1#element". One is for what producers must generate and one is for what consumers must accept.

Having two definitions for a single symbol was unexpected and caused some confusion for me. I even mistakenly reported a technical errata against the spec because the first definition didn't match up with something in the range request spec. Julian Reschke caught my mistake and suggested I report this as a potential usability issue.

In my particular case, I'm trying to write strict parsing code for HTTP range requests. This involves jumping back and forth between ABNF rules in the spec as I write the actual code. I didn't notice the prose around the rule that explained the duplication -- I just saw the first rule, assumed it was the only definition of that rule, and started writing code for it.

One change that could help would be to strictly avoid having two definitions for the same symbol. For example, maybe the left-hand side of the rule itself could be annotated with the context:

1#element {producer} => element *( OWS "," OWS element )
1#element {consumer} => *( "," OWS ) element *( OWS "," [ OWS element ] )

[reschke]

A simple band aid would be to add a bit more structure into this section (clearly separating sender from recipient requirements) by adding subsections.

[reschke]

Added subsections in 51578b2