Subject: [netmod] 6087bis: #37: EXAMPLE BEGINS

From: Andy Bierman <[email-masked]>
Date: Thu, 7 Jul 2016 09:38:53 -0700

Hi,

I want to resolve this issue because it affects RESTCONF and idnits

https://github.com/netmod-wg/rfc6087bis/issues/37

The new proposal is to get rid of EXAMPLE BEGINS in the draft.
id-nits MUST NOT complain about example modules.
Only YANG wrapped in <CODE BEGINS> <CODE ENDS>
is subject to idnits.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 7 Jul 2016 19:11:01 +0200

> Only YANG wrapped in <CODE BEGINS> <CODE ENDS>

I think we should distinguish

a) regular modules that
   - usually have a module name starting with ietf-
   - must be marked with <CODE BEGINS> <CODE ENDS>
   - must be validated using --ietf and
   - should generate errors during idnits processing

b) example modules that
   - usually have a module name	starting with ietf-
   - must be marked with <CODE BEGINS> <CODE ENDS>
   - may be validated without using strict -ietf checks
   - may lead to warnings during idnits processing

c) code snippets that
   - often written to highlight a certain feature and may be incomplete
   - do not have to follow any specific rules
   - may have modules names starting with example-
   - are not subject to automated extraction and validation

The purpose of the <CODE BEGINS> <CODE ENDS> markup is to allow
automated extraction of code components out of an RFC. It should not
be overloaded with additional semantics and we should not create
variations of this convention to express additional semantics.

The fact that a module is an example is encoded in the module name -
this makes sure the information stays with the module.

/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/>

---

From: Andy Bierman <[email-masked]>
Date: Thu, 7 Jul 2016 10:22:43 -0700

> I think we should distinguish

The draft already distinguishes between these 3 cases

>    - should generate errors during idnits processing

nobody is arguing differently for normative modules

>    - may lead to warnings during idnits processing

The problem with (b) is that the copyright for IETF Trust applies.
CODE BEGINS should be for normative modules.
I don't think the example-jukebox module loses its value because
there is no fake "contact" info in the module.

Examples MAY pass "pyang --ietf" checking but this is not required

> variations of this convention to express additional semantics.
There is no debate over code snippets either.
idnits MUST skip code snippets.
=

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 7 Jul 2016 19:40:39 +0200

> The draft already distinguishes between these 3 cases

Good. Then I am happy.

> Examples MAY pass "pyang --ietf" checking but this is not required

Who made <CODE BEGINS> <CODE ENDS> imply copyright? This should be
fixed. The copyright is usually stated in the module's description
statement - and this is where it should be stated. The <CODE BEGINS>
<CODE ENDS> mechanism was designed as a markup for tools to allow
automated extraction - no more and no less. Can we please avoid
overloading this with additional semantics?

/js

---

From: Andy Bierman <[email-masked]>
Date: Thu, 7 Jul 2016 10:53:48 -0700

> overloading this with additional semantics?
https://www.ietf.org/iesg/statement/copyright.html

Note para 4

In addition to the code component types listed, *any text found between the
markers <CODE BEGINS> and <CODE ENDS> shall be considered a code component.*
Authors may wish to use these markers as clear delimiters of code
components.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 7 Jul 2016 19:59:44 +0200

> Authors may wish to use these markers as clear delimiters of code

Well, I am not sure what this really means; if I have an example
module and I do not put it in <CODE BEGINS> and <CODE ENDS>, it
might still be a Code Component, no?

http://trustee.ietf.org/license-info/Code-Components-List-4-23-09.txt

If so, then the question whether some YANG module is wrapped in <CODE
BEGINS> and <CODE ENDS> does not matter.

/js

---

From: Andy Bierman <[email-masked]>
Date: Thu, 7 Jul 2016 12:21:03 -0700

> BEGINS> and <CODE ENDS> does not matter.
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.

Another issue Benoit raised is why doesn't the example-jukebox module pass
all the pyang --ietf strict checks. Do we expect examples to pass --ietf or
not?

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 8 Jul 2016 10:26:32 +0200

> 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.

> all the pyang --ietf strict checks. Do we expect examples to pass --ietf or

I would have to look into the details what --ietf actually does to
have an informed opinion.

/js

---

