jiebi/TextFlow huggingface dataset:
Original text:
to distinguish them from decimal literals. This specification describes binary formats using the convention <del> described in QUIC. </del>  The following terms are used:

Reviewer comments:
URL is frame formats. I've chosen to put blank lines before and after both frames and the stream identifier part of the stream header. That should make this a lot clearer. NAME was right that this was a little hard to process without that. Hopefully this is a tiny bit better.
I think this helps. The only other clarification I can think of is to pull the flags out into a separate illustration, but let's see if this is sufficient first.
Bah I didn't respond at the right place. One day I'll understand github's interface. Or not :-) Both changes look good and possibly sufficient to me. Let's just wait a bit to see if anyone in the WG has any better proposal. Thanks for your quick reaction!
For the flags (and only the flags), what about trying this:
Should I add the octet values of flags? I would only do that for non-unused flags though.
I believe the prose text contains them, so there's at least a defensible reason for leaving them off.
They're indeed present but not trivially spottable. I have a dead-tree copy of 7540 here with them overlined in pink to spot them faster :-/ We could save a tree by noting them there :-). I agree with Martin that we can avoid the unused ones though, because what matters in tests is not to know the unused ones but rather to figure them as the complement of all known ones. I won't roll over the floor crying if that's rejected, but as an implementer I find that it significantly helps during debugging.
As I don't know how to comment in this format and I don't want to start inventing something (else), I think I'm going to take the coward's option.
What are the semantics of a blank line in this format? /me ducks

Revised text:
to distinguish them from decimal literals. This specification describes binary formats using the convention  <ins> described in QUIC.  Note that this format uses network byte order and high-valued bits are listed before low-valued bits. </ins> The following terms are used:
Original text:
largely independent of each other, so a blocked or stalled request or response does not prevent progress on other streams. <del> Flow control and prioritization ensure that it is possible to efficiently use multiplexed streams.  FlowControl helps to ensure that only data that can be used by a receiver is transmitted. StreamPriority ensures that limited resources can be directed to the most important streams first. </del>  Because HTTP fields used in a connection can contain large amounts of redundant data, frames that contain them are FieldBlock.  This has

Reviewer comments:
The Priorities section itself has been replaced with a discussion of why priorities aren't there, which is all well and good (). So I found this still being in the introduction a bit odd: If we're talking about the structure of the protocol, I'd think either we don't talk about a feature that's no longer in the protocol, or we explicitly mention it's been cut out.

Revised text:
largely independent of each other, so a blocked or stalled request or response does not prevent progress on other streams.  <ins> Effective use of multiplexing depends on flow control and prioritization.  FlowControl ensures that it is possible to efficiently use multiplexed streams by restricting data that is transmitted to what the receiver is able to handle.  StreamPriority ensures that limited resources are used most effectively.  This revision of HTTP/2 deprecates the priority signaling scheme from RFC7540. </ins> Because HTTP fields used in a connection can contain large amounts of redundant data, frames that contain them are FieldBlock.  This has
Original text:
header field that appears in a field block after a regular field line MUST be treated as malformed.  8.3.1. The following pseudo-header fields are defined for HTTP/2 requests:

Reviewer comments:
This fixes issue .
I agree on 1 that there's no reason to exclude response pseudo-headers from this requirement. (I was worried about contradicting something regarding multiple interim responses, each of which needs a field, but each of those are in a separate field section, so a rule of no duplicates within a field section should work for pseudo-headers, both request and response.) However, I think that a general prohibition is a good thing. If a future (negotiated) extension wants to introduce a new pseudo-header that can be duplicated, it could override an otherwise general prohibition in this draft. If a future extension doesn't do that, it gets the more sane/safe default for free.
Hmm, yeah, I think I can see a justification for that argument. Given that adding new pseudo-headers needs to be negotiated anyway, I don't think that's a big deal. So I'm happy to go ahead with the change for (1) and skip (2).
NAME is "this" the current text, or revised text to address Cory's comment?
This pull request. I think that a blanket "at most once" is fine and what you have is enough. Future extensions can deal with the consequences of that if they want >1.
NAME Do you want the change to cover responses as well?
That would mean moving it up to the "HTTP Control Data" section. That is a good idea. I missed that this was under requests only.
I moved the language up to the HTTP Control Data section and slightly tweaked it.

