Re: [rfc-i] sourcecode type

This is becoming a bit ABNF-specific, but I’ve run into that problem as well.

Ideally, I’d like to be able to write a generic script that looks at JSON, ABNF, YANG, … in a draft and tells me what’s wrong.

A lot of insights that such a tool will need to consider are in [1]  — I don’t want to repeat them all here.

[1]: https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/195

In particular, we ran into the “exposition only” vs. “normative” part in RFC 8990, and came up with a solution [2] that works for this RFC, but not in general.

[2]: https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/195#issuecomment-850815497

> I've seen fragments of ABNF used in a variety of ways:
> 
> 1) Examples, perhaps just a single rule, typically with references to other rules not defined in the fragment. The definitions might be defined in other fragments, only described in text, or not defined at all.

You are missing:

1a) ABNF rule right-hand—sides (production “elements” in RFC 5234); exposition or normative.

See RFC 8288 for a ton of these.

This was pre-8650 (i.e., RFCXMLv2), but the XML source I saved from that time has type=“abnf2616” both for RHS only and full rules (2616 because it uses the extended ABNF from RFC 2616, which is similar to that from RFC 822, with #rulename for a comma-separate list).

> 2) A complete chunk of ABNF that has been broken into multiple fragments interspersed among text discussion of it, perhaps spread across multiple sections of a document.

That was the problem we solved in RFC 8990.
(The tool support for that is easy in CDDL, as CDDL allows having the same rule twice, so you just concatenate the extracted fragments with the normative part and check the result.)

> 3) A semi-complete chunk of ABNF with some undefined rules. Text or comments in the ABNF refer to other documents for definition of the missing rules.

ABNF-specific problem.  We should mitigate this a bit for ABNF, stay tuned…

> 4) A combination of (1) and (3), where the fragments are copies of portions of the full ABNF, accompanied with discussion.

Or may this was the problem we solved in 8990…
But I think we now know that, beyond sourcecode types, we need to distinguish exposition sourcecode from full sourcecode (and example from normative in the latter).  Add in deliberately broken examples...

> Required validation strategies vary for these cases. They typically require quite a bit of hands-on, which discourages doing it often (or ever). It is really easy to say "there was just a small change in this version - its obvious that it is ok".

Yeah.  I did this once, in RFC 7049, at the cost of two errata :-)
Right, let me add:

(5) sourcecode snippets that are integrated inline into the paragraphs of text, but still need to be validated.

> I would like to see some kind of framework for automated verification of sourcecode. The xml is just a piece of that, but an important piece.

This is clearly a larger development project, but a highly desirable one.
Getting sourcecode types right is going to be a small, but important element for that.
(Note that his is mostly going to be a tool that authors need to be comfortable using, but that will need to be applied at the RPC as well.)

Grüße, Carsten

_______________________________________________
rfc-interest mailing list
rfc-interest@rfc-editor.org
https://www.rfc-editor.org/mailman/listinfo/rfc-interest