jiebi/TextFlow huggingface dataset:
Original text:
an indefinite-length encoding enables efficient generation of messages where lengths are not known when encoding starts.  2. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

Reviewer comments:
The format is capable of capturing messages, but the design only really supports the expression of the semantics of valid messages. That makes it unsuitable for applications that need to know exactly what was put on the wire in a given protocol.
This document is going to be viewed by some as establishing the 'shape' of an HTTP message -- which is a good and perhaps necessary thing. However, some will be sad, because it doesn't suit some applications such as forensic preservation of messages, bot detection, debugging, faithful representation of HTTP/1, etc., due to transformations and loss of certain information (especially around headers). So it'd be good to set expectations early on (perhaps in the Introduction).
Good point. It's for semantics, not forensics and all that.

Revised text:
an indefinite-length encoding enables efficient generation of messages where lengths are not known when encoding starts. <ins> This format is designed to convey the semantics of valid HTTP messages as simply and efficiently as possible.  It is not designed to capture all of the details of the encoding of messages from specific HTTP versions (MESSAGING, H2, H3).  As such, this format is unlikely to be suitable for applications that depend on an exact recording of the encoding of messages. </ins> 2. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
Original text:
framing of responses that depends on the corresponding request (such as HEAD) or the value of the status code (such as 204 or <del> 304) </del>  Some of these features are also absent in HTTP/2 and HTTP/3.

Reviewer comments:
The original framing might have implied that they can't be sent, where it's just that they are the same as anything else.
In s 6: This is just a bit weird -- some may read it to mean that these messages can't be conveyed in this format.

Revised text:
framing of responses that depends on the corresponding request (such as HEAD) or the value of the status code (such as 204 or  <ins> 304); these responses use the same framing as all other messages </ins> Some of these features are also absent in HTTP/2 and HTTP/3.
Original text:
Optional padding.  Any amount of zero-valued bytes. All lengths and numeric values are encoded using the variable-length <del> integer encoding from QUIC. </del>  3.1.

Reviewer comments:
For the avoidance of doubt. This makes encoding easier if you don't care about wasting a few bytes.
The binary messages draft uses QUIC variable-length integers. Those allow encoding numbers multiple ways (for example 42 can be encoded minimally as 0x2A but also non-minimally as 0x402A). The draft should clarify whether using non-minimal encoding is allowed or not.
Thanks!

Revised text:
Optional padding.  Any amount of zero-valued bytes. All lengths and numeric values are encoded using the variable-length  <ins> integer encoding from QUIC.  Integer values do not need to be encoded on the minimum number of bytes necessary. </ins> 3.1.
Original text:
different structure; see informational. Fields in the header and trailer sections consist of a length- <del> prefixed name and length-prefixed value.  Both name and value are sequences of bytes that cannot be zero length. </del>  The format allows for the message to be truncated before any of the length prefixes that precede the field sections or content.  This

