Re: [xml2rfc] Links to rfc7991bis.rnc may need some fixing

> On 2/03/2022, at 8:16 PM, Carsten Bormann <cabo@tzi.org> wrote:
> 
> On 2. Mar 2022, at 07:24, Martin J. Dürst <duerst@it.aoyama.ac.jp> wrote:
>> 
>> Dear XML2RFC experts,
>> 
>> I just started recently with a new ID using xml2rfc, after a long hiatus. Things went fairly smooth, but one thing that caused problems was that there are links for rfc7991bis.rnc that actually go to
>> https://github.com/ietf-authors/rfcxml-templates-and-schemas/blob/main/rfc7991bis.rnc. I naively tried to just download that with "save link as" from my browser, but that didn't give me the actual file, just a github page including the actual file. It took me quite a while to figure out what the resulting error messages meant, and what had happened.
>> 
>> I no longer remember where I originally found such a link, but I have found one on https://authors.ietf.org/en/templates-and-schemas, in the Schemas section.
>> 
>> Anyway, if you put a link on a filename, make it so that it works for direct downloading. Everything else is highly confusing. If you want to link to the relevant github page, please add a separate link making clear that this link doesn't link to the actual file. Many thanks in advance.
> 
> This is also very confusing for me.

I believe this was explained previously but I’ve lost track of what list so here’s another explanation - the intent is to separate out the authoritative grammar from xml2rfc to support that grammar being used by other tools.  For example, by schema-aware XML editors.  The change management process should now be that changes are agreed by the xml-sg-cmt (later the RSWG/RSAB) and then the grammar is updated in the templates repo and that files is then used in xml2rfc.
> 
> The authoritative RFCXMLv3 grammar is at
> 
> https://github.com/ietf-tools/xml2rfc/blob/main/xml2rfc/data/v3.rnc
> (https://raw.githubusercontent.com/ietf-tools/xml2rfc/main/xml2rfc/data/v3.rnc is the raw version of that.)

After authors.ietf.org goes live, that should no longer be the authoritative version, it should be a copy of the authoritative version.
> 
> This appears to be a precursor to the one at rfcxml-templates-and-schemas, which has less indentation and more comment text.

Correct - the same but more readable.

> I also find a version of the v3.rnc that includes grammar for xi:xinclude, which is needed for some tools if you use that feature.

You will unfortunately find all sorts of versions of the grammar that do not appear to be documented or under any change control.  If you find some documentation on them then please point it out.

Also, what tools out there cannot work with separate XML namespaces (the normal way to enable use of xi:include)?

> 
> The name rfc7991bis.rnc also seems to relate to various other activities.

This has been done to address the issue of stable vs changing grammar files.  The v3.rnc you identified above has changed multiple times since RFC 7991 with limited visibility of those changes.  In future the grammars are to be named after the RFCs that document them and bis is used here to indicate a grammar that deviates from the standard and is still in a state of flux.

> There is an expired draft at:
> 
> https://datatracker.ietf.org/doc/html/draft-iab-rfc7991bis-03
> 
> … which points to the xml2rfc-dev mailing list as its locus of discussion.
> 
> While there is no repo information on that draft or its datatracker entry, there is a GitHub repo at
> 
> https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis
> 
> … which appears to have recent activity.
> 
> This includes a
> 
> https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/blob/master/xml2rfcv3.rng
> 
> … which is used in the accompanying Makefile to create an xml2rfcv3.rnc, as well as an annotated RNG from text from the I-D in that directory.
> 
> I don’t find documentation as to what the intentions with these various copies and versions is, and whether the naming of the files has any relation to those.

That repo was created last year (or maybe 2020) in order to address this issue of new releases of xml2rfc including new versions of the grammar all called v3.rnc.  It basically recreates the version history of that file in a repo.  

The activity that you see isthe Temporary RFC Series PM (John Levine) building a new grammar that includes all the changes made since RFC 7991 that the xml-sg-cmt have agreed should stay and some additional changes they have made.  John has kept the community up to date on these and solicited feedback.  That new grammar will of course need to be in a draft and hence rfc7991bis.

-- 
Jay Daley
IETF Executive Director 
exec-director@ietf.org

> Grüße, Carsten
> 
> _______________________________________________
> xml2rfc mailing list
> xml2rfc@ietf.org
> https://www.ietf.org/mailman/listinfo/xml2rfc