Re: [netmod] stable reference for tree diagram notation

[t.petch <[e-mail]>]

---- Original Message -----
From: "Andy Bierman" <[e-mail]>
To: "Kent Watsen" <[e-mail]>
Cc: <[e-mail]>
Sent: Wednesday, March 08, 2017 7:14 PM
> On Wed, Mar 8, 2017 at 10:56 AM, Kent Watsen <[e-mail]>
wrote:
>
> > > 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 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?
> >

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

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

> > K.
> >
> >
> >
>
> Andy
>