Subject: [xml2rfc-dev] v3 <seriesInfo> vs IMPNOTES vs canonical XML

From: Julian Reschke <[email-masked]>
Date: Thu, 19 Dec 2019 12:38:32 +0100

On 31.10.2019 14:03, Julian Reschke wrote:
> On 29.10.2019 19:30, Heather Flanagan wrote:
>> ...
>>
>> Right now, I’m in the middle of trying to figure out how to capture
>> the reality of <seriesInfo> and make appropriate changes. After that,
>> it will be <sourcecode> and then (if my brain hasn’t melted)
>> “keepWithNext”.
>>
>> -Heather
>> ...
>
> That is indeed both important and complex. I'll try to give feedback
> soonish.
>
> Best regards, Julian

So this is currently captured in
<https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation-notes-10#section-3.1.21>,
quoting the summary:

> 3.1.21.5.  Summary
>
>    The number of issues introduced with the move of the <seriesInfo>
>    element and its re-purposing in order to fill functionality in the
>    front of a document is wholly disproportionate with any added
>    functionality.  The specification [RFC7991] does not provide any
>    rationale for the changes, and there seems to be no major benefits to
>    the new schema.
>
>    Proposal:  Do a rewrite of this that does not add new details to the
>       already complex <seriesInfo> semantics, compared to the v2
>       vocabulary, and does not make non-IETF reference files obsolete,
>       but actually simplifies the model and use.
>
>       Limit the <seriesInfo> element to what is actually needed for use
>       within <reference/>, and do not add new functionality related to
>       the document <front>.  Deprecate any functionality not related to
>       usage within <reference/>.
>
>       The easiest approach would be to simply revert to the v2 semantics
>       and placement of <seriesInfo> elements, with documentation of
>       that.
>
>    Implementation:  The current implementation does not strip or
>       disregard the attributes on <rfc>; apart from that the schema is
>       not reverted to v2 in the current implementation, but see also
>       Section 3.1.17, Section 3.1.19 and Section 3.2.2.

I fully agree with this.

The bad news is that with the proposed change, the so-called "canonical
XML" that has been published in the last three months would become invalid.

I believe we need to compile a list of issues that fall into the same
category (the <br> discussion comes to mind as well), and then (1) fix
these issues and then (2) both mechanically fix the published XML and
re-generate the output formats (which in theory should not change at all
if we do things right).

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 19 Dec 2019 18:26:02 +0100

On Dec 19, 2019, at 12:38, Julian Reschke <[email-masked]> wrote:
> invalid

That points out a flaw of “validation thinking”:

There may be structures that are undesirable (deprecated, etc.), but should not trigger a validation failure (i.e., giving up processing).  If we want to evolve RFCXML over time, we’ll need this sooner or later.

I believe that structural immutability of published RFCs may be too high a goal; we of course want to keep a history of what has been published, but with something as complex, error-prone, and evolving (as in moving target) as RFCXML, it also may be necessary to fix bugs.

(I also think we should minimize those cases, and I’ll recognize that the current process is not conducive to minimizing them — that is a separate issue from the one I bring up here; it just makes being able to handle deprecation and fixes even more urgent.)

Grüße, Carsten

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 19 Dec 2019 09:56:19 -0800

> On Dec 19, 2019, at 3:38 AM, Julian Reschke <[email-masked]> wrote:
> 

While that is technically possible (to mechanically update source files), it is against policy. What you’re suggesting is in effect changing the canonical source file, and we’ve said that’s not something we’re going to do.

I expect future vocabulary changes may well make older XML invalid (in the same way that v2 XML is not v3 valid). We’re not going to go back and change the files to match whatever the new reality is; I don’t see this as significantly different a situation. John and the rest of the community may decide different in the future, of course, but I never intended changing source files for any reason.

-Heather

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 19 Dec 2019 18:09:10 +0000

> I expect future vocabulary changes may well make older XML invalid (in the same way that v2 XML is not v3 valid). We’re not going to go back and change the files to match whatever the new reality i…

The current canonical RFCs in XML don't match any published spec. This leaves us in the situation of having to publish a new spec that might have escape clauses ("the XML might contain X or Y for this element") and then later publish a more definitive spec that says what we really want. Or, we can admit that we made a mistake with the current canonical XML and fix them when the revision to RFC 7991 is finished. This is related to the decision about what the version number for the revision to RFC 7991 will be, given that the current canonical XML is not honestly reporting the version number.

--Paul Hoffman

---

From: "John R Levine" <[email-masked]>
Date: 19 Dec 2019 13:26:04 -0500

> The current canonical RFCs in XML don't match any published spec. This 
> leaves us in the situation of having to publish a new spec that might 
> have escape clauses ("the XML might contain X or Y for this element") 
> and then later publish a more definitive spec that says what we really 
> want. Or, we can admit that we made a mistake with the current canonical 
> XML and fix them when the revision to RFC 7991 is finished. This is 
> related to the decision about what the version number for the revision 
> to RFC 7991 will be, given that the current canonical XML is not 
> honestly reporting the version number.

One of the major reasons we moved from free text to XML is that it lets us 
write a well defined specification for what's in the XML.  That makes it 
possible to write translators into display formats, and write future 
translators for display formats that haven't been invented yet.

I would be dismayed if we had the XML equivalent of early Postscript RFCs 
where the Postscript is missing fonts and modern software can only guess 
at what it was supposed to look like.

Ten years from now when our successors have some new haptic accessible 
output devices, they should be able to write a converter and run the old 
XML through it to support the new devices.  If the XML changes from one 
RFC to the next, we'll have made that gratuitously much harder.

At this point I have no strong opinion about the best way to fix it, but 
we do need to fix it.

R's,
John

---

From: Julian Reschke <[email-masked]>
Date: Thu, 19 Dec 2019 19:40:22 +0100

> While that is technically possible (to mechanically update source files), it is against policy. What you’re suggesting is in effect changing the canonical source file, and we’ve said that’s not som…

Well, we are already violating policy by publishing "canonical" XML that
doesn't conform to *any* published spec.

> I expect future vocabulary changes may well make older XML invalid (in the same way that v2 XML is not v3 valid). We’re not going to go back and change the files to match whatever the new reality i…

I know that wasn't the intent, but given the situation it seems it's
hard to avoid now. You shouldn't have started publishing "v3" documents
without a clear understanding what "v3" is.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 19 Dec 2019 19:45:05 +0100

> That points out a flaw of “validation thinking”:

Well, I was referring to the concept of document validity (being valid
with respect to the published grammar and potentially additional prose
constraints).

> (I also think we should minimize those cases, and I’ll recognize that the current process is not conducive to minimizing them — that is a separate issue from the one I bring up here; it just makes…

Evolvability is indeed important. We can experiment with new features
(optimally in an extension namespace), and, for the time of the
experiment, down-convert when publishing canonical XML.

I also have no problem revising the vocabulary more quickly, but right
now the focus should be fixing the mess we're in, not adding more to it...

Best regards, Julian