jiebi/TextFlow huggingface dataset:
Original text:
This section describes how the registering endpoint can maintain the registrations that it created.  The registering endpoint can be the <del> registrant-ep or the CT.  An endpoint SHOULD NOT use this interface for registrations that it did not create.  The registrations are resources of the RD. </del>  After the initial registration, the registering endpoint retains the returned location of the Registration Resource for further Search criteria for limiting the number of results (optional).  Page (optional).  Parameter cannot be used without the count parameter.  Results are returned from result set in pages that contain 'count' links starting from index (page * count).  Page registration of endpoints, as a query parameter in lookups, or be expressed as a target attribute, <del> validity requirements if any, </del>  a description,

Reviewer comments:
It appears I've missed some of Alexey's remarks responding to the changes made after his initial review (, 2019-11-20). This contains fixes for the points he still wanted changed / suggested after my original response to his review.

Revised text:
This section describes how the registering endpoint can maintain the registrations that it created.  The registering endpoint can be the  <ins> registrant-ep or the CT.  The registrations are resources of the RD. An endpoint should not use this interface for registrations that it did not create.  This is usually enforced by security policies, which in general require equivalent credentials for creation of and operations on a registration. </ins> After the initial registration, the registering endpoint retains the returned location of the Registration Resource for further Search criteria for limiting the number of results (optional). <ins> The search criteria are an associative array, expressed in a form-style query as per the URI template (see RFC6570 Sections 2.4.2 and 3.2.8) </ins> Page (optional).  Parameter cannot be used without the count parameter.  Results are returned from result set in pages that contain 'count' links starting from index (page * count).  Page registration of endpoints, as a query parameter in lookups, or be expressed as a target attribute,  <ins> syntax and validity requirements if any, </ins> a description,
Original text:
12.  changes from -23 to -24 Discovery using DNS-SD added again

Reviewer comments:
This is the WIP work to go from "we explain how exactly to do RD security" (and get the details wrong) to "we outline what needs to be considered but it's really up to the application" talked about in URL
(as no single commit has this in its metadata)
From Russ's Genart review: It's tempting to say "squared number of maximum endpoints times security" here. But really what's the error mode here? If a registrant happens to pick something duplicate, it'll get a 4.03 Forbidden. It could then try a different value, but as the RD only "can" (and not MUST) check for collisions, it might have allowed someone else to take our registrant's ep name, and if the registrant was previously successful with that name, it can't change it any more as the RD would refuse it based on the MUST. We can make both MUSTs (the RD already needs to keep a list of used certificates already anyway, it only adds a requirement to use it (possibly via a new index)), but then still, what's a device to do if it receives a 4.03? Change its ep name as this is obviously not the same RD where it had worked before? Just fail? Can or must a device change its name if it is fashioned with a new certificate? Does it need to know the RD's criteria for equivalence of certificates to decide that?
With the text of f98deeee7bd603c7e6b4da2b9936d45a99e18ceb this is easier now (as the error mode in "and require the same properties" is implied to be 4.01); text to follow.

Revised text:
12. <ins> changes in this branch Large rework of section 7 (Security policies) Rather than prescribing which data in the RD _is_ authenticated (and how), it now describes what applications built on an RD _can_ choose to authenticate, show possibilities on how to do it and outline what it means for clients. This addresses Russ' Genart review points on details in the text in a rather broad fashion.  That is because the discussion on the topic inside the WG showed that that text on security has been driven more review-by-review than by the an architectural plan of the authors and WG. Add concrete suggestions (twice as long as registrant number with retries, or UUIDs without) for random endpoint names </ins> changes from -23 to -24 Discovery using DNS-SD added again
Original text:
4.04 "Not Found" or 404 "Not Found".  Registration does not exist (e.g. may have been removed). <del> If the registration fails in any way, including "Not Found" and request timeouts, or if the time indicated in a Service Unavailable Max-Age/Retry-After exceeds the remaining lifetime, the registering endpoint SHOULD attempt registration again. </del>  The following example shows how the registering endpoint updates its registration resource at an RD using this interface with the example

