>> 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)
> — validating artwork.
> > 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.
>> • 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,
> > • 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
> 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 &/<
> For the latter, doing a wholesale <![CDATA[ … ]]> is always a better approach than sprinkling &/<
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 >, 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.
> 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.
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 :-(
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
> 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 <cabo@xxxxxxx> wrote:
Hi David,
Thank you for your article in ietf@xxxxxxxx, 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 <davenoveck@xxxxxxxxx> 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 &/< (you almost never need >, 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
