Subject: [netmod] stable reference for tree diagram notation

From: Kent Watsen <[email-masked]>
Date: Fri, 3 Mar 2017 16:41:44 +0000

All,

Lou and I were discussing how it seems unnecessary that every draft
has the same boilerplate text regarding how to interpret tree diagram
notations.  It would be nice if drafts could instead just reference
another draft that contains this information.  Does this make sense?

Assuming we're interested in having such a reference, we could define
a mini-RFC or, perhaps, leverage Section 3 of 6087bis (YANG Tree 
Diagrams).  Either way, we'd want/need to ensure the information
is updated in a timely manner.

Two reasons for why we may not want to pursue this are:
  1) we can’t update the reference fast enough
  2) drafts might add some proprietary annotations

Is this worth pursuing at all?

Thanks,
Kent

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 3 Mar 2017 18:02:33 +0100

> Is this worth pursuing at all?

This has been discussed before. The tree format that tools generate
has evolved a bit over time and the current setup allows to have some
evolution. The question is whether we have reached a state where the
evolution has come to standstill and we can nail a common tree format
down. If so, someone should write an I-D and then the format should in
my opinion become a separate RFC that can be referenced. (I would not
roll this into RFC 6087 so that the tree format can be revised without
opening all of RFC 6087.) Others have argued in the past that the
replication is not such a big deal and the replication has the
advantage that people who do not read YANG everyday have an
explanation right in place without having to lookup another RFC.

For me personally, this is a low low priority item but if someone has
spare cycles to spend, this is a good target. Such an RFC will get
tons of references and you become famous. Oh, now I get interested...

/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: Fri, 3 Mar 2017 09:36:39 -0800

Hi,

Originally 6087bis had a guideline for each draft to have an informative
reference to
6087bis tree diagram section.  This got removed along the way (I can't find
it in sec 4.9).

It is important that documents use the exact same symbols as every other
tree diagram, so the reader can learn to interpret a tree diagram without
constantly checking the mapping guide.

It is less important that all documents have to same set of identifiers in
the diagram.
E.g., if the module only exports groupings, then the groupings should be in
the
tree diagram.

IMO the tree diagrams are too verbose now, mostly due to leafref and
if-features.

Andy

Here is the output of pyang v1.7.1 --tree-help

Each node is printed as:

<status> <flags> <name> <opts> <type> <if-features>

  <status> is one of:
    +  for current
    x  for deprecated
    o  for obsolete

  <flags> is one of:
    rw  for configuration data
    ro  for non-configuration data
    -x  for rpcs and actions
    -n  for notifications

  <name> is the name of the node
    (<name>) means that the node is a choice node
   :(<name>) means that the node is a case node

   If the node is augmented into the tree from another module, its
   name is printed as <prefix>:<name>.

  <opts> is one of:
    ?  for an optional leaf, choice, anydata or anyxml
    !  for a presence container
    *  for a leaf-list or list
    [<keys>] for a list's keys

  <type> is the name of the type for leafs and leaf-lists

    If the type is a leafref, the type is printed as "-> TARGET", where
    TARGET is either the leafref path, with prefixed removed if possible.

  <if-features> is the list of features this node depends on, printed
    within curly brackets and a question mark "{...}?"

On Fri, Mar 3, 2017 at 9:02 AM, Juergen Schoenwaelder <
[email-masked]> wrote:

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

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 07 Mar 2017 18:56:37 +0100 (CET)

Juergen Schoenwaelder <[email-masked]> wrote:
> down.

I don't think so.  For example, it was recently suggested that a
notion for "mount-points" should be defined.

I don't think this is a big problem.

/martin

---

From: Lou Berger <[email-masked]>
Date: Wed, 8 Mar 2017 10:05:07 -0500

Martin, Juergen,

>> evolution has come to standstill and we can nail a common tree format

I don't see that as the question at all - the issue for me is needing to
parse each document to see if and how it differs from the norm and then
figuring out if the differences are (a) a bug, (b) limited to the
specific document, (c) something that is a basic change that should
impact tools (i.e., pyang) and other documents.

> notion for "mount-points" should be defined.

Yes, and it is our (Martin, Lada and my) conversation in that context
that prompted this discussion.

