Original text:
1.3. <del> Packet and frame diagrams in this document use the format described in Section 3.1 of RFC2360, with the following additional conventions: </del>  <del> Indicates that x is optional </del>  <del> Indicates that x is A bits long </del>  <del> Indicates that x is one of A, B, or C bits long </del>  Indicates that x uses the variable-length encoding in <del> Indicates that x is variable-length </del>  2. packet protection keys for Initial packets. The client populates the Source Connection ID field with a value of <del> its choosing and sets the SCID Len field to indicate the length. </del>  The first flight of 0-RTT packets use the same Destination Connection ID and Source Connection ID values as the client's first Initial SHOULD be able to read longer connection IDs from other QUIC versions in order to properly form a version negotiation packet. <del> The Destination Connection ID field follows the DCID Len and is between 0 and 20 bytes in length. negotiating-connection-ids describes the use of this field in more detail. </del>  The byte following the Destination Connection ID contains the length in bytes of the Source Connection ID field that follows it. IDs from other QUIC versions in order to properly form a version negotiation packet. <del> The Source Connection ID field follows the SCID Len and is between 0 and 20 bytes in length. negotiating-connection-ids describes the use of this field in more detail. </del>  In this version of QUIC, the following packet types with the long header are defined: A Retry packet (shown in retry-format) does not contain any protected fields.  The value in the Unused field is selected randomly by the <del> server.  In addition to the long header, it contains these additional fields: </del>  An opaque token that the server can use to validate the client's address. in the same way as the path MTU, but it is a property of the endpoint and not the path.  It is expected that this is the space an endpoint dedicates to holding incoming packets. <del> initial_max_data (0x04): </del> The initial maximum data parameter is an integer value that contains the initial value for the maximum amount of data that can 19.3.1. <del> The ACK Ranges field consists of alternating Gap and ACK Range values in descending packet number order.  The number of Gap and ACK Range values is determined by the ACK Range Count field; one of each value is present for each value in the ACK Range Count field. </del>  ACK Ranges are structured as shown in ack-range-format. <del> The fields that form the ACK Ranges are: </del>  A variable-length integer indicating the number of contiguous unacknowledged packets preceding the packet number one lower than MAX_STREAMS frames contain the following fields: A count of the cumulative number of streams of the corresponding <del> type that can be opened over the lifetime of the connection. Stream IDs cannot exceed 2^62-1, as it is not possible to encode stream IDs larger than this value.  Receipt of a frame that permits opening of a stream larger than this limit MUST be treated as a FRAME_ENCODING_ERROR. </del>  Loss or reordering can cause a MAX_STREAMS frame to be received which states a lower stream limit than an endpoint has previously received. STREAMS_BLOCKED frames contain the following fields: <del> A variable-length integer indicating the stream limit at the time the frame was sent.  Stream IDs cannot exceed 2^62-1, as it is not possible to encode stream IDs larger than this value.  Receipt of a frame that encodes a larger stream ID MUST be treated as a STREAM_LIMIT_ERROR or a FRAME_ENCODING_ERROR. </del>  19.15. 19.18. The PATH_RESPONSE frame (type=0x1b) is sent in response to a <del> PATH_CHALLENGE frame.  Its format is identical to the PATH_CHALLENGE frame (frame-path-challenge). </del>  If the content of a PATH_RESPONSE frame does not match the content of a PATH_CHALLENGE frame previously sent by the endpoint, the endpoint

Reviewer comments:
This is not an editorial decision, this is a request for feedback on whether this form of presentation makes more sense. So far we have mixed feedback.
Did you consider TLS presentation language? It would be nice to not have n+1 formats.
NAME TLS presentation language implies length prefixes in a lot of places. Plus we already ripped out TLS presentation language for definition of the transport parameters. Bringing it back for definition of packet layouts would be... a bit weird.
As long as it was considered and found to be unsuitable, that's fine with me.
I definitely like this general structure better. As far as the question of whether we should import the TLS language, you would need some extensions, but I suspect that you could get pretty far with the following three: uintX == unsigned integer of size X uintv == varint opaque x[URL] == opaque vector without a header (TLS uses <> to mean that it has a header) and opaque x[y..] means "to end of the container and minimum size y] I believe we've already done uintv for MLS and NAME has been thinking about a generalized an a "TLS spec language"
Orthogonal to this PR, but perhaps we should align the "Maximum Data" and "Data Limit" terms which reference the same limit in different frames? Originally posted by NAME in URL
SGTM. Maximum Data(or Max Data) seems like the preferable option to me.
NAME The link to NAME post seems to be broken.
Odd, that was automatically generated by GitHub. That comment was on a review of .
But...! But...! Muh ASCII art! More seriously, this is probably a net improvement for readability. There's value in conforming to existing paradigms where possible, but we'd already had to define custom extensions to the notation from RFC2360 and from RFC7540, so this is probably no worse. What are your thoughts on applying this to QPACK as well? I'm really not a fan of the trailing comma in the lists, but that's neither here nor there.I really like this format.

