[rfc-i] [xml2rfc] use of sourcecode type

Paul Kyzivat pkyzivat at alum.mit.edu
Mon Jul 27 08:29:47 PDT 2020

On 7/27/20 7:32 AM, Julian Reschke wrote:
> Am 21.07.2020 um 17:10 schrieb Carsten Bormann:
>> A similar problem is giving examples that are intentionally bad in 
>> order to demonstrate a kind of error.
>> I typically tag them with a type that is derived from the one I would 
>> give for real code, e.g., “CDDLx” for a bad CDDL example.  I think it 
>> would be good to agree on some way to indicate this.
>> A related problem is that often several code blocks combine to one 
>> valid instance of CDDL, for example see Figure 1, 2, 3 in RFC 8428.  
>> There is no way to say that Figure 1 and 2 combine into a valid 
>> instance, and so do Figure 1 and 3, but not any other combination.
>> And, by the way, those type tags are conventionally lower-cased, but 
>> this is not made very explicit; you have to infer that from the list 
>> in Section 2.48.4 of RFC 7991 or the RFC editor’s updated copy of that 
>> list:
>> https://www.rfc-editor.org/materials/sourcecode-types.txt
>> (Ha, this doesn’t even have “cddl” in it; I’m not sure how this is 
>> updated and whether there shouldn’t really be an IANA registry for 
>> these.)
>> Grüße, Carsten
>> ...
> Picking a somewhat random message here to reply to... :-)
> There are multiple use cases to consider:
> 1) tagging for the purpose of validation
> 2) tagging for the purpose of syntax coloring
> (<https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#xml2rfc-ext-html-pretty-print>) 
> 3) hightlighting that something is a "bad" example
> (and maybe more)
> re 1) it is quite common that ABNF is spread over multiple parts of the
> document; each of these is supposed to be syntactically correct, but
> would fail validation if that includes checking for undefined rules

Giving all the pieces the same name will allow them to be accumulated 
into a single file for validation. This can potentially resolve some of 
the undefined rules. But to the best of my recollection I have never 
seen abnf in an ietf document that was complete on its own. Every one 
references rules defined somewhere else - usually in some other ietf 
document. These references all all informal, either stated in text 
before or after the abnf, or within the abnf as a comment or as a 
prose-val (e.g., <foo defined in RFC666>).

But I think *that* is a problem that we shouldn't attempt to solve here. 
IMO an abnf file that is intended to be syntactically correct and 
complete other than references to external rules should probably be 
tagged with type "abnf".

ABNF is particularly forgiving regarding statement ordering. So it may 
take further study to decide if/when marking abnf as a fragment makes sense.

When to a fragment modifier is much clearer when applied to sdp or sip or c.


More information about the rfc-interest mailing list