Hi Benoit, My proposal (and what I mentioned in the WG) was slightly different:
I don't think that we should require complete examples in the RFC. Specifically, I think that if we end up wrapping the examples with RFC 9195 instance data + YANG library schema information, and bearing in mind the short line lengths allowed in RFCs, I think that we will find "extra noise" and a lot of line wrapping in the examples which will make them hard to read and understand, defeating the purpose of putting them in the document in the first place. I also don't think that we should putting the YANG modules into the RFCs, but that is part of the separate Veloce discussion. What I propose is: 1. Full compilable examples should be stored somewhere else, e.g., in GitHub, or probably a more permanent home (e.g., IANA or RFC editor website). These should contain or reference any necessary extra metadata (e.g., the associated schema, or the contents of datastores if validating notifications). 1. Examples in documents should just be there to aid the reader understand the main structure of the module. They should be allowed to be incomplete, or leave out long noisy fields (e.g., eliding long keys/hashes in some of the crypto related drafts). However, the shorter examples in the draft should include a reference/link to where the full validatable examples can be found. Kind regards, Rob From: [email protected] <[email protected]> Date: Saturday, 15 November 2025 at 10:28 To: Carsten Bormann <[email protected]>, Kent Watsen <[email protected]> Cc: [email protected] <[email protected]>, Rob Wilton (rwilton) <[email protected]>, Camilo Cardona <[email protected]> Subject: Re: [netmod] Re: Should example modules be allowed to use code tags [Re: AD review of draft-ietf-netmod-intf-ext-yang-16] Dear all, I am trying to summarize the conclusions of this email thread, in light of the draft-cardona-claise-onion-yang-coverage<https://datatracker.ietf.org/doc/draft-cardona-claise-onion-yang-coverage/> presentation in the NETMOD meeting: - We want to have instance examples next to the IETF YANG module. Granted - We want to have those instance examples WITHIN the same document as the YANG module. I guess so. This is ideal but is it always possible, because there might be different contexts? See Rob Wilton's comment in the IETF 124 NETMOD meeting minutes<https://datatracker.ietf.org/doc/minutes-124-netmod-202511071430/> - I understand that the community would like a different tags for the instances (next to CODE BEGINS/END) And we have some in XML, great. - What I am not sure: do we also need the tags for the text draft/RFC (next to XML)? Where I would appreciate the help (of someone more clever that I): how to practically add those tags, when you start from editing markdown draft. A (process) example would be ideal. Thanks and regards, Benoit On Oct 13, 2025, at 16:30, Kent Watsen <[email protected]><mailto:[email protected]> wrote: I find that the ASCII-armor CODE BEGINS/CODE ENDS is an undesirable relic from days before XML-based RFCs. Now that RFCs are XML-native, better constructs are possible. I do not think that extracting from Text-formatted RFCs is necessary. Being able to extract from just XML is fine. Therefore I do NOT support adding support for code-tags for examples. RFCXML has markers= and related attributes name= etc. [1]; you never type CODE BEGINS/ENDS. There is no need to ever apply heuristics to pull source from plaintext renderings any more. Try kramdown-rfc-extract-sourcecode on the XML if you need a tool. Try https://tzi.de/~cabo/i-d or /rfc for a prototype of the “RFC filesystem” I’m proposing (not recently updated though). Grüße, Carsten [1]: https://authors.ietf.org/rfcxml-vocabulary#markers _______________________________________________ netmod mailing list -- [email protected]<mailto:[email protected]> To unsubscribe send an email to [email protected]<mailto:[email protected]>
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
