On Fri, Jul 8, 2016 at 4:01 AM, Robert Wilton <[email protected]> wrote:
> > > On 08/07/2016 11:41, Andy Bierman wrote: > > > > On Fri, Jul 8, 2016 at 2:02 AM, Robert Wilton <[email protected]> wrote: > >> >> >> On 08/07/2016 09:26, Juergen Schoenwaelder wrote: >> >>> On Thu, Jul 07, 2016 at 12:21:03PM -0700, Andy Bierman wrote: >>> >>>> The difference is that ietf-restconf-monitoring is NORMATIVE and >>>> REQUIRED >>>> for standards compliance. The example-jukebox module is not in any way >>>> part of the compliance requirements for RESTCONF. A code component >>>> that is part of the standard needs CODE BEGINS. IMO it confuses >>>> the reader to use if for examples. Sometimes (like in routing modules) >>>> it >>>> is not obvious >>>> that the examples are non-normative. >>>> >>>> You are adding semantics to what the CODE BEGIN / END means. I prefer >>> to consider this mechanism just a convenience markup so that code can >>> be easily extracted from RFCs. For me, any attempt to add additional >>> semantics is getting us into trouble. >>> >>> If example-* modules are expected to be validated, it may be good to >>> mark them such that they can be easily extracted. This is, as far as I >>> recall, what CODE BEGIN / END has been originally designed for. >>> >> I agree with both Juergen's points. >> >> I would suggesting using CODE BEGIN/END to mark code, and use the module >> name to denote whether or not it is an example. My understanding is that >> all modules in IETF drafts must either be prefixed as "ietf-" or >> "example-". It would be pretty easy for an RFC extraction tool to have a >> option to control whether to extract all code, just proper modules, or just >> examples. >> >> > > I do not agree that an example of any kind is a code component in a > standard. > It is irrelevant that the example has the structure of a YANG module. > > Not really. I see that marking them as code components has two advantages: > - it ensures that the examples are well formed/structured (i.e. the > tooling can help catch bugs in the drafts). > - if folks are learning yang and reading the draft, it provides them with > an easier starting point. I.e. an example module that they can > compile/play with. > > What if I want to show an example of an incorrect YANG module? > > OK. Do we have any drafts that require that? If so, then perhaps don't > mark those examples as CODE. > > But personally, being able to extract (and validate) examples generally > seems like a useful thing to me. > > I think some people will be confused by example YANG that is treated exactly the same as a normative module except the module name starts with "example". https://tools.ietf.org/html/draft-ietf-netmod-routing-cfg-22#appendix-C I guess I have seem so much thought-less cut-and-paste coding over my career that I have less faith than you. (I still regularly have to tell people that they are supposed to use their own domain in namespace URIs, not netconfcentral.org). > Rob > > Andy > > I guess that would become impossible if every example ever created > in an RFC MUST be extracted and compile without errors or even warnings. > > > >> Rob >> >> > Andy > > > >
_______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
