Re: [netmod] choice/case in tree diagrams

Martin Bjorklund <mbj@tail-f.com> Tue, 06 March 2018 12:10 UTC

Return-Path: <mbj@tail-f.com>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 30901127522 for <netmod@ietfa.amsl.com>; Tue, 6 Mar 2018 04:10:31 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.911
X-Spam-Level:
X-Spam-Status: No, score=-1.911 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id kdeE5ztH3TNQ for <netmod@ietfa.amsl.com>; Tue, 6 Mar 2018 04:10:28 -0800 (PST)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id 85062120047 for <netmod@ietf.org>; Tue, 6 Mar 2018 04:10:28 -0800 (PST)
Received: from localhost (unknown [173.38.220.45]) by mail.tail-f.com (Postfix) with ESMTPSA id 6CD721AE0339; Tue, 6 Mar 2018 13:10:27 +0100 (CET)
Date: Tue, 06 Mar 2018 13:10:26 +0100 (CET)
Message-Id: <20180306.131026.1561571560543888812.mbj@tail-f.com>
To: lberger@labn.net
Cc: vladimir@transpacket.com, netmod@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <161fb126c00.27d3.9b4188e636579690ba6c69f2c8a0f1fd@labn.net>
References: <c9a60629-a1de-0b5b-77a0-595f614bcad8@transpacket.com> <20180306.104411.829341372037212681.mbj@tail-f.com> <161fb126c00.27d3.9b4188e636579690ba6c69f2c8a0f1fd@labn.net>
X-Mailer: Mew version 6.7 on Emacs 24.5 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/bM_kPBSLXIl9KJJ1iwIO9-_kjcY>
Subject: Re: [netmod] choice/case in tree diagrams
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.22
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 06 Mar 2018 12:10:31 -0000

Lou Berger <lberger@labn.net> wrote:
> Martin,
> 
> 
> On March 6, 2018 4:44:47 AM Martin Bjorklund <mbj@tail-f.com> wrote:
> 
> > Hi,
> >
> > After thinking some more about this, realizing that this document is
> > in AUTH48, and looking at the first sentence in the Abstract:
> >
> >    This document captures the current syntax used in YANG module tree
> >    diagrams.
> >
> > I have reached the conclusion that we probably shouldn't make any
> > drastic changes.
> >
> 
> I agree.
> 
> > The current syntax, with flags for choice but not for case, may look a
> > bit odd, but it does follow RFC 7950 where a choice node can have a
> > config property, but case cannot.  Also, this syntax has now been used
> > for several years w/o causing much confusion.
> >
> > I suggest the following changes to this document:
> >
> > OLD:
> >
> >        <flags> is one of:
> >          rw  for configuration data
> >          ro  for non-configuration data, output parameters to rpcs
> >              and actions, and notification parameters
> >          -w  for input parameters to rpcs and actions
> >          -u  for uses of a grouping
> >          -x  for rpcs and actions
> >          -n  for notifications
> >          mp  for nodes containing a "mount-point" extension statement
> >
> > NEW:
> >
> >        <flags> is one of:
> >          rw  for configuration data
> >          ro  for non-configuration data, output parameters to rpcs
> >              and actions, and notification parameters
> >          -w  for input parameters to rpcs and actions
> >          -u  for uses of a grouping
> >          -x  for rpcs and actions
> >          -n  for notifications
> >          mp  for nodes containing a "mount-point" extension statement
> >
> >          case nodes do not have any <flags>.
> >
> 
> 
> > Then, since the syntax requires whitespace before <name>:
> >
> I think we should match current tooling/practice here as well. Can you
> confirm how pyang works today?
> 
> My memory is no such space is added.

This is correct.

> If my memory is correct, my
> preference is to change the text rather then the tooling.

Maybe we can simply do:

OLD:

    <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>, where <prefix> is the
      prefix defined in the module where the node is defined.

NEW:

    <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>, where <prefix> is the
      prefix defined in the module where the node is defined.

      If the node is a case node, there is no space before the
      <name>.


/martin



