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

[David Noveck <[e-mail]>]

>> Apparently an .xml file used to prodtce an rfc is not necessarily
acceptable to later versions of xml2rfc.

> Most of your changes have to do with the better validation in the current
tools, namely:

At least more extensive validation.

> — validating the syntax of anchors (no spaces, plus signs)

It is not clear to me, given that anchors are always in quotes, why these
restrictions were added

In any case, they were added with no concern about the fact that many
existing .xml files would be invalidated.  I hope future instances of such
changes can be avoided.

> — validating artwork.

Artwork, by its nature, does not need to be validated.  I really don't want
xml2rfc warnings about the quality of my artwork :-)

However, changes in the processing of character entities within artwork has
given rise to unxpected rejections of existing xml files :-(

> For the latter, doing a wholesale <![CDATA[ … ]]> is always a better
approach than sprinkling &amp;/&lt;

That's good advice which the nfsv4 working group would do well to follow
for future RFC's.

As our RFC's often have lots of XDR, it is all too easy for a case of
amper-lt/amper-gt dysphoria to develop (not in the DSM :-)

> (you almost never need &gt;, by the way).  (See also authoring tools
below.)

If it's *almost* never, my tendency would be to use it always, just in case.

> The anchor syntax — it is just too bad the v1 tool didn’t check that.

Since we can't go back in time and change the v1 tool, a better way to
provide compatibility would be for the existing tool to get a processing
option, allowing it to accept formerly acceptable anchors that have been
forbidden in recent times.

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

Good advice, but we need to deal with the fact imappropriate choices were
made in the past and incorporated published RFCs.

> This was stylistically appealing for some tiny documents, but rarely is
appropriate for actual specifications (and certainly not for NFSv4-sized
ones!).

I'm not sure how this choice came to be.   The actual .xml file was
generated by make and I don't think anybody really paid attention to the
processing instructions which were fixed early on and never really
reconsidered.

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

I hope so.  Why do you think that this will be getting better?

> but it does require tediously porting back changes to the document
source.

Yes :-(

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

I don't think it will be.   It will eliminate diffs due to different
numeric tags but the layout of the reference sections will be different,
which will show up as a diff.

I hope Adam's document would allow documents with such diffs to be
processed by his procedure.

> (really, for the sake of your readers, please don’t).

For RFC5661 and documents derived from it using Adam's procedure, that ship
has already sailed :-(.

However, when there is a full bis succeeeding RFC5661, not processed
according to Adam's procedure, it should not use numeric references :-)

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

> Again, tedious, but not really avoidable.

In cases in which it is not avoidable, the addition of DOI's should not
prevent processing of a document acccording to Adam's procedure.

> Of course, I would not recommend directly authoring in XML these days

Why not?

> (there are now good markdown and asciidoc choices, as well as an org-mode
one if that is your thing),

Where are these documented?

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

> (If you do want to make the transition, there are some conversion tools
available; I may be able to help.)

I would only make a transition for new documents.

For documents to be processed according to Adam's procedure, the likelihood
of minor diffs arising is such that I don't think a transition is possible.

For a later full bis, I would be replacing major sections of an existing
xml-written document which would make any transition especially difficult.

For completely new documents,my concerns would be to make sure that the
needs of those who might later be called upon to update the document were
taken account of.   Relevant issues:

   - Could we be sure that the new source could be processed at a later
   time, and give rise to the same xml?
   - Would the xml produced by a new tool be easily human-editable?


On Sat, May 11, 2019 at 2:10 AM Carsten Bormann <[e-mail]> wrote:

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