Reviewer comments:
Will still grow while I'm working through the latest discusses/comments; these are things not directly mentioned there but small errors that became obvious when working through the document to prepare responses and/or when preparing patches to address the issues.

Revised text:
4.04 "Not Found" or 404 "Not Found".  Registration does not exist (e.g. may have been removed).  <ins> If the registration update fails in any way, including "Not Found" and request timeouts, or if the time indicated in a Service Unavailable Max-Age/Retry-After exceeds the remaining lifetime, the registering endpoint SHOULD attempt registration again. </ins> The following example shows how the registering endpoint updates its registration resource at an RD using this interface with the example
Original text:
server as described in finding_an_rd. The registrant-ep sends (and regularly refreshes with) a POST <del> request to the "/.well-known/core" URI of the directory server of </del>  choice.  The body of the POST request is empty, and triggers the resource directory server to perform GET requests at the requesting registrant-ep's /.well-known/core to obtain the link- POST <del> /.well-known/core{?ep,d,lt,extra-attrs*} </del>  URI Template Variables are as they are for registration in registration.  The base attribute is not accepted to keep the registration interface simple; that rules out registration over CoAP- <del> over-TCP or HTTP that would need to specify one. </del>  The following response is expected on this interface: 9.6. <del> IANA is asked to extend the reference for the "core" URI suffix in the "Well-Known URIs" registry to reference this document next to RFC6690, as this defines the resource's behavior for POST requests. </del>  9.7. Home and building automation use case: Tie in with RD  changes from -24 to -25 Large rework of section 7 (Security policies)

Reviewer comments:
No deployed implementations of simple registration are known that can't switch over easily. As per URL

Revised text:
server as described in finding_an_rd. The registrant-ep sends (and regularly refreshes with) a POST  <ins> request to the "/.well-known/rd" URI of the directory server of </ins> choice.  The body of the POST request is empty, and triggers the resource directory server to perform GET requests at the requesting registrant-ep's /.well-known/core to obtain the link- POST  <ins> /.well-known/rd{?ep,d,lt,extra-attrs*} </ins> URI Template Variables are as they are for registration in registration.  The base attribute is not accepted to keep the registration interface simple; that rules out registration over CoAP-  <ins> over-TCP or HTTP that would need to specify one.  For some time during this document's development, the URI template "/.well-known/ core{?ep,...}" has been in use instead. </ins> The following response is expected on this interface: 9.6.  <ins> IANA is asked to permanently register the URI suffix "rd" in the "Well-Known URIs" registry.  The change controller is the IETF, this document is the reference. </ins> 9.7. Home and building automation use case: Tie in with RD <ins> Simple registration: Rather than coopting POSTs to /.well-known/ core, a new resource /.well-known/rd is registered.  A historical note in the text documents the change. </ins> changes from -24 to -25 Large rework of section 7 (Security policies)
Original text:
Any, all or none of the below can apply to an application.  Which are relevant depends on its protection objectives.  7.1. Whenever an RD needs to provide trustworthy results to clients doing firewalling than lookups to the RD, the RD may need to limit which lookup clients may access the information. <del> In those situations, the registrant needs to be careful to authenticate the RD as well.  The registrant needs to know in advance which AS, audience and scope values indicate an RD it may trust for this purpose, and cannot rely on the RD to provide AS address and token details.  (In contrast, in the other scenarios it may try to register, and follow the pointers the RD gives it as to which credentials it needs to provide in order to perform its registration). </del>  7.4. Abstract, introduction: removed "or disperse networks"  changes from -24 to -25 Large rework of section 7 (Security policies)

Reviewer comments:
…om authorized RDs This makes the paragraph that described that for a particular case largely redundant. The lines about that special case that described special considerations for ACE anticipate a mechanism that is not finished yet, and were removed.

