Subject: [Xml-sg-cmt] Formally deprecating processing instructions

From: Jay Daley <[email-masked]>
Date: Thu, 18 Nov 2021 14:52:52 +1300

The first implementation of xml2rfc (the TCL one) recognised a set of custom XML processing instructions, including at least the following:

	<?rfc toc="yes"?>
	<?rfc symrefs="yes"?> 
	<?rfc sortrefs="yes" ?>
	<?rfc compact="yes" ?>
	<?rfc subcompact="no" ?>
	<?rfc include="reference.RFC.2119.xml"?>

These have never been defined in any RFC that I am aware of.  

RFC7991 implicitly deprecated all except the last one in section 1.3.2 with the following text

>       Add "sortRefs", "symRefs", "tocDepth", and "tocInclude" attributes
>       to <rfc> to cover Processing Instructions (PIs) that were in v2
>       that are still needed in the grammar.

The functionality of the last one was replaced for v3 with the use of XInclude, which is strongly preferred because the <?rfc include …> PI breaks RelaxNG validation

	<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.2119.xml"/>

I’d like to recommend that the team formally deprecate all custom  (i.e. <?rfc …>) processing instructions because they have all been replaced with more suitable, standard mechanisms to achieve the same thing,

Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Robert Sparks <[email-masked]>
Date: Thu, 18 Nov 2021 09:49:30 -0600

These things are not part of the v3 processing engine (and certainly not 
part of the grammar) in the first place I think, so I'm not sure what 
you're trying to deprecate?

Are you trying to deprecate v2? That will be problematic for chains like 
kramdown that currently rely on v2v3. The list of PIs that xml2rfc 
consumes for v2 is longer than that list.

RjS

---

From: Robert Sparks <[email-masked]>
Date: Thu, 18 Nov 2021 09:56:53 -0600

Ah - will have to mine the code for all of them, but here is an 
existence-proof of a v3 custom pi from the documentation:

> Alternatively, instead of indicating this on the command line, an 
> xml2rfc-specific PI (processing instruction) is available for use in 
> XML input files. This will have the same effect as the example above, 
> except when processing prepped drafts; running the preptool on a file 
> will strip XML PIs before writing the prepped file:
> <?v3xml2rfc silence="The document date" ?>

On 11/18/21 9:49 AM, Robert Sparks wrote:
> These things are not part of the v3 processing engine (and certainly 
> not part of the grammar) in the first place I think, so I'm not sure 
> what you're trying to deprecate?
>
> Are you trying to deprecate v2? That will be problematic for chains 
> like kramdown that currently rely on v2v3. The list of PIs that 
> xml2rfc consumes for v2 is longer than that list.
>
> RjS
>
>> The first implementation of xml2rfc (the TCL one) recognised a set of 
>> custom XML processing instructions, including at least the following:
>>
>>     <?rfc toc="yes"?>
>>     <?rfc symrefs="yes"?>
>>     <?rfc sortrefs="yes" ?>
>>     <?rfc compact="yes" ?>
>>     <?rfc subcompact="no" ?>
>> The functionality of the last one was replaced for v3 with the use of 
>> XInclude, which is strongly preferred because the <?rfc include …> PI 
>> breaks RelaxNG validation
>>
>>     <xi:include 
>> href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.2119.xml"/>
>>
>> I’d like to recommend that the team formally deprecate all custom  
>> (i.e. <?rfc …>) processing instructions because they have all been 
>> replaced with more suitable, standard mechanisms to achieve the same 
>> thing,
>>
>> Jay
>>
>

---

From: "John R Levine" <[email-masked]>
Date: 18 Nov 2021 11:50:20 -0500

> kramdown that currently rely on v2v3. The list of PIs that xml2rfc consumes 
> for v2 is longer than that list.

Well, deprecate in the sense that we want everyone to use v3.  The goal is 
to find the bottlenecks that keep people using v2, and also make v3 work 
better with regular XML tools.  We understand we can't just turn it off any time soon,

>> I’d like to recommend that the team formally deprecate all custom  (i.e. 
>> <?rfc …>) processing instructions because they have all been replaced with 
>> more suitable, standard mechanisms to achieve the same thing,
>> 
>> Jay
>> 
>
>

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly

---

From: Jay Daley <[email-masked]>
Date: Fri, 19 Nov 2021 07:44:44 +1300

> On 19/11/2021, at 4:49 AM, Robert Sparks <[email-masked]> wrote:
> 
> These things are not part of the v3 processing engine (and certainly not part of the grammar) in the first place I think, so I'm not sure what you're trying to deprecate?
> 
> Are you trying to deprecate v2?  That will be problematic for chains like kramdown that currently rely on v2v3. 

As that’s such an unusual question I want to make sure we agree on terminology

- features are deprecated, versions are EOL’d.  Using deprecate in the context of a version doesn’t make sense
- when a feature is deprecated that is shorthand for "this feature that was supported in version N-1 is still available in version N but is no longer supported and may be removed in version N+1 or any time after that".

I am not suggesting EOL’ing v2 at this time though we will need to deal with that at some point.

