jiebi/TextFlow huggingface dataset:
Original text:
Properties when sending.) Abort: The action the application takes on a Connection to <del> indicate a Close and also indicate that the Transport System SHOULD NOT attempt to deliver any outstanding data.  This is intended for immediate termination of a connection, without </del>  cleaning up state. 4.2.

Reviewer comments:
Addresses
In the architecture document, I noticed that we sometimes say "Transport Services system" and sometimes "Transport System". Are these the same? Are "Transport Services implementation" and "Transport System implementation" the same, too?
I prefer "Transport Services system" and "Transport Services implementation"
I find it long and clumsy :( Side note: we'll have to rename it everywhere in the API draft too if we go with this.
was this fixed by ?
Yes it was. We already used Transport Services most places so it's not all that different.
Looks good, thanks!

Revised text:
Properties when sending.) Abort: The action the application takes on a Connection to  <ins> indicate a Close and also indicate that the Transport Services system SHOULD NOT attempt to deliver any outstanding data.  This is intended for immediate termination of a connection, without </ins> cleaning up state. 4.2.
Original text:
protocols are not incorrectly swapped, Transport Services systems SHOULD only automatically generate equivalent Protocol Stacks when the transport security protocols within the stacks are identical. <del> Specifically, a Transport System would consider protocols </del>  identical only if they are of the same type and version.  For example, the same version of TLS running over two different transport Protocol Stacks are considered equivalent, whereas TLS

