On Mon, Sep 29, 2025 at 6:01 PM Mahesh Jethanandani <[email protected]> wrote:
> [Changing the subject line as the discussion is tangential to the work at > hand] > > Hi Andy/Tom, > > Here is how I am trying to rationalize this: > > > - Should (complete, and not code snippets) example modules (or > instance data examples) be validated? Per rfc8407bis, Section 3.2.1, it is > pretty clear that they should be validated. > - Are those examples normative? The answer is no, and that is why the > examples should exist in the non-normative section of the draft. > - Separate from that, the question is how the examples can be > validated? The tools can validate them only if they are standalone files. > To create those standalone files, they have to be extracted from the draft. > Would you agree that how we extract them is less important than being able > to do so? > > > I was referring to snippets, not full modules, and not instance examples. I agree that complete modules should be validated, especially example modules meant to demonstrate how to augment the base module in the RFC. Currently, rfcstrip extracts all CODE BEGINS/ENDS blocks, which is correct. IMO the YANG guideline is wrong, and it is OK to put this wrapper around complete non-normative modules. > We can discuss whether we need a different tag to extract (complete) > examples, but given the current toolset, I do not believe we have a > conflict in how the examples are extracted and named. > > Cheers. > Andy > > On Sep 24, 2025, at 9:36 AM, Andy Bierman <[email protected]> wrote: > > On Wed, Sep 24, 2025 at 4:26 AM tom petch <[email protected]> wrote: > >> From: Mahesh Jethanandani <[email protected]> >> Sent: 23 September 2025 21:47 >> >> Hi Tom, >> >> My take is that code markers only say where the code begins and where it >> ends. It does not distinguish between it being YANG, MIB, an example or >> any other piece of code. The code markers can specify which file the said >> code should extract into. We do not need separate code markers for >> different pieces of code. >> >> <tp> >> >> Colour me confused. If we do not need separate code markers for >> different 'types' of code (which I agree with), then that tells me that the >> CODE START and CODE END should not appear in this I-D but should be >> replaced by CODE BEGINS and CODE ENDS. >> >> > > Correct. > > https://www.ietf.org/archive/id/draft-ietf-netmod-rfc8407bis-28.html#name-code-components > > Note that the MUST NOT rule in 3.2.1 is not being followed, and example > modules are commonly > documented as code components. > > There was discussion about EXAMPLE BEGINS/ENDS, but a new macro like that > was not added. > There was discussion about the importance of IETF Trust IPR issues > associated with code components. > That is why the guidelines draft distinguishes between normative and > non-normative YANG modules. > > Since examples are quite common in all I-Ds, this seems like an important > precedent being set here. > As a consumer of RFCs, I do not really want dozens of extracted files for > ad-hoc example snippets. > These snippets are not code components, and it would be better to handle > example validation another way. > > > > Mahesh Jethanandani > [email protected] > > > > > > >
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