Revised text:
header field that appears in a field block after a regular field line MUST be treated as malformed. <ins> The same pseudo-header field name MUST NOT appear more than once in a field block.  A field block for an HTTP request or response that contains a repeated pseudo-header field name MUST be treated as malformed. </ins> 8.3.1. The following pseudo-header fields are defined for HTTP/2 requests:
Original text:
compression and allowing multiple concurrent exchanges on the same connection. <del> This specification is an alternative to, but does not obsolete, the HTTP/1.1 message syntax.  HTTP's existing semantics remain unchanged. </del> This document obsoletes RFC 7540 and RFC 8740. Discussion Venues

Reviewer comments:
The abstract says This is taken directly from RFC 7540, and seems a bit old hat given where we are at now.
Yeah, probably not needed any more. Propose text?

Revised text:
compression and allowing multiple concurrent exchanges on the same connection.  This document obsoletes RFC 7540 and RFC 8740. Discussion Venues
Original text:
3.1. <del> The protocol defined in this document has two identifiers. Negotiating "h2" or "h2c" implies the use of the transport, security, framing, and message semantics described in this document. </del>  3.2.

Reviewer comments:
By removing the word negotiating and avoiding the actual identifiers, we can get the important point across
Maybe a hangover from trying to tear up the photos of the "http" URI and upgrade dance. But this seems to read oddly. On one hand: on the other: I don't have a solid suggestion to improve things.
How about we just remove "h2c" from the latter statement.
OK, that isn't going to fly. I just tried it. Pulling that string is unwise. We agreed to keep "prior knowledge" in the document, and the "h2c" ALPN token is part of that. The "h2c" upgrade token has been removed already. (Too subtle? Probably.)

Revised text:
3.1.  <ins> The protocol defined in this document has two identifiers.  Creating a connection based on either implies the use of the transport, security, framing, and message semantics described in this document. </ins> 3.2.
Original text:
The HEADERS frame changes the connection state as described in FieldBlock. <del> The HEADERS frame can include padding.  Padding fields and flags are identical to those defined for DATA.  Padding that exceeds the size remaining for the field block fragment MUST be treated as a PROTOCOL_ERROR. </del>  6.3.

Reviewer comments:
The old text stated padding things were identical to DATA frames. That might not be entirely true. So just spell out the requirements expicitly.
I just realised RFC 7540 was always this way, but it doesn't seem right to me. The DATA frame definition includes normative requirements on sender and receiver using the field. I presume the HEADERS frame is supposed the treat padding the same but it isn't written down. edit: plus PUSH_PROMISE
Ah, it's stated in a separate paragraph at the end of each frame definition section. That's annoying but I guess its fine.
Yeah, so the short answer there is that they behave differently in some ways (at least with respect to flow control). If you think there’s a better way to structure the section I think you’re welcome to take a crack at it.
I didn't actually make the leap to flow control, that makes me more inclined to avoid the cross reference to DATA frames. I made to just make everything explicit at the cost of a few more lines of text.

Revised text:
The HEADERS frame changes the connection state as described in FieldBlock.  <ins> The total number of padding octets is determined by the value of the Pad Length field.  Padding that exceeds the size remaining for the field block fragment MUST be treated as a PROTOCOL_ERROR. </ins> 6.3.
Original text:
Note that an illegal stream identifier is an identifier for a stream that is not currently in the "idle" state. <del> The PUSH_PROMISE frame can include padding.  Padding fields and flags are identical to those defined for DATA. </del>  6.7.