v3 deprecates a series of v2 features such as <spanx>, <ttcol> and more. I believe these processing instructions have been implicitly deprecated by their replacement with equivalent functionality, however they have never even been formally defined in an RFC let alone formally deprecated.  I am asking that they are formally deprecated in RFC7991bis so that this ambiguity is resolved.

> The list of PIs that xml2rfc consumes for v2 is longer than that list.

Where is the list of PIs defined?  It’s not in the xml2rfc documentation https://xml2rfc.tools.ietf.org/xml2rfc-doc.html <https://xml2rfc.tools.ietf.org/xml2rfc-doc.html>

Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Robert Sparks <[email-masked]>
Date: Thu, 18 Nov 2021 13:54:41 -0600

On 11/18/21 12:44 PM, Jay Daley wrote:
>> like kramdown that currently rely on v2v3.
>
Forgive my informality.
> - when a feature is deprecated that is shorthand for "this feature 
> that was supported in version N-1 is still available in version N but 
> is no longer supported and may be removed in version N+1 or any time 
> after that".
>
> v3 deprecates a series of v2 features such as <spanx>, <ttcol> and 
> more. I believe these processing instructions have been implicitly 
> deprecated by their replacement with equivalent functionality, however 
> they have never even been formally defined in an RFC let alone 
> formally deprecated.  I am asking that they are formally deprecated in 
> RFC7991bis so that this ambiguity is resolved.

Continuing to push with loose-ish terminology to get a clearer picture 
of what's being sought:

PIs aren't part of the document's character data - they aren't defined 
in the grammar (or am I misunderstanding?), so 7991 might not be the 
right vehicle.

For v2, we're not planning on changing what the implementation does with 
the PIs you listed.

For v3, the processors we have don't do anything already with the PIs 
you list (I believe, feel free to challenge that), so there's nothing in 
v3's grammar or the set of PIs that the processors we have (at least 
xml2rfc based ones) to deprecate.

Perhaps what you're looking for is an artifact somewhere that says "v2 
had this list of PIs that xml2rfc payed attention to, but it does not 
pay attention to them in v3" and possibly add "no other processors 
should either"? And at the same time, "v3 has this set of PIs that 
xml2rfc will pay attention to".

> Where is the list of PIs defined?  It’s not in the xml2rfc 
> documentation https://xml2rfc.tools.ietf.org/xml2rfc-doc.html
Only in code as far as I know and it will be an exercise to extract them.
>>> The first implementation of xml2rfc (the TCL one) recognised a set 
>>> of custom XML processing instructions, including at least the following:
>>>
>>> <?rfc toc="yes"?>
>>> <?rfc symrefs="yes"?>
>>> <?rfc sortrefs="yes" ?>
>>> <?rfc compact="yes" ?>
>>> <?rfc subcompact="no" ?>
>>> The functionality of the last one was replaced for v3 with the use 
>>> of XInclude, which is strongly preferred because the <?rfc include 
>>> …> PI breaks RelaxNG validation
>>>
>>> <xi:include

---

From: "John R Levine" <[email-masked]>
Date: 18 Nov 2021 15:56:46 -0500

> PIs aren't part of the document's character data - they aren't defined in the 
> grammar (or am I misunderstanding?), so 7991 might not be the right vehicle.

Interestinng point.  RFC 7990 says:

    o  The final XML will not contain comments or processing
       instructions.

RFC 7998 on the preptool says:

5.1.3.  Processing Instruction Removal

    Remove processing instructions.

RFC 7991 says nothing about PIs other than that xi:include replaces some 
of them and the "sortRefs", "symRefs", "tocDepth", and "tocInclude" 
attributes are supposed to replace the rest.

The xml2rfc doc file says that -r removes PIs, and describes one PI that 
has the same effect as the --silence flag:

So by my reading, the intention was that v3 wasn't supposed to have PIs 
except somehow it does.

R's,
John

> For v2, we're not planning on changing what the implementation does with the 
> PIs you listed.
>
> For v3, the processors we have don't do anything already with the PIs you 
> list (I believe, feel free to challenge that), so there's nothing in v3's 
> grammar or the set of PIs that the processors we have (at least xml2rfc based 
> ones) to deprecate.
>
> Perhaps what you're looking for is an artifact somewhere that says "v2 had 
> this list of PIs that xml2rfc payed attention to, but it does not pay 
> attention to them in v3" and possibly add "no other processors should 
> either"? And at the same time, "v3 has this set of PIs that xml2rfc will pay 
> attention to".
>
>
>> 
>> Where is the list of PIs defined?  It’s not in the xml2rfc documentation 
>> https://xml2rfc.tools.ietf.org/xml2rfc-doc.html
>>>> <?rfc …>) processing instructions because they have all been replaced 
>>>> with more suitable, standard mechanisms to achieve the same thing,
>>>> 
>>>> Jay
>>>> 
>>> 
>> 
>> -- 
>> Jay Daley
>> IETF Executive Director
>> [email-masked]
>

Regards,

---

From: Robert Sparks <[email-masked]>
Date: Thu, 18 Nov 2021 15:12:54 -0600

