Re: [netmod] Proposal to enhance the YANG tree output

[Martin Bjorklund <[e-mail]>]

Lou Berger <[e-mail]> wrote:
> 
> 
> On 9/19/2017 9:55 AM, Robert Wilton wrote:
> >
> > On 19/09/2017 14:47, Martin Bjorklund wrote:
> >> Robert Wilton <[e-mail]> wrote:
> >>> On 19/09/2017 14:28, Lou Berger wrote:
> >>>> On 9/19/2017 7:29 AM, Martin Bjorklund wrote:
> >>>>> Lou Berger <[e-mail]> wrote:
> >>>>>> Martin,
> >>>>>>
> >>>>>> Speaking as a contributor:
> >>>>>>
> >>>>>>
> >>>>>> On 9/15/2017 7:40 AM, Martin Bjorklund wrote:
> >>>>>>> Robert Wilton <[e-mail]> wrote:
> >>>>>>>> On 15/09/2017 11:21, Ladislav Lhotka wrote:
> >>>>>>>>> Andy Bierman píše v Čt 14. 09. 2017 v 08:43 -0700:
> >>>>>>>>>> Hi,
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>> Actually I liked the early pyang output that was concise and easy to
> >>>>>>>>>> remember.
> >>>>>>>>>> The current format gets very cluttered and there are too many little
> >>>>>>>>>> symbols
> >>>>>>>>>> to remember them all.
> >>>>>>>>> I agree.
> >>>>>>> Me too.  The current draft adds three new magic symbols: "mp" "@" and
> >>>>>>> "/".
> >>>>>>>
> >>>>>>> "mp" is for a mount point, and it can be generated directly from the
> >>>>>>> YANG modules.
> >>>>>>>
> >>>>>>> Directly under a "mp", "/" and "@" are used to indicate that a node is
> >>>>>>> mounted
> >>>>>>> or available through a parent reference, respectively.
> >>>>>>>
> >>>>>>> I actually question the usability of "/" and "@".
> >>>>>> I agree that / and @ are something new, and enabled by schema mount.
> >>>>>> There have been repeated comments in the RTG WG that there needs to be
> >>>>>> some way for vendors to convey what they have implemented with Schema
> >>>>>> mount
> >>>>> If that's the requirement, using the tree diagram is probably not the
> >>>>> best way.  The tree diagram is intended to provide an overview of a
> >>>>> given (set of) YANG module(s).
> >>>>>
> >>>>> A perhaps better way to convey the information is to create a file
> >>>>> with an instantiated /schema-mounts tree.
> >>>> using what syntax?  JSON and XML really isn't that easy for the
> >>>> (human)
> >>>> reader to parse.
> >>> Perhaps there needs to be multiple versions of the generated tree
> >>> output?
> >>>
> >>> 1) A normative tree diagram that shows the structure of the model.
> >>> 2) A subsequent example that demonstrates what it looks like with the
> >>> schema mounted modules.  Within the confines of a text document, the
> >>> tree format still seems like a reasonable way to illustrate this, and
> >>> I would say it is preferable to the verbosity of JSON or XML.
> >>>
> >>> I note that RFC 8022 includes an overview tree model in section 4 with
> >>> some branches pruned, and then the complete representation in an
> >>> appendix, which seems like a pragmatic approach.
> >> Sure, but the question is about what special symbols we define.  Do we
> >> need the extra symbols "/" and "@", and do we agree on what they mean?
> > If we agree that tree style output is OK to illustrate the use of schema 
> > mount, then I think that draft-ietf-netmod-yang-tree-diagrams could 
> > define them, but indicate that they are only used to illustrate how 
> > schema mount is used, and would not be seen in a regular YANG tree 
> > diagram illustrating the structure of a YANG module.  
> 
> This seems like a reasonable compromise to me, and not a major change to
> the draft.
> 
> Martin, what do you think?

This is not a compromise.  Either the tree document defines the
symbols or it doesn't.  The draft already says:

  Module trees may be included in a document as a whole, by one or
  more sections, or even subsets of nodes.

and

  At times when the composition of the nodes within a module schema
  are not important in the context of the presented tree, peer nodes
  and their children can be collapsed using the notation '...' in
  place of the text lines used to represent the summarized nodes.

so the usage in 8022 is already covered.


> > The alternative 
> > might be that the RFCs that uses them defines what '/' and '@' mean for 
> > that specific example.
> >
> > As for what the precise definition of '/' and '@' should be, I'm not 
> > sure.  I think that you and Lou have a better handle on that ;-)

Since Lou and I have different opinions on this, it would be very
useful to hear what others think.


/martin