Reviewer comments:
The old text stated padding things were identical to DATA frames. That might not be entirely true. So just spell out the requirements expicitly.
I just realised RFC 7540 was always this way, but it doesn't seem right to me. The DATA frame definition includes normative requirements on sender and receiver using the field. I presume the HEADERS frame is supposed the treat padding the same but it isn't written down. edit: plus PUSH_PROMISE
Ah, it's stated in a separate paragraph at the end of each frame definition section. That's annoying but I guess its fine.
Yeah, so the short answer there is that they behave differently in some ways (at least with respect to flow control). If you think there’s a better way to structure the section I think you’re welcome to take a crack at it.
I didn't actually make the leap to flow control, that makes me more inclined to avoid the cross reference to DATA frames. I made to just make everything explicit at the cost of a few more lines of text.

Revised text:
Note that an illegal stream identifier is an identifier for a stream that is not currently in the "idle" state.  <ins> The total number of padding octets is determined by the value of the Pad Length field.  Padding that exceeds the size remaining for the field block fragment MUST be treated as a PROTOCOL_ERROR. </ins> 6.7.
Original text:
1. <del> The Hypertext Transfer Protocol (HTTP) is a wildly successful protocol.  However, the way HTTP/1.1 uses the underlying transport (HTTP11) has several characteristics that have a negative overall effect on application performance today. In particular, HTTP/1.0 allowed only one request to be outstanding at a time on a given TCP connection.  HTTP/1.1 added request pipelining, but this only partially addressed request concurrency and still suffers from head-of-line blocking.  Therefore, HTTP/1.0 and HTTP/1.1 clients that need to make many requests use multiple connections to a server in order to achieve concurrency and thereby reduce latency. </del>  Furthermore, HTTP fields are often repetitive and verbose, causing unnecessary network traffic as well as causing the initial TCP TCP

Reviewer comments:
thanks both, good suggestions
... and HTTP/2's positives too! protocol. However, the way HTTP/1.1 uses the underlying transport ([RFC7230], Section 6) has several characteristics that have a negative overall effect on application performance today. a time on a given TCP connection. HTTP/1.1 added request pipelining, but this only partially addressed request concurrency and still suffers from head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1 clients that need to make many requests use multiple connections to a server in order to achieve concurrency and thereby reduce latency. I think time has shown these claims to not be great. How about cutting cruft and saying and then a tweak to a later paragraph in the intro to state that no one is perfect
It looks like you have a pull request that is dressed up as an issue :)
If you're receptive to change, I am willing to try and edit horrible XML
One change and I'm happy

Revised text:
1.  <ins> The performance of applications using the Hypertext Transfer Protocol (HTTP) is linked to how each version of HTTP uses the underlying transport, and the conditions under which the transport operates. Making multiple concurrent requests can reduce latency and improve application performance.  HTTP/1.0 allowed only one request to be outstanding at a time on a given TCP connection.  HTTP/1.1 (HTTP11) added request pipelining, but this only partially addressed request concurrency and still suffers from application-layer head-of-line blocking.  Therefore, HTTP/1.0 and HTTP/1.1 clients use multiple connections to a server to make concurrent requests. </ins> Furthermore, HTTP fields are often repetitive and verbose, causing unnecessary network traffic as well as causing the initial TCP TCP
Original text:
TCP connections can be used in comparison to HTTP/1.x.  This means less competition with other flows and longer-lived connections, which in turn lead to better utilization of available network capacity.  Finally, HTTP/2 also enables more efficient processing of messages through use of binary message framing.

Reviewer comments:
thanks both, good suggestions
... and HTTP/2's positives too! protocol. However, the way HTTP/1.1 uses the underlying transport ([RFC7230], Section 6) has several characteristics that have a negative overall effect on application performance today. a time on a given TCP connection. HTTP/1.1 added request pipelining, but this only partially addressed request concurrency and still suffers from head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1 clients that need to make many requests use multiple connections to a server in order to achieve concurrency and thereby reduce latency. I think time has shown these claims to not be great. How about cutting cruft and saying and then a tweak to a later paragraph in the intro to state that no one is perfect
It looks like you have a pull request that is dressed up as an issue :)
If you're receptive to change, I am willing to try and edit horrible XML
One change and I'm happy

