jiebi/TextFlow huggingface dataset:
Original text:
(e.g.  I-D.ietf-httpbis-priority. A Transport Services system gives no guarantees about how its <del> expression of relative priorities will be realized; for example, if a transport stack that only provides a single in-order reliable stream is selected, prioritization information can only be ignored. However, the Transport Services system will seek to ensure that performance of relatively-prioritized connections and messages is not worse with respect to those connections and messages than an equivalent configuration in which all prioritization properties are left at their defaults. </del>  The Transport Services interface does order Connection Priority over the Priority Message Property.  In the absense of other externalities

Reviewer comments:
Section 7.2.6. says " for example, if a transport stack that only provides a single in-order reliable stream is selected, prioritization information can only be ignored." I don't think this is entirely true as you can still decide in which order you schedule independent messages on one stream.
I don't get this. The sentence says "in-order". Scheduling them from buffer A into buffer B in accordance with priorities won't help when everything leaves buffer B in a fixed sequence.
How about a less complex sentence: ..."for example, if the transport system selects a stack that only provides a single in-order reliable stream, the prioritization information is ignored."
message on the taps "layer" are independent. so the order an application calls send on these message doesn't have to be the same order the messages are send on an "in-order stream"
Oh, now I see what you mean. Hmmm... looking at the text, it seems that we could just delete this sentence and the problem is solved?
I think what was intended with the example was to show that the set priorities may not have any effect. Perhaps we should instead just add "and the set priorities may not have any effect" if we want to be explicit? Removing it also works though.
I think just add that!
I'm for removing it (I think I wrote this sentence btw :-) ). Giving this example just throws off someone who thinks about this case like Mirja did here - even if we say "may not apply", the reader may (correctly) think "but why, in this case they CAN well apply!". So I don't find that helpful. For context, the full current statement is: and I believe that we say everything we need to say if we just change this into:
I like simple examples, this one wasn't great so this is OK.

Revised text:
(e.g.  I-D.ietf-httpbis-priority. A Transport Services system gives no guarantees about how its  <ins> expression of relative priorities will be realized.  However, the Transport Services system will seek to ensure that performance of relatively-prioritized connections and messages is not worse with respect to those connections and messages than an equivalent configuration in which all prioritization properties are left at their defaults. </ins> The Transport Services interface does order Connection Priority over the Priority Message Property.  In the absense of other externalities
Original text:
Preference <del> Prefer </del>  This property specifies whether the application needs or prefers to use a transport protocol that preserves message boundaries.

Reviewer comments:
I am sure this has been discussed, but reading now it seems strange to me to use "Prefer" as the default for a Selection Property that affects how the application interacts with the API. Using "Prefer" means that I do not know what service I will get when using the default settings? In this case I do not know if I get messages or not if I use the defaults.
This should be Ignore as a default.

Revised text:
Preference  <ins> Ignore </ins> This property specifies whether the application needs or prefers to use a transport protocol that preserves message boundaries.
Original text:
applications written to a single API to make use of transport protocols in terms of the features they provide. <del> A unified interface to datagram and connection-oriented transports, allowing use of a common API for connection- establishment and closing. </del>  Message-orientation, as opposed to stream-orientation, using application-assisted framing and deframing where the underlying

Reviewer comments:
Interface, Section 2, "A unified interface to datagram and connection-oriented transports, allowing use of a common API for connection-establishment and closing". Should this be "…to datagram and stream-oriented transports"? At what point do we explain that and are also used for connectionless protocols? This change would finesse the question here, leaving it for Section 3, or we can restructure the draft to clarify earlier.
Yes to (1): Datagram protocols can be connection-oriented or not; however the point here seems to be either: /interface to datagram and stream-oriented transports/ or /interface to both connection-less and connection-oriented transports/ ... I'd favour the first, it's clear enough and doesn't use terms that we later re-use. Also to (2): I think we could insert a specific sentence after: " A Connection represents an instance of a transport Protocol Stack on which data can be sent to and/or received from a Remote Endpoint (i.e., depending on the kind of transport, connections can be bi-directional or unidirectional). " That explicitly says something like: "This connections are presently consistently to the application, irrespective of whether the underlying transport is connection-less and connection-oriented."

Revised text:
applications written to a single API to make use of transport protocols in terms of the features they provide.  <ins> A unified interface to datagram and stream-oriented transports, allowing use of a common API for connection establishment and closing. </ins> Message-orientation, as opposed to stream-orientation, using application-assisted framing and deframing where the underlying
Original text:
and/or received from a Remote Endpoint (i.e., a logical connection that, depending on the kind of transport, can be bi-directional or unidirectional, and that can use a stream protocol or a datagram <del> protocol).  Connections can be created from Preconnections in three ways: by initiating the Preconnection (i.e., actively opening, as in a client; initiate), through listening on the Preconnection (i.e., passively opening, as in a server listen), or rendezvousing on the Preconnection (i.e., peer to peer establishment; rendezvous). </del>  Once a Connection is established, data can be sent and received on it in the form of Messages.  The interface supports the preservation of

Reviewer comments:
Interface, Section 2, "A unified interface to datagram and connection-oriented transports, allowing use of a common API for connection-establishment and closing". Should this be "…to datagram and stream-oriented transports"? At what point do we explain that and are also used for connectionless protocols? This change would finesse the question here, leaving it for Section 3, or we can restructure the draft to clarify earlier.
Yes to (1): Datagram protocols can be connection-oriented or not; however the point here seems to be either: /interface to datagram and stream-oriented transports/ or /interface to both connection-less and connection-oriented transports/ ... I'd favour the first, it's clear enough and doesn't use terms that we later re-use. Also to (2): I think we could insert a specific sentence after: " A Connection represents an instance of a transport Protocol Stack on which data can be sent to and/or received from a Remote Endpoint (i.e., depending on the kind of transport, connections can be bi-directional or unidirectional). " That explicitly says something like: "This connections are presently consistently to the application, irrespective of whether the underlying transport is connection-less and connection-oriented."

Revised text:
and/or received from a Remote Endpoint (i.e., a logical connection that, depending on the kind of transport, can be bi-directional or unidirectional, and that can use a stream protocol or a datagram  <ins> protocol).  Connections are presented consistently to the application, irrespective of whether the underlying transport is connection-less or connection-oriented.  Connections can be created from Preconnections in three ways: by initiating the Preconnection (i.e., actively opening, as in a client; initiate), through listening on the Preconnection (i.e., passively opening, as in a server listen), or rendezvousing on the Preconnection (i.e., peer to peer establishment; rendezvous). </ins> Once a Connection is established, data can be sent and received on it in the form of Messages.  The interface supports the preservation of
Original text:
The messageData object provides access to the bytes that were received for this Message, along with the length of the byte array. The messageContext is provided to enable retrieving metadata about <del> the message and referring to the message, e.g., to send replies and map responses to their requests.  See msg-ctx for details. </del>  See framing for handling Message framing in situations where the Protocol Stack only provides a byte-stream transport.

Reviewer comments:
The text below is a bit confusing as there are no details about how to to send replies and map responses to their requests in Section 7.1.1. This can be easily fixed by clarifying what Section 7.1.1 provides details on. But I was also wondering if there should be some more details on how to send replies and map responses to their requests somewhere?
Note: this will be in §9.3.2.1. after merge.
Is seems the concept of mapping requests/replies has been fully eliminated. So just removing this part of the example.
Thanks Philipp, LGTM.

Revised text:
The messageData object provides access to the bytes that were received for this Message, along with the length of the byte array. The messageContext is provided to enable retrieving metadata about  <ins> the message and referring to the message.  The messageContext object ist described in msg-ctx. </ins> See framing for handling Message framing in situations where the Protocol Stack only provides a byte-stream transport.
Original text:
is Any-source Multicast, and the path selection is based on the outbound route to the group supplied in the Local Endpoint.  UDP Multicast Receive Listeners will deliver new connections once they have received traffic from a new Remote Endpoint.

Reviewer comments:
This adds SO_reuse commentry on the multicast UDP service. It seeks to
The implementation document should explain IGMP joining and SO_REUSEADDR for multicast
Text blob for thought or incorporation: In some uses, it is required to open multiple connections for the same address(es). This is used for some multicast applications. For example, one connection might be opened to listen to a multicast group, and later a separate one to send to the same group; two applications might independently listen to the same address(es) to send signals to and/or receive signals from a common multicast control bus. In these cases, the interface needs to explicitly enable re-use of the same set of addresses (equivalent to setting SO_REUSEADDR in the socket API).

Revised text:
is Any-source Multicast, and the path selection is based on the outbound route to the group supplied in the Local Endpoint. <ins> There are cases where it is required to open multiple connections for the same address(es).  For example, one Connection might be opened for a multicast group to for a multicast control bus, and another application later opens a separate Connection to the same group to send signals to and/or receive signals from the common bus.  In such cases, the interface needs to explicitly enable re-use of the same set of addresses (equivalent to setting SO_REUSEADDR in the socket API). </ins> UDP Multicast Receive Listeners will deliver new connections once they have received traffic from a new Remote Endpoint.
Original text:
3. <del> The Transport Services API is the basic common abstract application programming interface to the Transport Services Architecture defined in the TAPS Architecture I-D.ietf-taps-arch. </del> An application primarily interacts with this API through two Objects: Preconnections and Connections.  A Preconnection object (pre- establishment) represents a set of properties and constraints on the

Reviewer comments:
, , , , , .
In 8.1.1 the second sentence is convoluted. Is there a way to restate it without as many nots, nons, an different zeros?
Do you really mean "host" at "(endpoints) SHOULD represent the same host" in section 6, or do you mean something more like service, given that an endpoint may configured with a DNS name?
actually we mean service, good catch.
The "reformatted where necessary" part of the requirement in the last paragraph of 4.1 makes the MUST NOT almost impossible to conform to. I think I understand what the paragraph is trying to say, but the current formulation leaves the reader guessing. I think you are trying to say "Avoid using any of the terms listed as keywords in the protocol numbers registry as any part of a vendor or implementation-specific property name".
The first sentence-paragraph of section 4 is complex. Please break it apart.
has a comment that's too long for the text version
In the text version of the document, the last paragraph before 3.1.3 has some markup (~~~) that has leaked through.
As you can tell, I don't think the documents do what the first sentence of the API summary claims. This document would not lose anything if you deleted the sentence.
Agreed, we can lose this sentence.
Why? Removing this makes no sense to me.
For one, it's redundant - it only repeats what we already say earlier twice.
Ah, I see - so just this one instance..... then go ahead, we don't need to say something twice.

Revised text:
3.  An application primarily interacts with this API through two Objects: Preconnections and Connections.  A Preconnection object (pre- establishment) represents a set of properties and constraints on the
Original text:
Preconnections are reusable after being used to initiate a Connection.  Hence, for example, after the Connections were closed, <del> the following would be correct: ~~~ //.. carry out adjustments to the Preconnection, if desire Connection := Preconnection.Initiate() ~~~ </del>  3.1.3.

Reviewer comments:
, , , , , .
In 8.1.1 the second sentence is convoluted. Is there a way to restate it without as many nots, nons, an different zeros?
Do you really mean "host" at "(endpoints) SHOULD represent the same host" in section 6, or do you mean something more like service, given that an endpoint may configured with a DNS name?
actually we mean service, good catch.
The "reformatted where necessary" part of the requirement in the last paragraph of 4.1 makes the MUST NOT almost impossible to conform to. I think I understand what the paragraph is trying to say, but the current formulation leaves the reader guessing. I think you are trying to say "Avoid using any of the terms listed as keywords in the protocol numbers registry as any part of a vendor or implementation-specific property name".
The first sentence-paragraph of section 4 is complex. Please break it apart.
has a comment that's too long for the text version
In the text version of the document, the last paragraph before 3.1.3 has some markup (~~~) that has leaked through.
As you can tell, I don't think the documents do what the first sentence of the API summary claims. This document would not lose anything if you deleted the sentence.
Agreed, we can lose this sentence.
Why? Removing this makes no sense to me.
For one, it's redundant - it only repeats what we already say earlier twice.
Ah, I see - so just this one instance..... then go ahead, we don't need to say something twice.

Revised text:
Preconnections are reusable after being used to initiate a Connection.  Hence, for example, after the Connections were closed,  <ins> the following would be correct: </ins> 3.1.3.
Original text:
4. Each application using the Transport Services Interface declares its <del> preferences for how the transport service should operate using properties at each stage of the lifetime of a connection using Transport Properties, as defined in I-D.ietf-taps-arch. </del>  Transport Properties are divided into Selection, Connection, and Message Properties.  Selection Properties (see selection-props) can

Reviewer comments:
, , , , , .
In 8.1.1 the second sentence is convoluted. Is there a way to restate it without as many nots, nons, an different zeros?
Do you really mean "host" at "(endpoints) SHOULD represent the same host" in section 6, or do you mean something more like service, given that an endpoint may configured with a DNS name?
actually we mean service, good catch.
The "reformatted where necessary" part of the requirement in the last paragraph of 4.1 makes the MUST NOT almost impossible to conform to. I think I understand what the paragraph is trying to say, but the current formulation leaves the reader guessing. I think you are trying to say "Avoid using any of the terms listed as keywords in the protocol numbers registry as any part of a vendor or implementation-specific property name".
The first sentence-paragraph of section 4 is complex. Please break it apart.
has a comment that's too long for the text version
In the text version of the document, the last paragraph before 3.1.3 has some markup (~~~) that has leaked through.
As you can tell, I don't think the documents do what the first sentence of the API summary claims. This document would not lose anything if you deleted the sentence.
Agreed, we can lose this sentence.
Why? Removing this makes no sense to me.
For one, it's redundant - it only repeats what we already say earlier twice.
Ah, I see - so just this one instance..... then go ahead, we don't need to say something twice.

Revised text:
4. Each application using the Transport Services Interface declares its  <ins> preferences for how the transport service should operate.  This is done by using Transport Properties, as defined in I-D.ietf-taps-arch, at each stage of the lifetime of a connection. </ins> Transport Properties are divided into Selection, Connection, and Message Properties.  Selection Properties (see selection-props) can
Original text:
Namespaces for each of the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol- <del> numbers/protocol-numbers.xhtml), reformatted where necessary to conform to an implementation's naming conventions, are reserved for Protocol Specific Properties and MUST NOT be used for vendor or implementation-specific properties. </del>  4.2.

Reviewer comments:
, , , , , .
In 8.1.1 the second sentence is convoluted. Is there a way to restate it without as many nots, nons, an different zeros?
Do you really mean "host" at "(endpoints) SHOULD represent the same host" in section 6, or do you mean something more like service, given that an endpoint may configured with a DNS name?
actually we mean service, good catch.
The "reformatted where necessary" part of the requirement in the last paragraph of 4.1 makes the MUST NOT almost impossible to conform to. I think I understand what the paragraph is trying to say, but the current formulation leaves the reader guessing. I think you are trying to say "Avoid using any of the terms listed as keywords in the protocol numbers registry as any part of a vendor or implementation-specific property name".
The first sentence-paragraph of section 4 is complex. Please break it apart.
has a comment that's too long for the text version
In the text version of the document, the last paragraph before 3.1.3 has some markup (~~~) that has leaked through.
As you can tell, I don't think the documents do what the first sentence of the API summary claims. This document would not lose anything if you deleted the sentence.
Agreed, we can lose this sentence.
Why? Removing this makes no sense to me.
For one, it's redundant - it only repeats what we already say earlier twice.
Ah, I see - so just this one instance..... then go ahead, we don't need to say something twice.

Revised text:
Namespaces for each of the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol-  <ins> numbers/protocol-numbers.xhtml) are reserved for Protocol Specific Properties and MUST NOT be used for vendor or implementation-specific properties.  Avoid using any of the terms listed as keywords in the protocol numbers registry as any part of a vendor- or implementation- specific property name. </ins> 4.2.
Original text:
If more than one Remote Endpoint is specified on the Preconnection, then all the Remote Endpoints on the Preconnection SHOULD represent <del> the same host.  For example, the Remote Endpoints might represent </del>  various network interfaces of a host, or a server reflexive address that can be used to reach a host, or a set of hosts that provide equivalent local balanced service.

