Subject: Comments on draft-roach-bis-documents-00

From: David Noveck <[email-masked]>
Date: Fri, 10 May 2019 19:31:45 -0400

First of all, I'd like to thank you for writing this document.   Magnus
Westerlund brought it to my attention in connection with my attempt to
provide an updated explanation of the multi-server namespace features of
NFSv4.1 (with draft-nfsv4-ietf-mv1-msns-update and then
draft-ietf-nfsv4-rfc5661-msns-update).  It seems to me that your document
provides a good model to present an updated description of NFSv4.1 without
having to deal with NFSv4's lingering security deficits which are pretty
orthogonal to the multi-server namespace features which require revisions
to deal with trunking and transparent state migration.

I have a couple of issues with the doument that I'd like to bring to your
attention.   They concern the use of the term "bis documents" and some
apparent assumptions about how easy/diffcult it might be to get to a usable
base document to which desirted cghanges might be made.  Details below.

The first issue has to do with terminology, specfically your use of the
term "bis documents".    Since I anticipate a non-major update to NFSv4.1
using your procedure and also a later major update, I'm particularly
focused on that distinction and feel it would be wrong to obscure it, since
both your form of document, (to effect non-major revisions) as well as the
sort of bis documents that the NFSv4 working group has on rare occasions
been doing, will continue to exist even though the former are likely to
greatly outnumber the latter.

