Subject: [apps-discuss] [Editorial Errata Reported] RFC7386 (4132)

From: RFC Errata System <[email-masked]>
Date: Wed, 15 Oct 2014 11:37:52 -0700 (PDT)

The following errata report has been submitted for RFC7386,
"JSON Merge Patch".

--------------------------------------
You may review the report below and at:
http://www.rfc-editor.org/errata_search.php?rfc=7386&eid=4132

--------------------------------------
Type: Editorial
Reported by: Stéphane Bortzmeyer <[email-masked]>

Section: 2

Original Text
-------------
define MergePatch(Target, Patch):
       if Patch is an Object:
         if Target is not an Object:
       Target = {} # Ignore the contents and set it to an empty Object
         for each Name/Value pair in Patch:
       if Value is null:
         if Name exists in Target:
           remove the Name/Value pair from Target
       else:
         Target[Name] = MergePatch(Target[Name], Value)
         return Target
       else:
         return Patch

Corrected Text
--------------
   define MergePatch(Target, Patch):
     if Patch is an Object:
       if Target is not an Object:
         Target = {} # Ignore the contents and set it to an empty Object
       for each Name/Value pair in Patch:
         if Value is null:
           if Name exists in Target:
             remove the Name/Value pair from Target
         else:
           Target[Name] = MergePatch(Target[Name], Value)
       return Target
     else:
       return Patch

Notes
-----
Indentation of the pseudo-code example was correct in the Internet-Drafts but was  messed up in the final version. For instance, "Target = {}" should be under the two ifs. (Reported by James H. Manger on the appsawg mailing list.)

Instructions:
-------------
This erratum is currently posted as "Reported". If necessary, please
use "Reply All" to discuss whether it should be verified or
rejected. When a decision is reached, the verifying party (IESG)
can log in to change the status and edit the report, if necessary. 

--------------------------------------
RFC7386 (draft-ietf-appsawg-json-merge-patch-07)
--------------------------------------
Title               : JSON Merge Patch
Publication Date    : October 2014
Author(s)           : P. Hoffman, J. Snell
Category            : PROPOSED STANDARD
Source              : Applications Area Working Group
Area                : Applications
Stream              : IETF
Verifying Party     : IESG

---

From: "Manger, James" <[email-masked]>
Date: Thu, 16 Oct 2014 10:06:37 +1100

Thanks for reporting this as an errata Stephane. "Editorial" is the wrong classification however; it is "Technical". The indentation is critical to understanding the function. The function isn't merely to reinforce normative text -- the function is the only normative specification of the Merge-Patch processing rules. The other text only gives a casual description of some rules (in the introduction), calls attention to some corner cases, and provides examples.

If the RFC editors cannot correct the indentation, we need a new RFC.
Personally I don't think an accepted errata is sufficient. The doc is too unusable in its current state.
Can this sort of critical typo be fixed without a new RFC number?

