Re: [Ext] Re: [rfc-i] Evolving document sources over a long time (Re: Comments on draft-roach-bis-documents-00)

[David Noveck <[e-mail]>]

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 <[e-mail]>
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 <[e-mail]> on behalf of Adam Roach <
> [e-mail]>
> *Date: *Sunday, May 19, 2019 at 2:00 PM
> *To: *David Noveck <[e-mail]>, Magnus Westerlund <
> [e-mail]>
> *Cc: *Julian Reschke <[e-mail]>, Carsten Bormann <
> [e-mail]>, IETF Discussion Mailing List <[e-mail]>
> *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
>
>
>
> 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.
>
>
>
> 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 <[e-mail]> 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
>
> > 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.
> >>
> >> 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'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 <[e-mail]> wrote:
>
> Hi Julian,
>
> > 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…
>
> 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.
>
> >>>> 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.
> >>
> >> 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.
>
> 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
>
>
>