> 
> Lou
> (As contributor)
> 
> >      <status>--<flags> <name><opts> <type> <if-features>
> >
> > we need to fix the examples:
> >
> > OLD:
> >
> >              +--rw (root-type)
> >                 +--:(vrf-root)
> >
> > NEW:
> >
> >              +--rw (root-type)
> >                 +-- :(vrf-root)
> >
> > (two occurances)
> >
> >
> >
> > /martin
> >
> >
> >
> > Vladimir Vassilev <vladimir@transpacket.com> wrote:
> >>
> >>
> >> On 03/05/2018 06:40 PM, Per Hedeland wrote:
> >> > On 2018-03-05 16:06, Ladislav Lhotka wrote:
> >> >> On Mon, 2018-03-05 at 15:49 +0100, Per Hedeland wrote:
> >> >>> On 2018-03-05 15:41, Ladislav Lhotka wrote:
> >> >>>> On Mon, 2018-03-05 at 15:26 +0100, Martin Bjorklund wrote:
> >> >>>>> Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> wrote:
> >> >>>>>> On Mon, Mar 05, 2018 at 02:54:18PM +0100, Martin Bjorklund wrote:
> >> >>>>>>>> So it seems the running code got it right. ;-)
> >> >>>>>>> As the author of that code, I think that was purely by accident...
> >> >>>>>>>
> >> >>>>>>> But I'm not convinced it is the correct solution.  We have one
> >> >>>>>>> example
> >> >>>>>>> in the other thread where someone was confused by the "rw" flag and
> >> >>>>>>> thought that it implied that the node would be present in the data
> >> >>>>>>> tree.
> >> >>>>>>>
> >> >>>>>> So what does rw mean?
> >> >>>>>>
> >> >>>>>> (i)  The schema node has a rw property.
> >> >>>>>> (ii) The schema node can be instantiated and the instantiated data
> >> >>>>>> node
> >> >>>>>>       has a rw property.
> >> >>>>>>
> >> >>>>>> I think it is difficult to have both at the same time. If the tree
> >> >>>>>> is
> >> >>>>>> a representation of schema nodes, then (i) seems to make more
> >> >>>>>> sense. That said, the explanation in 2.6 is somewhat vague since it
> >> >>>>>> says 'data' and not 'nodes' (like everywhere else):
> >> >>>>>>
> >> >>>>>> OLD:
> >> >>>>>>
> >> >>>>>>         <flags> is one of:
> >> >>>>>>           rw  for configuration data
> >> >>>>>>           ro  for non-configuration data, output parameters to rpcs
> >> >>>>>>               and actions, and notification parameters
> >> >>>>>>
> >> >>>>>> NEW:
> >> >>>>>>
> >> >>>>>>         <flags> is one of:
> >> >>>>>>           rw  for configuration data nodes
> >> >>>>>>           ro for non-configuration data nodes, output parameters to
> >> >>>>>>           rpcs
> >> >>>>>>               and actions, and notification parameters
> >> >>>>> I think this is ok.  But that means that we also have to add:
> >> >>>>>
> >> >>>>>             --  for a choice or case node
> >> >>>>>
> >> >>>>> But in order to be consistent, we should probably have:
> >> >>>>>
> >> >>>>>             --  for a choice, case, input or output node
> >> >>>> But unlike the three other statements, "choice" can have the config
> >> >>>> substatement, so "rw/ro" makes sense there.
> >> >>> I don't think so - that config statement does not a define a property
> >> >>> of
> >> >>> the choice node (it can obviously neither be read nor written), only a
> >> >>> default for descendant data nodes, as described in section 7.21.1 of
> >> >>> RFC
> >> >>> 7950.
> >> >> It is not a default - if a choice has "config false", then no
> >> >> descendant can be
> >> >> "config true". One of the benefits of having rw/ro in the ascii tree
> >> >> is to see
> >> >> where a state data subtree actually starts.
> >> > It is a default, but yes, it is also a restriction in the specific
> >> > case
> >> > of the argument being "false" at a point where the default would
> >> > otherwise be "true". And in that case it is equivalent to having
> >> > "config
> >> > false" on all the descendant data nodes, and they will of course be
> >> > flagged as "ro" regardless of whether the "config false" comes from
> >> > the
> >> > choice or the individual data nodes - and that is where the state
> >> > *data*
> >> > suntree(s) actually start(s).
> >> >
> >> > So I guess the question then is whether this specific case motivates
> >> > always having flags on specifically choice nodes, while the other
> >> > non-data nodes have no flags. Since the 'config' statement is ignored
> >> > in
> >> > rpc/action input/output and notification, choice nodes there should
> >> > then
> >> > presumably have "-w"/"ro"/"-n". Personally I think the diagram is
> >> > clearer with flags only on the data nodes.
> >> When I think about it <flags> do not have any information contents 
> >> outside of the context of a data tree and its schema. So if we are
> >> removing clutter we should probably start there by specifying that
> >> <flags> should be ommited under rpc,notification and action.
> >>
> >> Vladlimir
> >> >
> >> > --Per
> >> >
> >> >> Lada
> >> >>
> >> >>> --Per
> >> >>>
> >> >>>> Lada
> >> >>>>
> >> >>>>>
> >> >>>>> This means that the correct tree syntax for choice and case will be:
> >> >>>>>
> >> >>>>>       +-- (subnet)?
> >> >>>>>          +-- :(prefix-length)
> >> >>>>>          |  +--rw prefix-length?   uint8
> >> >>>>>          +-- :(netmask)
> >> >>>>>             +--rw netmask?         yang:dotted-quad
> >> >>>>>
> >> >>>>>
> >> >>>>> /martin
> >> >>>>>
> >> >>>>>
> >> >>>>>> The document (as far as I searched for it) does not clearly say that
> >> >>>>>> 'node' means 'schema node'. In hindsight, it might have been useful
> >> >>>>>> to
> >> >>>>>> explicitely import terminology from RFC 7950 and to use it carefully
> >> >>>>>> (RFC 7950 has 'schema node' and 'data node' but here we largely talk
> >> >>>>>> about 'nodes' - and my assumption is that this means 'schema
> >> >>>>>> nodes'.)
> >> >>>>> _______________________________________________
> >> >>>>> netmod mailing list
> >> >>>>> netmod@ietf.org
> >> >>>>> https://www.ietf.org/mailman/listinfo/netmod
> >> >>> _______________________________________________
> >> >>> netmod mailing list
> >> >>> netmod@ietf.org
> >> >>> https://www.ietf.org/mailman/listinfo/netmod
> >> > _______________________________________________
> >> > netmod mailing list
> >> > netmod@ietf.org
> >> > https://www.ietf.org/mailman/listinfo/netmod
> >>
> >> _______________________________________________
> >> netmod mailing list
> >> netmod@ietf.org
> >> https://www.ietf.org/mailman/listinfo/netmod
> >
> > _______________________________________________
> > netmod mailing list
> > netmod@ietf.org
> > https://www.ietf.org/mailman/listinfo/netmod
> >
> 
>