On Sat, Jul 9, 2016 at 6:51 AM, Andy Bierman <a...@yumaworks.com> wrote:
> > > On Fri, Jul 8, 2016 at 10:50 PM, Juergen Schoenwaelder < > j.schoenwael...@jacobs-university.de> wrote: > >> On Fri, Jul 08, 2016 at 08:15:26AM -0700, Andy Bierman wrote: >> > On Fri, Jul 8, 2016 at 4:53 AM, Juergen Schoenwaelder < >> > j.schoenwael...@jacobs-university.de> wrote: >> > >> > > On Fri, Jul 08, 2016 at 04:45:36AM -0700, Andy Bierman wrote: >> > > > >> > > > 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 >> > > > >> > > >> > > This example is a good example why requiring --ietf is likely not >> > > desirable. The example module lacks meta information but this is just >> > > fine I think for the example. >> > > >> > > People who do cut'n'paste blindly will do so regardless how we mark up >> > > things. We can't fix that problem. >> > >> > My point of showing "example-rip" is that there is absolutely no >> indication >> > that the extracted module is just an example and not actually supposed >> > to be implemented. The module looks plenty real to most of us. >> >> Well, its called example-rip. If people go and implement without ever >> looking at the name etc., well, they get what they deserve to get - an >> example implemented. >> >> > Why does anyone want all the examples extracted exactly? >> > I completely understand why we want the normative modules that >> > are supposed to be implemented, but not so sure why <CODE BEGINS> <CODE >> > ENDS> around an example is supposed to be useful. >> >> I thought automated checking of examples was the reason. Or are you >> saying tools are just fine with extracting YANG anyway, regardless of >> the convention? If so, we should discuss to get rid of it in general. >> >> > > idnits and rfcstrip have no problem finding and extracting anything that > looks > like a YANG module. > > $ rfcstrip draft-ietf-netconf-restconf-15.txt > example-ops.yang: 37 lines. > example-actions.yang: 44 lines. > example-jukebox.yang: 5 lines. > example-mod.yang: 13 lines. > ietf-restc...@2016-07-07.yang: 282 lines. > ietf-restconf-monitor...@2016-07-07.yang: 152 lines. > example-jukebox.yang: 246 lines. > example-interface.yang: 20 lines. > > Actually, this exercise of running rfcstrip got me to change my mind. Look closely at the output. rfcstrip is matching a code fragment as module example-jukebox: GET https://example.com/mymodules/example-jukebox/2015-04-04 HTTP/1.1 Host: example.com Accept: application/yang The server might respond: HTTP/1.1 200 OK Date: Thu, 11 Feb 2016 11:10:31 GMT Server: example-server Content-Type: application/yang * module example-jukebox {* * // contents of YANG module deleted for this example...* * }* This 5 line version happens to appear before the real example-jukebox.yang so it gets inadvertently overwritten by rfcstrip with the correct version. The tools are not clever enough to know real YANG from a code snippet, so they need CODE BEGINS to allow "module" to start a code snippet. IMO adding CODE BEGINS around every little example (eg example-mod.yang) > is not needed, but if the WG wants it this way, then fine. > The rfcstrip can do a stupid-grep for "module " same as it can for <CODE > BEGINS>. > We should optimize for readers not tool writers. > > The YANG authors need to decide which examples are worth extracting. (Otherwise we don't need CODE BEGINS for examples at all since everything that looks like a module is already extracted) > > Andy > Andy > > > >> > I suppose then every type of complete example needs >> > <CODE BEGINS> and <CODE ENDS> right? >> >> No, only those examples that are complete enough that it makes sense >> to check them. >> >> > Is there something special about a YANG module vs. ABNF or SMIv2? >> > Why haven't we been doing this for years with these code components? >> >> I do not recall many SMIv2 example modules. The reason I think is that >> we moved towards having more core YANG modules that assume to be >> extended and this is where more substantial examples come into play. >> >> Regarding ABNF, I never understood why ABNF definitions are often >> difficult to extract. RFC 6020 and RFC 6020bis have the ABNF wrapped >> in <CODE BEGINS> <CODE ENDS>, which I think is a good way of doing it. >> >> /js >> >> -- >> Juergen Schoenwaelder Jacobs University Bremen gGmbH >> Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany >> Fax: +49 421 200 3103 <http://www.jacobs-university.de/> >> > >
_______________________________________________ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
