jiebi/TextFlow huggingface dataset:
Original text:
multiple times.  See also send-idempotent.  This is a strict requirement.  The default is to not have this option. <del> Efficient use of Connection Groups: This boolean property specifies whether an application considers it useful to create Connection Groups, e.g. to explicitly prioritize between Connections within a Connection Group.  This property will tend to select multistreaming transport protocols, which can multiplex Connections into a Connection Group over a single flow.  This is not a strict requirement.  The default is to not have this option. </del>  Notification of special errors (excessive retransmissions, ICMP error message arrival): This boolean property specifies whether an each such Connection must be established separately.  Changes to the parameters of a Preconnection entangled with a Preconnection from which a Connection has already been established will fail.  Calling <del> Clone on a Preconnection may be taken by the system an implicit sign that protocol stacks supporting efficient connection group usage are preferred by the application. </del>  There is only one Protocol Property that is not entangled, i.e., it is a separate per-Connection Property for individual Connections in

Reviewer comments:
The API document says: I'm not sure I follow this. The text doesn't seem to match the option name: it isn't saying use connection groups efficiently or not, it's specifying whether connection groups can be used at all. It's also not clear why prioritisation is given as an example. Would it be clearer written something more like the following?
yep. Although you still have to explicitly entangle connections by cloning them if you want them to be guaranteed to be within a connection group.
URL makes me question why we need this parameter?
To explicitly prefer multistreaming protocols during selection, because you wrote your app to clone connections instead of cloning preconnections.
(see )

Revised text:
multiple times.  See also send-idempotent.  This is a strict requirement.  The default is to not have this option.  <ins> Multiplex connections: This boolean property specifies that the application would prefer multiple Connections between the same endpoints within a Connection Group to be multiplexed onto a single underlying transport connection where possible, for reasons of efficiency.  This is not a strict requirement.  The default is to not have this option. </ins> Notification of special errors (excessive retransmissions, ICMP error message arrival): This boolean property specifies whether an each such Connection must be established separately.  Changes to the parameters of a Preconnection entangled with a Preconnection from which a Connection has already been established will fail.  Calling  <ins> Clone on a Preconnection may be taken by the system an implicit signal that protocol stacks supporting multiplexed connections for efficient connection grouping are preferred by the application. </ins> There is only one Protocol Property that is not entangled, i.e., it is a separate per-Connection Property for individual Connections in
Original text:
The application expects to send/receive data at a constant rate after connection establishment.  Delay and delay variation should be optimized at the expense of bandwidth efficiency.  The application is not interactive.  It expects to send/receive a large amount of data, without any urgency.  This can be used