Reviewer comments:
, , , , , .
In 8.1.1 the second sentence is convoluted. Is there a way to restate it without as many nots, nons, an different zeros?
Do you really mean "host" at "(endpoints) SHOULD represent the same host" in section 6, or do you mean something more like service, given that an endpoint may configured with a DNS name?
actually we mean service, good catch.
The "reformatted where necessary" part of the requirement in the last paragraph of 4.1 makes the MUST NOT almost impossible to conform to. I think I understand what the paragraph is trying to say, but the current formulation leaves the reader guessing. I think you are trying to say "Avoid using any of the terms listed as keywords in the protocol numbers registry as any part of a vendor or implementation-specific property name".
The first sentence-paragraph of section 4 is complex. Please break it apart.
has a comment that's too long for the text version
In the text version of the document, the last paragraph before 3.1.3 has some markup (~~~) that has leaked through.
As you can tell, I don't think the documents do what the first sentence of the API summary claims. This document would not lose anything if you deleted the sentence.
Agreed, we can lose this sentence.
Why? Removing this makes no sense to me.
For one, it's redundant - it only repeats what we already say earlier twice.
Ah, I see - so just this one instance..... then go ahead, we don't need to say something twice.

Revised text:
If more than one Remote Endpoint is specified on the Preconnection, then all the Remote Endpoints on the Preconnection SHOULD represent  <ins> the same service.  For example, the Remote Endpoints might represent </ins> various network interfaces of a host, or a server reflexive address that can be used to reach a host, or a set of hosts that provide equivalent local balanced service.