Hi Rob, > On Nov 17, 2025, at 1:37 AM, Rob Wilton (rwilton) > <[email protected]> wrote: > > 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: > > 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).
I am willing to add complete data instance examples to the discussion around Veloce. We will need them anyway as part of setting up a CI/CD pipeline in GitHub to validate the models whenever they undergo a change. Similar to you, I have a workflow in https://github.com/mjethanandani/ietf-bgp-yang, where the YANG module, the examples and everything resides in GitHub, and they are pulled together when I am ready to publish a draft. Cheers. > > > 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 <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 > <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] Mahesh Jethanandani [email protected]
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