Reviewer comments:
For the Constant Rate capacity profile, should we state that this implies that the connection will fail if there is insufficient capacity? (i.e., you're requesting a circuit breaker rather than congestion control)
may fail instead of will fail, but yeah, this seems sensible.
lgtm

Revised text:
The application expects to send/receive data at a constant rate after connection establishment.  Delay and delay variation should be optimized at the expense of bandwidth efficiency. <ins> This implies that the Connection may fail if the desired rate cannot be maintained across the Path.  A transport may interpret this capacity profile as preferring a circuit breaker RFC8084 to a rate adaptive congestion controller. </ins> The application is not interactive.  It expects to send/receive a large amount of data, without any urgency.  This can be used
Original text:
Connection Groups.  This is not a strict requirement.  The default is to have this option. <del> Notification of ICMP error message arrival: This boolean property specifies whether an application considers it useful to be informed when an ICMP error message arrives.  This property applies to Connections and Connection Groups.  This is not a strict requirement.  The default is to have this option. </del>  Control checksum coverage on sending or receiving: This boolean property specifies whether the application considers it useful to aborted the Connection; however, there is no guarantee that an abort will be signaled:  11. RFC-EDITOR: Please remove this section before publication.

Reviewer comments:
TEXT: informed when an ICMP error message arrives. I think this is OK. but is this intended to be for soft-errors, since hard-errors break the connection? I think I get this, although some transports obvioulsy "eat" the ICMP packets they receive, and many ICMP messages have no meaning to an app, but some can be important. Tell me more please...
this comes from minset - and so it’s based on the rfc “soft error” text. true, no guarantee that you get it.
So, maybe the next rev of text should just say this and it will be fine.

Revised text:
Connection Groups.  This is not a strict requirement.  The default is to have this option.  <ins> Notification of ICMP soft error message arrival: This boolean property specifies whether an application considers it useful to be informed when an ICMP error message arrives that does not force termination of a connection.  This property applies to Connections and Connection Groups.  Received ICMP errors will be available as SoftErrors.  Note that even if a protocol supporting this property is selected, not all ICMP errors will necessarily be delivered, so applications cannot rely on receiving them.  This is not a strict requirement.  The default is not to have this option. </ins> Control checksum coverage on sending or receiving: This boolean property specifies whether the application considers it useful to aborted the Connection; however, there is no guarantee that an abort will be signaled: <ins> A SoftError can inform the application about the receipt of an ICMP error message that does not force termination of the connection, if the underlying protocol stack supports access to soft errors; however, even if the underlying stack supports it, there is no guarantee that a soft error will be signaled. </ins> 11. RFC-EDITOR: Please remove this section before publication.
Original text:
7.1.5.  This numeric property specifies the length of the section of the Message, starting from byte 0, that the application assumes will be received without corruption due to lower layer errors.  It is used to be used to indicate the default.  Only full coverage is guaranteed, any other requests are advisory. <del> 7.1.6. </del>  This enumerated property specifies the application's preferred tradeoffs for sending this Message; it is a per-Message override of 8.1.  The Receive Event is intended to be fired once per application-layer Message sent by the remote endpoint; i.e., it is a desired property of this interface that a Send at one end of a Connection maps to

Reviewer comments:
Satisfies
Okay, addressed capitalization and took Brian's suggested paragraph (with one tiny change).
Fine with me - go ahead
NAME NAME any further comments on this one?
ship it
Sorry, seems I should have clicked "approve" earlier. Still being clumsy in github :(

Revised text:
7.1.5. <ins> Final is a boolean property.  If true, this Message is the last one that the application will send on a Connection.  This allows underlying protocols to indicate to the Remote Endpoint that the Connection has been effectively closed in the sending direction.  For example, TCP-based Connections can send a FIN once a Message marked as Final has been completely sent.  Protocols that do not support signalling the end of a Connection in a given direction will ignore this property. Note that a Final Message must always be sorted to the end of a list of Messages.  The Final property overrides Niceness and any other property that would re-order Messages.  If another Message is sent after a Message marked as Final has already been sent on a Connection, the new Message will report an error. 7.1.6. </ins> This numeric property specifies the length of the section of the Message, starting from byte 0, that the application assumes will be received without corruption due to lower layer errors.  It is used to be used to indicate the default.  Only full coverage is guaranteed, any other requests are advisory.  <ins> 7.1.7. </ins> This enumerated property specifies the application's preferred tradeoffs for sending this Message; it is a per-Message override of 8.1. <ins> The application may check a property to determine if a received Message is the Final Message on a Connection.  For any Message that is marked as Final, the application can assume that there will be no more Messages received on the Connection once the Message has been completely delivered.  This corresponds to the Final property that may be marked on a sent Message send-final. Some transport protocols and peers may not support signaling of the Final property.  Applications therefore should not rely on receiving a Message marked Final to know that the other endpoint is done sending on a connection. Any calls to "Receive" once the Final Message has been delivered will result in errors. 8.2. </ins> The Receive Event is intended to be fired once per application-layer Message sent by the remote endpoint; i.e., it is a desired property of this interface that a Send at one end of a Connection maps to
Original text:
representations. Multiple endpoint identifiers can be specified for each Local <del> Endpoint and RemoteEndoint.  For example, a Local Endpoint could be </del>  configured with two interface names, or a Remote Endpoint could be specified via both IPv4 and IPv6 addresses.  These multiple identifiers refer to the same transport endpoint. <del> The transport services API will resolve names internally, when the </del>  Initiate(), Listen(), or Rendezvous() method is called establish a <del> Connection.  The API does not need the application to resolve names, and premature name resolution can damage performance by limiting the scope for alternate path discovery during Connection establishment. The Resolve() method is, however, provided to resolve a Local Endpoint or a Remote Endpoint in cases where this is required, for example with some Network Address Translator (NAT) traversal protocols (see rendezvous). </del>  5.2. Local Endpoint will be configured with some method of discovering NAT bindings, e.g., a Session Traversal Utilities for NAT (STUN) server. In this case, the Local Endpoint may resolve to a mixture of local <del> and server reflexive addresses.  The Resolve() method on the </del>  Preconnection can be used to discover these bindings: The Resolve() call returns a list of Preconnection Objects, that

Reviewer comments:
as I started reviewing issues in advance of the interim, I saw that was already mostly fixed, but I made a few editorial changes to the language there.

Revised text:
representations. Multiple endpoint identifiers can be specified for each Local  <ins> Endpoint and Remote Endpoint.  For example, a Local Endpoint could be </ins> configured with two interface names, or a Remote Endpoint could be specified via both IPv4 and IPv6 addresses.  These multiple identifiers refer to the same transport endpoint.  <ins> The transport services API resolves names internally, when the </ins> Initiate(), Listen(), or Rendezvous() method is called establish a  <ins> Connection.  The API explicitly does not require the application to resolve names, though there is a tradeoff between early and late binding of addresses to names.  Early binding allows the API implementation to reduce connection setup latency, at the cost of potentially limited scope for alternate path discovery during Connection establishment, as well as potential additional information leakage about application interest when used with a resolution method (such as DNS without TLS) which does not protect query confidentiality. The Resolve() action on Preconnection can be used by the application to force early binding when required, for example with some Network Address Translator (NAT) traversal protocols (see rendezvous). </ins> 5.2. Local Endpoint will be configured with some method of discovering NAT bindings, e.g., a Session Traversal Utilities for NAT (STUN) server. In this case, the Local Endpoint may resolve to a mixture of local  <ins> and server reflexive addresses.  The Resolve() action on the </ins> Preconnection can be used to discover these bindings: The Resolve() call returns a list of Preconnection Objects, that
Original text:
The application can set a minIncompleteLength value to indicates the smallest partial Message data size in bytes that should be delivered in response to this Receive.  By default, this value is infinite, <del> which means that only complete Messages should be delivered.  If this value is set to some smaller value, the associated receive event will be triggered only when at least that many bytes are available, or the Message is complete with fewer bytes, or the system needs to free up memory.  Applications should always check the length of the data delivered to the receive event and not assume it will be as long as minIncompleteLength in the case of shorter complete Messages or memory issues. </del>  The maxLength argument indicates the maximum size of a Message in bytes the application is currently prepared to receive.  The default Multiple invocations of ReceivedPartial deliver data for the same Message by passing the same messageContext, until the endOfMessage <del> flag is delivered.  All partial blocks of a single Message are delivered in order without gaps.  This event does not support delivering discontiguous partial Messages. </del>  If the minIncompleteLength in the Receive request was set to be infinite (indicating a request to receive only complete Messages),

Reviewer comments:
1 tiny fix suggested to make the text a little clearer (because the default "complete message" delivery may need a de-framer, or the whole Connection may function as a message), and pointed at a possible error when delivering partial data (it's already written elsewhere, but the suggestion makes a sentence more correct, I believe).
Looks good, thanks!
lgtm

Revised text:
The application can set a minIncompleteLength value to indicates the smallest partial Message data size in bytes that should be delivered in response to this Receive.  By default, this value is infinite,  <ins> which means that only complete Messages should be delivered (see receive-partial and receive-framing for more information on how this is accomplished).  If this value is set to some smaller value, the associated receive event will be triggered only when at least that many bytes are available, or the Message is complete with fewer bytes, or the system needs to free up memory.  Applications should always check the length of the data delivered to the receive event and not assume it will be as long as minIncompleteLength in the case of shorter complete Messages or memory issues. </ins> The maxLength argument indicates the maximum size of a Message in bytes the application is currently prepared to receive.  The default Multiple invocations of ReceivedPartial deliver data for the same Message by passing the same messageContext, until the endOfMessage  <ins> flag is delivered or a ReceiveError occurs.  All partial blocks of a single Message are delivered in order without gaps.  This event does not support delivering discontiguous partial Messages. </ins> If the minIncompleteLength in the Receive request was set to be infinite (indicating a request to receive only complete Messages),
Original text:
An Action creates an Object:  An Action is performed on an Object: An Object sends an Event: The Resolve() call returns a list of Preconnection Objects, that represent the concrete addresses, local and server reflexive, on which a Rendezvous() for the Preconnection will listen for incoming <del> Connections.  This list can be passed to a peer via a signalling protocol, such as SIP RFC3261 or WebRTC RFC7478, to configure the remote. </del>  6.4.

Reviewer comments:
section 6.3 (Rendezvous) has the following line: PreconnectionBinding := Preconnection.Resolve() If i read the text correctly, I'd propose to change this to Preconnection<> := Preconnection.Resolve()
Agreed, not sure what a is...
Agreed; the text would need to change to compensate as well. NAME is the on an array of preconnections? I don't think we have a notation for this yet ( are event params), but we probably should.
Agree with the change. are new objects derived from the initial by a process like ICE. E.g., once the resolve call has done a STUN exchange to find the external address of a NAT you're behind, you'll get back an object that represents that external address.
lgtm

Revised text:
An Action creates an Object: <ins> An Action creates an array of Objects: </ins> An Action is performed on an Object: An Object sends an Event: The Resolve() call returns a list of Preconnection Objects, that represent the concrete addresses, local and server reflexive, on which a Rendezvous() for the Preconnection will listen for incoming  <ins> Connections.  These resolved Preconnections will share all other Properties with the Preconnection from which they are derived, though some Properties may be made more-specific by the resolution process. This list can be passed to a peer via a signalling protocol, such as SIP RFC3261 or WebRTC RFC7478, to configure the remote. </ins> 6.4.
Original text:
Connection Properties: The Connection Properties are used to configure protocol-specific options and control per-connection behavior of the Transport System.  For example, a protocol- <del> specific property on the connection can express that if UDP is used, the implementation ought to use checksums.  Note that the presence of such a property does not require that a specific protocol will be used.  In general, these properties do not explicitly determine the selection of paths or protocols, but MAY be used in this way by an implementation during connection establishment. </del>  4.1.3.

Reviewer comments:
As discussed at the January interim last week
This definition is exactly right, IMO.Exactly right.

Revised text:
Connection Properties: The Connection Properties are used to configure protocol-specific options and control per-connection behavior of the Transport System.  For example, a protocol-  <ins> specific Connection Property can express that if UDP is used, the implementation ought to use checksums.  Note that the presence of such a property does not require that a specific protocol will be used.  In general, these properties do not explicitly determine the selection of paths or protocols, but MAY be used in this way by an implementation during connection establishment.  Connection Properties SHOULD be specified on a Preconnection prior to Connection establishment, but MAY be modified later.  Changes made to Connection Properties after establishment take effect on a best-effort basis. </ins> 4.1.3.
Original text:
An Object sends an Event: An Action takes a set of Parameters; an Event contains a set of <del> Parameters: </del>  Actions associated with no Object are Actions on the abstract interface itself; they are equivalent to Actions on a per-application Messages for streaming large data is also supported (see send- partial).  7.1. The most basic form of sending on a connection involves enqueuing a For application-layer protocols where the Connection initiator also sends the first message, the InitiateWithSend() action combines <del> Connection initiation with a first Message sent. Without a message context (as in send-basic): With a message context (as in message-props): </del>  Whenever possible, a messageContext should be provided to declare the message passed to InitiateWithSend as idempotent.  This allows the

Reviewer comments:
Even though all the languages we want to support don't have convenient syntax for optional parameters to functions/methods, it would be nice to note that we intend for some parameters to not be mandatory on every call.
Looks good! This approach certainly clarifies things.LGTM except for the paragraph that I commented on; I'd just delete that.Fine withe mit (with some minor knit)

Revised text:
An Object sends an Event: An Action takes a set of Parameters; an Event contains a set of  <ins> Parameters.  Action parameters whose names are suffixed with a question mark are optional. </ins> Actions associated with no Object are Actions on the abstract interface itself; they are equivalent to Actions on a per-application Messages for streaming large data is also supported (see send- partial). <ins> Messages are sent on a Connection using the Send action: where messageData is the data object to send.  The optional messageContext parameter supports per-message properties and is described in message-props.  The optional endOfMessage parameter supports partial sending and is described in send-partial. </ins> 7.1. The most basic form of sending on a connection involves enqueuing a For application-layer protocols where the Connection initiator also sends the first message, the InitiateWithSend() action combines  <ins> Connection initiation with a first Message sent: </ins> Whenever possible, a messageContext should be provided to declare the message passed to InitiateWithSend as idempotent.  This allows the
Original text:
path, the transport system will try the path first, ignoring the preference. <del> Both Selection and Connection Properties can be added to a Preconnection to configure the selection process, and to further configure the eventually selected protocol stack(s).  They are collected into a TransportProperties object to be passed into a Preconnection object: </del>  Individual properties are then added to the TransportProperties Object: retransmission of the 0-RTT data may cause the remote application to receive the Message multiple times.  7.3.5. Boolean

Reviewer comments:
This came up in a dinner among some of us yesterday: all UDP messages should be understood as being idempotent, because UDP doesn't protect the receiver against getting duplicates. This is different from unreliable transmission with, e.g., SCTP (or, probably, a future such extension of QUIC?), where you can be sure you're not getting a duplicate.
wfm

Revised text:
path, the transport system will try the path first, ignoring the preference.  <ins> Selection, and Connection Properties, as well as defaults for Message Properties, can be added to a Preconnection to configure the selection process, and to further configure the eventually selected protocol stack(s).  They are collected into a TransportProperties object to be passed into a Preconnection object: </ins> Individual properties are then added to the TransportProperties Object: retransmission of the 0-RTT data may cause the remote application to receive the Message multiple times. <ins> Note that for protocols that do not protect against duplicated messages, e.g., UDP, all messages MUST be marked as Idempotent.  In order to enable protocol selection to choose such a protocol, Idempotent MUST be added to the TransportProperties passed to the Preconnection.  If such a protocol was chosen, disabling Idempotent on individual messages MUST result in a SendError. </ins> 7.3.5. Boolean