On 11/18/21 2:56 PM, John R Levine wrote:
>> PIs aren't part of the document's character data - they aren't 
>> defined in the grammar (or am I misunderstanding?), so 7991 might not 
>> be the right vehicle.
>
> RFC 7991 says nothing about PIs other than that xi:include replaces 
> some of them and the "sortRefs", "symRefs", "tocDepth", and 
> "tocInclude" attributes are supposed to replace the rest.
>
> The xml2rfc doc file says that -r removes PIs, and describes one PI 
> that has the same effect as the --silence flag:
>
> So by my reading, the intention was that v3

I think there's a distinction here between "published RFCs" and "works 
in progress" - clearly it was intended that published RFCs not contain PIs.

> wasn't supposed to have PIs except somehow it does.
>
> R's,
> John
>
>> For v2, we're not planning on changing what the implementation does 
>> with the PIs you listed.
>>
>> you list (I believe, feel free to challenge that), so there's nothing 
>> in v3's grammar or the set of PIs that the processors we have (at 
>> least xml2rfc based ones) to deprecate.
>>
>> Perhaps what you're looking for is an artifact somewhere that says 
>> "v2 had this list of PIs that xml2rfc payed attention to, but it does 
>> not pay attention to them in v3" and possibly add "no other 
>> processors should either"? And at the same time, "v3 has this set of 
>> PIs that xml2rfc will pay attention to".
>>
>>
>>>
>>>>>  (i.e. <?rfc …>) processing instructions because they have all 
>>>>> been replaced with more suitable, standard mechanisms to achieve 
>>>>> the same thing,
>>>>>
>>>>> Jay
>>>>>
>>>>
>>>
>>> -- 
>>> Jay Daley
>>> IETF Executive Director
>>> [email-masked]
>>
>
> Regards,

---

From: Robert Sparks <[email-masked]>
Date: Thu, 18 Nov 2021 15:26:41 -0600

Fwiw, on a skim, I think silence is the only pi looked for the v2rfc2xml 
target

It is _heavily_ used in the tests.

See for example: 
https://trac.ietf.org/trac/xml2rfc/browser/trunk/cli/tests/input/elements.xml 
and look around at the other inputs.

RjS

On 11/18/21 3:12 PM, Robert Sparks wrote:
>>> defined in the grammar (or am I misunderstanding?), so 7991 might 
>>> not be the right vehicle.
>>
>>> For v3, the processors we have don't do anything already with the 
>>> PIs you list (I believe, feel free to challenge that), so there's 
>>> nothing in v3's grammar or the set of PIs that the processors we 
>>> have (at least xml2rfc based ones) to deprecate.
>>>
>>> "v2 had this list of PIs that xml2rfc payed attention to, but it 
>>> does not pay attention to them in v3" and possibly add "no other 
>>>>>> The first implementation of xml2rfc (the TCL one) recognised a 
>>>>>> set of custom XML processing instructions, including at least the 
>>>>>> following:
>>>>>>
>>>>>> <?rfc toc="yes"?>
>>>>>> <?rfc symrefs="yes"?>
>>>>>> <?rfc sortrefs="yes" ?>
>>>>>> <?rfc compact="yes" ?>
>>>>>> <?rfc subcompact="no" ?>
>>>>>> The functionality of the last one was replaced for v3 with the 
>>>>>> use of XInclude, which is strongly preferred because the <?rfc 
>>>>>> include …> PI breaks RelaxNG validation
>>>>>>
>>>>>> <xi:include

---

From: Jay Daley <[email-masked]>
Date: Fri, 19 Nov 2021 11:31:07 +1300

> On 19/11/2021, at 8:54 AM, Robert Sparks <[email-masked]> wrote:
> 
> 
> 
> Continuing to push with loose-ish terminology to get a clearer picture of what's being sought:
> 
> PIs aren't part of the document's character data - they aren't defined in the grammar (or am I misunderstanding?), so 7991 might not be the right vehicle.

They are not strictly part of the grammar, but they are used to achieve similar things and as they have been replaced by grammar elements and attributes, I think 7991bis is the right place to deprecate them.

> 
> For v2, we're not planning on changing what the implementation does with the PIs you listed.

I don’t want any changes to v2.

> For v3, the processors we have don't do anything already with the PIs you list (I believe, feel free to challenge that), so there's nothing in v3's grammar or the set of PIs that the processors we have (at least xml2rfc based ones) to deprecate.

That’s my concern - these PIs are not used in v3 and yet that is not stated clearly anywhere,

> Perhaps what you're looking for is an artifact somewhere that says "v2 had this list of PIs that xml2rfc payed attention to, but it does not pay attention to them in v3" and possibly add "no other processors should either"? And at the same time, "v3 has this set of PIs that xml2rfc will pay attention to". 

Almost.  I want something that says, "the following processing instructions that were available for v2 are now deprecated and alternative functionality provided in the v3 grammar" to go into 7991bis.

>> Where is the list of PIs defined?  It’s not in the xml2rfc documentation https://xml2rfc.tools.ietf.org/xml2rfc-doc.html

I’ll follow up on that separately.

Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]