Subject: [rfc-i] XInclude usage

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 4 Aug 2021 11:51:04 -0600

Back in 2017, Julian Reschke asked [1] that we clarify the scope of
XInclude [2] usage, to wit:

###

1. It should be clarified how much of XInclude needs to be supported.
I'm mentioning this because RFC7991 says that includes can not happen
where no elements are allowed, but XInclude allows inclusion of plain
text as well.

2. Is support of the xpointer attribute required? If so, do we have any
guidance how this will work when the document from which to include uses
xml2rfc format, and the pointer relies on the id-ness of an attribute?

###

We discussed this recently [3] within the RFC XML and Style Guide Change
Management Team. Our understanding is that x:include is used primarily
or perhaps exclusively to pull in reference files structured as XML. In
order to keep things as simple as possible, my suggestion to the team
and to this list is as follows:

a. Limit the usage of XInclude to XML only (parse="xml"), not arbitrary
text (parse="text")

b. Don't support fallback [4]

c. Don't support XPointer [5]

I'm curious what others think.

Peter

[1] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/18 see
also https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/128
[2] https://www.w3.org/TR/2006/REC-xinclude-20061115/
[3] https://codimd.ietf.org/cmt-20210726
[4] https://www.w3.org/TR/2006/REC-xinclude-20061115/#fallback
[5] https://www.w3.org/TR/2003/REC-xptr-framework-20030325/

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 05 Aug 2021 08:18:59 +1000

> c. Don't support XPointer [5]

I've always said that we should aggressively limit the capabilities we need.  I will note that XInclude is generally only used for intermediate formats, so the "interop" case for a limited profile is less than elsewhere.  Perhaps your tool just supports XPointer and that's OK.  It's even possible that it would be work to remove that capability from xml2rfc.

That all said, I support keeping it simple: this is the feature set we depend on (a lot), so this is what we should say has to be supported.  Nothing stopping a tool from supporting or even relying on more, but the resulting document wouldn't be for consumption by anything else.

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 5 Aug 2021 10:02:33 +1000

It seems to me that we really need two schema:

1) what the RPC accepts as input

2) what the RPC publishes as an RFC

... because they are getting more different, and trying to accommodate both in a single schema confuses people who want to know what (1) and (2) are definitively.

> On 5 Aug 2021, at 8:18 am, Martin Thomson <[email-masked]> wrote:
> 

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

---

From: Jay Daley <[email-masked]>
Date: Thu, 5 Aug 2021 14:44:04 +1200

Hi Peter

One of my high level concerns about RFC XML is that it should use a formally defined syntax and thereby support validation by a range of common XML tools, not just xml2rfc.  Another one is that if we’re going to use XML then we should use XML and not some custom simulacrum that looks like it but doesn’t walk like it, because then we lose the power of the many XML processing tools out there.

In that regard, imposing any limitations on XInclude is problematic because it means that either only xml2rfc can validate a document, or we need to define our own inclusion mechanism (e.g. RFCInclude) that can be validated.  My strong preference would therefore be not to limit XInclude as per your a., b. and c. below.  

I'm also not clear why we need to limit XInclude this way.  When XInclude is used, it introduces a double validation step, one before the XInclude is processed and one after it is processed.  This can’t really be avoided.  If XInclude is used incorrectly then the second validation will pick that up.  For example, DocBook does not include XInclude in its syntax [1] and only validates the XML that is constructed *after* any XInclude statements are processed and the contents inserted.   

However, we really should examine if we need XInclude or not.  A good example is the way we include IPR boilerplate, which is by an attribute not any form of XML inclusion.  (BTW By doing this we have effectively created two separate XML vocabularies, as Mark was highlighting, and forced the usage of our custom processor, xml2rfc, to get from one to the other).  We could take a similar approach for BibXML references and define a syntax whereby they are simply identified by name and our custom processor inserts them at the right stage.  We already have a 'database' of BibXML references that this name could be used as the key for and we could provide a mechanism for people to add new references to that if needed.

> On 5/08/2021, at 5:51 AM, Peter Saint-Andre <[email-masked]> wrote:
> 
> 2. Is support of the xpointer attribute required?

see above

> If so, do we have any

I need to think this through more, but it would be useful to understand the use case given that RFCs are immutable, so is this only for I-Ds and why are people doing it?

[1]  http://www.sagehill.net/docbookxsl/ValidXinclude.html

Jay 

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

---

From: tjw ietf <[email-masked]>
Date: Wed, 4 Aug 2021 22:48:50 -0400

> On Aug 4, 2021, at 22:44, Jay Daley <[email-masked]> wrote:
> 
> Hi Peter
> 

Strongly agree with jay here.  

RFCXML should not be some snowflake.  

Tim

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 5 Aug 2021 07:20:44 +0200

> ... because they are getting more different, and trying to accommodate both in a single schema confuses people who want to know what (1) and (2) are definitively.

We definitely need to recognise this split, along with

0) what the tools that people who author RFCs in XML accept/work with.

Clearly, (0) includes XInclude for text files, which is in use for components such as YANG modules.
(The alternative is to use a preprocessor such as custom Makefiles and/or kramdown-rfc to assemble the document, but if we embrace XInclude at all, this is a natural way to use something that more than one XML tool might understand.)
(Note that we have src= attributes in a few places, too, so we already have some custom facility for some applications of this.)

We generally try to inline these includes before handing over to the RPC, but could stop doing this (i.e., add that feature to (1)) if we were to recognize other forms of canonical input.

(2) does not include XInclude.

(The v3.rnc I have been using out of xml2rfc source does not include XInclude, IIRC.)

I’m not going to include the obligatory rant about validation, but want to note that there are a lot of validation rules that would be hard to express in terms of XML validation, e.g., the need for relative= for a section reference if and only if it is not to an IETF document (I-D or RFC).

BTW, introducing custom elements for something that could also be achieved based on some generic mechanism such as XInclude can improve both the author experience in terms of reducing busywork and increasing the benefit of validation (e.g., by specifically identifying a reference to an IETF document as such).

Grüße, Carsten

---

From: Peter Saint-Andre <[email-masked]>
Date: Thu, 5 Aug 2021 14:56:28 -0600

> ... because they are getting more different, and trying to accommodate both in a single schema confuses people who want to know what (1) and (2) are definitively.

This an interesting suggestion but personally I need to think about it
before commenting further. :-)

Peter

---

From: "John Levine" <[email-masked]>
Date: 5 Aug 2021 20:21:59 -0400

>before commenting further. :-)

There is the prepped vs. unprepped difference, but it's all the same schema.

The RPC will accept v2 but they immediately run it through the mechanical v2v3 converter
so they're only accepting it in the sense they'll accept an unformatted text draft, too.

R's,
John