Revised text:
1.3.  <ins> Packet and frame diagrams in this document use a bespoke format.  The purpose of this format is to summarize, not define, protocol elements.  Prose defines the complete semantics and details of structures. </ins>  <ins> Complex fields are named and then followed by a list of fields surrounded by a pair of matching braces.  Each field in this list is separated by commas. </ins>  <ins> Individual fields include length information, plus indications about fixed value, optionality, or repetitions.  Individual fields use the following notational conventions, with all lengths in bits: </ins>  <ins> Indicates that x is A bits long </ins> Indicates that x uses the variable-length encoding in  <ins> Indicates that x can be any length from A to B; A can be omitted to indicate a mimumum of zero bits and B can be omitted to indicate no set upper limit; values in this format always end on an octet boundary Indicates that x has a fixed value of C Indicates that x has a value in the range from C to D, inclusive Indicates that x is optional (and has length of E) Indicates that x is repeated zero or more times (and that each instance is length E) By convention, individual fields reference a complex field by using the name of the complex field. For example: </ins> 2. packet protection keys for Initial packets. The client populates the Source Connection ID field with a value of  <ins> its choosing and sets the SCID Length field to indicate the length. </ins> The first flight of 0-RTT packets use the same Destination Connection ID and Source Connection ID values as the client's first Initial SHOULD be able to read longer connection IDs from other QUIC versions in order to properly form a version negotiation packet.  <ins> The Destination Connection ID field follows the DCID Length field and is between 0 and 20 bytes in length. negotiating-connection- ids describes the use of this field in more detail. </ins> The byte following the Destination Connection ID contains the length in bytes of the Source Connection ID field that follows it. IDs from other QUIC versions in order to properly form a version negotiation packet.  <ins> The Source Connection ID field follows the SCID Length field and is between 0 and 20 bytes in length. negotiating-connection-ids describes the use of this field in more detail. </ins> In this version of QUIC, the following packet types with the long header are defined: A Retry packet (shown in retry-format) does not contain any protected fields.  The value in the Unused field is selected randomly by the  <ins> server.  In addition to the fields from the long header, it contains these additional fields: </ins> An opaque token that the server can use to validate the client's address. in the same way as the path MTU, but it is a property of the endpoint and not the path.  It is expected that this is the space an endpoint dedicates to holding incoming packets.  The initial maximum data parameter is an integer value that contains the initial value for the maximum amount of data that can 19.3.1.  <ins> Each ACK Range consists of alternating Gap and ACK Range values in descending packet number order.  ACK Ranges can be repeated.  The number of Gap and ACK Range values is determined by the ACK Range Count field; one of each value is present for each value in the ACK Range Count field. </ins> ACK Ranges are structured as shown in ack-range-format.  <ins> The fields that form each ACK Range are: </ins> A variable-length integer indicating the number of contiguous unacknowledged packets preceding the packet number one lower than MAX_STREAMS frames contain the following fields: A count of the cumulative number of streams of the corresponding  <ins> type that can be opened over the lifetime of the connection.  This value cannot exceed 2^60, as it is not possible to encode stream IDs larger than 2^62-1.  Receipt of a frame that permits opening of a stream larger than this limit MUST be treated as a FRAME_ENCODING_ERROR. </ins> Loss or reordering can cause a MAX_STREAMS frame to be received which states a lower stream limit than an endpoint has previously received. STREAMS_BLOCKED frames contain the following fields:  <ins> A variable-length integer indicating the maximum number of streams allowed at the time the frame was sent.  This value cannot exceed 2^60, as it is not possible to encode stream IDs larger than 2^62-1.  Receipt of a frame that encodes a larger stream ID MUST be treated as a STREAM_LIMIT_ERROR or a FRAME_ENCODING_ERROR. </ins> 19.15. 19.18. The PATH_RESPONSE frame (type=0x1b) is sent in response to a  <ins> PATH_CHALLENGE frame.  Its format, shown in fig-path-response is identical to the PATH_CHALLENGE frame (frame-path-challenge). </ins> If the content of a PATH_RESPONSE frame does not match the content of a PATH_CHALLENGE frame previously sent by the endpoint, the endpoint