Revised text:
Any, all or none of the below can apply to an application.  Which are relevant depends on its protection objectives. <ins> Security policies are set by configuration of the RD, or by choice of the implementation.  Lookup clients (and, where relevant, endpoints) can only trust an RD to uphold them if it is authenticated, and authorized to serve as an RD according to the application's requirements. </ins> 7.1. Whenever an RD needs to provide trustworthy results to clients doing firewalling than lookups to the RD, the RD may need to limit which lookup clients may access the information.  <ins> In this case, the endpoint (and not the lookup clients) needs to be careful to check the RD's authorization. </ins> 7.4. Abstract, introduction: removed "or disperse networks" <ins> Security policies: Clarify that with all security policies, clients must verify the authorization of the RD. Remove speculation about how in detail ACE scopes are obtained. </ins> changes from -24 to -25 Large rework of section 7 (Security policies)
Original text:
victim's .well-known/core content in the RD.  Mitigation for this is recommended in simple.  8.3. Access control SHOULD be performed separately for the RD registration Acknowledge that most discovery operations are not secured; mention consequences and mitigation.  RDAO: Clarify that it is an option for RAs and not other ND messages.

Reviewer comments:
This is a result of the discussion following Roman's "> But why expose them at all if they're not going to be accessible?" comment.

Revised text:
victim's .well-known/core content in the RD.  Mitigation for this is recommended in simple. <ins> The Registration Resource path is visible to any client that is allowed endpoint lookup, and can be extracted by resource lookup clients as well.  The same goes for registration attributes that are shown as target attributes or lookup attributes.  The RD needs to consider this in the choice of Registration Resource paths, and administrators or endpoint in their choice of attributes. </ins> 8.3. Access control SHOULD be performed separately for the RD registration Acknowledge that most discovery operations are not secured; mention consequences and mitigation. <ins> Add note about information in Registration Resource path. </ins> RDAO: Clarify that it is an option for RAs and not other ND messages.
Original text:
An update MAY update the lifetime or context registration parameters "lt", "con" as in registration ) if the previous settings are to be <del> retained.  Parameters that are not being changed changed SHOULD NOT be included in an update.  Adding parameters that have not changed </del>  increases the size of the message but does not have any other implications.  Parameters MUST be included as query parameters in an update operation as in registration.

Reviewer comments:
This PR fixes a simple typo. Side question: I found a number of lines in the markdown document that have spaces before the newline character. Would a PR removing those also be of interest?
Thanks! Re your side question: So I'm not the only person annoyed by trailing spaces :-) I went ahead and fixed this (one command in Emacs :-), including re-aligning a markdown table.

Revised text:
An update MAY update the lifetime or context registration parameters "lt", "con" as in registration ) if the previous settings are to be  <ins> retained.  Parameters that are not being changed SHOULD NOT be included in an update.  Adding parameters that have not changed </ins> increases the size of the message but does not have any other implications.  Parameters MUST be included as query parameters in an update operation as in registration.
Original text:
Luminary example: Explain example addresses  impl-info: Add note about the type being WIP Error handling: Place a SHOULD around the likely cases, and make

Reviewer comments:
The generated address failed to follow the guidance of RFC 3307 and set the first bit of the Group ID.
Since the example prefix is 2001:db8::/32 , I would assume the plen field is also set to 32, so we would get: ff35:20:2001:db8::8000:x Or is there a reason here to use plen=0x30 (48) bits ?
Throughout the examples, we use the third word to distinguish between separate logically distinct examples (2001:db8:1:: .. 2001:db8:4::), so it seemed logical to take a /48 for this example as well. (Although in keeping with the other appendix that uses 2001:db8:f0::, something like 2001:db8:e0::/48 and thus ff35:30:2001:db8:e0::1 would enhance consistency).
Ok, thanks - I see - so in example nr 4 the prefix 2001:db8:4/48 is used, then the mcast address would become ff35:30:2001:db8:4::8000:x right? If the ':4' is omitted it looks like a prefix 2001:db8/32 is being used.
The last commit on this series (c4d24f38342a6a6e0074a26dfd88db302b62d47c) now has something in the original addresses 3rd word (2001:db8:f1::/48) to make the choice of 30 in the prefix length more understandable, and for consistency.

