[xml2rfc] Differentiating prepped from unprepared documents

[Jay Daley <[e-mail]>]

A group of us have been discussing [1] an issue we see with the current grammar and I would like to continue that discussion on list, but I thought I should give some background first for others on this list.

The issue is that there are certain elements and attributes of the grammar that are only used by the prep tool and yet are 'visible' in the grammar specification, though not consistently, and are known to cause author confusion.  For those who are not clear on this, the 'prep tool' is a specific function of xml2rfc that add various RFCXML markup [2] to a document as a key step in converting an I-D into an RFC.  What the five of us have been discussing is how we separate the prepped and unprepped grammar in order to make it significantly easier for any reader (human or machine) to distinguish between the two.

A good example of the problem is the <toc> (table of contents) element, which is added by the prep tool.  This is included in the documentation (https://authors.ietf.org/en/rfcxml-vocabulary#toc-1) but with the warning "As a document author, you should not use <toc> directly".  However, the "pn" attribute that is added to multiple elements by the prep tool and which is the target of the table of contents entries, is not covered in the documentation.

Julian has suggested that we use a namespace extension for the prepped grammar.  That would mean that the prep tool would add a namespace attribute, such as xmlns:prep="http://www.rfc-editor.org/prep-namespace", to the <rfc> element and then all markup inserted by the tool would be prefixed with "prep" ("prep" is just an example prefix) such as the <prep:toc …> element and "prep:pn" attributes.  There would still only be one grammar file (i.e. rfcXXXX.rnc) but that would be amended to specify the namespace of each element/attribute. 

Personally, I think this is the best way forward given where we are now, though I would have preferred us to have started differently.  Ideally we would have more clearly differentiated between I-Ds and RFCs in the authoring format to match the distinction that is so apparent in how these documents are used.  That would mean having two different grammar files, one for I-Ds with a root element <i-d> and one for RFCs with a root element of <rfc>, and with the prep tool converting between the two.  However, moving to that now seems excessive.

The only practical downside of the namespace solution is that it constricts I-D grammar to always being a subset of RFC grammar (as the latter is implemented by an extension) and so it makes it messy to implement such things as including annotations in the grammar that are only for use in I-Ds and not RFCs.

Jay

[1]  https://github.com/ietf-tools/xml2rfc/issues/791
[2]  https://www.rfc-editor.org/rfc/rfc7998.html

-- 
Jay Daley
IETF Executive Director
[e-mail]