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

[David Noveck <[e-mail]>]

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