On 9/19/2017 9:42 AM, Martin Bjorklund wrote: > Lou Berger <lber...@labn.net> wrote: >> >> On 9/19/2017 7:29 AM, Martin Bjorklund wrote: >>> Lou Berger <lber...@labn.net> wrote: >>>> Martin, >>>> >>>> Speaking as a contributor: >>>> >>>> >>>> On 9/15/2017 7:40 AM, Martin Bjorklund wrote: >>>>> Robert Wilton <rwil...@cisco.com> 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. > Either JSON or XML. This is fine for code, less so for humans. We include both in the NI draft, the tree provides a quick overview, the JSON provides the details.
> >>>> and this is one way to help convey (a) what is expected of server >>>> implementors and (b) what client implementors should expect. >>>> >>> Hence the >>>> current draft text: >>>> >>>> In describing the intended use of a module containing a mount point, >>>> it is helpful to show how the mount point would look with mounted >>>> modules. >>>> >>>> The whole point of trees is to facilitate understanding for those who >>>> are less familiar with a model than the authors, and IMO that's the >>>> paramount perspective in this discussion. >>> Fully agree! I would say that we have to make sure that the diagrams >>> can be understood by people less familiar with the technology than the >>> authors. Mixing schema and instance data does not help here. >> Can you propose an alternative? > As I have written before, I think the "/" is not needed, so I would > remove that. I would also not list the nodes from "parent-references" > in the same tree ouput. It is not clear to me that this level of > detail is needed in the tree, and - as noted before - it isn't even > correct to list e.g. "interfaces" when the parent-reference in fact > selects a single interface. > >> The routing WG participants seem to >> find these useful, we can also ask there for broader input if you'd like. > One approach is to add the union of eveything that some people find > useful. In the end we have to look for WG consensus. Several people > have said that they prefer a less cluttered format. In the context of listing enums... > >>>>> Since a parent >>>>> reference can be very specific, e.g. one specific interface, it isn't >>>>> really accurate to show: >>>>> >>>>> +--mp vrf-root >>>>> +--rw rt:routing/ >>>>> | ... >>>>> +--ro if:interfaces@ >>>> This is just a conditional and we have precedent on how to handle >>>> conditional representation. >>>> >>>>> And the trailing "/" on rt:routing doesn't add any information we >>>>> don't already know. Since vrf-root is a mount point, it follows that >>>>> its children are mounted. >>>> The issue is a bit more complex when considering some real use cases, >>>> particularity when parent references and augmentations are used. For >>>> example consider the following *without* the use / or @: >>>> >>>> module: ietf-network-instance >>>> +--rw network-instances >>>> +--rw network-instance* [name] >>>> | ... >>>> +--rw (root-type) >>>> +--:(vrf-root) >>>> +--mp vrf-root >>>> +--ro rt:routing-state >>>> | +--ro router-id? yang:dotted-quad >>>> | +--ro control-plane-protocols >>>> | +--ro control-plane-protocol* [type name] >>>> | +--ro ospf:ospf >>>> | +--ro instance* [af] >>>> +--rw rt:routing >>>> | +--rw router-id? yang:dotted-quad >>>> | +--rw control-plane-protocols >>>> | +--rw control-plane-protocol* [type name] >>>> | +--rw ospf:ospf >>>> | +--rw instance* [af] >>>> | +--rw areas >>>> | +--rw area* [area-id] >>>> | +--rw interfaces >>>> | +--rw interface* [name] >>>> | +--rw name if:interface-ref >>>> | +--rw cost? uint16 >>>> +--ro if:interfaces >>>> | ... >>>> +--ro if:interfaces-state >>>> | ... >>>> >>>> >>>> It's certainly not too hard to spot the top level mounts, but it is >>>> impossible to distinguish the parent references from the actual mounts. >>> My proposal would be to not even show the parent references in the >>> diagram. If we do that, the '/' is not needed. >>> >>>> Further more, some mounts are hard to spot. For example, notice ospf. >>>> Did you notice that it's a mount? >>> This is actually not correct. ospf is *not* a mount; it is an augment. >>> >> it's a mounted module that augments another mounted module. > But why would it have a "/" just b/c it is augmented, when its sibling > 'control-plan-protocol' doesn't have the "/"? What addition info does > the "/" convey? That it is a (sub)tree that is present due to a mounted module. Lou > > > /martin _______________________________________________ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
