Re: [Rswg] Making progress on RFC 7991-bis

[Mark Nottingham <[e-mail]>]

That's a good start. I'm assuming something like that would show up in the Abstract, and also in the Introduction with a bit more detail?

The other thing to discuss is the document title. 7991 is 'The "xml2rfc" Version 3 Vocabulary'. How about something like 'The XML format currently supported by xml2rfc'?

Cheers,


P.S. I considered document status too, but 7991 is already Informational. That brings an interesting question about whether we can publish documents with any status but Informational - I think that already came up, but at some point we should revisit it.


> On 12 Aug 2022, at 12:30 pm, Joel Halpern <[e-mail]> wrote:
> 
> Fair enough.
> 
> How about as the opening of the document: "This document describes the state of the XML grammar that is used for producing RFCs at the time of its publication.  It makes no claim as to what the grammar should be, and acknowledges that this grammar represents non-consensus changes from the consensus grammar documented in RFC 7991."  ?
> 
> As for the issue of misrepresentation of RFC, I think we are all painfully familiar with the problem.  In this case we have the advantage that the primary consumers of the document are IETF participants, rather than targets of marketing campaigns by corporate promoters.  And further, as far as I can tell the situations where the status of the grammar in the document is important will be discussion in the RSWG.  if the RSWG can't keep track of the status of RFCs and the meaning, then we probably have a VERY different problem.
> 
> Yours,
> 
> Joel
> 
> On 8/11/2022 9:59 PM, Mark Nottingham wrote:
>> Maybe. There have been many attempts over the years to contextualise and add nuance to documents about things like their status, authority, source, relationship to other documents, etc. Those three magical letters 'R' 'F' 'C' seem to be all that most people see...
>> 
>> Perhaps I (and others?) will be more comfortable if we saw what that wording would look like.
>> 
>> Cheers,
>> 
>> 
>>> On 12 Aug 2022, at 11:52 am, Joel Halpern <[e-mail]> wrote:
>>> 
>>> If I thought we could not construct the document so as to avoid implying that "what is" is also "what should be", then I would agree with your opposition to publishing it as an RFC.
>>> 
>>> I believe we have agreed that the wording needs to be clear that it describes "what is" not "what was agreed" nor "what is desired by the community".  As long as we care clear about that, having it published as an RFC so there is a stable referent for people to know what we are doing, in the obvious place for such a document, seems effective and suitable.
>>> 
>>> Yours,
>>> 
>>> Joel
>>> 
>>> On 8/11/2022 9:44 PM, Mark Nottingham wrote:
>>>> Hi Jay,
>>>> 
>>>>> On 12 Aug 2022, at 12:57 am, Jay Daley <[e-mail]> wrote:
>>>>> 
>>>>>> On 2 Aug 2022, at 18:07, Eric Rescorla <[e-mail]> wrote:
>>>>>> 
>>>>>> 1. Do we need to publish the current de facto format as an
>>>>>>   RFC or should it be in some other form such as an I-D
>>>>>>   or a Web page?
>>>>> I believe it should be an RFC because that forces a specific process on us whereby there is a lot of discussion, each new version incorporates a big set of changes and new versions are infrequent and well distributed.  By contrast, a web page or I-D would quickly become a much faster changing process with each new version having a small number of changes.  I see the former process as better for the following reasons:
>>>> I agree that we eventually want to end up with an RFC that reflects community consensus on a stable format, but that wasn't the question asked -- it was whether the _current_ de facto format (possibly with minor adjustments to reflect the current state of the tool) should be published as an RFC.
>>>> 
>>>> As has been discussed extensively, some people (myself included) have a real problem with elevating something which is not the result of a consensus process. Publishing it as an RFC makes it archival and lends it authority, but we haven't yet agreed that the de facto format should be long-lived, and we don't (yet) want to imbue it with authority.
>>>> 
>>>> 
>>>>> 1.  As has been amply demonstrated, allowing a relatively quick, much less visible and non-consensus change process has got us into a mess.
>>>>> 
>>>>> 2.  Almost every change that might go into the grammar has a significant level of complexity and a full WG process is the best way to tease out that complexity and ensure that any changes are good changes.
>>>>> 
>>>>> 3.  We have never had an example of an urgent change needed to the grammar such that the RFC development process would be too slow.
>>>>> 
>>>>> 4.  We have many people in the community who still use v2 and even those who use v3 are using different versions depending on how up to date their xml2rfc is, and what files they copied into working directories when.  A slow running RFC process is the best fit to the way the community works whereas a fast changing process will increase this lack of cohesion.
>>>>> 
>>>>> 5.  If we want to move from the situation where we have only two tools (xml2rfc and Julian’s XSLT) that directly support the grammar, to an ecosystem of tools that do so, then an RFC is the best support of that from an implementer perspective.
>>>> All very true, but these are arguments as to why the consensus product needs to be an RFC, not the de facto (and presumably temporary) format.
>>>> 
>>>> 
>>>>> 6.  One element of the mess has been identifying where the authoritative version of the grammar can be found.  Until recently that was the rnc source file as found in the subversion repository of the xml2rfc tool.  Now it is this file in GitHub https://raw.githubusercontent.com/ietf-tools/rfcxml-templates-and-schemas/main/rfc7991bis.rnc but other than us simply declaring that, there’s no way to always point to that.   If we have an RFC then that becomes the authoritative source.
>>>> I agree that this is an issue that needs to be addressed, and soon. The most straightforward way of doing that might be updating the links and text on rfc-editor.org (and perhaps authors.ietf.org). Publishing it as an RFC doesn't do this -- most people won't realise.
>>>> 
>>>> 
>>>>>> 2. Should we just publish the de facto format as-is
>>>>>>   or should we make limited changes prior to the completion of
>>>>>>   a more complete format document? If the latter, what process
>>>>>>   should we use to vet those changes?
>>>>> Sorry, this is a complex answer:
>>>>> 
>>>>> A.  Yes we must document the de facto grammar as is.  Please note that there are three parts to this:
>>>>> 
>>>>>  i.  The changes documented in https://www.ietf.org/archive/id/draft-levkowetz-xml2rfc-v3-implementation-notes-13.html
>>>>> 
>>>>>  ii.  The elements defined in the grammar that are not documented in any RFC such as <toc>
>>>>> 
>>>>>  iii.  There are a number of xml2rfc specific processing instructions (those of the form <?rfc … >) and these, while not strictly part of the grammar, were the only way to achieve things in v2 that can now be done in the v3 grammar and so were effectively obsoleted by RFC 7991 thought that was never explicitly stated. It would be very useful to have a simple statement that all xml2rfc specific PIs are now obsoleted because people are still confused by this.
>>>>> 
>>>>> B.  This new RFC should describe version "3.1" of the grammar, reflecting its backward compatibility rather than be also be numbered v3 or jump to v4.
>>>>> 
>>>>> C.  If the chairs think we can reasonably quickly get agreement on deprecating any features (such as the complex postal stuff) then that deprecation should follow the normal use of deprecation - the grammar feature remains and can be used as before and deprecation is only forward guidance that this feature will be removed in a future version.
>>>> I think these are all entirely reasonable things to document, just not in an RFC published soon by this WG.
>>>> 
>>>>> D.  I would like to see this document formally rename "The xml2rfc vocabulary" to "RFCXML" reflecting the de facto renaming in the authoritative documentation and the discussion around that on the tools-discuss list.  I’ll post a separate message reminding people why this has happened and re-opening the discussion to see how this group feels about it.
>>>> I think renaming like this is a good thing, but only appropriate when it's a format that isn't driven by the implementation decisions of one tool. Labeling the de facto format as tool-specific is entirely appropriate.
>>>> 
>>>> Cheers,
>>>> 
>>>> --
>>>> Mark Nottingham   https://www.mnot.net/
>>>> 
>> --
>> Mark Nottingham   https://www.mnot.net/
>> 

--
Mark Nottingham   https://www.mnot.net/