Reviewer comments:
Addresses
In the architecture document, I noticed that we sometimes say "Transport Services system" and sometimes "Transport System". Are these the same? Are "Transport Services implementation" and "Transport System implementation" the same, too?
I prefer "Transport Services system" and "Transport Services implementation"
I find it long and clumsy :( Side note: we'll have to rename it everywhere in the API draft too if we go with this.
was this fixed by ?
Yes it was. We already used Transport Services most places so it's not all that different.
Looks good, thanks!

Revised text:
protocols are not incorrectly swapped, Transport Services systems SHOULD only automatically generate equivalent Protocol Stacks when the transport security protocols within the stacks are identical.  <ins> Specifically, a Transport Services system would consider protocols </ins> identical only if they are of the same type and version.  For example, the same version of TLS running over two different transport Protocol Stacks are considered equivalent, whereas TLS
Original text:
protocol state, cached path state, and heuristics, may be shared (e.g. across multiple connections in an application).  This provides efficiency and convenience for the application, since the Transport <del> System implementation can automatically optimize behavior. </del>  There are several reasons, however, that an application might want to explicitly isolate some Connections.  These reasons include:

Reviewer comments:
Addresses
In the architecture document, I noticed that we sometimes say "Transport Services system" and sometimes "Transport System". Are these the same? Are "Transport Services implementation" and "Transport System implementation" the same, too?
I prefer "Transport Services system" and "Transport Services implementation"
I find it long and clumsy :( Side note: we'll have to rename it everywhere in the API draft too if we go with this.
was this fixed by ?
Yes it was. We already used Transport Services most places so it's not all that different.
Looks good, thanks!

Revised text:
protocol state, cached path state, and heuristics, may be shared (e.g. across multiple connections in an application).  This provides efficiency and convenience for the application, since the Transport  <ins> Services implementation can automatically optimize behavior. </ins> There are several reasons, however, that an application might want to explicitly isolate some Connections.  These reasons include:
Original text:
than -1, it sets the minimum protection in protocols that allow limiting the checksum length (e.g.  UDP-Lite). <del> Singular Transmission: when this is true, the application requests to avoid transport-layer segmentation or network-layer fragmentation.  Some transports implement network-layer fragmentation avoidance (Path MTU Discovery) without exposing this functionality to the application; in this case, only transport- layer segmentation should be avoided, by fitting the message into a single transport-layer segment or otherwise failing.  Otherwise, network-layer fragmentation should be avoided--e.g. by requesting the IP Don't Fragment bit to be set in case of UDP(-Lite) and IPv4 (SET_DF in RFC8304). </del>  5.1.2.

Reviewer comments:
this should
Right there was a typo: Replacing the last 2 sentences, the last sentence ought to be: " Endpoints should avoid IP fragmentation ({{!RFC8304}}) and when used with transports running over IP version 4 the Don't Fragment bit will be set." These are two separate issues that a stack implementor has to decide to do: (1) Decide if the endpoint will fragment; (2) decide if the path can fragment the fragments. In some OS this will be bundled together, in other OS they will not.
Discussed on the interim call. The name probably could be much better. We also want to model in the text the atomicity property of UDP transfers.
This text is broken: section 5.1 / o Singular Transmission: when this is true, the application requests to avoid transport-layer segmentation or network-layer fragmentation. Some transports implement network-layer fragmentation avoidance (Path MTU Discovery) without exposing this functionality to the application; in this case, only transport- layer segmentation should be avoided, by fitting the message into a single transport-layer segment or otherwise failing. Otherwise, network-layer fragmentation should be avoided--e.g. by requesting the IP Don't Fragment bit to be set in case of UDP(-Lite) and IPv4 (SET_DF in [RFC8304]). / we need to rewrite
Waiting to see exactly how DPLPMTUD finishes WGLC ... will be ready for text in Jan.
Reads much better except the last broken sentence

Revised text:
than -1, it sets the minimum protection in protocols that allow limiting the checksum length (e.g.  UDP-Lite).  <ins> Singular Transmission: When set, this property limits the message size to the Maximum Message Size Before Fragmentation or Segmentation (see Section 10.1.7 of I-D.ietf-taps-interface). Messages larger than this size generate an error.  Setting this avoids transport-layer segmentation or network-layer fragmentation.  When used with transports running over IP version 4 the Don't Fragment bit will be set to avoid on-path IP fragmentation (RFC8304). </ins> 5.1.2.
Original text:
actions are alternatives (e.g., whether to initiate a connection or to listen for incoming connections), while others are optional (e.g., setting Connection and Message Properties in Pre-Establishment) or <del> have been omitted for brevity. </del>  4.1.1.

Reviewer comments:
Fig. 4 isn't fully consistent with sec. 12 in the API document. A few things that stood out to me: InitiateWithSend() is missing. I can see that this isn't trying to cover everything, but randomly leaving some things out makes it all a bit confusing IMO... "Connection Received" reads as if it should really be the "ConnectionReceived<>" event in the API doc. So I would put these events there and use the "<>" to indicate them. Same with "Closed"... this is actually an event, so why not write it as such, with the "<>"? RendezvousDone is missing... should we include all events or not? Of course that would then also require adding Sent, Received, ... maybe it would be better to indicate that events are events, but put a statement somewhere saying that not all events are shown. In the same vein, I would replace "Connection Ready" with "Ready<>" "Conn. Finished" reads as if it might be an event, but this event doesn't exist... I would just remove this
I've added InitiateWithSend(), and removed Conn. Finished; you're right, these are confusing. This diagram does not use the API draft's event notation, and I'm not sure it makes sense to introduce it here -- it would require a bit more expository text only to make a diagram that is an attempt to provide a high-level view provide a... less high-level view. (The expository text now says "... some actions ... have been omitted for brevity and simplicity" and I think that's the right approach.)
Agreed!
lgtm

Revised text:
actions are alternatives (e.g., whether to initiate a connection or to listen for incoming connections), while others are optional (e.g., setting Connection and Message Properties in Pre-Establishment) or  <ins> have been omitted for brevity and simplicity. </ins> 4.1.1.
Original text:
10.2. <del> These properties specifies configurations for the User Timeout Option </del>  (UTO), in case TCP becomes the chosen transport protocol. Implementation is optional and of course only sensible if TCP is implemented in the transport system. <del> All of the below parameters are optional (e.g., it is possible to </del>  specify "User Timeout Enabled" as true, but not specify an Advertised User Timeout value; in this case, the TCP default will be used).

Reviewer comments:
Following the discussion in , explain why TCP UTO is included as a Protocol-Specific Property, while other properties are not. Also, some minor consistency fixes.
Thanks for doing this!Thanks

Revised text:
10.2.  <ins> These properties specify configurations for the User Timeout Option </ins> (UTO), in case TCP becomes the chosen transport protocol. Implementation is optional and of course only sensible if TCP is implemented in the transport system.  <ins> These TCP-specific properties are included here because the feature "Suggest timeout to the peer" is part of the minimal set of transport services I-D.ietf-taps-minset, where this feature was categorized as "functional".  This means that when an implementation offers this feature, it has to expose an interface to it to the application. Otherwise, the implementation might violate assumptions by the application, which could cause the application to fail. All of the below properties are optional (e.g., it is possible to </ins> specify "User Timeout Enabled" as true, but not specify an Advertised User Timeout value; in this case, the TCP default will be used).
Original text:
Integer <del> Default: :the TCP default </del>  This time value is advertised via the TCP User Timeout Option (UTO) RFC5482 at the remote endpoint to adapt its own "Timeout for aborting

Reviewer comments:
Following the discussion in , explain why TCP UTO is included as a Protocol-Specific Property, while other properties are not. Also, some minor consistency fixes.
Thanks for doing this!Thanks

Revised text:
Integer  <ins> the TCP default </ins> This time value is advertised via the TCP User Timeout Option (UTO) RFC5482 at the remote endpoint to adapt its own "Timeout for aborting
Original text:
All data sent with the same MessageContext object will be treated as belonging to the same Message, and will constitute an in-order series <del> until the endOfMessage is marked.  Once the end of the Message is marked, the MessageContext object may be re-used as a new Message with identical parameters. </del>  7.7.

Reviewer comments:
... as suggested by NAME
The section on partial send says: "All data sent with the same MessageContext object will be treated as belonging to the same Message, and will constitute an in-order series until the endOfMessage is marked. Once the end of the Message is marked, the MessageContext object may be re-used as a new Message with identical parameters." Can we reconsider for a second if that is really the way we want to design this? This is really implicit and therefore an easy source for errors. I guess we could alternatively use an explicit message identifier...? Or the send action always return an identifier and for subsequent sends we input this identifier again? Or someone has a smarter idea?
I don't have my head buried in code like some others here (NAME NAME , ..), so I guess that these folks should speak up - but just from reading this, I agree that the current design sounds like an easy source for errors.
I'd prefer to just remove the part that mentions reusing the same object. That's an implementation detail (and a perf optimization). The rest seems correct.

Revised text:
All data sent with the same MessageContext object will be treated as belonging to the same Message, and will constitute an in-order series  <ins> until the endOfMessage is marked. </ins> 7.7.
Original text:
Abstract <del> This document describes an abstract programming interface, API, to the transport layer, following the Transport Services Architecture. It supports the asynchronous, atomic transmission of messages over transport protocols and network paths dynamically selected at runtime.  It is intended to replace the traditional BSD sockets API as the common interface to the transport layer, in an environment where endpoints could select from multiple interfaces and potential transport protocols. </del>  1.

Reviewer comments:
Fixing three oddities in the abstract, issue
Odd English: /where endpoints have multiple interfaces and potential transport protocols to select from/where endpoints could select from multiple interfaces and potential transport protocols./ We use the words /abstract programming interface/ and the acronym /API/ but never tie these two together. I am not huge fan of: /lowest common denominator interface/ ... as an engineer, this sounds like a good thing, although /lowest/ isn't that clear, so I wonder if we can find a better term?
Resolved in PR
LGTM modulo one nit

Revised text:
Abstract  <ins> This document describes an abstract application programming interface, API, to the transport layer, following the Transport Services Architecture.  It supports the asynchronous, atomic transmission of messages over transport protocols and network paths dynamically selected at runtime.  It is intended to replace the traditional BSD sockets API as the common interface to the transport layer, in an environment where endpoints could select from multiple interfaces and potential transport protocols. </ins> 1.
Original text:
5.1.1. Lifetime: this should be implemented by removing the Message from <del> its queue of pending Messages after the Lifetime has expired.  A </del>  queue of pending Messages within the transport system implementation that have yet to be handed to the Protocol Stack can always support this property, but once a Message has been sent into the send buffer of a protocol, only certain protocols may <del> support de-queueing a message.  For example, TCP cannot remove bytes from its send buffer, while in case of SCTP, such control over the SCTP send buffer can be exercised using the partial reliability extension RFC8303.  When there is no standing queue of Messages within the system, and the Protocol Stack does not support removing a Message from its buffer, this property may be ignored. </del>  Priority: this represents the ability to prioritize a Message over other Messages.  This can be implemented by the system re-ordering

Reviewer comments:
Changes to address Issue
Message Properties This isn’t really about /removing/ we need to express this differently, not sure what you wish to say: For example, TCP cannot remove bytes from its send buffer, while in case of SCTP, such control over the SCTP send buffer can be exercised using the partial reliability extension [RFC8303]. and: /Final: when this is true, it means that a transport connection can be closed immediately after its transmission./ I think this is: /Final: when this is true, it means that a transport connection can be closed immediately after transmission of the message./
See PR Update draft-ietf-taps-URL
Looks good, just some more nits on top

Revised text:
5.1.1. Lifetime: this should be implemented by removing the Message from  <ins> the queue of pending Messages after the Lifetime has expired.  A </ins> queue of pending Messages within the transport system implementation that have yet to be handed to the Protocol Stack can always support this property, but once a Message has been sent into the send buffer of a protocol, only certain protocols may  <ins> support removing a message.  For example, an implementation cannot cannot remove bytes from a TCP send buffer, while it can remove data from a SCTP send buffer using the partial reliability extension RFC8303.  When there is no standing queue of Messages within the system, and the Protocol Stack does not support the removal of a Message from the stack's send buffer, this property may be ignored. </ins> Priority: this represents the ability to prioritize a Message over other Messages.  This can be implemented by the system re-ordering
Original text:
could choose to send Messages of different Priority on streams of different priority. <del> Ordered: when this is false, it disables the requirement of in- </del>  order-delivery for protocols that support configurable ordering. <del> Safely Replayable: when this is true, it means that the Message </del>  can be used by mechanisms that might transfer it multiple times - e.g., as a result of racing multiple transports or as part of TCP Fast Open. <del> Final: when this is true, it means that a transport connection can be closed immediately after its transmission. </del>  Corruption Protection Length: when this is set to any value other than -1, it sets the minimum protection in protocols that allow

Reviewer comments:
Changes to address Issue
Message Properties This isn’t really about /removing/ we need to express this differently, not sure what you wish to say: For example, TCP cannot remove bytes from its send buffer, while in case of SCTP, such control over the SCTP send buffer can be exercised using the partial reliability extension [RFC8303]. and: /Final: when this is true, it means that a transport connection can be closed immediately after its transmission./ I think this is: /Final: when this is true, it means that a transport connection can be closed immediately after transmission of the message./
See PR Update draft-ietf-taps-URL
Looks good, just some more nits on top

Revised text:
could choose to send Messages of different Priority on streams of different priority.  <ins> Ordered: when this is false, this disables the requirement of in- </ins> order-delivery for protocols that support configurable ordering.  <ins> Safely Replayable: when this is true, this means that the Message </ins> can be used by mechanisms that might transfer it multiple times - e.g., as a result of racing multiple transports or as part of TCP Fast Open.  <ins> Final: when this is true, this means that a transport connection can be closed immediately after transmission of the message. </ins> Corruption Protection Length: when this is set to any value other than -1, it sets the minimum protection in protocols that allow
Original text:
Enumeration: can take one value of a finite set of values, dependent on the property itself.  The representation is <del> implementation dependent; however, implementations MUST provide a method for the application to determine the entire set of possible values for each property. </del>  Preference: can take one of five values (Prohibit, Avoid, Ignore, Prefer, Require) for the level of preference of a given property

Reviewer comments:
sec 4.2.2 "implementations MUST provide a method for the application to determine the entire set of possible values for each property." Is this meant to be a requirement for a machine-readable API for learning the enum, or merely a requirement for documentation? i.e. is it satisfied if the values are in the man page or comments of the C header file?
As a by-note, isn't this a great place to use "REQUIRED" and say whether it is required to specify or required to support :-).
Proposal: Just remove "however, implementations MUST provide a method for the application to determine the entire set of possible values for each property." This is too implementation- and language- specific.

Revised text:
Enumeration: can take one value of a finite set of values, dependent on the property itself.  The representation is  <ins> implementation dependent. </ins> Preference: can take one of five values (Prohibit, Avoid, Ignore, Prefer, Require) for the level of preference of a given property
Original text:
Handover This property specifies the local policy for transferring data across <del> multiple paths between the same end hosts if Parallel Use of Multiple Paths is not set to Disabled (see multipath-mode).  Possible values are: </del>  The connection ought only to attempt to migrate between different paths when the original path is lost or becomes unusable.  The

Reviewer comments:
Note, the change to the API draft here is a purely editorial detail that I fixed here in passing: the multipath selection property was renamed and this fixes the text referring to it.
"what we discussed" - you mean in , where I say that I stumbled over a sentence? This PR does update that sentence (simply removing "with migration support" from it because any multipath protocol can do that).
no, i meant what we discussed at the interim about using the handover, interactive, aggregate terminology. but i saw that this was not so easily done and we are all happy with your solution, so all good :)
Before distinguishing between protocols that do "multipath" and "migrating between paths", it might help to define these terms. This is tripping is up in QUIC, and IIRC the original "Multipath TCP" was pretty much the migration case. Something like, "In this section we distinguish between 'multipath' protocols and protocols that allow migration between paths. The first means ..."
This is in section 7.2 of taps-impl.
We define multipath (by policy in section 6.1.7 handover, interactive, aggregate) in the API doc. Section 4.2 in Implementation should use these definitions.
I wanted to fix this now, but stumbled over the following sentence in the implementation draft: This talks about the protocol below the transport services system; do multipath-supporting protocols with no migration support exist? I struggle to imagine a scheduler that wouldn't make this happen... e.g. lowest latency scheduling, but with the exception: if a path becomes completely unavailable, keep going? :-) Looking at the three policies in section 6.1.7 of our API, clearly, migration should work with all of them (and "Handover" is limited in that it doesn't do anything else, but it's gotta be a subset of the others anyway, I'd say). Am I missing something? Just checking...
I think the example of no migration support would be a multipath protocol that is not able to add new paths, so SCTP without support for the ADD_ADDR extension perhaps? Not sure this is a case we need to worry about though...
Ah, a multipath protocol that doesn't do multipath :-)
Well, it can do multipath with the paths you give it from the beginning :) Possibly something else was intended with the text from the beginning, but this is what I could think of...
Looks good to me!Thanks for fixing the nits!

Revised text:
Handover This property specifies the local policy for transferring data across  <ins> multiple paths between the same end hosts if Multipath Transport is not set to Disabled (see multipath-mode).  Possible values are: </ins> The connection ought only to attempt to migrate between different paths when the original path is lost or becomes unusable.  The