> I don't think this is a big problem.

Again, I do see this as an issue worth solving and am appreciative that
6087bis is available to easily provide a stable reference until such
time as an update/replacement is needed.

Lou

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 8 Mar 2017 17:40:11 +0100

> On 8 Mar 2017, at 16:05, Lou Berger <[email-masked]> wrote:
> 
> Martin, Juergen,
> 
> 

If the format itself isn't stable, how can 6087bis (after it becomes an RFC) provide a stable reference?

I agree with Juergen and Martin and don't mind having the section about tree symbols in each document that needs it.

Lada

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

---

From: Andy Bierman <[email-masked]>
Date: Wed, 8 Mar 2017 09:15:48 -0800

On Wed, Mar 8, 2017 at 8:40 AM, Ladislav Lhotka <[email-masked]> wrote:

> I agree with Juergen and Martin and don't mind having the section about
> tree symbols in each document that needs it.
>
>
The text in question is in section 4.3:

   If YANG tree diagrams are used, then a sub-section explaining the
   YANG tree diagram syntax MUST be present, containing the following
   text:

     A simplified graphical representation of the data model is used in
     this document.  *The meaning of the symbols in these diagrams is
     defined in [RFCXXXX].*

     -- RFC Editor: Replace XXXX with RFC number and remove note

Given that work on YANG 1.2 is likely to begin just after YANG 1.1 was
published,
it is hard to pretend that this is a stable language.  So I agree this text
should be
replaced with new text that reflects the lack of a stable reference.

Suggested Text:

OLD:

   If YANG tree diagrams are used, then a sub-section explaining the
   YANG tree diagram syntax MUST be present, containing the following
   text:

     A simplified graphical representation of the data model is used in
     this document.  The meaning of the symbols in these diagrams is
     defined in [RFCXXXX].

NEW:

   If YANG tree diagrams are used, then a sub-section explaining the
   YANG tree diagram syntax MUST be present, explaining the symbols

   in the diagram.  The actual text will depend on the version of

   the YANG tree diagram syntax used in the document.

Lada

Andy

---

From: Lou Berger <[email-masked]>
Date: Wed, 8 Mar 2017 12:26:06 -0500

Lada,

> If the format itself isn't stable, how can 6087bis (after it becomes an RFC) provide a stable reference?

huh? - any RFC can be updated per normal process whenever appropriate. 

> I agree with Juergen and Martin and don't mind having the section about tree symbols in each document that needs it.

I completely disagree - it means we constantly need to do diffs. 
There's a good reason to reference prior work when *not* changing
something which shows up, in this case in potentially 10s if not 100s of
drafts.  This allows *everyone* to immediately notice when something new
or unique is done.  (I'll have to find it, but I really loved the RFC
that used a well known term, but then redefined it for that one and only
document -- why do we want to allow this???)

What benefit comes from defining tree syntax by reference?

BTW if you/the WG prefers for the definition to be in its own document,
that would work too.

Lou

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 8 Mar 2017 19:02:11 +0100

>    the YANG tree diagram syntax used in the document.

I think we can allow both and leave it to the document author. Either
the author uses a well known tree format and refers to its definition
or the author usees a not yet well known tree format and then it has
to be defined inline:

    If YANG tree diagrams are used, then a sub-section explaining the
    YANG tree diagram syntax MUST be present, explaining the symbols
    used in the tree diagram. This sub-section can either explain the
    tree diagram format inline or it can refer to an external
    specification of the tree diagram format that is used.

    A specification using the tree diagram format defined in this
    document may simply state:

       The meaning of the symbols in these diagrams is defined in [RFCXXXX].

The way bigger issue I think is how to make sure that the text in this
sub-section is actually inline with the tree diagram itself since it
is easy for this to get out of sync (I admit that I generally do not
read the tree diagram blurb and I would not be surprised if people
cut'n'paste tree diagram blurbs). In other words, what we may want is
a short label _in_ the tree format itself that uniquely identifies the
format and is generated by the tool producing the tree format.

  pyang -f tree --tree-RFCWXYZ foo.yang

format: RFCWXYZ
module: foo
   ....