Specfically I feel that your use of the followng phrase in the
Abstract: "updated
procedure for publishing newer versions (colloquially known as 'bis
versions')" should be changed for the following reasons:

   - It ibscures the important distinction between mahor and non-major
   updates.
   - Different working groups use this term in different ways.   For may
   working groups, such as the NFSv4 working group, bis documents are rarely
   done and limited to major updates.   While other groups may have different
   experiences, it really doesn't make sense to build your document around an
   approach to terminology that is not universal
   - It has the unfortunate effect of obscuring what you have done, which
   is provide a way to do something desirable, that had not been possible
   before.  Instead, it treats your work as merely providing a new procedure
   for doing something that has been done all along.  In fact, the procedure
   for making major updates remains as it was, while you have provided a
   usable procedure for doing something that has, practically speaking, for
   many working groups, not been possible before, i.e. as your title
   indicates, it provides "A Process for Handling Non-Major Revisions to
   Existing RFCs"

I'd like to suggest the following changes:

   - Replace the second clause of the first sentence of the abstract by
   "presents a procedure for publishing newer versions of existing RFCs that
   is appropiate when major changes are not being made to an existing
   specfication".
   - Replace the second sentence of the abstract by "This procedure, which
   produces a document whose form is quite similar to that of existing bis
   documents, is expected to be easier for both authors and consumers of RFCs.
   - Add the following as a new first paragrph to section 3:

The process of producing revised versions is designed to allow the
production of revised documents, each of which will constitute a complete
replacement for the updated document in a fashiion similar to that which
has been used for bis documents.   Sections not affected by the updates to
be made will be reproduced unchanged.

   - In the existing first sentence of Section 3, replace  " At a high
   level, the process described in this document allows bis versions of
   documents" by "This process allows revised versions of existing RFCs"
   - Replace subsequent uses of the phrase "the process described in this
   document" by "the process of producing revised versions"
   - Delete Section 4.

The other set of issuues has to do with the document's assumption that one
could start with a document identical to the base rfc, and make only the
desired changes, considering all other changes as "spurious".   I have some
experience trying to produce the framework for an rfc5661bis (making a
major respecfication of the protocol, i.e. a "true bis document" as I would
have it) and I've seen a number of difficulties in which diffs will show,
for various reasons, differences between rfc5661 and any reasonably
possible base document.   Let me tell you my experiences.  I'll try not to
sound whiny but it may be unavoidable:

   - First of all .xml files for rfcs are not routinely kept, although they
   should be.  I'm not sure how to get that to change or exactly how it might
   affect your document but it is certainly relevant to what you want to do.
   - I was able to get a .xml file for rfc5661, somehow, from the RFC
   editor.
   - I found that xml2rfc would not process it successfully.   It took
   consideable work to get a file xml2rfc would process successfully.

Apparently an .xml file used to prodtce an rfc is not necessarily
acceptable to later versions of xml2rfc.  You can get an idea of the issues
by looking at rc5661Base.xml and the file I wound up with,
rfc5661Ready.xml; both are attached.

I was able to get a an .xml from which a .txt file could be generated, but
despite my best efforts there were differences (more than a few) between it
and rfc5661, which your document would consider to be "spurious" but appear
to be unavoidable. In any case they are not gratuitous changes and should
not interfere with consideration of the document.   The majority of the
diffs arise from the following  issues:

   - Despite the fact that the xml for the reference sections of both xml
   files are identical and the processing options are identical (symrefs="no"
   sortrefs="yes") the reference ids in rfc5661Ready.txt and in rfc5661 are
   different so that rfcdiff shows every line containing a reference as part
   of a diff.  Apparently, different versions of xml2rfc use different
   approaches to sorting references.
   - There are a fair number of difference that seem to have arisen because
   the RFC edtitor made minor corrections directly on the .txt file so that
   each such correction (while valid) is reported by rfcdiiff as a difference.
   - The reference sections are exposed to the same sorting issues as the
   reference id's.  To the naked eye, and to rfcdiff they look very different,
   despite that fact that they contain the same references.

To top it all off, it seems that there is a bug in rfcdiff.  it appears to
get confused, not report diffs in the reference and, fairly late in the
document start reporting major differences that dont exist.  Sigh!

I'm not sure exactly how to deal with all these these issues in your
document but I think that it is necessary to rethink item 3 in the
qualification list in section 3.1.   Even without these specific issues, it
seem unduly harsh to me to have any such difference foreclose consideration
of a document under your procedure.   There would be room for criteria
rejecting gratuitous changes as part of the process, even fairly strict
ones.  In any case, I don't feel that denying acess to the process totally
is right particularly in light of the kind of issues I've run up against.
:-(

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 11 May 2019 08:10:03 +0200

Hi David,

Thank you for your article in [email-masked], it is really a little treasure-trove.

Let me extract those parts that pertain to your experiences with the evolution of RFCXML and add rfc-interest; please continue discussion on rfc-interest (which you may want to subscribe if RFC authoring is part of your life).

> On May 11, 2019, at 01:31, David Noveck <[email-masked]> wrote:
> 
> Apparently an .xml file used to prodtce an rfc is not necessarily acceptable to later versions of xml2rfc.  You can get an idea of the issues by looking at rc5661Base.xml and the file I wound up with, rfc5661Ready.xml; both are attached.

Most of your changes have to do with the better validation in the current tools, namely:

— validating the syntax of anchors (no spaces, plus signs)
— validating artwork.

For the latter, doing a wholesale <![CDATA[ … ]]> is always a better approach than sprinkling &amp;/&lt; (you almost never need &gt;, by the way).  (See also authoring tools below.)

The anchor syntax — it is just too bad the v1 tool didn’t check that.  

> I was able to get a an .xml from which a .txt file could be generated, but despite my best efforts there were differences (more than a few) between it and rfc5661, which your document would consider to be "spurious" but appear to be unavoidable. In any case they are not gratuitous changes and should not interfere with consideration of the document.   The majority of the diffs arise from the following  issues:
> 	• Despite the fact that the xml for the reference sections of both xml files are identical and the processing options are identical (symrefs="no" sortrefs="yes") the reference ids in rfc5661Ready.txt and in rfc5661 are different so that rfcdiff shows every line containing a reference as part of a diff.  Apparently, different versions of xml2rfc use different approaches to sorting references. 

Protip: DO NOT USE numeric references.  Ever.  This was stylistically appealing for some tiny documents, but rarely is appropriate for actual specifications (and certainly not for NFSv4-sized ones!).

> 	• There are a fair number of difference that seem to have arisen because the RFC edtitor made minor corrections directly on the .txt file so that each such correction (while valid) is reported by rfcdiiff as a difference.

Right.  That will be less of a problem in the future, but it does require tediously porting back changes to the document source.  

> 	• The reference sections are exposed to the same sorting issues as the reference id's.  To the naked eye, and to rfcdiff they look very different, despite that fact that they contain the same references.

The sorting issue should be taken care of by not using numeric references (really, for the sake of your readers, please don’t).
Since RFC 5661, we also got DOIs on RFCs, so it is inevitable there are a lot of diffs.  Again, tedious, but not really avoidable.

Of course, I would not recommend directly authoring in XML these days (there are now good markdown and asciidoc choices, as well as an org-mode one if that is your thing), but that was the way things were done in 2010.  (If you do want to make the transition, there are some conversion tools available; I may be able to help.)

Grüße, Carsten

---

From: David Noveck <[email-masked]>
Date: Sun, 12 May 2019 11:11:22 -0400

>> Apparently an .xml file used to prodtce an rfc is not necessarily
acceptable to later versions of xml2rfc.

> Most of your changes have to do with the better validation in the current
tools, namely:

At least more extensive validation.

> — validating the syntax of anchors (no spaces, plus signs)

It is not clear to me, given that anchors are always in quotes, why these
restrictions were added

In any case, they were added with no concern about the fact that many
existing .xml files would be invalidated.  I hope future instances of such
changes can be avoided.

> — validating artwork.

Artwork, by its nature, does not need to be validated.  I really don't want
xml2rfc warnings about the quality of my artwork :-)

However, changes in the processing of character entities within artwork has
given rise to unxpected rejections of existing xml files :-(

> For the latter, doing a wholesale <![CDATA[ … ]]> is always a better
approach than sprinkling &amp;/&lt;

That's good advice which the nfsv4 working group would do well to follow
for future RFC's.

As our RFC's often have lots of XDR, it is all too easy for a case of
amper-lt/amper-gt dysphoria to develop (not in the DSM :-)

> (you almost never need &gt;, by the way).  (See also authoring tools
below.)

If it's *almost* never, my tendency would be to use it always, just in case.

> The anchor syntax — it is just too bad the v1 tool didn’t check that.

Since we can't go back in time and change the v1 tool, a better way to
provide compatibility would be for the existing tool to get a processing
option, allowing it to accept formerly acceptable anchors that have been
forbidden in recent times.

> > I was able to get a an .xml from which a .txt file could be generated,
but despite my best efforts there were differences (more than a few)
between it and rfc5661, which your document would consider to be "spurious"
but appear to be unavoidable. In any case they are not gratuitous changes
and should not interfere with consideration of the document.   The majority
of the diffs arise from the following  issues:
> >       • Despite the fact that the xml for the reference sections of
both xml files are identical and the processing options are identical
(symrefs="no" sortrefs="yes") the reference ids in rfc5661Ready.txt and in
rfc5661 are different so that rfcdiff shows every line containing a
reference as part of a diff.  Apparently, different versions of xml2rfc use
different approaches to sorting references.

> Protip: DO NOT USE numeric references.  Ever.

Good advice, but we need to deal with the fact imappropriate choices were
made in the past and incorporated published RFCs.

> This was stylistically appealing for some tiny documents, but rarely is
appropriate for actual specifications (and certainly not for NFSv4-sized
ones!).

I'm not sure how this choice came to be.   The actual .xml file was
generated by make and I don't think anybody really paid attention to the
processing instructions which were fixed early on and never really
reconsidered.

>>       • There are a fair number of difference that seem to have arisen
because the RFC edtitor made minor corrections directly on the .txt file so
that each such correction (while valid) is reported by rfcdiiff as a
difference.

> Right.  That will be less of a problem in the future,

I hope so.  Why do you think that this will be getting better?

> but it does require tediously porting back changes to the document
source.

Yes :-(

> >       • The reference sections are exposed to the same sorting issues
as the reference id's.  To the naked eye, and to rfcdiff they look very
different, despite that fact that they contain the same references.

> The sorting issue should be taken care of by not using numeric references

I don't think it will be.   It will eliminate diffs due to different
numeric tags but the layout of the reference sections will be different,
which will show up as a diff.

I hope Adam's document would allow documents with such diffs to be
processed by his procedure.

> (really, for the sake of your readers, please don’t).

For RFC5661 and documents derived from it using Adam's procedure, that ship
has already sailed :-(.

However, when there is a full bis succeeeding RFC5661, not processed
according to Adam's procedure, it should not use numeric references :-)

> Since RFC 5661, we also got DOIs on RFCs, so it is inevitable there are a
lot of diffs.

It is not inevitable as shown by the fact that I didn't run into that
issue.   It's kind of nice to know that there was an issue out there that I
didn't run into :-)

For reasons I  really don't understand, the xml for rfc5661 does not
include rfc reference from external libraries.   It includes them inline,
so a new rfc derived from that xml  file will not include DOIs.   That is
not a problem for Adam's procedure, but it may be for the IESG or the RFC
editor.   I hope that, in processing RFC's using Adam's procedure, people
will overlook the lack of DOIs in the same way that they overlook other
aspects of the document that would prevent a new document of that form from
being published.

> Again, tedious, but not really avoidable.

In cases in which it is not avoidable, the addition of DOI's should not
prevent processing of a document acccording to Adam's procedure.

> Of course, I would not recommend directly authoring in XML these days

Why not?

> (there are now good markdown and asciidoc choices, as well as an org-mode
one if that is your thing),

Where are these documented?

> but that was the way things were done in 2010.

I'm prepared to stick with that, unless there is something better about the
alternatives.

> (If you do want to make the transition, there are some conversion tools
available; I may be able to help.)

I would only make a transition for new documents.

For documents to be processed according to Adam's procedure, the likelihood
of minor diffs arising is such that I don't think a transition is possible.

For a later full bis, I would be replacing major sections of an existing
xml-written document which would make any transition especially difficult.

For completely new documents,my concerns would be to make sure that the
needs of those who might later be called upon to update the document were
taken account of.   Relevant issues:

   - Could we be sure that the new source could be processed at a later
   time, and give rise to the same xml?
   - Would the xml produced by a new tool be easily human-editable?

On Sat, May 11, 2019 at 2:10 AM Carsten Bormann <[email-masked]> wrote:

> Let me extract those parts that pertain to your experiences with the
> evolution of RFCXML and add rfc-interest; please continue discussion on
> rfc-interest (which you may want to subscribe if RFC authoring is part of
> your life).
>
> For the latter, doing a wholesale <![CDATA[ … ]]> is always a better
> approach than sprinkling &amp;/&lt; (you almost never need &gt;, by the
> way).  (See also authoring tools below.)
>
> > I was able to get a an .xml from which a .txt file could be generated,
> but despite my best efforts there were differences (more than a few)
> between it and rfc5661, which your document would consider to be "spurious"
> but appear to be unavoidable. In any case they are not gratuitous changes
> and should not interfere with consideration of the document.   The majority
> of the diffs arise from the following  issues:
> >       • Despite the fact that the xml for the reference sections of both
> xml files are identical and the processing options are identical
> (symrefs="no" sortrefs="yes") the reference ids in rfc5661Ready.txt and in
> rfc5661 are different so that rfcdiff shows every line containing a
> reference as part of a diff.  Apparently, different versions of xml2rfc use
> different approaches to sorting references.
>
> Protip: DO NOT USE numeric references.  Ever.  This was stylistically
> appealing for some tiny documents, but rarely is appropriate for actual
> specifications (and certainly not for NFSv4-sized ones!).
>
> >       • There are a fair number of difference that seem to have arisen
> because the RFC edtitor made minor corrections directly on the .txt file so
> that each such correction (while valid) is reported by rfcdiiff as a
> difference.
>
> Right.  That will be less of a problem in the future, but it does require
> tediously porting back changes to the document source.
>
> >       • The reference sections are exposed to the same sorting issues as
> the reference id's.  To the naked eye, and to rfcdiff they look very
> different, despite that fact that they contain the same references.
>
> The sorting issue should be taken care of by not using numeric references
> (really, for the sake of your readers, please don’t).
> Since RFC 5661, we also got DOIs on RFCs, so it is inevitable there are a
> lot of diffs.  Again, tedious, but not really avoidable.
>
> Of course, I would not recommend directly authoring in XML these days
> (there are now good markdown and asciidoc choices, as well as an org-mode
> one if that is your thing), but that was the way things were done in 2010.
> (If you do want to make the transition, there are some conversion tools
> available; I may be able to help.)
>
> Grüße, Carsten
>
>

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 12 May 2019 18:16:34 +0200

> It is not clear to me, given that anchors are always in quotes, why these restrictions were added

RFC 2629 provides a DTD for RFCXML.  This enables XML-based tools to meaningfully process RFCXML.
In this DTD, anchors were supposed to be XML “ID” type strings.  Using non-conforming strings here created problems for some tools.  So the v1 tool’s overly enthusiastic “be liberal what you accept” wan’t really helpful.  This was fixed in v2.

> In any case, they were added with no concern about the fact that many existing .xml files would be invalidated.  

(It would have been easy to create a transition tool.  I have no idea why this wasn’t done — maybe people finished their work on existing v1 documents with the v1 tool, so the problem never occurred in practice.  Or it was simply too easy to fix by hand — I remember doing this for a few documents before I completely stopped using XML as an authoring format.)

> I hope future instances of such changes can be avoided.

Yes (preferably by following the specification in the first place, or by providing transition tools, as we’ll have for v2 to v3).
 
> > — validating artwork.
> 
> Artwork, by its nature, does not need to be validated.  

But it still needs to be encoded in well-formed XML — which requires CDATA or &amp; etc.
Again, the v1 tool was more “liberal” (broken) here than it should have been.

> Since we can’t go back in time and change the v1 tool, a better way to provide compatibility would be for the existing tool to get a processing option, allowing it to accept formerly acceptable anchors that have been forbidden in recent times.

A better option is to provide a migration tool, so previously invalid (and incorrectly accepted) input documents can be transformed into well-formed input documents that have the intended effect — these can then be processed by other XML-based tools as well.

[…]
> The actual .xml file was generated by make

That is actually a good way to generate a non-trivial document.
In many cases, today’s Makefiles generate markdown documents, or generate pieces that are then included from the main markdown document.  The Makefile then translates into XML whole-sale.

> I hope so.  Why do you think that this will be getting better?

With the move to v3, an XML document will be the main publication format.
(It still isn’t the same as that submitted by the authors, but I think one could continue authoring from that.)

> For RFC5661 and documents derived from it using Adam’s procedure, that ship has already sailed :-(.

As the references section needs to be updated anyway (for the DOIs), I’m not sure this is really true.  Or, if it is, RFC 5661 maybe isn’t really a candidate for this process, because it may be impractical to re-generate the exact numbering that RFC 5661 used.

> > Since RFC 5661, we also got DOIs on RFCs, so it is inevitable there are a lot of diffs.  
> 
> It is not inevitable as shown by the fact that I didn't run into that issue.   It's kind of nice to know that there was an issue out there that I didn't run into :-)
> 
> For reasons I  really don't understand, the xml for rfc5661 does not include rfc reference from external libraries.   It includes them inline, so a new rfc derived from that xml  file will not include DOIs.  

Yes.  All these RFC references would be updated by the RFC editor into current references.

> That is not a problem for Adam's procedure, but it may be for the IESG or the RFC editor.   I hope that, in processing RFC’s using Adam's procedure, people will overlook the lack of DOIs in the same way that they overlook other aspects of the document that would prevent a new document of that form from being published.

AFAICT, they can’t, as the RFC editor has committed to providing DOIs.

Because:

> > (there are now good markdown and asciidoc choices, as well as an org-mode one if that is your thing), 
> 

These are not maintained by the IETF, so they are documented at the place wherever the authors liked to document them.

Try http://rfc.space and the links emanating from that (well, maybe re-consult in a day or so; I just noticed the links are rather incomplete as of today).

> I’m prepared to stick with that, unless there is something better about the alternatives.

Right, for a minor update, digging out the v1 tools and finding a platform where they can still run may actually be the best way to proceed.

> > (If you do want to make the transition, there are some conversion tools available; I may be able to help.)
> 

I have helped people transition the authoring format of quite well-advanced documents, and it seems it actually helped them complete them.  (A routine check after transition is whether the formatted output is the same, and it typically is, except occasionally for minor differences in hyphenation and spacing caused by different versions of xml2rfc being in use.)

> For documents to be processed according to Adam’s procedure, the likelihood of minor diffs arising is such that I don't think a transition is possible.

There is no way the v2 tool will create the same formatting that the v1 tool did, so I think minor diffs are nearly impossible to avoid anyway.

> For a later full bis, I would be replacing major sections of an existing xml-written document which would make any transition especially difficult.
> 
> For completely new documents,my concerns would be to make sure that the needs of those who might later be called upon to update the document were taken account of.   Relevant issues: 
> 	• Could we be sure that the new source could be processed at a later time, and give rise to the same xml?

Different authoring tools may differ in their priority on forward compatibility.
The one I can talk about authoritatively has created the same formatted documents for more than 8 years now, but not necessarily exactly the same xml.

> 	• Would the xml produced by a new tool be easily human-editable? 

For all of them that I have looked at in some detail: yes.
But you wouldn’t want to do this (as with any compiler, you would edit the input), except if you want to migrate to a different authoring tool (which is an important option that is easily provided by the common XML format).

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Sun, 12 May 2019 18:41:08 +0200

On 12.05.2019 18:16, Carsten Bormann wrote:
> ...

First of, +1 to almost everything you said...

> .. >> For RFC5661 and documents derived from it using Adam’s procedure,
that ship has already sailed :-(.
> Yes.  All these RFC references would be updated by the RFC editor into current references.

Actually, I think a processor should optionally insert the DOIs
automatically. The current way of doing things just introduced a
completely unneeded incompatibility.

> ...

FWIW, I disagree (but I realize that I'm probably in a minority). The
problem with Markdown is that the simple things are easy, but everything
else gets messy. I'm looking forward to see how you kram (pun intended)
the V3 features into your tool...

> Right, for a minor update, digging out the v1 tools and finding a platform where they can still run may actually be the best way to proceed.

All you need is a TCL processor. Works fine over here on a newly
installed notebook with Windows 10 and Cygwin.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 12 May 2019 18:57:22 +0200

Hi Julian,

> the V3 features into your tool…

Do I have to?

If an author wants to use a V3 feature that does not lend itself to authoring in markdown, they can always put the XML tags right into their markdown source.

> installed notebook with Windows 10 and Cygwin.

Haven’t tried that in a while…  
Works for me, too (macOS 10.13.6, on a small document, with the usual formatting differences from v2…).  
Good to know.
(Although I have heard people have had problems on other platforms recently.)

Grüße, Carsten

---

From: David Noveck <[email-masked]>
Date: Mon, 13 May 2019 05:22:25 -0400

> As the references section needs to be updated anyway (for the DOIs), I’m
not sure this is really true.  Or, if it is,
> RFC 5661 maybe isn’t really a candidate for this process, because it may
be impractical to re-generate the exact
> numbering that RFC 5661 used.

I had been assuming that you could turn off sortrefs and construct a
reference section in the exact order that the
v1 tool.   I'll try some experientsto validate that approach.

.> > > Since RFC 5661, we also got DOIs on RFCs, so it is inevitable there
are a lot of diffs.
include rfc reference from external libraries.   It includes them inline,
so a new rfc derived from that xml  file will not include DOIs.

> Yes.  All these RFC references would be updated by the RFC editor into
current references.

That's not a problem for Adam's procedure :-).   The RFC candidate
considred by the IESG would still match
rfc5661.   Then, during RFC editing, the reference section could be revised
to include the DOI's.

>> That is not a problem for Adam's procedure, but it may be for the IESG
or the RFC editor.   I hope that, in processing RFC’s using Adam's
procedure, people will overlook the lack of DOIs in the same way that they
overlook other aspects of the document that would prevent a new document of
that form from being published.

>AFAICT, they can’t, as the RFC editor has committed to providing DOIs.

Please see above:

   - The IESG doesn't have to deal with the DOI diffs, since it won't see
   them.
   - The RFC editor would create DOI diffs but not be bound by Adam's
   procedure in doing so.

Where this might be a problem is in document where the existing xml uses
external reference libraries.   That avoids the need for the RFC to do
anything to provide the DOI's other that updating the libraries.   However
the IESG will see the diffs resulting from the inclusion of DOI's so I
would hope that Adam's document is clear thar they should not be considered
"spurous".

On Sun, May 12, 2019 at 12:57 PM Carsten Bormann <[email-masked]> wrote:

> If an author wants to use a V3 feature that does not lend itself to
> authoring in markdown, they can always put the XML tags right into their
> markdown source.
>
> >> Right, for a minor update, digging out the v1 tools and finding a
> platform where they can still run may actually be the best way to proceed.
> >

---

From: David Noveck <[email-masked]>
Date: Sun, 19 May 2019 10:54:50 -0400

Thanks to everyone for their suggestions.   Now that I've followed up on
many of them, I'd like to tell everybody what I've found so that people can
consider the implicationss for Adam's document and for the processing of
upcoming updates to RFC5661.   In particular, use of the existing v1 tools
has proved quite helpful although it is not a panacea.

So what I've found is that:

   - Even with the v1 xml2rfc, the .xml that I have gotten for RFC5661 from
   the RFC editor cannot be successfully processed.   Whether you use the
   existing v2 xml2rfc  or the v1 xml2rfc available on the web, considerable
   effort is required to get to an xml that can be processed successfully.
    The xml file I received from the RFC editor is attached as rfc5661Base.xml
   while the one I arrived at is attached as rfc5661Ready.xml.
   - Processing of the best xml that I have been able to arrive at for
   rfc5661 using the current v2 xml2rfc results in a document which, when
   compared with rfc5661 using rfcdiff,  has a large number of differences
   which might be considered spurious.  Although I don't feel any of these are
   in fact spurious, they are numerous enough that it might be hard to make
   this determination quickly.  The largest part of these differences concern
   text tables which rfcdiff flags as different even in cases in which the
   tables seem identical.   Also, there re small formtting differences that
   resul from the use of the v2 xml2rfc as well as issues arsing from
   different handling policies for hyphenated words.  I've attached the
   resulting .txt file as rfc5661Ready.txt so that people can rfcdiff it
   against rfc5661.
   - Processing of the best xml that I have been able to arrive at for
   rfc5661 using the v1 xml2rfc available on the web results in a document
   which, when compared with rfc5661 using rfcdiff, shows a small number of
   differences but is not identical to rfc5661.   Besides the small set of
   difference mentioned below, common to both v1 and v2 xml2rfc, the main
   issue concerns a number of cases in which the xml (and rfc5661) has two
   spaces following a period while the v1 xml2rfc has only a single space.
    This is a formatting change but if it is considered "spurious", then that
   spurious change is unavoidable when using the v1 xml2rfc.  It can be
   avoided using the v2 xml2rfc but that causes many more differences with
   rfc5661, as discusssed above.   I've attached the resulting .txt file as
   rfc5661ReadyV1.txt so that people can rfcdiff it against rfc5661.
   - In addition there are a few differences that appear whether the v1 or
   v2 xml2rfc is used.
      - One source of these concerrns the capitalization (or not) of the
      words "profile" and "type" in the titles of many stringprep-related
      sections.  Since RFC5661 uses different forms in the section
itself and in
      the table-of-contents, it is impossible to avoid one of those being
      different from RFC5661.
      - Other problems arise from the different lengths of
      xml2rfc-generated introductory material before the table of
contents.   The
      page count is different for v1 and v2 but both differ from rfc5661.
      - References to ancohor are handled differently in v1 and v2 but
      neither can be made to match the results in rfc5661.
      - Another problem is that rfcdiff appears to have a bug resulting in
      it showing that a significant piece of the definition of CB_COMPOUND is
      missing, even though the .txt file shows no such difference :-(

Based on my experences, I'd like to suggest:

   - That the following addition be made to item 3 in section 3.1 of Adam's
   document.

In evaluating whether such disqualifying changes have occurred, it is
intended that changes due solely to changes in the tools used to generate
RFC .txt files be allowed.  In addition, issues resulting from changes made
by the RFC editor but not reflected in the xml file for the RFC not
interfere with IESG consideration of the document and can be made, if
necessary, by the RFC editor after the revised documment is approved for
publication.

   - That the following addition be made to item 6 in section 3.1 of Adam's
   document.

This will include the AD's determination that the requirements of item 3
above have been met.

   - That, if possible, somebody should fix the bug in rfcdiff noted above.

On Mon, May 13, 2019 at 5:22 AM David Noveck <[email-masked]> wrote:

> rfc5661.   Then, during RFC editing, the reference section could be
> revised to include the DOI's.
>

---

From: Adam Roach <[email-masked]>
Date: Sun, 19 May 2019 15:59:36 -0500

Thanks for the feedback! These seem like reasonable changes for the next 
version.

/a

On 5/19/19 9:54 AM, David Noveck wrote:
> Thanks to everyone for their suggestions.   Now that I've followed up 
> on many of them, I'd like to tell everybody what I've found so that 
> people can consider the implicationss for Adam's document and for the 
> processing of upcoming updates to RFC5661.   In particular, use of the 
> existing v1 tools has proved quite helpful although it is not a panacea.
>
>   * Even with the v1 xml2rfc, the .xml that I have gotten for RFC5661
>     from the RFC editor cannot be successfully processed.   Whether
>     you use the existing v2 xml2rfc  or the v1 xml2rfc available on
>     the web, considerable effort is required to get to an xml that can
>     be processed successfully.   The xml file I received from the RFC
>     editor is attached as rfc5661Base.xml while the one I arrived at
>     is attached as rfc5661Ready.xml.
>   * Processing of the best xml that I have been able to arrive at for
>     rfc5661 using the current v2 xml2rfc results in a document which,
>     when compared with rfc5661 using rfcdiff,  has a large number of
>     differences which might be considered spurious.  Although I don't
>     feel any of these are in fact spurious, they are numerous enough
>     that it might be hard to make this determination quickly.  The
>     largest part of these differences concern text tables which
>     rfcdiff flags as different even in cases in which the tables seem
>     identical.   Also, there re small formtting differences that resul
>     from the use of the v2 xml2rfc as well as issues arsing from
>     different handling policies for hyphenated words.  I've attached
>     the resulting .txt file as rfc5661Ready.txt so that people can
>     rfcdiff it against rfc5661.
>   * Processing of the best xml that I have been able to arrive at for
>     rfc5661 using the v1 xml2rfc available on the web results in a
>     document which, when compared with rfc5661 using rfcdiff, shows a
>     small number of differences but is not identical to rfc5661. 
>      Besides the small set of difference mentioned below, common to
>     both v1 and v2 xml2rfc, the main issue concerns a number of cases
>     in which the xml (and rfc5661) has two spaces following a period
>     while the v1 xml2rfc has only a single space.  This is a
>     formatting change but if it is considered "spurious", then that
>     spurious change is unavoidable when using the v1 xml2rfc.  It can
>     be avoided using the v2 xml2rfc but that causes many more
>     differences with rfc5661, as discusssed above. I've attached the
>     resulting .txt file as rfc5661ReadyV1.txt so that people can
>     rfcdiff it against rfc5661.
>   * In addition there are a few differences that appear whether the v1
>     or v2 xml2rfc is used.
>       o One source of these concerrns the capitalization (or not) of
>         the words "profile" and "type" in the titles of many
>         stringprep-related sections.  Since RFC5661 uses different
>         forms in the section itself and in the table-of-contents, it
>         is impossible to avoid one of those being different from RFC5661.
>       o Other problems arise from the different lengths of
>         contents.   The page count is different for v1 and v2 but both
>         differ from rfc5661.
>       o References to ancohor are handled differently in v1 and v2 but
>       o Another problem is that rfcdiff appears to have a bug
>         resulting in it showing that a significant piece of the
>         definition of CB_COMPOUND is missing, even though the .txt
>         file shows no such difference :-(
>
>   * That the following addition be made to item 3 in section 3.1 of
>     Adam's document.
>
>         In evaluating whether such disqualifying changes have
>         occurred, it is intended that changes due solely to changes in
>         the tools used to generate RFC .txt files be allowed.  In
>         addition, issues resulting from changes made by the RFC editor
>         but not reflected in the xml file for the RFC not interfere
>         with IESG consideration of the document and can be made, if
>         necessary, by the RFC editor after the revised documment is
>         approved for publication.
>
>   * That the following addition be made to item 6 in section 3.1 of
>     Adam's document.
>
>         This will include the AD's determination that the requirements
>         of item 3 above have been met.
>
>   * That, if possible, somebody should fix the bug in rfcdiff noted above.
>
>
> On Mon, May 13, 2019 at 5:22 AM David Noveck <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     > As the references section needs to be updated anyway (for the
>     DOIs), I’m not sure this is really true. Or, if it is,
>     > RFC 5661 maybe isn’t really a candidate for this process,
>     because it may be impractical to re-generate the exact
>     I had been assuming that you could turn off sortrefs and construct
>     a reference section in the exact order that the
>     .> > > Since RFC 5661, we also got DOIs on RFCs, so it is
>     inevitable there are a lot of diffs.
>     >>
>     >> It is not inevitable as shown by the fact that I didn't run
>     into that issue.   It's kind of nice to know that there was an
>     issue out there that I didn't run into :-)
>     >>
>     >> For reasons I  really don't understand, the xml for rfc5661
>     does not include rfc reference from external libraries.   It
>     includes them inline, so a new rfc derived from that xml  file
>     will not include DOIs.
>
>     >> That is not a problem for Adam's procedure, but it may be for the IESG or the RFC editor. 
>      I hope that, in processing RFC’s using Adam's procedure, people
>     will overlook the lack of DOIs in the same way that they overlook
>     other aspects of the document that would prevent a new document of
>       * The IESG doesn't have to deal with the DOI diffs, since it
>         won't see them.
>       * The RFC editor would create DOI diffs but not be bound by
>         Adam's procedure in doing so.
>
>     Where this might be a problem is in document where the existing
>     xml uses external reference libraries.  That avoids the need for
>     the RFC to do anything to provide the DOI's other that updating
>     the libraries.  However the IESG will see the diffs resulting from
>     the inclusion of DOI's so I would hope that Adam's document is
>     clear thar they should not be considered "spurous".
>
>
>     On Sun, May 12, 2019 at 12:57 PM Carsten Bormann <[email-masked]
>     <mailto:[email-masked]>> wrote:
>
>         Hi Julian,
>
>         If an author wants to use a V3 feature that does not lend
>         itself to authoring in markdown, they can always put the XML
>         tags right into their markdown source.
>
>         >> Right, for a minor update, digging out the v1 tools and
>         finding a platform where they can still run may actually be
>         the best way to proceed.
>         >
>         Works for me, too (macOS 10.13.6, on a small document, with
>         the usual formatting differences from v2…).
>         Good to know.

---

From: John C Klensin <[email-masked]>
Date: Mon, 20 May 2019 11:36:44 -0400

David,

Like Adam, I appreciate the detailed feedback.  However, let me
make a small appeal on the part of those of us who see (and
would like to see discussion of) issues in Adam's document that
have more to do with strategy (and alternative strategies) than
with particular text and that of people who follow the IETF list
but who have little interest in this particular topic.   There
are mail systems out there that, at least in the absence of
prior arrangements, treat large, multiple-body-part, messages
(yours was more than eight megabytes in size) as an attack
and/or as requiring special per-message approval.   Even for
those of us with mail systems that are friendlier to larger
messages (at least from IETF lists), multi-megabyte messages may
discourage reading.   Could you please try to figure out a way
to go easy on this, possibly putting files up somewhere and
supplying links to them and/or aggressively trimming previous
messages?

By the way, at least some of the issues with xml2rfc versions of
documents and regenerating equivalent text from them result from
the design of generic text markup systems:  that approach was
never intended to produce closely-controlled page formatting
and, while the degree has changed over time, the RFC Editor has
done a certain amount of page layout formatting after final
approval of documents by authors and what we now call the
relevant stream.  rfcdiff can compensate for some of those
changes but not others; "fixing" to to adjust for all such
changes would probably require heuristics that, not being
perfect, would then lead us to complain about incorrect results.
More important, as the RFC Editor moves toward xml2rfc v3 and
treating those source documents as the authoritative/archival
form, the problems you describe are either going to get worse
(more differences between older documents and documents in the
source form preferred by the authors and the published xml2rfc
v3 form) or better (because xml2rfc v3 seems to drift
significantly in the direction of formatting markup, once
documents are published in that form, they should be more stable
and questions about matching output should become irrelevant).
Some of don't consider those trends desirable, but we are fairly
clearly in the rough. 

If you decide to take on that topic, please start a separate
thread.  In the interim, if Adam's document is going anywhere,
he (and you) should be quite careful about changes that get down
to the xml2rfc level without carefully considering both v3 and
the RFC evolution (including "authoritative XML") plan and their
implications.

thanks,
    john

--On Sunday, May 19, 2019 10:54 -0400 David Noveck
<[email-masked]> wrote:

> Thanks to everyone for their suggestions.   Now that I've
> followed up on many of them, I'd like to tell everybody what
> I've found so that people can consider the implicationss for
> Adam's document and for the processing of upcoming updates to
> RFC5661.   In particular, use of the existing v1 tools has
> proved quite helpful although it is not a panacea.
> 
>    - Even with the v1 xml2rfc, the .xml that I have gotten for
> RFC5661 from    the RFC editor cannot be successfully
> processed.   Whether you use the    existing v2 xml2rfc  or
> the v1 xml2rfc available on the web, considerable    effort is
> required to get to an xml that can be processed successfully.
>...

---

From: Michelle Cotton <[email-masked]>
Date: Tue, 21 May 2019 14:03:17 +0000

Additional comments related to IANA Considerations for bis documents:  What is most important is that the document clearly states what should be updated and what should not.  We have seen varying instructions in bis documents where some replace all references and some replace just some.  If authors can give clear and accurate instructions on what IANA is being requested to do, that is appreciated.

Hope this is helpful.

Thanks,

Michelle

From: ietf <[email-masked]> on behalf of Adam Roach <[email-masked]>
Date: Sunday, May 19, 2019 at 2:00 PM
To: David Noveck <[email-masked]>, Magnus Westerlund <[email-masked]>
Cc: Julian Reschke <[email-masked]>, Carsten Bormann <[email-masked]>, IETF Discussion Mailing List <[email-masked]>
Subject: [Ext] Re: [rfc-i] Evolving document sources over a long time (Re: Comments on draft-roach-bis-documents-00)

Thanks for the feedback! These seem like reasonable changes for the next version.

/a

Thanks to everyone for their suggestions.   Now that I've followed up on many of them, I'd like to tell everybody what I've found so that people can consider the implicationss for Adam's document and for the processing of upcoming updates to RFC5661.   In particular, use of the existing v1 tools has proved quite helpful although it is not a panacea. 

Even with the v1 xml2rfc, the .xml that I have gotten for RFC5661 from the RFC editor cannot be successfully processed.   Whether you use the existing v2 xml2rfc  or the v1 xml2rfc available on the web, considerable effort is required to get to an xml that can be processed successfully.   The xml file I received from the RFC editor is attached as rfc5661Base.xml while the one I arrived at is attached as rfc5661Ready.xml. 
Processing of the best xml that I have been able to arrive at for rfc5661 using the current v2 xml2rfc results in a document which, when compared with rfc5661 using rfcdiff,  has a large number of differences which might be considered spurious.  Although I don't feel any of these are in fact spurious, they are numerous enough that it might be hard to make this determination quickly.  The largest part of these differences concern text tables which rfcdiff flags as different even in cases in which the tables seem identical.   Also, there re small formtting differences that resul from the use of the v2 xml2rfc as well as issues arsing from different handling policies for hyphenated words.  I've attached the resulting .txt file as rfc5661Ready.txt so that people can rfcdiff it against rfc5661.
Processing of the best xml that I have been able to arrive at for rfc5661 using the v1 xml2rfc available on the web results in a document which, when compared with rfc5661 using rfcdiff, shows a small number of differences but is not identical to rfc5661.   Besides the small set of difference mentioned below, common to both v1 and v2 xml2rfc, the main issue concerns a number of cases in which the xml (and rfc5661) has two spaces following a period while the v1 xml2rfc has only a single space.   This is a formatting change but if it is considered "spurious", then that spurious change is unavoidable when using the v1 xml2rfc.  It can be avoided using the v2 xml2rfc but that causes many more differences with rfc5661, as discusssed above.   I've attached the resulting .txt file as rfc5661ReadyV1.txt so that people can rfcdiff it against rfc5661. 
In addition there are a few differences that appear whether the v1 or v2 xml2rfc is used.    
One source of these concerrns the capitalization (or not) of the words "profile" and "type" in the titles of many stringprep-related sections.  Since RFC5661 uses different forms in the section itself and in the table-of-contents, it is impossible to avoid one of those being different from RFC5661.   
Other problems arise from the different lengths of xml2rfc-generated introductory material before the table of contents.   The page count is different for v1 and v2 but both differ from rfc5661. 
References to ancohor are handled differently in v1 and v2 but neither can be made to match the results in rfc5661.    
Another problem is that rfcdiff appears to have a bug resulting in it showing that a significant piece of the definition of CB_COMPOUND is missing, even though the .txt file shows no such difference :-( 
Based on my experences, I'd like to suggest:

That the following addition be made to item 3 in section 3.1 of Adam's document. 
In evaluating whether such disqualifying changes have occurred, it is intended that changes due solely to changes in the tools used to generate RFC .txt files be allowed.  In addition, issues resulting from changes made by the RFC editor but not reflected in the xml file for the RFC not interfere with IESG consideration of the document and can be made, if necessary, by the RFC editor after the revised documment is approved for publication.

That the following addition be made to item 6 in section 3.1 of Adam's document. 
This will include the AD's determination that the requirements of item 3 above have been met.

That, if possible, somebody should fix the bug in rfcdiff noted above. 

> As the references section needs to be updated anyway (for the DOIs), I’m not sure this is really true.  Or, if it is,  

> RFC 5661 maybe isn’t really a candidate for this process, because it may be impractical to re-generate the exact 

> numbering that RFC 5661 used.

I had been assuming that you could turn off sortrefs and construct a reference section in the exact order that the

.> > > Since RFC 5661, we also got DOIs on RFCs, so it is inevitable there are a lot of diffs.  

> Yes.  All these RFC references would be updated by the RFC editor into current references.

That's not a problem for Adam's procedure :-).   The RFC candidate considred by the IESG would still match

rfc5661.   Then, during RFC editing, the reference section could be revised to include the DOI's.

Please see above:

The IESG doesn't have to deal with the DOI diffs, since it won't see them. 
The RFC editor would create DOI diffs but not be bound by Adam's procedure in doing so. 
Where this might be a problem is in document where the existing xml uses external reference libraries.   That avoids the need for the RFC to do anything to provide the DOI's other that updating the libraries.   However the IESG will see the diffs resulting from the inclusion of DOI's so I would hope that Adam's document is clear thar they should not be considered "spurous".

Hi Julian,

Do I have to?

Grüße, Carsten

---

From: David Noveck <[email-masked]>
Date: Tue, 21 May 2019 13:50:46 -0400

Good point.

The IANA Considerations section in non-update RFC's primarily serves as a
means if requesting IANA actions.  When you consider how this maps to bis
documents and bis-like updates, there is a conflict between IANA's
expectations and Adam's desire to have the updated document be current as a
whole, with discussion of changes put in an appendix,  It might be possible
to point out the actions required in the appendix but I have been thinking
of the following as an alternative:

   - Create, at the start of the IANA Considerations section, a new
   subsection entitled "What IANA now needs to do".
   - For the rest of the section, organize as it would be with updates
   included in appropriate places, but distinguish, using tense/auxiliaries
   between things that IANA has already done and those that it has yet to do.

On Tue, May 21, 2019 at 10:03 AM Michelle Cotton <[email-masked]>
wrote:

> Additional comments related to IANA Considerations for bis documents:
> What is most important is that the document clearly states what should be
> updated and what should not.  We have seen varying instructions in bis
> documents where some replace all references and some replace just some.  If
> authors can give clear and accurate instructions on what IANA is being
> requested to do, that is appreciated.
>
>
>
> Hope this is helpful.
>
>
>
> Thanks,
>
> Michelle
>
>
>
> *From: *ietf <[email-masked]> on behalf of Adam Roach <
> [email-masked]>
> *Date: *Sunday, May 19, 2019 at 2:00 PM
> *To: *David Noveck <[email-masked]>, Magnus Westerlund <
> [email-masked]>
> *Cc: *Julian Reschke <[email-masked]>, Carsten Bormann <
> [email-masked]>, IETF Discussion Mailing List <[email-masked]>
> *Subject: *[Ext] Re: [rfc-i] Evolving document sources over a long time
> (Re: Comments on draft-roach-bis-documents-00)
>
>
>
>    - Even with the v1 xml2rfc, the .xml that I have gotten for RFC5661
>    from the RFC editor cannot be successfully processed.   Whether you use the
>    - In addition there are a few differences that appear whether the v1
>    or v2 xml2rfc is used.
>
>
>       sections.  Since RFC5661 uses different forms in the section itself and in
>       xml2rfc-generated introductory material before the table of contents.   The
>       - Another problem is that rfcdiff appears to have a bug resulting
>       in it showing that a significant piece of the definition of CB_COMPOUND is
>    - That the following addition be made to item 3 in section 3.1 of
>    Adam's document.
>
>    - That the following addition be made to item 6 in section 3.1 of
>    Adam's document.
>

---

From: "Andrew G. Malis" <[email-masked]>
Date: Tue, 21 May 2019 14:13:45 -0400

David,

A good suggestion, but it might be easier for IANA to just have two
subsections in the IANA Considerations section:

- What IANA Now Needs to Do (this could be nothing, but should be explicit)

- What IANA Already Did in RFC XXXX

and keep this section identical to the original RFC.

Of course, we should ask Michelle what she would like to see! :-)

Cheers,
Andy

On Tue, May 21, 2019 at 1:51 PM David Noveck <[email-masked]> wrote:

>> <davenoveck@gmail..com>> wrote:
>>
>> >> For RFC5661 and documents derived from it using Adam’s procedure, that
>> ship has already sailed :-(..
>>
>> > As the references section needs to be updated anyway (for the DOIs),
>> I’m not sure this is really true.  Or, if it is,
>>
>> > RFC 5661 maybe isn’t really a candidate for this process, because it
>> may be impractical to re-generate the exact
>>
>>    - The IESG doesn't have to deal with the DOI diffs, since it won't
>>    see them.

---

From: tom petch <[email-masked]>
Date: Thu, 23 May 2019 08:02:16 +0000

----- Original Message -----
From: "Andrew G. Malis" <[email-masked]>
Sent: Tuesday, May 21, 2019 7:13 PM

David,

- What IANA Now Needs to Do (this could be nothing, but should be
explicit)

<tp>

Why?

The purpose of an RFC is to provide information for the community so my
starting point is what is it that the community wants to see.  Once that
is determined, then then is the time to ask Michele and company what
they want to see to ensure that the section meets those requirements.

I make frequent reference to the IANA Considerations section of RFC
going back decades, because they constrain what can and cannot be done
now, and it is a pain when the information is scattered across multiple
RFC, or when the key RFC is badly worded, ambiguous.  Examples of  the
latter keep cropping up.

So, I would say that an IANA Considerations should be complete and
should never say this is what we did last time and here is a delta for
you to (mis-)apply.

A minor example of this is RFC7950 which many cite in the IANA
Considerations of an I-D containing a YANG module in order that the YANG
modules is registered with IANA.  Wrong!  All that RFC7950 says is that
the procedure is described in RFC6020 so you have to get out RFC6020 to
know what to do and the sort-of-obsolete RFC6020 then has to be a
Normative Reference of the new I-D.  Far better if the authors of
RFC7950 had included the procedure for registering a YANG module;
instead, RFC6020 remains a Normative Reference unless and until a YANG
1.2 or YANG 2.0 appears and addresses the problem.

Tom Petch.

Cheers,
Andy

>> Thanks to everyone for their suggestions.   Now that I've followed up
on
>>    - Even with the v1 xml2rfc, the .xml that I have gotten for
RFC5661
>>    from the RFC editor cannot be successfully processed.   Whether
you use the
>>    rfc5661 using the current v2 xml2rfc results in a document which,
when
>>    different handling policies for hyphenated words.  I've attached
the
>>    rfc5661 using the v1 xml2rfc available on the web results in a
document
>>    spurious change is unavoidable when using the v1 xml2rfc.  It can
be
itself and in
contents.   The
>>       page count is different for v1 and v2 but both differ from
rfc5661..
>> > As the references section needs to be updated anyway (for the
DOIs),
>> > Yes.  All these RFC references would be updated by the RFC editor
into

---

From: "Andrew G. Malis" <[email-masked]>
Date: Thu, 23 May 2019 05:30:43 -0400

Tom,

I think you might have misunderstood my suggestion. To make it more
concrete, let's say that we're creating RFC 1234bis to replace RFC 1234.

Then RFC 1234bis's IANA considerations section would have two subsections:

- What IANA Now Needs to Do (these are new actions resulting from the bis
document)

- What IANA Already Did in RFC 1234 (what IANA originally did, the original
text from RFC 1234)

That way you don't have to look in two places (RFC 1234bis and RFC 1234) to
see everything that IANA did, both historically and now.

Cheers,
Andy

---

From: Julian Reschke <[email-masked]>
Date: Thu, 23 May 2019 11:46:10 +0200

On 23.05.2019 11:30, Andrew G. Malis wrote:
> - What IANA Now Needs to Do (these are new actions resulting from the
> bis document)
>
> - What IANA Already Did in RFC 1234 (what IANA originally did, the
> original text from RFC 1234)
>
> That way you don't have to look in two places (RFC 1234bis and RFC 1234)
> to see everything that IANA did, both historically and now.

Understood - but why is that actually important enough to drag the old
information in? Wouldn't be linking to it be sufficient? Also, doesn't
it give the potentially incorrect impression that this is a complete
view of all IANA actions related to the protocol?

Best regards, Julian

---

From: "Andrew G. Malis" <[email-masked]>
Date: Thu, 23 May 2019 07:05:02 -0400

Julian,

My understanding of the goal in draft-roach-bis-documents is to make the
bis RFC as close to the original as possible, including formatting (modulo
changes resulting from tooling changes), so that you don't need linking or
to look in multiple places.

This would include a complete view of all IANA actions related to the
protocol in one place. draft-roach wants to completely replace the original
RFC with the bis, not just update it.

Cheers,
Andy

---

From: Julian Reschke <[email-masked]>
Date: Thu, 23 May 2019 13:10:21 +0200

On 23.05.2019 13:05, Andrew G. Malis wrote:
> bis RFC as close to the original as possible, including formatting
> (modulo changes resulting from tooling changes), so that you don't need
> linking or to look in multiple places.

Yes. But...

> protocol in one place. draft-roach wants to completely replace the
> original RFC with the bis, not just update it

I still don't get why past IANA actions are of any relevance for an
updated specification.

And yes, I understand that this is about replacing (obsoleting) a
document, not simply updating it. There may be cases where it's as
simple as that (RFC X replaced by RFC Xbis), but in my experience, there
are frequently other RFCs published in between that indeed updated the
original RFC and had their own IANA actions - so just having those from
X and Xbis does not give a complete picture.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 23 May 2019 13:17:03 +0200

On May 23, 2019, at 13:05, Andrew G. Malis <[email-masked]> wrote:
> 
> bis RFC as close to the original as possible

In a case we are looking at right now, that would actually be true with respect to the contribution of the spec to the registry content (the registry probably should be updated to point to the bis).  But it is a bit weird to talk about the initial assignments for a registry that has since gained dozens of additional entries…

I think the IANA considerations should contain:
— all “new” registries defined by this spec
— all procedures/policies for these (might want to update)
— registry entries (in old or new registries) that should now point to the bis document as documentation (need not be wholesale — maybe the bis is dropping some cobwebs)

Usually, for RFCs the IANA considerations should already be in past tense, so that will not be a big change.  If the diff is manageable, IANA should be able to see from that what the actual actions are (new new registries, new new entries…).

Note that the documentation of the existing registered entry might very well be updated in the bis document, so updating the pointer from IANA to the bis is important.

Grüße, Carsten

---

From: "Salz, Rich" <[email-masked]>
Date: Thu, 23 May 2019 14:26:25 +0000

Mega-dittos as they say.

---

From: tom petch <[email-masked]>
Date: Thu, 23 May 2019 16:08:16 +0000

----- Original Message -----
From: "Julian Reschke" <[email-masked]>
Sent: Thursday, May 23, 2019 12:10 PM

Yes. But...

<tp>

me too, or me neither.

A statement that the registry was first set up in RFCxxxx is fine, plus
a change log if appropriate, but no more than that of the history.

The thornier question is of entries that have been added to a registry
since the initial setup. Most ADs do not regard adding an entry as being
an update to the original RFC so I would expect the bis to list the
registry entries that appear in the bis document referencing the
sections defining them and noting that this new bis is now the
definition of them and that the initial definition was in RFCxxxx.  We
need to end up with an RFCbis that is unequivocal about where the
authoritative text for the registry now is and I want that to be the bis
and to say so.

Assuming that the group and registry names are stable, and that the
intervening RFC that added entries to the registry have used the right
terminology then the fact that the definition of the registry is now in
RFCbis which has appeared years after the intervening RFC would not be a
problem.

Tom Petch

Best regards, Julian