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

[Carsten Bormann <[e-mail]>]

Hi David,

Thank you for your article in [e-mail], 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 <[e-mail]> 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