From: Robert Wilton <[email-masked]>
Date: Fri, 8 Jul 2016 09:56:54 +0100

On 07/07/2016 20:21, Andy Bierman wrote:
>
>
> On Thu, Jul 7, 2016 at 10:59 AM, Juergen Schoenwaelder 
> <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     > [email-masked]
>     <mailto:[email-masked]>> wrote:
>     >
> the reader to use if for examples.  Sometimes (like in routing 
> modules) it is not obvious
> all the pyang --ietf strict checks. Do we expect examples to pass 
> --ietf or not?

Surely it would always get warnings from --ietf, just from its module 
name not starting "ietf-".

Perhaps pyang could be extended to support an --ietf-example option for 
any modules extracted from RFCs with a module name that begins 
"example-...".  This could then use a subset of the --ietf rules that 
make sense for example modules.  This would presumable allow the <CODE 
BEGINS> and <CODE ENDS> markers to be used for example modules.

Rob

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Robert Wilton <[email-masked]>
Date: Fri, 8 Jul 2016 10:02:56 +0100

> 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.

Rob

---

From: Andy Bierman <[email-masked]>
Date: Fri, 8 Jul 2016 03:41:16 -0700

On Fri, Jul 8, 2016 at 2:02 AM, Robert Wilton <[email-masked]> wrote:

> 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.
What if I want to show an example of an incorrect YANG module?
I guess that would become impossible if every example ever created
in an RFC MUST be extracted and compile without errors or even warnings.

Andy

---

From: Robert Wilton <[email-masked]>
Date: Fri, 8 Jul 2016 12:01:48 +0100

On 08/07/2016 11:41, Andy Bierman wrote:
>
>
> On Fri, Jul 8, 2016 at 2:02 AM, Robert Wilton <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>
>
>     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.
>
>
>
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.

Rob

---

From: Andy Bierman <[email-masked]>
Date: Fri, 8 Jul 2016 04:45:36 -0700

On Fri, Jul 8, 2016 at 4:01 AM, Robert Wilton <[email-masked]> wrote:

> - 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.
>

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).

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 8 Jul 2016 13:53:07 +0200

> 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.

/js

---

From: Andy Bierman <[email-masked]>
Date: Fri, 8 Jul 2016 08:15:26 -0700

> 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.

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 suppose then every type of complete example needs
<CODE BEGINS> and <CODE ENDS> right?

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?

Andy

---

From: Robert Wilton <[email-masked]>
Date: Fri, 8 Jul 2016 16:39:19 +0100

On 08/07/2016 16:15, Andy Bierman wrote:
>
>
> On Fri, Jul 8, 2016 at 4:53 AM, Juergen Schoenwaelder 
No indication other than its name :-)

Your issue is presumably that if you fetch all RFCs and extract all 
modules you don't know which are real modules and which are examples?

> Why does anyone want all the examples extracted exactly?
They don't necessarily, but they might.  Why can't there just be an 
optional switch to rfcstrip to include example modules (and excluded 
them by default)?

> are supposed to be implemented, but not so sure why <CODE BEGINS> 
> <CODE ENDS>
For me, I see that having the idnits tooling checking and validating the 
YANG example modules is useful and likely to catch bugs early.

> <CODE BEGINS> and <CODE ENDS> right?
Yes, excluding deliberate erroneous examples.

Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 9 Jul 2016 07:50:51 +0200

> 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.

> 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.

> <CODE BEGINS> and <CODE ENDS> right?

No, only those examples that are complete enough that it makes sense
to check them.

> 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

---

From: Andy Bierman <[email-masked]>
Date: Sat, 9 Jul 2016 06:51:55 -0700

> 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.
[email-masked]: 282 lines.
[email-masked]: 152 lines.
example-jukebox.yang: 246 lines.
example-interface.yang: 20 lines.

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.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Sat, 9 Jul 2016 07:02:28 -0700

> 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.

> 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

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 25 Jul 2016 13:44:22 +0200

> BEGINS> and <CODE ENDS> markers to be used for example modules.

Another option also might be to indicate the intended compliance level
directly in the module, e.g., using an extension.

So we would have

module ietf-routing {
    ietf:compliance-level rfc6087;
    …
}

module example-rip {
    ietf:compliance-level rfc6020; // may be the default
    …
}

Lada

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C