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