Re: [netmod] choice/case in tree diagrams

[Lou Berger <[e-mail]>]

On 3/6/2018 7:10 AM, Martin Bjorklund wrote:
> Lou Berger <[e-mail]> wrote:
>> Martin,
>>
>>
>> On March 6, 2018 4:44:47 AM Martin Bjorklund <[e-mail]> 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>.
Looks good to me.

Thanks,
Lou

>
> /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 <[e-mail]> 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 <[e-mail]> 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
>>>>>>>>> [e-mail]
>>>>>>>>> https://www.ietf.org/mailman/listinfo/netmod
>>>>>>> _______________________________________________
>>>>>>> netmod mailing list
>>>>>>> [e-mail]
>>>>>>> https://www.ietf.org/mailman/listinfo/netmod
>>>>> _______________________________________________
>>>>> netmod mailing list
>>>>> [e-mail]
>>>>> https://www.ietf.org/mailman/listinfo/netmod
>>>> _______________________________________________
>>>> netmod mailing list
>>>> [e-mail]
>>>> https://www.ietf.org/mailman/listinfo/netmod
>>> _______________________________________________
>>> netmod mailing list
>>> [e-mail]
>>> https://www.ietf.org/mailman/listinfo/netmod
>>>
>>