[rfc-i] What the text version is used for (was Re: The <tt> train wreck)

Paul Kyzivat pkyzivat at alum.mit.edu
Tue Aug 24 12:28:17 PDT 2021

On 8/24/21 2:39 PM, Carsten Bormann wrote:

>> For internet-drafts (what are they? who cares...)   where the YANG might not
>> validate (or might not validate with the version of pyang that the DT uses),
>> how does not reference the problem part?
> I never understood why people are submitting drafts with formal descriptions that don’t even parse.  I’d suggest we stop doing that.

I can't speak for YANG, but for ABNF there are a reasons:

1) snippets of ABNF tend to be interspersed in text discussions. They 
sometimes are just examples, where the context is understood from the 
text. Other times a "complete" ABNF is introduced bit by bit across the 
document. In this case the snippets are are typically small, so they 
don't, by themselves, make referencing difficult.

2) very often (in my experience, most of the time) the ABNF in one 
document builds on the ABNF in one or more other documents. Comments in 
the ABNF or accompanying text say "See RFCnnn for the definition of 
FOO". It can take considerable work to pull together all the referenced 
pieces that are necessary for the ABNF to verify. (In this case the ABNF 
is well formed except that some terms are undefined.)

Also, I find problematic the idea of needing source-language-specific 
ways of constructing references to points within a document. It presumes 
that a person reviewing who needs to make or follow a reference will be 
familiar with the specific language mechanism. Oft times this is not a 
reasonable assumption.

For instance, I do my best to avoid any document that has YANG in its 
title, but sometimes I can't. (E.g., when doing a genart review.) I'm 
not going to be making any deep comments on the YANG, but I may still 
need to reference it. If so, I'm not going to be using a YANG-specific 
mechanism to do so. Cutting a a seemingly unique block of the document 
and pasting it into my review is easier and works for anything.


More information about the rfc-interest mailing list