Re: [netmod] stable reference for tree diagram notation

[Andy Bierman <[e-mail]>]

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 <
[e-mail]> wrote:

> On Fri, Mar 03, 2017 at 04:41:44PM +0000, Kent Watsen wrote:
> >
> > 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?
>
> 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: [phone]         Campus Ring 1 | 28759 Bremen | Germany
> Fax:   [phone]         <http://www.jacobs-university.de/>
>
> _______________________________________________
> netmod mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod
>