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

[Adam Roach <[e-mail]>]

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.
>       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
>         xml2rfc-generated introductory material before the table 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
>         neither can be made to match the results in rfc5661.
>       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 :-(
>
> 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] 
> <mailto:[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]
>     <mailto:[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
>