Reviewer comments:
by using a citation rather than a redundant and wrong statement. by removing the minimum length (zero is totally fine).
The Known-Length Messages section states that whereas the Header and Trailer Field Lines section allows empty field values. Which is it?
Editorial error on my part. Someone pointed out that fields can have empty values (yet another feature of the protocol that is weird and unnecessary). I fixed it one place, but not the other. Thanks for noticing.
The draft currently shows: This Length field isn't well defined. Is it the length of the Known-Length Field Section in bytes or in lines? If in bytes, does it include or exclude the length of the Length field itself? Either way, I don't understand why Length is at least 2. Either it's possible for there to not be any field lines, in which case maybe it should be zero. And if there needs to be at least one field line, then (we should say so, and) the minimum number should be 3, because a field line is two lengths and at least one byte of field name.
To pile on here, the spec also says in one place and in another It's a little ambiguous but f the value also can't be zero-length, then the minimum should be 4? (by David's second interpretation)
NAME see
Yeah saw that after hitting the button. Didn't intend to derail
Thanks!

Revised text:
different structure; see informational. Fields in the header and trailer sections consist of a length-  <ins> prefixed name and length-prefixed value; see fields. </ins> The format allows for the message to be truncated before any of the length prefixes that precede the field sections or content.  This
Original text:
prefixed name and length-prefixed value; see fields. The format allows for the message to be truncated before any of the <del> length prefixes that precede the field sections or content.  This reduces the overall message size.  A message that is truncated at any other point is invalid; see invalid. </del>  The variable-length integer encoding means that there is a limit of 2^62-1 bytes for each field section and the message content.

Reviewer comments:
Basically, it saves the effort of writing stuff that you know to be empty. It's not a critical feature, but it turns out to be a simple way to deal with not sending trailers or a body. In the extreme, you can also drop headers to produce the simplest and shortest HTTP message ever: 0x0140c8. CLoses .
Hey David, I've made some larger edits here to factor the truncation text better. I've included your normative language.
The draft mentions that messages can be truncated in some places, but not in others. I think it would help to explain why one would want to truncated a message.
This is really just a neat way to avoid having to write out all of the pieces of a message. So if you don't have trailers, it's OK not to say "I have 0 trailers". The decoder is required to deal with it. Before you say "that's hard", you don't need to change the parser to deal with truncation. Adding three zero-valued bytes to the end of any message you receive does the job just fine. If it isn't truncated, those will be treated as padding.
Thanks

Revised text:
prefixed name and length-prefixed value; see fields. The format allows for the message to be truncated before any of the  <ins> length prefixes that precede the field sections or content; see padding. </ins> The variable-length integer encoding means that there is a limit of 2^62-1 bytes for each field section and the message content.
Original text:
indeterminate-length, it can only appear in response messages. Indeterminate-length messages can be truncated in a similar way as <del> known-length messages.  Truncation occurs after the control data, or after the Content Terminator field that ends a field section or sequence of content chunks.  A message that is truncated at any other point is invalid; see invalid. </del>  Indeterminate-length messages use the same encoding for field lines as known-length messages; see fields.

Reviewer comments:
Basically, it saves the effort of writing stuff that you know to be empty. It's not a critical feature, but it turns out to be a simple way to deal with not sending trailers or a body. In the extreme, you can also drop headers to produce the simplest and shortest HTTP message ever: 0x0140c8. CLoses .
Hey David, I've made some larger edits here to factor the truncation text better. I've included your normative language.
The draft mentions that messages can be truncated in some places, but not in others. I think it would help to explain why one would want to truncated a message.
This is really just a neat way to avoid having to write out all of the pieces of a message. So if you don't have trailers, it's OK not to say "I have 0 trailers". The decoder is required to deal with it. Before you say "that's hard", you don't need to change the parser to deal with truncation. Adding three zero-valued bytes to the end of any message you receive does the job just fine. If it isn't truncated, those will be treated as padding.
Thanks

Revised text:
indeterminate-length, it can only appear in response messages. Indeterminate-length messages can be truncated in a similar way as  <ins> known-length messages; see padding. </ins> Indeterminate-length messages use the same encoding for field lines as known-length messages; see fields.
Original text:
it is unlikely to be a practical limitation.  There is no limit to the size of content in an indeterminate length message. <del> Omitting content by truncating a message is only possible if the content is zero-length. </del> 3.8. Messages can be padded with any number of zero-valued bytes.  Non-

Reviewer comments:
Basically, it saves the effort of writing stuff that you know to be empty. It's not a critical feature, but it turns out to be a simple way to deal with not sending trailers or a body. In the extreme, you can also drop headers to produce the simplest and shortest HTTP message ever: 0x0140c8. CLoses .
Hey David, I've made some larger edits here to factor the truncation text better. I've included your normative language.
The draft mentions that messages can be truncated in some places, but not in others. I think it would help to explain why one would want to truncated a message.
This is really just a neat way to avoid having to write out all of the pieces of a message. So if you don't have trailers, it's OK not to say "I have 0 trailers". The decoder is required to deal with it. Before you say "that's hard", you don't need to change the parser to deal with truncation. Adding three zero-valued bytes to the end of any message you receive does the job just fine. If it isn't truncated, those will be treated as padding.
Thanks

Revised text:
it is unlikely to be a practical limitation.  There is no limit to the size of content in an indeterminate length message.  3.8. Messages can be padded with any number of zero-valued bytes.  Non-
Original text:
Unlike other parts of a message, a processor MAY decide not to validate the value of padding bytes.  Padding is compatible with truncation of empty parts of the messages. Zero-valued bytes will be interpreted as zero-length part, which is semantically equivalent to the part being absent.

Reviewer comments:
Basically, it saves the effort of writing stuff that you know to be empty. It's not a critical feature, but it turns out to be a simple way to deal with not sending trailers or a body. In the extreme, you can also drop headers to produce the simplest and shortest HTTP message ever: 0x0140c8. CLoses .
Hey David, I've made some larger edits here to factor the truncation text better. I've included your normative language.
The draft mentions that messages can be truncated in some places, but not in others. I think it would help to explain why one would want to truncated a message.
This is really just a neat way to avoid having to write out all of the pieces of a message. So if you don't have trailers, it's OK not to say "I have 0 trailers". The decoder is required to deal with it. Before you say "that's hard", you don't need to change the parser to deal with truncation. Adding three zero-valued bytes to the end of any message you receive does the job just fine. If it isn't truncated, those will be treated as padding.
Thanks

Revised text:
Unlike other parts of a message, a processor MAY decide not to validate the value of padding bytes. <ins> Truncation can be used to reduce the size of messages that have no data in trailing field sections or content.  If the trailers of a message is empty, it MAY be omitted by the encoder in place of adding a length field equal to zero.  An encoder MAY omit empty content in the same way if the trailers are also empty.  A message that is truncated at any other point is invalid; see invalid. Decoders MUST treat missing truncated fields as equivalent to having been sent with the length field sent to zero. </ins> Padding is compatible with truncation of empty parts of the messages. Zero-valued bytes will be interpreted as zero-length part, which is semantically equivalent to the part being absent.
Original text:
prefix. Response messages that contain informational status codes result in a <del> different structure; see informational. </del>  Fields in the header and trailer sections consist of a length- prefixed name and length-prefixed value; see fields.

Reviewer comments:
The diagram resulted in a few double-takes that might be helped by a little bit of a note pointing this out.
I suspect that requests do not carry the Known-Length Informational Response field (otherwise how do you know how many of them there are?) but that should be spelled out explicitly. I'd suggest creating a different diagram for known-length request vs known-length responses to make this easier to reason about, and same for indeterminate length
I think the optionality is supposed to be indicated by the three trailing dots . I admit to doing a double-take on this during my initial review, similar to David's question. It's optional for a server, sure, but it's never optional for a request just wrong. I agree that separate diagrams would help, at the minor cost of some page space.

Revised text:
prefix. Response messages that contain informational status codes result in a  <ins> different structure; see informational.  Note that while the Known- Length Informational Response field is shown in format-known-length, it can only appear in response messages. </ins> Fields in the header and trailer sections consist of a length- prefixed name and length-prefixed value; see fields.
Original text:
value, and a trailer section that is terminated by a zero value. Response messages that contain informational status codes result in a <del> different structure; see informational. </del>  Indeterminate-length messages can be truncated in a similar way as known-length messages.  Truncation occurs after the control data, or

Reviewer comments:
The diagram resulted in a few double-takes that might be helped by a little bit of a note pointing this out.
I suspect that requests do not carry the Known-Length Informational Response field (otherwise how do you know how many of them there are?) but that should be spelled out explicitly. I'd suggest creating a different diagram for known-length request vs known-length responses to make this easier to reason about, and same for indeterminate length
I think the optionality is supposed to be indicated by the three trailing dots . I admit to doing a double-take on this during my initial review, similar to David's question. It's optional for a server, sure, but it's never optional for a request just wrong. I agree that separate diagrams would help, at the minor cost of some page space.

Revised text:
value, and a trailer section that is terminated by a zero value. Response messages that contain informational status codes result in a  <ins> different structure; see informational.  Note that while the Indeterminate-Length Informational Response field is shown in format- indeterminate-length, it can only appear in response messages. </ins> Indeterminate-length messages can be truncated in a similar way as known-length messages.  Truncation occurs after the control data, or
Original text:
arise from receiving large messages, particularly those with large numbers of fields. <del> The format is designed to allow for minimal state when translating for use with HTTP proper.  However, producing a combined value for fields, which might be necessary for the "Cookie" field when translating this format (like HTTP/1.1 MESSAGING), can require the commitment of resources.  Implementations need to ensure that they aren't subject to resource exhaustion attack from a maliciously crafted message. </del>  9.

Reviewer comments:
A combined "field value" is a term that HTTP defines, but we didn't link to that. Also, the structure of this paragraph was a little more terse than it needed to be.
Security Considerations state: but the Header and Trailer Field Lines section states: The same field name can be repeated in multiple field lines; see Section 5.2 of HTTP for the semantics of repeated field names and rules for combining values. This leaves me confused, why would it be necessary to produce a combined value if repeated field names are allowed?

Revised text:
arise from receiving large messages, particularly those with large numbers of fields.  <ins> Implementations need to ensure that they aren't subject to resource exhaustion attack from a maliciously crafted message.  Overall, the format is designed to allow for minimal state when processing messages.  However, producing a combined field value (HTTP) for fields might require the commitment of resources.  In particular, combining might be necessary for the "Cookie" field when translating this format for use in other contexts, such as use in an API or translation to HTTP/1.1 MESSAGING, where the recipient of the field might not expect multiple values. </ins> 9.
Original text:
how those content encoding(s) can be removed. The "Encryption" header field uses the extended ABNF syntax defined <del> in Section 1.2 of RFC7230 and the "parameter" rule from </del>  If the payload is encrypted more than once (as reflected by having multiple content-codings that imply encryption), each application of

Reviewer comments:
: These rules do not permit whitespace between a semicolon and a parameter, which was probably intended (judging from the examples and from similar rules elsewhere in HTTP). They should be rewritten as follows: and the import of the rule from RFC 7230 should be noted in the preceding text (“The "Encryption" header field uses the extended ABNF syntax . . .” and similarly for ).
Thanks for picking this up.

Revised text:
how those content encoding(s) can be removed. The "Encryption" header field uses the extended ABNF syntax defined  <ins> in Section 1.2 of RFC7230 and the "parameter" and "OWS" rules from RFC7231. </ins> If the payload is encrypted more than once (as reflected by having multiple content-codings that imply encryption), each application of
Original text:
material used in the Encryption header field. The Crypto-Key header field uses the extended ABNF syntax defined in <del> Section 1.2 of RFC7230 and the "parameter" rule from RFC7231. </del>  The "keyid" parameter corresponds to the "keyid" parameter in the Encryption header field.

Reviewer comments:
: These rules do not permit whitespace between a semicolon and a parameter, which was probably intended (judging from the examples and from similar rules elsewhere in HTTP). They should be rewritten as follows: and the import of the rule from RFC 7230 should be noted in the preceding text (“The "Encryption" header field uses the extended ABNF syntax . . .” and similarly for ).
Thanks for picking this up.

Revised text:
material used in the Encryption header field. The Crypto-Key header field uses the extended ABNF syntax defined in  <ins> Section 1.2 of RFC7230 and the "parameter" and "OWS" rules from RFC7231. </ins> The "keyid" parameter corresponds to the "keyid" parameter in the Encryption header field.
Original text:
consumes the resources of both endpoints.  See also digest-and- content-location. <del> Digest fields SHOULD always be used over a connection that provides integrity at the transport layer that protects HTTP fields. A "Representation-Digest" field using NOT RECOMMENDED hashing algorithms SHOULD NOT be used in signatures. Using signatures to protect the checksum of an empty representation allows receiving endpoints to detect if an eventual payload has been stripped or added. </del>  Any mangling of digest fields, including de-duplication of representation-data-digest values or combining different field values

Reviewer comments:
no normative text in security considerations.
no normative statements in security considerations
Separately, this could be read to imply that a TCP checksum is sufficient. I'm not enthusiastic about that, URL Originally posted by NAME in URL In reply, I said
This has been slightly modified by ... TLS can't probably be normative, but people already knows...

Revised text:
consumes the resources of both endpoints.  See also digest-and- content-location.  <ins> Signatures are likely to be deemed an adversarial setting when applying Integrity fields; see algorithms.  Using signatures to protect the checksum of an empty representation allows receiving endpoints to detect if an eventual payload has been stripped or added. </ins> Any mangling of digest fields, including de-duplication of representation-data-digest values or combining different field values
Original text:
7.1.  This memo sets this specification to be the establishing document for the Hash Algorithms for HTTP Digest Fields [2] registry defined in algorithms.

Reviewer comments:
simplifies IANA field registration section obsolete Digest
Thanks for this, it's almost there. I suggest we just have two sections that ask IANA to do things directly, rather than giving any prelude to those instructions.

Revised text:
7.1. <ins> IANA is asked to update the "Hypertext Transfer Protocol (HTTP) Field Name Registry" registry (SEMANTICS) according to the table below: 7.2. </ins> This memo sets this specification to be the establishing document for the Hash Algorithms for HTTP Digest Fields [2] registry defined in algorithms.
Original text:
IANA is asked to initialize the registry with the entries in iana- hash-algorithm-table. <del> 7.2. This section registers the "Representation-Digest" field in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" SEMANTICS. Field name: "Representation-Digest" Status: permanent Specification document(s): representation-digest of this document 7.3. This section registers the "Content-Digest" field in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" SEMANTICS. Field name: "Content-Digest" Status: permanent Specification document(s): content-digest of this document 7.4. This section registers the "Want-Representation-Digest" field in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" SEMANTICS. Field name: "Want-Representation-Digest" Status: permanent Specification document(s): want-fields of this document 7.5. This section registers the "Want-Content-Digest" field in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" SEMANTICS. Field name: "Want-Content-Digest" Status: permanent Specification document(s): want-fields of this document </del> 8.  References 8.1.  URIs

Reviewer comments:
simplifies IANA field registration section obsolete Digest
Thanks for this, it's almost there. I suggest we just have two sections that ask IANA to do things directly, rather than giving any prelude to those instructions.

Revised text:
IANA is asked to initialize the registry with the entries in iana- hash-algorithm-table.  8.  References 8.1.  URIs