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

Carsten Bormann cabo at tzi.org
Tue Aug 24 11:39:05 PDT 2021



> On 2021-08-24, at 20:26, Michael Richardson <mcr+ietf at sandelman.ca> wrote:
> 
> 
> Carsten Bormann <cabo at tzi.org> wrote:
>> What we essentially are discussing here is a way to point into a YANG specification.
>> Line numbers have been mentioned as one such way.
>> We do have a fragment identifier syntax for lines in (at least a plain) text file (RFC 5147).
>> But these are brittle.  Adding a line number every, say, 70 lines would also be disruptive.
> 
>> However, a YANG spec is a structured document.  So why not employ the
>> structure of that document as a fragment identifier syntax?
> 
> That works for valid YANG, and we should do that.
> And the HTML should get anchors in... but that's into "sourcecode",
> "artwork", etc.
> 
> 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.

>> (And, as a side effect, having the full schema tree identifier handy
>> would also help with reading through 40-page YANG specs.)
> 
> It would be nice if we could reflow the YANG and syntax highlight it.

Syntax highlighting is one of the applications of type= (and one of the reasons why artwork needs to have a proper replacement for type=, given that type= means something different for artwork).

Reflowing:
I seem to remember that YANG specs are regularly pretty-printed (reformatted) before publishing them; what would “reflowing” add to that?  Reflowing comments (descriptions etc.)?  That would require comments to have a reflowable syntax (e.g., one of the markdown flavors).

Grüße, Carsten



More information about the rfc-interest mailing list