P.S. Curiously, the "Diff2" format on tools.ietf.org [https://tools.ietf.org/rfcdiff?url2=rfc7386] shows the indentation as being correct in rfc7386.txt and draft-ietf-appsawg-json-merge-patch-07. Probably a tools glitch.

--
James Manger

-----Original Message-----
From: apps-discuss [mailto:[email-masked]] On Behalf Of RFC Errata System
Sent: Thursday, 16 October 2014 5:38 AM
To: [email-masked]; [email-masked]; [email-masked]; [email-masked]; [email-masked]; [email-masked]
Cc: [email-masked]; [email-masked]
Subject: [apps-discuss] [Editorial Errata Reported] RFC7386 (4132)

The following errata report has been submitted for RFC7386, "JSON Merge Patch".

--------------------------------------
Type: Editorial
Reported by: StÃ©phane Bortzmeyer <[email-masked]>

Section: 2

Original Text
-------------

Corrected Text
--------------

Notes
-----

Instructions:
-------------
This erratum is currently posted as "Reported". If necessary, please use "Reply All" to discuss whether it should be verified or rejected. When a decision is reached, the verifying party (IESG) can log in to change the status and edit the report, if necessary.

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 16 Oct 2014 01:39:37 +0200

(Trimming cc list:)

This is now also
http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/276

Grüße, Carsten

On 16 Oct 2014, at 01:16, Carsten Bormann <[email-masked]> wrote:

> On 16 Oct 2014, at 01:06, Manger, James <[email-masked]> wrote:
> 
> This looks like the canonical tab-width confusion.
> The correct text had a tab-width of 8, but the RFC text was converted to spaces applying a tab-width of 4.
> 
> Yep, the copy of rfc7386.xml I have has been tabified, while draft-ietf-appsawg-json-merge-patch-07.xml is clean.
> 
> NEVER, EVER, tabify documents.
> THROW OUT ALL TOOLS THAT DO THIS.
> (Sorry for shouting, but this TAB nonsense has cost too much time in my life already.)
> 
> Grüße, Carsten
> 
> 
>

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 16 Oct 2014 01:51:07 +0200

> Yep, the copy of rfc7386.xml I have has been tabified, while draft-ietf-appsawg-json-merge-patch-07.xml is clean.

One more data point: Appendix A has *not* been tabified (and thus is the only artwork that isn’t munged).  There are also lines of XML in the front matter (James’ email address, abstract) that haven’t been tabified (which has no consequence either way).

Grüße, Carsten

---

From: Barry Leiba <[email-masked]>
Date: Thu, 16 Oct 2014 10:53:20 -0400

I will mark the report as Verified (and will change it to Technical), but
there is no way to have the RFC fixed without a new RFC that obsoletes it.
This is all stuff that should be checked in AUTH48, and is why the RFC
Editor recommends not relying only on the diff.

James, if you want to get it updated tout de suite, you can submit a
7386bis draft, which I will immediately last call.  To do the draft, get
the final 7386.xml from the RFC Editor, add an "obsoletes=7386" at the top
(and take off the special RFC Editor attributes), make sure all the tabs
are replaced by spaces and everything lines up correctly, and add a
paragraph to the Abstract and Introduction that says that this is a
replacement to RFC 7386 that corrects indentation errors.  Make no other
changes, and I'll note in the last call note that no other changes are in
scope.

The replacement RFC will have a new RFC number.

Barry

On Wednesday, October 15, 2014, Manger, James <
[email-masked]> wrote:

> Thanks for reporting this as an errata Stephane. "Editorial" is the wrong
> classification however; it is "Technical". The indentation is critical to
> understanding the function. The function isn't merely to reinforce
> normative text -- the function is the only normative specification of the
> Merge-Patch processing rules. The other text only gives a casual
> description of some rules (in the introduction), calls attention to some
> corner cases, and provides examples.
>
> P.S. Curiously, the "Diff2" format on tools.ietf.org [
> https://tools.ietf.org/rfcdiff?url2=rfc7386] shows the indentation as
> being correct in rfc7386.txt and draft-ietf-appsawg-json-merge-patch-07.
> Probably a tools glitch.
>
> --
> James Manger
>
>
> From: apps-discuss [mailto:[email-masked] <javascript:;>]
> On Behalf Of RFC Errata System
> To: [email-masked] <javascript:;>; [email-masked] <javascript:;>;
> [email-masked] <javascript:;>; [email-masked]
> <javascript:;>; [email-masked] <javascript:;>;
> [email-masked] <javascript:;>
> Cc: [email-masked] <javascript:;>; [email-masked]
> <javascript:;>
> Reported by: StÃ©phane Bortzmeyer <[email-masked] <javascript:;>>
>
> Section: 2
>
> Original Text
> -------------
> Indentation of the pseudo-code example was correct in the Internet-Drafts
> but was  messed up in the final version. For instance, "Target = {}" should
> be under the two ifs. (Reported by James H. Manger on the appsawg mailing
> list.)
>
> Instructions:
> -------------
> This erratum is currently posted as "Reported". If necessary, please use
> "Reply All" to discuss whether it should be verified or rejected. When a
> decision is reached, the verifying party (IESG) can log in to change the
> status and edit the report, if necessary.
>

---

From: Tim Bray <[email-masked]>
Date: Thu, 16 Oct 2014 07:57:50 -0700

Yep, what Barry said; this one needs to be re-issued under a new number.

On Thu, Oct 16, 2014 at 7:53 AM, Barry Leiba <[email-masked]> wrote:
> James, if you want to get it updated tout de suite, you can submit a 7386bis
> draft, which I will immediately last call.  To do the draft, get the final
> 7386.xml from the RFC Editor, add an "obsoletes=7386" at the top (and take
> off the special RFC Editor attributes), make sure all the tabs are replaced
> by spaces and everything lines up correctly, and add a paragraph to the
> Abstract and Introduction that says that this is a replacement to RFC 7386
> that corrects indentation errors.  Make no other changes, and I'll note in
> the last call note that no other changes are in scope.
>
> On Wednesday, October 15, 2014, Manger, James
> <[email-masked]> wrote:
>>
>> understanding the function. The function isn't merely to reinforce normative
>> text -- the function is the only normative specification of the Merge-Patch
>> processing rules. The other text only gives a casual description of some
>> rules (in the introduction), calls attention to some corner cases, and
>> provides examples.
>>
>> P.S. Curiously, the "Diff2" format on tools.ietf.org
>> [https://tools.ietf.org/rfcdiff?url2=rfc7386] shows the indentation as being
>> correct in rfc7386.txt and draft-ietf-appsawg-json-merge-patch-07. Probably
>> a tools glitch.
>>
>> --
>> James Manger
>>
>>
>> To: [email-masked]; [email-masked]; [email-masked];
>> [email-masked]; [email-masked]; [email-masked]
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

-- 
- Tim Bray (If you’d like to send me a private message, see
https://keybase.io/timbray)

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 16 Oct 2014 01:16:59 +0200

Grüße, Carsten

---

From: Paul Hoffman <[email-masked]>
Date: Fri, 17 Oct 2014 07:07:39 -0700

On Oct 16, 2014, at 7:53 AM, Barry Leiba <[email-masked]> wrote:

> I will mark the report as Verified (and will change it to Technical), but there is no way to have the RFC fixed without a new RFC that obsoletes it.  This is all stuff that should be checked in AUTH48, and is why the RFC Editor recommends not relying only on the diff.

I will investigate when the changes happened, and how. I can believe I missed the changes, but I can also believe that they were introduced after the AUTH48 review that James and I did.

> James, if you want to get it updated tout de suite, you can submit a 7386bis draft, which I will immediately last call.  

Barry: this feels terribly inappropriate. We don't need a third author on the draft to make this one change. James and I can do it.

--Paul Hoffman

---

From: Barry Leiba <[email-masked]>
Date: Fri, 17 Oct 2014 10:37:41 -0400

>
> I will investigate when the changes happened, and how. I can believe I
> missed the changes, but I can also believe that they were introduced after
> the AUTH48 review that James and I did.

Certainly possible.  It's hard to tell, because there's no iterative record
of the versions during and after AUTH48.

> 7386bis draft, which I will immediately last call.
>
> Barry: this feels terribly inappropriate. We don't need a third author on
> the draft to make this one change. James and I can do it.
>

Of course you're right about that.  I was just confused about which James
was which -- I'm travelling, iPad only, and didn't look closely enough at
who the 7386 authors are.  So, yes, of course one of the 7386 authors
should do this, not James Manger.

Barry

---

From: RFC Editor <[email-masked]>
Date: Fri, 17 Oct 2014 09:44:34 -0700

Greetings All,

We've been investigating how this error crept in on our end so we can
explain and understand how to avoid a similar issue in the future.
After reviewing the files and running a copy of the .xml through
xml2rfc,  we think there may be an error with xml2rfc.  

In the XML file we have archived, we see the following:

<figure><artwork>                                                                            
</artwork></figure>

which produces the following text:

and also produces the following .nroff:

We believe Carsten has submitted a ticket to have this corrected; see
<http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/276>.   Until a
fix has been implemented, we will be careful to checkthe indentation
of artwork.

Thank you,
RFC Editor/sg

---

From: Pete Resnick <[email-masked]>
Date: Fri, 17 Oct 2014 11:48:37 -0500

On 10/16/14 9:53 AM, Barry Leiba wrote:
> To do the draft, get the final 7386.xml from the RFC Editor, add an 
> "obsoletes=7386" at the top (and take off the special RFC Editor 
> attributes), make sure all the tabs are replaced by spaces and 
> everything lines up correctly, and add a paragraph to the Abstract and 
> Introduction that says that this is a replacement to RFC 7386 that 
> corrects indentation errors.  Make no other changes, and I'll note in 

There are examples where the spacing also go screwed up. I hope you 
didn't mean to put those into the "no other changes" category.

pr

-- 
Pete Resnick<http://www.qualcomm.com/~presnick/>
Qualcomm Technologies, Inc. - +1 (858)651-4478

---

From: Barry Leiba <[email-masked]>
Date: Fri, 17 Oct 2014 12:52:58 -0400

No: I meant to correct all the indentation/spacing issues, but only those.

On Friday, October 17, 2014, Pete Resnick <[email-masked]> wrote:

>> attributes), make sure all the tabs are replaced by spaces and everything
>> lines up correctly, and add a paragraph to the Abstract and Introduction
>> that says that this is a replacement to RFC 7386 that corrects indentation
>> errors.  Make no other changes, and I'll note in the last call note that no
>> other changes are in scope.
>>
>
> There are examples where the spacing also go screwed up. I hope you didn't
> mean to put those into the "no other changes" category.
>
> pr
>
> --

---

From: John C Klensin <[email-masked]>
Date: Fri, 17 Oct 2014 14:11:15 -0400

--On Friday, October 17, 2014 09:44 -0700 RFC Editor
<[email-masked]> wrote:

> We've been investigating how this error crept in on our end so
> we can explain and understand how to avoid a similar issue in
> the future. After reviewing the files and running a copy of
> the .xml through xml2rfc,  we think there may be an error with
> xml2rfc.  
>...

> the last call note that no other changes are in scope.

Folks,

I don't know whether it is less painful to do a narrow Last Call
or to risk opening a can of worms, but my recollection is that
there have been a few times in which the RFC Editor has simply
issued a replacement document with a new number to correct
editing or formatting problems with the earlier document.  The
principle that justified that action would seem to apply here,
so maybe the right solution is Just Do It with the "Obsoletes"
field as above and a status note from the RFC Editor explaining
the change.  No need to waste community or IESG time on a
vacuous LC and the further advantage of getting the replacement
document up a lot sooner.

I also observe that 7386 appears to be the highest-numbered RFC
issued to date.  If other things are not already well along in
the pipe, it would be nice to reserve 7387 for this revised
version, leaving them consecutive in various indices.

     john

p.s. to RFC Editor: you can incorporate several years of
comments about the use of generic markup (e.g., xml2rfc) as a
final formatting specification in lieu of observations about the
causes and history of this problem.

---

From: Pete Resnick <[email-masked]>
Date: Fri, 17 Oct 2014 13:52:28 -0500

> document up a lot sooner.

We have done it once recently, with RFC 7158/7159, so I wouldn't be 
opposed to doing so in this case. There is a small tooling issue in that 
the datatracker doesn't have history on the latter RFC, but I suspect 
that's something that the tools team can fix at some point.

Barry should make the call on this, but I'm OK with the idea.

pr

---

From: Barry Leiba <[email-masked]>
Date: Fri, 17 Oct 2014 14:57:55 -0400

Yes, OK by me as well: Sandy, can you guys fix this, with a check by the
authors?

Barry

---

From: Julian Reschke <[email-masked]>
Date: Fri, 24 Oct 2014 08:27:36 +0200

> (Sorry for shouting, but this TAB nonsense has cost too much time in my life already.)

For the record, I see at least two RFCs in AUTH48 with HTAB characters: 
RFC 7390 and 7391 (reminder: there's an Atom feed with validation 
results: <http://greenbytes.de/tech/tc/xml2rfc/rfcdiags.atom>).

Best regards, Julian

---

From: John C Klensin <[email-masked]>
Date: Fri, 24 Oct 2014 08:28:07 -0400

(RFC Errata system address removed -- this is not an errata
issue)

--On Friday, October 24, 2014 08:27 +0200 Julian Reschke
<[email-masked]> wrote:

>> Yep, the copy of rfc7386.xml I have has been tabified, while
>> draft-ietf-appsawg-json-merge-patch-07.xml is clean.
>> 
>> (Sorry for shouting, but this TAB nonsense has cost too much
>> time in my life already.) ...
> 
> For the record, I see at least two RFCs in AUTH48 with HTAB
> characters: RFC 7390 and 7391 (reminder: there's an Atom feed
> with validation results:
> <http://greenbytes.de/tech/tc/xml2rfc/rfcdiags.atom>).

Folks, regardless of what the IESG and posting tools choose to
allow in I-Ds, it would be extremely simple to direct the RFC
Production Center to remove all tabs from documents as part of
their processing and then verify that the results look
reasonable before documents are handed back to authors, etc., at
AUTH48.  It would also be easy for them to add a note about
checking formatting on the possibly de-tabbed documents to their
AUTH48 instructions to authors and, with only a tad more work,
to include that instruction only if there were tabs in the I-D
that came to them for processing.

While it would impose more burden on authors, it would be easier
yet (and at least equally effective) for the RFC Editor Function
to require that documents not contain tabs when they were
submitted for publication, to perform a very simple check, and
to bounce the documents back to the submitting Stream if one or
more tabs were present.

If you believe any of those things are important, take it up
with the RSE (copied on at least the last few of these notes)
and/or on the rfc-interest list.   If you don't get the results
you like, take it up with the IAB.

It would only affect some I-Ds, but a suggestion that XML2RFC
might generate warnings if tabs appeared, either at all or in
artwork or equivalent might help too.  Or one could suggest that
the posting tools at least warn if tabs are present in their
initial nits check.  For those suggestions, talk with the tools
team and/or the IESG.

But, at least IMO, continuing to kick this particular horse, of
already dubious viability, on the apps-discuss list is a waste
of time and distracts from topics that are actually in the Apps
Area critical path.

    john

---

From: Paul Hoffman <[email-masked]>
Date: Fri, 24 Oct 2014 07:44:59 -0700

On Oct 24, 2014, at 5:28 AM, John C Klensin <[email-masked]> wrote:
> AUTH48.  

Note that, for the RFC in question, the tabs were inserted by the RFC Production Center. Thus, "directing" them to do something will require more care all around.

--Paul Hoffman

---

From: t.petch <[email-masked]>
Date: Fri, 24 Oct 2014 17:58:29 +0100

----- Original Message -----
From: "Julian Reschke" <[email-masked]>
To: "Carsten Bormann" <[email-masked]>; "Manger, James"
<[email-masked]>
Cc: <[email-masked]>; "RSE" <[email-masked]>
Sent: Friday, October 24, 2014 7:27 AM
> >> P.S. Curiously, the "Diff2" format on tools.ietf.org
[https://tools.ietf.org/rfcdiff?url2=rfc7386] shows the indentation as
being correct in rfc7386.txt and draft-ietf-appsawg-json-merge-patch-07.
Probably a tools glitch.
> > The correct text had a tab-width of 8, but the RFC text was
converted to spaces applying a tab-width of 4.
> results: <http://greenbytes.de/tech/tc/xml2rfc/rfcdiags.atom>).

This scratches my itch.

A long time ago, I downloaded RFC2328 (OSPF v2) but found that any
utility I used to view it produced a mess, hard to use in any way.  I
eventually looked at the binary and found that it was riddled with tab
characters.  I downloaded it several times from different sites, using
FTP, with the same result.  I tried all the combinations I could think
of for tab settings to no avail.  (Interestingly, using IE now to access
the
web site gives a reasonable display).

I eventually gave up (on OSPF that is:-)

I notice that the last modified date for this RFC is 1998 on the web
site so things would appear not to have changed.  Well, RFCs are never
changed no matter what:-(

Tom Petch