Revised text:
TCP connections can be used in comparison to HTTP/1.x.  This means less competition with other flows and longer-lived connections, which in turn lead to better utilization of available network capacity. <ins> Note, however, that TCP head-of-line blocking is not addressed by this protocol. </ins> Finally, HTTP/2 also enables more efficient processing of messages through use of binary message framing.
Original text:
11.7. <del> Previous versions of this document (RFC7540) registered an upgrade token.  This capability has been removed: see versioning. </del> 

Reviewer comments:
At two points in the document, it refers to "previous versions of this document," which I take to mean RFC 7540, since we don't discuss differences from previous drafts when we publish the RFC. Is there a reason not to simply say "RFC 7540" in these places, similar to the discussion in 5.3?
Probably not.

Revised text:
11.7.  <ins> RFC7540 registered an upgrade token.  This capability has been removed: see versioning. </ins>
Original text:
does not affect the existing options for extending HTTP, such as defining new methods, status codes, or fields (see HTTP). <del> Extensions are permitted to use new FrameHeader, new SettingValues, or new ErrorCodes.  Registries are established for managing these extension points: iana-frames, iana-settings, and iana-errors. </del>  Implementations MUST ignore unknown or unsupported values in all extensible protocol elements.  Implementations MUST discard frames

Reviewer comments:
Which changes to
The new reference is to the frame type (not the settings themselves), so I might have preferred the original, but I don't mind. The section is about more than the frame anyway.

Revised text:
does not affect the existing options for extending HTTP, such as defining new methods, status codes, or fields (see HTTP).  <ins> Extensions are permitted to use new FrameHeader, new SETTINGS, or new ErrorCodes.  Registries are established for managing these extension points: iana-frames, iana-settings, and iana-errors. </ins> Implementations MUST ignore unknown or unsupported values in all extensible protocol elements.  Implementations MUST discard frames
Original text:
Streams have the following states: <del> In the absence of more specific guidance elsewhere in this document, implementations SHOULD treat the receipt of a frame that is not expressly permitted in the description of a state as a ConnectionErrorHandler of type PROTOCOL_ERROR.  Note that PRIORITY can be sent and received in any stream state.  Frames of unknown types are ignored. </del>  An example of the state transitions for an HTTP request/response exchange can be found in HttpExamples.  An example of the state

Reviewer comments:
We could try to make every statement precise. We could add "of the frames defined in this document" to a bunch of places. Or we could make a (better) blanket statement. That is what this does.
As discussed in , the current language of 5.1 prohibits all frames on closed streams other than the ones indicated. It is not clear whether the requirement in Section 5.5 constitutes "more specific guidance." My suggestion in the erratum was to scope "any frame" to "any frame defined in this document" where we might allow an extension frame to appear, since that was the minimal change to the RFC 7540 text, but the editors might choose a broader rewording.
So the text already says: "Frames of unknown types are ignored." right next to the guidance you refer to. Maybe we just need to be more direct about this.
Be careful Martin, you removed the sentence "Frames of unknown types are ignored" so I think we're losing one piece of information when looking at the patch. I should re-read it withiin its context to make sure we don't miss anything, but I preferred to warn.
NAME yes, that was a deliberate change. I replaced that text with a complete paragraph and a reference to the extensibility section, which already covers the rules for unknown frames clearly: "Implementations MUST discard frames that have unknown or unsupported types."
I think this is fine.