I personally would trust such an inline label way more than any tree
diagram sections because the label is likely created by the tool that
created the diagram. We have seen I-Ds where the tree diagram is out
of sync with the YANG definitions. Perhaps the idea to have tools for
checking tree diagrams is not that far fetched. (Even though I first
thought the idea of checking tree diagrams is somewhat ridiculous.)

/js

---

From: Kent Watsen <[email-masked]>
Date: Wed, 8 Mar 2017 18:56:20 +0000

> or the author uses a not yet well known tree format and then it has
> to be defined inline:

Nice compromise, but even then it would be helpful if a draft that wants
to use some custom-annotations do so on top of a standard tree-diagram.
So, for instance, the draft might say something like:

  Tree diagrams used in this draft use notation described in
  [RFCXXXX] with the following additional annotations:

     @ - means ...
     # - means ...
     etc.

This way, reader can focus more quickly on the diffs, but also this
likely mimics what happened in reality (start with `pyang -f tree`
and then manually edit from there).  What do you think?

K.

---

From: Andy Bierman <[email-masked]>
Date: Wed, 8 Mar 2017 11:14:56 -0800

> and then manually edit from there).  What do you think?

YANG is supposed to be prioritized for readers, writers, and then
tool-makers.
As a reader of YANG modules, I do not want people creating their own
tree diagram syntax.  I prefer all tree diagrams use the same syntax.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 8 Mar 2017 20:34:34 +0100

> and then manually edit from there).  What do you think?

Manually edited tree diagrams? I hope not. Perhaps we should have text
saying that tree diagrams are expected to be generated by tools and
that they are expected to be consistent with the model (and hence they
need to be updated with every change, hence usage of tools is a damn
good idea).

[I thought this is obvious but perhaps this is not.]

/js

---

From: Kent Watsen <[email-masked]>
Date: Wed, 8 Mar 2017 20:57:58 +0000

> [I thought this is obvious but perhaps this is not.]

Right, but what happens when the draft precedes the tool being
updated (e.g., schema-mount)?  It's a rare case and you already
said authors can address it on a case-by-case basis, so I think
we're covered either way.

K.

---

From: Robert Wilton <[email-masked]>
Date: Thu, 9 Mar 2017 11:07:22 +0000

On 08/03/2017 20:57, Kent Watsen wrote:
> updated (e.g., schema-mount)?
Or the output has been generated by someone without the latest revision 
of the tool installed (which has happened to me previously).

>    It's a rare case and you already
Having the key inline in the documents is generally slightly more 
convenient for readers, but not at the expense of it being a hassle 
during review, or having people define custom formats.

So, I support the idea of putting the table key into its own draft. Not 
6087bis because we need it to be quick/easy to update when required.

Rob

> .

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 9 Mar 2017 12:42:01 +0100

> On 8 Mar 2017, at 20:34, Juergen Schoenwaelder <[email-masked]> wrote:
> 

Tools typically have options so even with their use the output needn't always be the same (for example, types and leafref pointers may be present or not).

Lada

---

From: t.petch <[email-masked]>
Date: Thu, 9 Mar 2017 12:19:07 +0000

---- Original Message -----
From: "Andy Bierman" <[email-masked]>
To: "Kent Watsen" <[email-masked]>
Cc: <[email-masked]>
Sent: Wednesday, March 08, 2017 7:14 PM

> tree diagram syntax.  I prefer all tree diagrams use the same syntax.

Spot on.

I was about to say that this thread is YANG experts discussing what is
best for YANG experts and ignoring the needs of the other 90-something
percent of those involved with YANG but Andy expressed it much better
than I

I want not just the tree diagram to be unchanging (except when something
big like schema mount comes along) but I struggle when the explanation
of the diagram changes.

Why does netmod-syslog-model have a completely different explanation to
most other models?  Is there a functional difference I need to know?  I
cannot look at netmod-syslog-model and recognise whether there is or not
without doing a compare and contrast with a 'proper' explanation, such
as netmod-entity or 6087bis-09; and I don't want to spend time on that.

Tom Petch

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Sat, 11 Mar 2017 21:25:41 +0000

Hi Juergen, 

On 3/8/17, 2:34 PM, "netmod on behalf of Juergen Schoenwaelder"
<[email-masked] on behalf of
[email-masked]> wrote:

