On 01/16/2018 11:56 AM, Martin Bjorklund wrote:
Vladimir Vassilev <[email protected]> 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
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