Revised text:
Luminary example: Explain example addresses <ins> Multicast addresses in the examples were changed from ff35:30:2001:db8::x to ff35:30:2001:db8:f1::8000:x; the 8000 is to follow RFC 3307, and the f1 is for consistency with all the other example addresses where 2001:db8::/32 is subnetted to 2001:db8:x::/48 by groups of internally consistent examples. </ins> impl-info: Add note about the type being WIP Error handling: Place a SHOULD around the likely cases, and make
Original text:
Section 3.2.1).  The endpoint name MUST NOT contain any character in the inclusive ranges 0-31 or 127-159.  The maximum length of this parameter is 63 UTF-8 encoded bytes.  If the RD <del> is configured to recognize the endpoint (e.g. based on its security context), the RD assigns an endpoint name based on a set of configuration parameter values. </del>  Sector (optional).  The sector to which this endpoint belongs. When this parameter is not present, the RD MAY associate the <del> endpoint with a configured default sector or leave it empty. The sector is encoded like the ep parameter, and is limited to 63 UTF-8 encoded bytes as well.  The endpoint name and sector name are not set when one or both are set in an accompanying authorization token. </del>  Lifetime (optional).  Lifetime of the registration in seconds. Range of 1-4294967295.  If no lifetime is included in the Error handling: Place a SHOULD around the likely cases, and make the previous "MUST to the best of their capabilities" a "must".  changes from -24 to -25 Large rework of section 7 (Security policies)

Reviewer comments:
This also answers the repeated questions that were asked about conflicts between recognized and given ep names, and brings the wording in line with the more consistent application of the security glossary.