Revised text:
Streams have the following states:  <ins> In the absence of more specific rules, implementations SHOULD treat the receipt of a frame that is not expressly permitted in the description of a state as a ConnectionErrorHandler of type PROTOCOL_ERROR.  Note that PRIORITY can be sent and received in any stream state. The rules in this section only apply to frames defined in this document.  Receipt of frames for which the semantics are unknown cannot be treated as an error as the conditions for sending and receiving those frames are also unknown; see extensibility. </ins> An example of the state transitions for an HTTP request/response exchange can be found in HttpExamples.  An example of the state
Original text:
PROTOCOL_ERROR; errors on the connection flow-control window MUST be treated as a ConnectionErrorHandler. <del> WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the END_STREAM flag.  This means that a receiver could receive a </del>  WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream. A receiver MUST NOT treat this as an error (see StreamStates).

Reviewer comments:
Going to let NAME have a look at this as well.
(Warning, I may have reached peak pedantry.) In Section 5.1, there are two references to frames which "contain" an ENDSTREAM flag. All HEADERS, CONTINUATION, and DATA frames contain this flag, which might be set or not. Most other references in the document are to the flag being set, which is more precise. There are also two references to frames "bearing" ENDSTREAM, which could be taken either way.
If you care enough to write the issue, maybe you also care enough to offer a pull request.

Revised text:
PROTOCOL_ERROR; errors on the connection flow-control window MUST be treated as a ConnectionErrorHandler.  <ins> WINDOW_UPDATE can be sent by a peer that has sent a frame with the END_STREAM flag set.  This means that a receiver could receive a </ins> WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream. A receiver MUST NOT treat this as an error (see StreamStates).
Original text:
interim response consists of a HEADERS frames (which might be followed by zero or more CONTINUATION frames) containing the control data and header section of an interim (1xx) HTTP response (see HTTP). <del> A HEADERS frame with an END_STREAM flag that carries an informational status code is malformed. </del>  The last frame in the sequence bears an END_STREAM flag, noting that <del> a HEADERS frame bearing the END_STREAM flag can be followed by </del>  CONTINUATION frames that carry any remaining fragments of the field block.

Reviewer comments:
Going to let NAME have a look at this as well.
(Warning, I may have reached peak pedantry.) In Section 5.1, there are two references to frames which "contain" an ENDSTREAM flag. All HEADERS, CONTINUATION, and DATA frames contain this flag, which might be set or not. Most other references in the document are to the flag being set, which is more precise. There are also two references to frames "bearing" ENDSTREAM, which could be taken either way.
If you care enough to write the issue, maybe you also care enough to offer a pull request.

Revised text:
interim response consists of a HEADERS frames (which might be followed by zero or more CONTINUATION frames) containing the control data and header section of an interim (1xx) HTTP response (see HTTP).  <ins> A HEADERS frame with the END_STREAM flag set that carries an informational status code is malformed. </ins> The last frame in the sequence bears an END_STREAM flag, noting that  <ins> a HEADERS frame with the END_STREAM flag set can be followed by </ins> CONTINUATION frames that carry any remaining fragments of the field block.
Original text:
An HTTP request/response exchange fully consumes a single stream.  A request starts with the HEADERS frame that puts the stream into an <del> "open" state.  The request ends with a frame bearing END_STREAM, which causes the stream to become "half-closed (local)" for the </del>  client and "half-closed (remote)" for the server.  A response stream starts with zero or more interim responses in HEADERS frames or a HEADERS frame containing a final status code.

Reviewer comments:
Going to let NAME have a look at this as well.
(Warning, I may have reached peak pedantry.) In Section 5.1, there are two references to frames which "contain" an ENDSTREAM flag. All HEADERS, CONTINUATION, and DATA frames contain this flag, which might be set or not. Most other references in the document are to the flag being set, which is more precise. There are also two references to frames "bearing" ENDSTREAM, which could be taken either way.
If you care enough to write the issue, maybe you also care enough to offer a pull request.

Revised text:
An HTTP request/response exchange fully consumes a single stream.  A request starts with the HEADERS frame that puts the stream into an  <ins> "open" state.  The request ends with a frame with the END_STREAM flag set, which causes the stream to become "half-closed (local)" for the </ins> client and "half-closed (remote)" for the server.  A response stream starts with zero or more interim responses in HEADERS frames or a HEADERS frame containing a final status code.