jiebi/TextFlow huggingface dataset:
Original text:
Append the result of running Serializing a Key (ser-key) with member's member_name to output. <del> Append "=" to output. </del>  <del> If member_value is an array, append the result of running Serialising an Inner List (ser-innerlist) with (member_value, parameters) to output. </del>  <del> Otherwise, append the result of running Serializing an Item (ser-item) with (member_value, parameters) to output. </del>  If more members remain in input_dictionary:

Reviewer comments:
For . Note that this makes missing values ; if we like that approach, I think we should do it for missing parameter values too (currently they use , which isn't part of our type system). I used because it aligns with the semantics of current uses nicely.
OK with me.
NAME This is a keen observation. Assuming that we are fine with requiring that knowledge on what the top type is, maybe we should also consider adding support for rule. It has been my understanding that the only reason we do not support rule in SH is because can only be applied for certain top types (but we are now requiring that knowledge).
We've discussed requiring knowledge of top-level types extensively, and I think we have agreement that it's OK. I"m not sure what you want regarding support for ; can you give an example (or open a new issue)?
I'm running my SH implementation against the HTTP Archive dumps (400,000,000+ HTTP requests) to see how the from BSH parse in something like the real world. A number of headers are failing because they have valueless dictionary members; e.g., , , . It should be pretty easy to accommodate these, as we already have optional values on parameters.
PTAL at the PR, especially the note about using True for missing parameter values.
Ping NAME NAME
Seems like a reasonable change. I'm happy to remove the 'null' from parameters too.
(already OK'ed in the PR)

Revised text:
Append the result of running Serializing a Key (ser-key) with member's member_name to output.  <ins> If member_value is not Boolean true or parameters is not empty: </ins>  <ins> Append "=" to output. </ins>  <ins> If member_value is an array, append the result of running Serialising an Inner List (ser-innerlist) with (member_value, parameters) to output. Otherwise, append the result of running Serializing an Item (ser-item) with (member_value, parameters) to output. </ins> If more members remain in input_dictionary:
Original text:
If dictionary already contains the name this_key, there is a duplicate; fail parsing. <del> Consume the first character of input_string; if it is not "=", fail parsing. </del>  <del> Let member be the result of running Parsing an Item or Inner List (parse-item-or-list) with input_string. </del>  Add name this_key with value member to dictionary.

Reviewer comments:
For . Note that this makes missing values ; if we like that approach, I think we should do it for missing parameter values too (currently they use , which isn't part of our type system). I used because it aligns with the semantics of current uses nicely.
OK with me.
NAME This is a keen observation. Assuming that we are fine with requiring that knowledge on what the top type is, maybe we should also consider adding support for rule. It has been my understanding that the only reason we do not support rule in SH is because can only be applied for certain top types (but we are now requiring that knowledge).
We've discussed requiring knowledge of top-level types extensively, and I think we have agreement that it's OK. I"m not sure what you want regarding support for ; can you give an example (or open a new issue)?
I'm running my SH implementation against the HTTP Archive dumps (400,000,000+ HTTP requests) to see how the from BSH parse in something like the real world. A number of headers are failing because they have valueless dictionary members; e.g., , , . It should be pretty easy to accommodate these, as we already have optional values on parameters.
PTAL at the PR, especially the note about using True for missing parameter values.
Ping NAME NAME
Seems like a reasonable change. I'm happy to remove the 'null' from parameters too.
(already OK'ed in the PR)

Revised text:
If dictionary already contains the name this_key, there is a duplicate; fail parsing.  <ins> If the first character of input_string is "=": Consume the first character of input_string. Let member be the result of running Parsing an Item or Inner List (parse-item-or-list) with input_string. Otherwise: Let value be Boolean true. Let parameters be an empty, ordered map. </ins>  <ins> Let member be the tuple (value, parameters). </ins> Add name this_key with value member to dictionary.
Original text:
whitespace, while names and values are separated by "=" (without whitespace).  For example:  A dictionary with a member whose value is an inner-list of tokens: A dictionary with a mix of singular and list values, some with

Reviewer comments:
I'm really not sure what happened there, but don't have time to investigate. I suspect GitHub didn't actually merge.

Revised text:
whitespace, while names and values are separated by "=" (without whitespace).  For example: <ins> Members whose value is Boolean true MUST omit that value when serialised, unless it has parameters.  For example, here both "b" and "c" are true, but "c"'s value is serialised because it has parameters: Note that this requirement is only on serialisation; parsers are still required to correctly handle the true value when it appears in dictionary values. </ins> A dictionary with a member whose value is an inner-list of tokens: A dictionary with a mix of singular and list values, some with
Original text:
Append the result of running Serializing a Key (ser-key) with member's member_name to output.  Append "=" to output. <del> If member_value is an array, append the result of running Serialising an Inner List (ser-innerlist) with (member_value, parameters) to output. </del>  <del> Otherwise, append the result of running Serializing an Item (ser-item) with (member_value, parameters) to output. </del>  <del> If more members remain in input_dictionary: </del>  <del> Append a COMMA to output. </del>  <del> Append a single WS to output. </del>  Return output.

Reviewer comments:
I'm really not sure what happened there, but don't have time to investigate. I suspect GitHub didn't actually merge.

Revised text:
Append the result of running Serializing a Key (ser-key) with member's member_name to output. <ins> If member_value is not Boolean true or parameters is not empty: </ins> Append "=" to output.  <ins> If member_value is an array, append the result of running Serialising an Inner List (ser-innerlist) with (member_value, parameters) to output. </ins>  <ins> Otherwise, append the result of running Serializing an Item (ser-item) with (member_value, parameters) to output. </ins>  <ins> If more members remain in input_dictionary: </ins>  <ins> Append a COMMA to output. </ins>  <ins> Append a single WS to output. </ins> Return output.
Original text:
If dictionary already contains the name this_key, there is a duplicate; fail parsing. <del> Consume the first character of input_string; if it is not "=", fail parsing. </del>  <del> Let member be the result of running Parsing an Item or Inner List (parse-item-or-list) with input_string. </del>  Add name this_key with value member to dictionary.

Reviewer comments:
I'm really not sure what happened there, but don't have time to investigate. I suspect GitHub didn't actually merge.

Revised text:
If dictionary already contains the name this_key, there is a duplicate; fail parsing.  <ins> If the first character of input_string is "=": Consume the first character of input_string. Let member be the result of running Parsing an Item or Inner List (parse-item-or-list) with input_string. Otherwise: Let value be Boolean true. Let parameters be an empty, ordered map. </ins>  <ins> Let member be the tuple (value, parameters). </ins> Add name this_key with value member to dictionary.
Original text:
A complete field section consists of either: <del> Field compression is stateful.  One compression context and one decompression context are used for the entire connection.  A decoding error in a field block MUST be treated as a ConnectionErrorHandler of type COMPRESSION_ERROR. </del> Each field block is processed as a discrete unit.  Field blocks MUST be transmitted as a contiguous sequence of frames, with no interleaved frames of any other type or from any other stream.  The

Reviewer comments:
As they relate to changes in SETTINGSHEADERTABLE_SIZE. This is the strict, by-the-book interpretation. That is, if the value changes, you have to send the update, even if it is pointless (that is, you aren't changing the size of the table). Note that I'm eliding the point about multiple instructions, which are necessary if the decoder reduces the maximum below the current size. The only nod in that direction is "at least one" and a reference to the section that talks about the need for multiple updates. This pulls in more of RFC 7541 than I might have liked, but we have to deal with the integration somewhere and this seems like a reasonable place to do that. It might have been better to put this text in a -bis revision of RFC 7541, but we decided to leave that document as-is.
LGTM, this is a nice clarification that removes the possibility of a different interpretation that's known to have caused interoperability issues (nghttp2 vs haproxy). Let's merge it!
Oh I see this PR already being merged. Opened .
I think this PR is in the correct direction. Endpoints have to process instructions using dynamic table, even when they advertise SETTINGSMAXHEADERLISTSIZE of zero. That is because the default is 4096. We did fix this problem in QPACK, but HPACK had already shipped. OTOH, I have concerns regarding new text suggesting Dynamic Table Update Size be sent even when there is no change in the size.I agree with Willy, this is a really good clarification.

Revised text:
A complete field section consists of either:  Each field block is processed as a discrete unit.  Field blocks MUST be transmitted as a contiguous sequence of frames, with no interleaved frames of any other type or from any other stream.  The
Original text:
<del> Hypertext Transfer Protocol Version 2 (HTTP/2) </del>  draft-ietf-httpbis-http2bis-latest Abstract

Reviewer comments:
draft-ietf-httpbis-messaging is now going to be known as "HTTP/1.1". Follow suit.

Revised text:
 <ins> HTTP/2 </ins> draft-ietf-httpbis-http2bis-latest Abstract
Original text:
While some of the frame and stream layer concepts are isolated from HTTP, this specification does not define a completely generic frame <del> layer.  The frame and stream layers are tailored to the needs of the HTTP protocol. </del>  2.2.

Reviewer comments:
Not "of the HTTP protocol".
and 9: To avoid the appearance of "of the Hypertext Transfer Protocol protocol", should these two instances of "of the HTTP protocol" be "of HTTP" (or perhaps, in the case of , "HTTP attributes" instead of "attributes of the HTTP protocol")? Original: The frame and stream layers are tailored to the needs of the HTTP protocol. ... This section outlines attributes of the HTTP protocol that improve interoperability, reduce exposure to known security vulnerabilities, or reduce the potential for implementation variation.
Yeah, "of HTTP" is probably best here.

Revised text:
While some of the frame and stream layer concepts are isolated from HTTP, this specification does not define a completely generic frame  <ins> layer.  The frame and stream layers are tailored to the needs of HTTP. </ins> 2.2.
Original text:
9. <del> This section outlines attributes of the HTTP protocol that improve </del>  interoperability, reduce exposure to known security vulnerabilities, or reduce the potential for implementation variation.

Reviewer comments:
Not "of the HTTP protocol".
and 9: To avoid the appearance of "of the Hypertext Transfer Protocol protocol", should these two instances of "of the HTTP protocol" be "of HTTP" (or perhaps, in the case of , "HTTP attributes" instead of "attributes of the HTTP protocol")? Original: The frame and stream layers are tailored to the needs of the HTTP protocol. ... This section outlines attributes of the HTTP protocol that improve interoperability, reduce exposure to known security vulnerabilities, or reduce the potential for implementation variation.
Yeah, "of HTTP" is probably best here.

Revised text:
9.  <ins> This section outlines attributes of HTTP that improve </ins> interoperability, reduce exposure to known security vulnerabilities, or reduce the potential for implementation variation.
Original text:
mandatory frame data.  A frame size error in a frame that could alter the state of the entire connection MUST be treated as a ConnectionErrorHandler; this includes any frame carrying a FieldBlock <del> (that is, HEADERS, PUSH_PROMISE, and CONTINUATION), SETTINGS, and any frame with a stream identifier of 0. </del>  Endpoints are not obligated to use all available space in a frame. Responsiveness can be improved by using frames that are smaller than

Reviewer comments:
: We had trouble parsing this sentence. Is a word missing? If neither suggestion below is correct, please clarify what "any frame carrying ... SETTINGS" refers to. Original: A frame size error in a frame that could alter the state of the entire connection MUST be treated as a connection error (); this includes any frame carrying a field block () (that is, HEADERS, PUSHPROMISE, and CONTINUATION), SETTINGS, and any frame with a stream identifier of 0. Suggestion (... and a SETTINGS frame): A frame size error in a frame that could alter the state of the entire connection MUST be treated as a connection error (); this includes any frame carrying a field block () (that is, HEADERS, PUSHPROMISE, and CONTINUATION) and a SETTINGS frame, and any frame with a stream identifier of 0. Suggestion (... or a SETTINGS frame): A frame size error in a frame that could alter the state of the entire connection MUST be treated as a connection error (); this includes any frame carrying a field block () (that is, HEADERS, PUSH_PROMISE, and CONTINUATION) or a SETTINGS frame, and any frame with a stream identifier of 0.
Suggestion 1 is correct.
I think that the list structure is supposed to be... includes: any frame carrying a field block (...), a SETTINGS frame, and any frame with a stream identifier of 0. Which suggests option 3, in my PR.
LGTM.

Revised text:
mandatory frame data.  A frame size error in a frame that could alter the state of the entire connection MUST be treated as a ConnectionErrorHandler; this includes any frame carrying a FieldBlock  <ins> (that is, HEADERS, PUSH_PROMISE, and CONTINUATION), a SETTINGS frame, and any frame with a stream identifier of 0. </ins> Endpoints are not obligated to use all available space in a frame. Responsiveness can be improved by using frames that are smaller than
Original text:
employ flow control to limit the amount of memory a peer can consume. Note, however, that this can lead to suboptimal use of available network resources if flow control is enabled without knowledge of the <del> bandwidth-delay product (see RFC7323). </del>  <del> Even with full awareness of the current bandwidth-delay product, </del>  implementation of flow control can be difficult.  Endpoints MUST read and process HTTP/2 frames from the TCP receive buffer as soon as data is available.  Failure to read promptly could lead to a deadlock when

Reviewer comments:
This looks terrible, but it's the form that the RFC we cite uses (also, RFC 1323).
: We changed "Flow Control Performance" to "Flow-Control Performance" per the title of ("Flow-Control Principles"). Please let us know any concerns. Original: 5.2.3. Flow Control Performance Currently: 5.2.3. Flow-Control Performance
and 5.2.3: Should "bandwidth-delay product" be written as "bandwidth * delay product" per RFC 7323? Original: Note, however, that this can lead to suboptimal use of available network resources if flow control is enabled without knowledge of the bandwidth-delay product (see [RFC7323]). Even with full awareness of the current bandwidth-delay product, implementation of flow control can be difficult. ... If an endpoint cannot ensure that its peer always has available flow control window space that is greater than the peer's bandwidth-delay product on this connection, its receive throughput will be limited by HTTP/2 flow control.
I think "bandwidth-delay product" is the standard representation of the term. It's not a term specific to this document but a broader term of art. I recommend not taking this suggestion.
Thanks, I hate it.

Revised text:
employ flow control to limit the amount of memory a peer can consume. Note, however, that this can lead to suboptimal use of available network resources if flow control is enabled without knowledge of the  <ins> bandwidth * delay product (see RFC7323). </ins>  <ins> Even with full awareness of the current bandwidth * delay product, </ins> implementation of flow control can be difficult.  Endpoints MUST read and process HTTP/2 frames from the TCP receive buffer as soon as data is available.  Failure to read promptly could lead to a deadlock when
Original text:
5.2.3. If an endpoint cannot ensure that its peer always has available flow <del> control window space that is greater than the peer's bandwidth-delay product on this connection, its receive throughput will be limited by HTTP/2 flow control.  This will result in degraded performance. </del>  Sending timely WINDOW_UPDATE frames can improve performance. Endpoints will want to balance the need to improve receive throughput

Reviewer comments:
This looks terrible, but it's the form that the RFC we cite uses (also, RFC 1323).
: We changed "Flow Control Performance" to "Flow-Control Performance" per the title of ("Flow-Control Principles"). Please let us know any concerns. Original: 5.2.3. Flow Control Performance Currently: 5.2.3. Flow-Control Performance
and 5.2.3: Should "bandwidth-delay product" be written as "bandwidth * delay product" per RFC 7323? Original: Note, however, that this can lead to suboptimal use of available network resources if flow control is enabled without knowledge of the bandwidth-delay product (see [RFC7323]). Even with full awareness of the current bandwidth-delay product, implementation of flow control can be difficult. ... If an endpoint cannot ensure that its peer always has available flow control window space that is greater than the peer's bandwidth-delay product on this connection, its receive throughput will be limited by HTTP/2 flow control.
I think "bandwidth-delay product" is the standard representation of the term. It's not a term specific to this document but a broader term of art. I recommend not taking this suggestion.
Thanks, I hate it.

Revised text:
5.2.3. If an endpoint cannot ensure that its peer always has available flow  <ins> control window space that is greater than the peer's bandwidth * delay product on this connection, its receive throughput will be limited by HTTP/2 flow control.  This will result in degraded performance. </ins> Sending timely WINDOW_UPDATE frames can improve performance. Endpoints will want to balance the need to improve receive throughput
Original text:
GOAWAY frame, the identified stream is the highest-numbered stream initiated by the client. <del> Once sent, the sender will ignore frames sent on streams initiated by the receiver if the stream has an identifier higher than the included last stream identifier.  Receivers of a GOAWAY frame MUST NOT open additional streams on the connection, although a new connection can be established for new streams. </del>  If the receiver of the GOAWAY has sent data on streams with a higher stream identifier than what is indicated in the GOAWAY frame, those

Reviewer comments:
: As this sentence seemed to indicate that the sender itself was sent, we updated the text to clarify that the GOAWAY is sent. Please let us know if this update is incorrect. Original: Once sent, the sender will ignore frames sent on streams initiated by the receiver if the stream has an identifier higher than the included last stream identifier. Currently: Once the GOAWAY is sent, the sender will ignore frames sent on streams initiated by the receiver if the stream has an identifier higher than the included last stream identifier.

Revised text:
GOAWAY frame, the identified stream is the highest-numbered stream initiated by the client.  <ins> Once the GOAWAY is sent, the sender will ignore frames sent on streams initiated by the receiver if the stream has an identifier higher than the included last stream identifier.  Receivers of a GOAWAY frame MUST NOT open additional streams on the connection, although a new connection can be established for new streams. </ins> If the receiver of the GOAWAY has sent data on streams with a higher stream identifier than what is indicated in the GOAWAY frame, those
Original text:
8.2.3. The COOKIE uses a semicolon (";") to delimit cookie-pairs (or <del> "crumbs").  This header field contains multiple values, but does not use a COMMA (",") as a separator, which prevents cookie-pairs from being sent on multiple field lines (see HTTP).  This can </del>  significantly reduce compression efficiency as updates to individual cookie-pairs would invalidate any field lines that are stored in the HPACK table.

Reviewer comments:
: We had trouble parsing this sentence. If the suggested text is not correct, please clarify what prevents cookie-pairs from being sent on multiple field lines. Original: This header field contains multiple values, but does not use a COMMA (",") as a separator, which prevents cookie-pairs from being sent on multiple field lines (see Section 5.2 of [HTTP]). Suggested: This header field contains multiple values but does not use a COMMA (",") as a separator, thereby preventing cookie-pairs from being sent on multiple field lines (see Section 5.2 of [HTTP]).

Revised text:
8.2.3. The COOKIE uses a semicolon (";") to delimit cookie-pairs (or  <ins> "crumbs").  This header field contains multiple values but does not use a COMMA (",") as a separator, thereby preventing cookie-pairs from being sent on multiple field lines (see HTTP).  This can </ins> significantly reduce compression efficiency as updates to individual cookie-pairs would invalidate any field lines that are stored in the HPACK table.
Original text:
The following pseudo-header fields are defined for HTTP/2 requests: <del> All HTTP/2 requests MUST include exactly one valid value for the </del>  <del> , </del>  <del> , and </del>  <del> pseudo-header fields, unless it is a CONNECT.  An HTTP request that </del>  omits mandatory pseudo-header fields is malformed. Individual HTTP/2 requests do not carry an explicit indicator of

Reviewer comments:
I had to add to one use of :authority.
and subsequent: Please note that, per the rest of this cluster of documents, we have placed the terms beginning with a colon (":method", ":scheme", etc.) in double quotes where they appear in running text. Please review, and let us know any objections.

Revised text:
The following pseudo-header fields are defined for HTTP/2 requests:  <ins> All HTTP/2 requests MUST include exactly one valid value for the " </ins>  <ins> ", " </ins>  <ins> ", and " </ins>  <ins> " pseudo-header fields, unless it is a CONNECT.  An HTTP request that </ins> omits mandatory pseudo-header fields is malformed. Individual HTTP/2 requests do not carry an explicit indicator of