Revised text:
Section 3.2.1).  The endpoint name MUST NOT contain any character in the inclusive ranges 0-31 or 127-159.  The maximum length of this parameter is 63 UTF-8 encoded bytes.  If the RD  <ins> is configured to recognize the endpoint to be authorized to use exactly one endpoint name, the RD assigns that name.  In that case, giving the endpoint name becomes optional for the client; if the client gives any other endpoint name, it is not authorized to perform the registration. </ins> Sector (optional).  The sector to which this endpoint belongs. When this parameter is not present, the RD MAY associate the  <ins> endpoint with a configured default sector (possibly based on the endpoint's authorization) or leave it empty.  The sector is encoded like the ep parameter, and is limited to 63 UTF-8 encoded bytes as well. </ins> Lifetime (optional).  Lifetime of the registration in seconds. Range of 1-4294967295.  If no lifetime is included in the Error handling: Place a SHOULD around the likely cases, and make the previous "MUST to the best of their capabilities" a "must". <ins> Registration: Wording around "mostly mandatory" has been improved, conflicts clarified and sector default selection adjusted. </ins> changes from -24 to -25 Large rework of section 7 (Security policies)
Original text:
This and the following sections define the required set of REST interfaces between an RD, endpoints and lookup clients.  Although the examples throughout these sections assume the use of CoAP RFC7252, <del> these REST interfaces can also be realized using HTTP RFC7230.  Only multicast discovery operations are not possible on HTTP, and Simple Registration cannot be executed as the base attribute (which is mandatory for HTTP) cannot be used there.  In all definitions in these sections, both CoAP response codes (with dot notation) and HTTP response codes (without dot notation) are shown.  An RD implementing this specification MUST support the discovery, registration, update, lookup, and removal interfaces. </del>  All operations on the contents of the RD MUST be atomic and idempotent.

Reviewer comments:
The previous sentence was barely readable. Details were removed as they are obvious (multicast) or already mentioned in the respective section (simple registration).

Revised text:
This and the following sections define the required set of REST interfaces between an RD, endpoints and lookup clients.  Although the examples throughout these sections assume the use of CoAP RFC7252,  <ins> these REST interfaces can also be realized using HTTP RFC7230.  The multicast discovery and simple registration operations are exceptions to that, as they rely on mechanisms unavailable in HTTP.  In all definitions in these sections, both CoAP response codes (with dot notation) and HTTP response codes (without dot notation) are shown. An RD implementing this specification MUST support the discovery, registration, update, lookup, and removal interfaces. </ins> All operations on the contents of the RD MUST be atomic and idempotent.
Original text:
3.6. Home and commercial building automation systems can benefit from the <del> use of M2M web services.  The discovery requirements of these </del>  applications are demanding.  Home automation usually relies on run- time discovery to commission the system, whereas in building automation a combination of professional commissioning and run-time Two phases can be discerned for a network servicing the system: (1) installation and (2) operation.  During the operational phase, the <del> network is connected to the Internet with a Border router (6LBR) and the nodes connected to the network can use the Internet services that are provided by the Internet Provider or the network administrator. During the installation phase, the network is completely stand-alone, no 6LBR is connected, and the network only supports the IP </del>  communication between the connected nodes.  The installation phase is usually followed by the operational phase.  As an RD's operations work without hard dependencies on names or addresses, it can be used "coap://[MCD1]/.well-known/core?rt=core.rd*".  RDs within the multicast scope will answer the query. <del> When answering a multicast request directed at a link-local address, </del>  the RD may want to respond from a routable address; this makes it easier for registrants to use one of their own routable addresses for registration.

Reviewer comments:
Use case HA/BA: Expand and reference term "6LBR" Use case HA/BA: Use term 'IoT' that's more common in that area these days

Revised text:
3.6. Home and commercial building automation systems can benefit from the  <ins> use of IoT web services.  The discovery requirements of these </ins> applications are demanding.  Home automation usually relies on run- time discovery to commission the system, whereas in building automation a combination of professional commissioning and run-time Two phases can be discerned for a network servicing the system: (1) installation and (2) operation.  During the operational phase, the  <ins> network is connected to the Internet with a Border Router (e.g. a 6LoWPAN Border Router (6LBR), see RFC6775) and the nodes connected to the network can use the Internet services that are provided by the Internet Provider or the network administrator.  During the installation phase, the network is completely stand-alone, no Border Router is connected, and the network only supports the IP </ins> communication between the connected nodes.  The installation phase is usually followed by the operational phase.  As an RD's operations work without hard dependencies on names or addresses, it can be used "coap://[MCD1]/.well-known/core?rt=core.rd*".  RDs within the multicast scope will answer the query.  <ins> When answering a multicast request directed at a link-local group, </ins> the RD may want to respond from a routable address; this makes it easier for registrants to use one of their own routable addresses for registration.
Original text:
9.2. This document registers one new ND option type under the sub-registry <del> "IPv6 Neighbor Discovery Option Formats": </del>  Resource Directory Address Option (TBD38)

Reviewer comments:
rather than only referring to the subregistry's name See-Also: URL I concur with my colleagues who commended the authors for making the document very readable. I support Roman's first two DISCUSS points. In Section 9.2, you might want to mention that you're talking about a sub-registry under "Internet Control Message Protocol version 6 (ICMPv6) Parameters". In Section 9.3, you enumerate six fields in each registration, but the initial table of entries has only five columns. It's obvious (I think) that the sixth column would be "this document" for all entries, but I suggest that you should either include the column or some prose making this explicit (since everything else is).

Revised text:
9.2. This document registers one new ND option type under the sub-registry  <ins> "IPv6 Neighbor Discovery Option Formats" of the "Internet Control Message Protocol version 6 (ICMPv6) Parameters" registry: </ins> Resource Directory Address Option (TBD38)