>Manually edited tree diagrams? I hope not.

I frequently have to manually edit the pyang-generated trees to get them
to fit in the xml2rfc output. Is there a work around for this that I don¹t
know about? 

Thanks,
Acee

>Perhaps we should have text

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 11 Mar 2017 22:49:51 +0100 (CET)

> to fit in the xml2rfc output. Is there a work around for this that I don¹t

In the latest pyang, I have added --tree-line-length.  Use:

  pyang -f -tree --tree-line-length 69 ...

to fit RFCs.

/martin

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Sat, 11 Mar 2017 22:29:59 +0000

Excellent!! 

Thanks,
Acee

---

From: Robert Wilton <[email-masked]>
Date: Mon, 13 Mar 2017 18:20:16 +0000

Hi Andy,

Would it make sense to update 6087bis section 4.4 to reference this new 
pyang option for generated tree diagrams?

Thanks,
Rob

---

From: Robert Wilton <[email-masked]>
Date: Mon, 13 Mar 2017 18:24:02 +0000

Hi Martin,

It looks like it needs a further tweak to also wrap augments.  I just 
tried (with the latest master off github) and hasn't wrapped the augment 
line.

E.g.

module: ietf-if-l3-vlan
   augment 
/if:interfaces/if:interface/if-cmn:encapsulation/if-cmn:encaps-type:
     +--:(vlan)
        +--rw vlan
           +--rw tag* [index]
              +--rw index        uint8
              +--rw dot1q-tag
                 +--rw tag-type    dot1q-tag-type
                 +--rw vlan-id     ieee:vlanid

Thanks,
Rob

---

From: Lou Berger <[email-masked]>
Date: Mon, 13 Mar 2017 14:26:15 -0400

FYI - just slapped together and published:

https://tools.ietf.org/html/draft-bjorklund-netmod-yang-tree-diagrams-00

Lou

(as contributor)

PS I'm happy with the definition being in 6780bis or in a standalone doc
(as above), but really think we as a WG need to decide ASAP so as not to
hold up 6780bis any further...

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 13 Mar 2017 19:59:23 +0100 (CET)

Robert Wilton <[email-masked]> wrote:
> tried (with the latest master off github) and hasn't wrapped the
> augment line.

Ok.  In general, it will not be possible to cover all cases.  An
example would be if you have a deeply nested module and some long leaf
names in the end.  In such cases it might be better to split the
diagram into many smaller diagrams, using --tree-path and maybe
--tree-depth.

But this particular case should be possible to handle.  I'll have a
look.  Meanwhile you'll have to tweak this manually.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Mon, 13 Mar 2017 12:07:10 -0700

> hold up 6780bis any further...

standalone doc is fine.

does this mean the contents of the tree diagram and the syntax for the
tree diagram are subject to WG consensus?

Andy

---

From: Robert Wilton <[email-masked]>
Date: Mon, 13 Mar 2017 19:10:40 +0000

On 13/03/2017 19:07, Andy Bierman wrote:
>
>
> On Mon, Mar 13, 2017 at 11:26 AM, Lou Berger <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     <https://tools.ietf.org/html/draft-bjorklund-netmod-yang-tree-diagrams-00>
>
>     Lou
>
>     (as contributor)
>
That would seem to make sense, given that they are used in all drafts 
describing YANG models.

Rob

>     >> "Acee Lindem (acee)" <[email-masked] <mailto:[email-masked]>>
>     wrote:
>     >>> Hi Juergen,
>     >>>
>     >>> <[email-masked] <mailto:[email-masked]> on
>     behalf of
>     >>> [email-masked]
>     <mailto:[email-masked]>> wrote:
>     >>>
>     >> [email-masked] <mailto:[email-masked]>
>     <https://www.ietf.org/mailman/listinfo/netmod>
>     >> .
>     >>
>     > [email-masked] <mailto:[email-masked]>
>     <https://www.ietf.org/mailman/listinfo/netmod>
>     >
>
>

---

From: Lou Berger <[email-masked]>
Date: Mon, 13 Mar 2017 15:45:36 -0400

Andy,

> tree diagram are subject to WG consensus?

As contained in RFCs - I would think so. 

As available from tools -- This is for the tools author IMO.

Lou