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

["Andrew G. Malis" <[e-mail]>]

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 <[e-mail]> wrote:

> 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]
>> <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
>>
>> > 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
>>
>>
>>
>