Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-diagrams

[Vladimir Vassilev <[e-mail]>]

On 01/16/2018 11:56 AM, Martin Bjorklund wrote:

> Vladimir Vassilev <[e-mail]> wrote:
>> Hi,
>>
>> I have reviewed and implemented (apart from schema mount specific
>> functionality) draft-ietfetf-netmod-yang-tree-diagrams-04 and found
>> the following issues:
>>
>> ==sec 2.6.  Node Representation==
>>
>> 1. To correctly reflect the current pyang output one needs to add '--'
>> between <status> and <flags>.
>> OLD:
>>      <status> <flags> <name> <opts> <type> <if-features>
>> NEW:
>>      <status>--<flags> <name> <opts> <type> <if-features>
> Ok.
>
>> There is also undocumented alignment space count function before
>> <type> that pyang uses to align the <type> fields of child data leafs
>> with common ancestor. If this is specified in the draft the tree
>> output can be deterministic and for me this is an advantage. This is
>> currently one of the few underspecified pieces of the tree format so I
>> had to check pyang implementation in oder to generate same alignment
>> space counts and binary identical tree output results.
> I think that we at least should write that there may be more than one
> space between <opts> and <type>:
>
>    There may be any number of additional space characters between
>    <opts> and <type>.
For the sake of the argument (at least having this on the mailing list 
as reference):

   <type> should be aligned at a common offset for all sibling nodes
   from the start of <name> by adding trailing spaces. The recommended
   offset is 3 plus the length of the longest node name among all 
sibling nodes
   including those siblings defined under choice and case nodes.

This is what pyang does now. It is not a perfect solution but it allows 
identical output down to the bit.

>
> I also just realized that we need to add text to the line wrapping
> section about line breaks between <type> and <if-feature>:
>
> OLD:
>
>     Internet Drafts and RFCs limit the number of characters that may in a
>     line of text to 72 characters.  When the tree representation of a
>     node results in line being longer than this limit the line should be
>     broken between <opts> and <type>.  The type should be indented so
>     that the new line starts below <name> with a white space offset of at
>     least two characters.
>
> NEW:
>
>     Internet Drafts and RFCs limit the number of characters in a line
>     of text to 72 characters.  When the tree representation of a node
>     results in line being longer than this limit the line should be
>     broken between <opts> and <type>, or between <type> and
>     <if-feature>.  The new line should be indented so that it starts
>     below <name> with a white space offset of at least two characters.
>
>
>> 2. It is unclear which <flags> option should be used for rpc and
>> action input/output and child nodes and the notification child
>> nodes. pyang uses '-w' for input and input/* and 'ro' for output and
>> output/*:
>>
>>      module: ietf-netconf-partial-lock
>>        rpcs:
>>          +---x partial-lock
>>          |  +---w input
>>          |  |  +---w select*   string
>>      ...
> I'll do:
>
> OLD:
>
>         <flags> is one of:
>           rw  for configuration data
>           ro  for non-configuration data
>           -u  for uses of a grouping
>           -x  for rpcs and actions
>           -n  for notifications
>           mp  for nodes containing a "mount-point" extension statment
>
> 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 statment
OK
>
>> pyang also uses '--' as <flags> for augmentation data nodes for
>> actions input.
> I think that this is a bug in pyang, which I have now fixed.
OK
>
>>      ...
>>        augment
>> /rt:routing-state/rt:ribs/rt:rib/rt:active-route/rt:input:
>>          +---- destination-address?   inet:ipv4-address
>>      ...
>>
>>
>> 3. pyang is prefixing choice node names with the parent <flags>
>> e.g. +--ro (next-hop-options) while case nodes are not prefixed. I
>> guess this is a bug in pyang since it is not specified in the draft
>> but choice nodes prefixed with parent <flags> are  also present in the
>> sec 4 and 4.1 examples?
> [ignoring based on latest email from Vladimir]
>
>> 4. This bit I found confusing. I propose this change to unambiguously
>> describe the current pyang format.
>>
>> OLD:
>>           *  for a leaf-list or list
>>           [<keys>] for a list's keys
>> NEW:
>>           *  for a leaf-list or list without keys
>>           * [<keys>] for a list with keys
> Hmm, wouldn't it be better to use [] for a list w/o keys?
Yes I also agree this improves readability at the cost of slight 
redundancy increase and modification to format of diagrams already used 
in RFCs. Your call.

Vladimir
>
>
> /martin
>
>
>
>> Vladimir
>>
>> On 01/01/2018 11:01 PM, joel jaeggli wrote:
>>> Greetings,
>>>
>>> We hope  the new year is a time to make great progess on outstanding
>>> documents before preparation for the  London IETF begins in earnest.
>>>
>>> This starts a two-week working group last call on:
>>>
>>>    YANG Tree Diagrams
>>> draft-ietf-netmod-yang-tree-diagrams
>>>
>>> https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-tree-diagrams/
>>>
>>> Please send email to the list indicating your support or concerns.
>>>
>>> We are particularly interested in statements of the form:
>>>
>>>     * I have reviewed this draft and found no issues.
>>>     * I have reviewed this draft and found the following issues: ...
>>>
>>>
>>> Thank you,
>>> NETMOD WG Chairs
>> _______________________________________________
>> netmod mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/netmod