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

From: joel jaeggli <[email-masked]>
Date: Mon, 1 Jan 2018 14:01:45 -0800

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

---

From: joel jaeggli <[email-masked]>
Date: Wed, 10 Jan 2018 08:16:54 -0800

Just a reminder given the date that this was posted. This last call is
expected to complete Monday 1/15/18.

Thanks

joel

---

From: Qin Wu <[email-masked]>
Date: Sat, 13 Jan 2018 03:49:34 +0000

The draft is well written and I found no issue with it.

Sent from HUAWEI AnyOffice
发件人： joel jaeggli
收件人： NETMOD Working Group;
抄送： [email-masked];
主题： [netmod] Reminder: WGLC - draft-ietf-netmod-yang-tree-diagrams
时间： 2018-01-11 00:17:32

Thanks

joel

>   * I have reviewed this draft and found the following issues: ...

_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: "t.petch" <[email-masked]>
Date: Sat, 13 Jan 2018 13:00:19 -0000

I think that the outstanding issue is what to do with long tree
diagrams. Yes, we have discussed it and have a statement about one page
being a good idea but very few of the I-Ds I see can manage that.

RIP has four pages, NAT has six.  OSPF and BFD have divided the diagram
up but many if not most of the subdivisions still exceed one page (I
would regard two as more or less ok but many exceed that).

My own take is that a too long tree diagram reflects a too flat module
structure, just as many years ago, code would be a long unbroken
sequence and now is divided up into manageable modules, so a YANG module
should be structured as smaller pieces, bite-size chunks, and a tree
diagram of one page is a good indicator of a manageable chunk size.

Tom Petch

----- Original Message -----
From: "joel jaeggli" <[email-masked]>
Sent: Monday, January 01, 2018 10:01 PM

Greetings,

 YANG Tree Diagrams

Thank you,
NETMOD WG Chairs

------------------------------------------------------------------------
--------

---

From: Benoit Claise <[email-masked]>
Date: Sat, 13 Jan 2018 15:08:27 +0100

Hi Tom,

IMO, the best to proceed is exactly like done in the RIP draft.
Some sections 2.* explains how the module was build, based one excerpts 
of the tree diagram.
Then we have the full tree if someone wants to see the big structure.

In the end, the tree view should be browsed with tooling.
https://datatracker.ietf.org/doc/draft-ietf-rtgwg-yang-rip/
    => Yang catalog entry for [email-masked] 
<https://www.yangcatalog.org/yang-search/module_details.php?module=[email-masked]>
    => [Tree View for ietf-rip] Tree View 
<https://www.yangcatalog.org/yang-search/yang_tree.php?module=ietf-rip>

Regards, Benoit
> .

---

From: Robert Wilton <[email-masked]>
Date: Mon, 15 Jan 2018 10:53:23 +0000

Hi,

I agree with all of Benoit's points below.

On 13/01/2018 14:08, Benoit Claise wrote:
> Some sections 2.* explains how the module was build, based one 
> excerpts of the tree diagram.
Yes, smaller chunks of tree output can be very useful to explain parts 
of the model.

> Then we have the full tree if someone wants to see the big structure.
Yes, personally, I think that it is probably useful to have the full 
tree output as a reference (probably even if it is 10 pages long). If it 
is particularly long then it would be better put into an appendix.

> <https://www.yangcatalog.org/yang-search/yang_tree.php?module=ietf-rip>
+1, having a GUI interface into YANG modules (and the combined YANG tree 
with all standard YANG models augmented together) seems like it should 
be the future.

>> diagram of one page is a good indicator of a manageable chunk size.
I think its hard to judge whether a module is too flat or not.

I'm more concerned that YANG groupings make it easy to repeat large 
chunks of YANG in multiple places in a module tree, and I'm not 
convinced that this is always the right thing to do.  Sometimes it may 
be better to add a layer of indrection to avoid the need to reuse the 
same large chunk of YANG in multiple places in the tree. Of course, this 
is all highly subjective ...

Thanks,
Rob

>> From: "joel jaeggli"<[email-masked]>

---

From: Robert Wilton <[email-masked]>
Date: Mon, 15 Jan 2018 13:56:07 +0000

Hi Lou, Martin

I've done a quick review of draft -04.

It looks well written to me.

I have a spotted a few minor nits/questions.

Section 1:

(i) "Such diagrams are commonly used to provided " => "Such diagrams are 
used to provide"?

(ii) "This document provides the syntax used in YANG Tree Diagrams." => 
"This document describes the syntax used in YANG Tree Diagrams", or if 
not "describes", perhaps "specifies"?

(iii) "common practice is include" => "common practice is to include"

Section 2:
(iv) Are the top level data nodes really offset by 4 spaces, or should 
this be 2 spaces?  The example in section 2, and section 4 seem to 
differ here.  The submodule example in Sec 2.1 looks like it is using 2 
spaces.

(v) "is prefaces with" => "is prefaced with"

(vi) Section 2.2, should there be an example of an unexpanded uses 
statement?  I was wondering if this section was under specified?

Section 2.6:
(vii) "If the node is augmented into the tree from another module, its 
name is printed as <prefix>:<name>."  Does there need to be a 
clarification that the prefix name used is the one used by the module's 
import statement?  Or does it use the prefix statement from the imported 
modules instead (I know that these should normally be the same, but this 
is not guaranteed).

Section 3.2.
(viii) It would be slightly easier to read if there wasn't a linebreak 
between "--" and "tree-print-groupings", not sure if that is feasible to 
force this.

Thanks,
Rob

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 15 Jan 2018 15:39:33 +0100 (CET)

Hi,

Thanks for the review!  Comments inline.

Robert Wilton <[email-masked]> wrote:
> (i) "Such diagrams are commonly used to provided " => "Such diagrams
> are used to provide"?

Ok.

> (ii) "This document provides the syntax used in YANG Tree Diagrams."
> => "This document describes the syntax used in YANG Tree Diagrams", or
> if not "describes", perhaps "specifies"?

I changed to "describes".

> (iii) "common practice is include" => "common practice is to include"

Ok.

> differ here.  The submodule example in Sec 2.1 looks like it is using
> 2 spaces.

It should be 4 spaces.  I fixed the example in 2.1.

> (v) "is prefaces with" => "is prefaced with"

Ok.

> statement?  I was wondering if this section was under specified?

I have added:

   For example, the following diagram shows the "tls-transport" grouping
   from [RFC7407] unexpanded:

       +--rw tls
          +---u tls-transport

   If the grouping is expanded, it could be printed as:

       +--rw tls
          +--rw port?                 inet:port-number
          +--rw client-fingerprint?   x509c2n:tls-fingerprint
          +--rw server-fingerprint?   x509c2n:tls-fingerprint
          +--rw server-identity?      snmp:admin-string

> clarification that the prefix name used is the one used by the
> module's import statement?  Or does it use the prefix statement from
> the imported modules instead (I know that these should normally be the
> same, but this is not guaranteed).

Since this is used when a node is augmented *into* the main tree, it
can't be the prefix in import, since the augmenting module is not
imported from the augmented module.  I did:

OLD:

      If the node is augmented into the tree from another module,
      its name is printed as <prefix>:<name>.

NEW:

      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.

> between "--" and "tree-print-groupings", not sure if that is feasible
> to force this.

I don't think I can enforce this, but I'll look into it.  If nothing
else, the RFC editor will fix this.

/martin

---

From: Robert Wilton <[email-masked]>
Date: Mon, 15 Jan 2018 15:07:22 +0000

Hi Martin,

All OK with me except where I have further comments/questions inline below:

> It should be 4 spaces.  I fixed the example in 2.1.
Hum, OK.  Is this the right choice?
  - It means that the tree is indented 2 spaces further than everything 
else (e.g. groupings, augments, etc).
  - YANG modules in RFC's already struggle with line length anyway, 
hence wouldn't the use of 2 spaces give the model a bit more space.

I also think that it would be good to check the indent of all the tree 
diagram snippets in the doc, it looks like they may be using somewhat 
varying levels of indents (between 2 and 6 spaces).

>            +--rw server-identity?      snmp:admin-string
Yes, looks good.

> imported from the augmented module.  I did:
But the YANG module must import the module that it is augmenting. If a 
local import prefix is used in the actual YANG module then it would be 
slightly harder to relate the tree output back to local import prefixes 
used in the YANG module.

>        prefix defined in the module where the node is defined.
This is OK with me, but there is still a potential for a prefix 
namespace clash (since prefixes are not guaranteed to be unique).

An alternative solution would be for the YANG tree diagram to list (at 
the beginning or the end of the diagram) the mappings from prefix -> 
module name used.  This has the bonus that it also explicitly lists the 
YANG modules that are being augmented, but conversely, this might end up 
just adding unnecessary noise to a diagram that should be short and 
simple ...

A second alternative would be to add some vague text to state that the 
prefix to module mapping should be explicitly listed in any cases where 
the prefix name alone is not obvious.

Thanks,
Rob

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Mon, 15 Jan 2018 15:19:51 +0000

Hi Rob, 

On 1/15/18, 10:07 AM, "netmod on behalf of Robert Wilton -X (rwilton -
ENSOFT LIMITED at Cisco)" <[email-masked] on behalf of

>varying levels of indents (between 2 and 6 spaces).

I agree - it is already hard to fit the tree diagrams into RFCs.

Thanks,
Acee

---

From: Lou Berger <[email-masked]>
Date: Mon, 15 Jan 2018 10:26:01 -0500

Rob,
	Thanks for all the helpful feedback!

On 01/15/2018 10:07 AM, Robert Wilton wrote:
...

> An alternative solution would be 
I don't we need to optimize for a every corner case.  We have the actual
module that provides detail.

> for the YANG tree diagram to list (at

I think this falls in the category of unnecessary noise.  At least at
this time.

Lou
(as contributor)

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 15 Jan 2018 16:26:23 +0100 (CET)

> else (e.g. groupings, augments, etc).

Well, I think it is consistent as it is now:

module: <module-name>
    +--<node>
    |  +--<node>
    |     +--<node>
    +--<node>
       +--<node>
          +--<node>

  augment <target-node>:
    +--<node>
       +--<node>
       +--<node>
          +--<node>

Nodes are always intended 4 spaces.

> hence wouldn't the use of 2 spaces give the model a bit more space.

This is a good argument.  I'm happy to save spaces by using 2 instead:

module: <module-name>
  +--<node>
  |  +--<node>
  |     +--<node>
  +--<node>
     +--<node>
        +--<node>

  augment <target-node>:
  +--<node>
     +--<node>
     +--<node>
        +--<node>

Ok.

> slightly harder to relate the tree output back to local import
> prefixes used in the YANG module.

Here's an example:

module: ietf-interfaces
    +--rw interfaces
    |  +--rw interface* [name]
    |     +--rw name                        string
    ...
    |     +--rw ip:ipv4!

ietf-interfaces doesn't import ietf-ip, so there is no other prefix to
use for "ipv4" than the one defined in ietf-ip!

> module name used.

The tree diagram is supposed to give a simplified overview of the
structure of a module.  I agree with your statemenet below that such a
mappig adds noise...  I prefer to keep the diagram as is.

/martin

> This has the bonus that it also explicitly lists
> the YANG modules that are being augmented, but conversely, this might
> end up just adding unnecessary noise to a diagram that should be short
> and simple ...
> 
> prefix to module mapping should be explicitly listed in any cases
> where the prefix name alone is not obvious.
> 
> Thanks,
> Rob
> 
> 
> >
> >> Section 3.2.

---

From: Robert Wilton <[email-masked]>
Date: Mon, 15 Jan 2018 15:48:38 +0000

> Nodes are always intended 4 spaces.
Yes, agree that it is consistent, but personally I would also be happy 
for the nodes to be intended 2 spaces for the main tree, and then 4 
spaces for everything else (effectively 2 spaces beyond the 
augment/rpc/etc).

> This is a good argument.  I'm happy to save spaces by using 2 instead:
I think that compact is better, if not quite so pretty, so this solution 
is also OK with me.

Personally, I quite like a relative indent, i.e. the tree is intended 2 
spaces more than its parent "thing", e.g.

module: <module-name>
   +--<node>
   |  +--<node>
   |     +--<node>
   +--<node>
      +--<node>
         +--<node>

   augment <target-node>:
     +--<node>
        +--<node>
        +--<node>
           +--<node>

> use for "ipv4" than the one defined in ietf-ip!
Ah, yes, OK.  I was assuming that the tree diagram would always be done 
from the augmenting module, but clearly that is not necessarily the case.

> mappig adds noise...  I prefer to keep the diagram as is.
That is fine with me, really just raising so that the point could be 
discussed and closed.

Thanks,
Rob

---

From: Vladimir Vassilev <[email-masked]>
Date: Mon, 15 Jan 2018 21:41:55 +0100

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>

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.

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
     ...

pyang also uses '--' as <flags> for augmentation data nodes for actions 
input.

     ...
       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?

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

Vladimir

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 16 Jan 2018 09:45:17 +0100 (CET)

Ok.

> I think that compact is better, if not quite so pretty, so this
> solution is also OK with me.
> 
> Personally, I quite like a relative indent, i.e. the tree is intended
> 2 spaces more than its parent "thing", e.g.
> 
> module: <module-name>
>   +--<node>
>   |  +--<node>
>   |     +--<node>
>   +--<node>
>      +--<node>
>         +--<node>
> 
>   augment <target-node>:
>     +--<node>
>        +--<node>
>        +--<node>
>           +--<node>

Ok, I will use this.

/martin

> Ah, yes, OK.  I was assuming that the tree diagram would always be
> done from the augmenting module, but clearly that is not necessarily
> the case.
> 
> 
> >
> >>> OLD:
> >>>

---

From: Vladimir Vassilev <[email-masked]>
Date: Tue, 16 Jan 2018 10:19:34 +0100

On 01/15/2018 09:41 PM, Vladimir Vassilev wrote:
> functionality) draft-ietfetf-netmod-yang-tree-diagrams-04 and found 
> the following issues:
>
> 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.
>
>
> 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/*:
>
> pyang also uses '--' as <flags> for augmentation data nodes for 
> actions input.
>
>     ...
> +--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?
Ignore 3. choice had a config substatement which explains the presence 
of <flags>.

---

From: Benoit Claise <[email-masked]>
Date: Tue, 16 Jan 2018 10:51:11 +0100

> That is fine with me, really just raising so that the point could be 
Sections such as this one are super useful and should ideally become 
common practice.
https://tools.ietf.org/html/draft-ietf-netmod-rfc8022bis-08#section-2.3

Regards, Benoit

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 16 Jan 2018 11:56:06 +0100 (CET)

Ok.

> 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>.

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.

> action input/output and child nodes and the notification child
> nodes. pyang uses '-w' for input and input/* and 'ro' for output and
> output/*:
> 

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

> pyang also uses '--' as <flags> for augmentation data nodes for

I think that this is a bug in pyang, which I have now fixed.

>     ...
>       augment
> /rt:routing-state/rt:ribs/rt:rib/rt:active-route/rt:input:
> 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]

>          * [<keys>] for a list with keys

Hmm, wouldn't it be better to use [] for a list w/o keys?

/martin

---

From: Vladimir Vassilev <[email-masked]>
Date: Tue, 16 Jan 2018 16:08:50 +0100

>    There may be any number of additional space characters between
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.

>           mp  for nodes containing a "mount-point" extension statment
OK
> I think that this is a bug in pyang, which I have now fixed.
OK
> 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

---

From: Robert Wilton <[email-masked]>
Date: Tue, 16 Jan 2018 15:15:27 +0000

>> Vladimir Vassilev <[email-masked]> wrote:
<snipped>
> redundancy increase and modification to format of diagrams already 
> used in RFCs. Your call.

I like the idea of using [] for a list without keys, to cleanly 
differentiate list vs leaf-list.

I presume that they don't turn up that much in practice, so presumably 
not many RFC's would be impacted.

Thanks,
Rob

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 16 Jan 2018 16:40:53 +0100 (CET)

> > Vladimir Vassilev <[email-masked]> wrote:

[...]

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

Does anyone else have an opinion on this?  I can see three
alternatives:

  1) allow any number of addtional spaces
  2) allow any number of addtional spaces + define a suggested
     alignment algorithm
  3) mandate the alignment algorithm

/martin

---

From: Lou Berger <[email-masked]>
Date: Tue, 16 Jan 2018 10:18:22 -0500

> redundancy increase and modification to format of diagrams already used

(as contributor) I agree with martin on this point.

Lou

---

From: Robert Wilton <[email-masked]>
Date: Tue, 16 Jan 2018 16:01:48 +0000

>    3) mandate the alignment algorithm

Definition of symbols should be precise/consistent, so that readers can 
consistently interpret tree diagrams.

I think that flexibility in layout should be OK, but the draft should 
provide guideline to ensure the output is readable, and likely to be 
broadly consistent (since consistency aids readability).

If the IETF data modeling group is trying to specify text output 
precisely enough that it can be screen scraped then we may want to 
consider whether we are focusing on the right solution ;-)

In summary, (2) is my preference, followed by (1), followed by (3).

Thanks,
Rob

---

From: joel jaeggli <[email-masked]>
Date: Tue, 16 Jan 2018 09:24:06 -0800

The current dicussion on the draft is not yet concluded. The WGLC will
conclude when discussion of the editorial changes is complete.

Thanks
joel

---

From: joel jaeggli <[email-masked]>
Date: Tue, 16 Jan 2018 09:34:28 -0800

>> Vladimir Vassilev <[email-masked]> wrote:
<snip>
> Definition of symbols should be precise/consistent, so that readers
> can consistently interpret tree diagrams.
>
I would hope that we are not, as the diagrams are programmatically 
generated if you wanted to for example validate them one should do that
from the sources. 

Approaches that result in the most easily human readable, followed by
consistency between tools is probably better for that. That said this is
almost the indentation wars so the proscriptive it gets the more dissent
you can probably find (e.g. 3).

---

From: Vladimir Vassilev <[email-masked]>
Date: Tue, 16 Jan 2018 20:19:38 +0100

> you can probably find (e.g. 3).
To make it clear I think 1) works with the text proposed by Martin.

As said I posted the pyang alignment algorithm description in a sort of 
2) variant only for reference on the mailing list since I implemented 
that too. Starting indentation war was not my intention.

As for the automated validation of the tree diagrams as an added value 
to the human readability I have the following thoughts. I would like to 
be able to compare unlimited line length tree outputs generated by 
different YANG compilers for equality. This is mainly a way to have some 
partial common denominator output for validating YANG is correctly 
compiled which we did not have until now. For example as soon as I have 
support for Schema mount I would compare the tree output with another 
tool known to work and add some testcases based on that. I do not see 
any automated alternative for doing this except writing NETCONF chat 
scripts (also module specific), or writing not only YANG module specific 
but also API specific test cases as 3rd option. 1) does not compromise 
this automated validation option since space sequences can be collapsed 
to single space. If the alignment algorithm was creating a possibility 
for nontrivial output variation then I would have supported strongly 3) 
but this is not the current case.

Vladimir

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 16 Jan 2018 21:06:36 +0100

On Tue, Jan 16, 2018 at 08:19:38PM +0100, Vladimir Vassilev wrote:
> 
> As for the automated validation of the tree diagrams as an added value to
> the human readability I have the following thoughts. I would like to be able
> to compare unlimited line length tree outputs generated by different YANG
> compilers for equality. This is mainly a way to have some partial common
> denominator output for validating YANG is correctly compiled which we did
> not have until now. For example as soon as I have support for Schema mount I
> would compare the tree output with another tool known to work and add some
> testcases based on that. I do not see any automated alternative for doing
> this except writing NETCONF chat scripts (also module specific), or writing
> not only YANG module specific but also API specific test cases as 3rd
> option. 1) does not compromise this automated validation option since space
> sequences can be collapsed to single space. If the alignment algorithm was
> creating a possibility for nontrivial output variation then I would have
> supported strongly 3) but this is not the current case.
>

If you want to make sure a YANG compiler is correct, simply write a
backend that generates a serialized YANG module in canonical
form. They YANG modules should be the same. Determining YANG compiler
correctness by comparing tree diagrams does not seem to be a
convincing approach since tree diagrams by design leave many details
out.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Alexander Clemm <[email-masked]>
Date: Wed, 17 Jan 2018 02:20:53 +0000

+1 to (2) as preference, followed by (1).  I don't think (3) is needed here.  The purpose is to make this human-readable and provide readers a good sense of the overall structure.  The authoritative specification is still the .yang itself.  Providing some guidance for how to represent the tree is good but let's not over-engineer this; I believe retaining some flexibility is good. 

--- Alex 

> -----Original Message-----
...
> I think that flexibility in layout should be OK, but the draft should provide
> guideline to ensure the output is readable, and likely to be broadly consistent
> (since consistency aids readability).
> 
> If the IETF data modeling group is trying to specify text output precisely
> enough that it can be screen scraped then we may want to consider whether
> we are focusing on the right solution ;-)
>

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 17 Jan 2018 08:43:18 +0100 (CET)

Alexander Clemm <[email-masked]> wrote:
> +1 to (2) as preference, followed by (1).  I don't think (3) is needed
> here.  The purpose is to make this human-readable and provide readers
> a good sense of the overall structure.  The authoritative
> specification is still the .yang itself.  Providing some guidance for
> how to represent the tree is good but let's not over-engineer this; I
> believe retaining some flexibility is good.

The last sentence summarizes my personal view.  I prefer (1), followed
by (2).

/martin

> > provide
> > precisely

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 17 Jan 2018 09:30:05 +0100

> The last sentence summarizes my personal view.  I prefer (1), followed

+1

/js

---

From: Vladimir Vassilev <[email-masked]>
Date: Wed, 17 Jan 2018 10:08:02 +0100

> convincing approach since tree diagrams by design leave many details
The advantage I see is that 'uses' and 'augments' are resolved in the 
tree output. For example one can not cach bug in the reolution of the 
configure flag in a uses expanded under case with "configure false;" by 
generating YANG with unresolved 'uses'.  Another example - one can not 
represent the result of multiple modules augmenting e.g. /interfaces 
with a YANG module. The only universal representation is the YANG tree.

Vladimir

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 17 Jan 2018 10:17:52 +0100

On Wed, Jan 17, 2018 at 10:08:02AM +0100, Vladimir Vassilev wrote:
> 
> The advantage I see is that 'uses' and 'augments' are resolved in the tree
> output. For example one can not cach bug in the reolution of the configure
> flag in a uses expanded under case with "configure false;" by generating
> YANG with unresolved 'uses'.  Another example - one can not represent the
> result of multiple modules augmenting e.g. /interfaces with a YANG module.
> The only universal representation is the YANG tree.
>

But then the tree diagram leave out tons of other details. Anyway, if
you insist on using tree diagrams for testing, your test can simply
tolerate white space differences.

/js

---

From: Robert Wilton <[email-masked]>
Date: Wed, 17 Jan 2018 10:10:57 +0000

> The last sentence summarizes my personal view.  I prefer (1), followed
OK, so the "Providing some guidance for how to represent the tree is 
good" is along the lines of what I was thinking for the "algorithm" 
would be for 2.

E.g. something along the lines of:
"Arbitrary whitespace is allowed between any of the whitespace separated 
fields (e.g. <opts> and <type>).  Additional whitespace may be used to 
column align fields (e.g. within a list or container) to improve 
readability".

But just saying implementations can use arbitrary whitespace is also 
fine with me.  I certainly err on the side of not being overly 
prescriptive on this ..

I'm not really a fan of the comparing tree output as a method of 
verifying a YANG parser idea.

Thanks,
Rob

---

From: "t.petch" <[email-masked]>
Date: Wed, 17 Jan 2018 09:52:27 -0000

----- Original Message -----
From: "Alexander Clemm" <[email-masked]>
Sent: Wednesday, January 17, 2018 2:20 AM

> +1 to (2) as preference, followed by (1).  I don't think (3) is needed
here.  The purpose is to make this human-readable and provide readers a
good sense of the overall structure.

<tp>

That's what I thought until Benoit said, and Robert agreed, that

'In the end, the tree view should be browsed with tooling.'

i.e. the tree view should be machine readable after which something is
produced for human consumption; not a view I share.

Tom Petch

   The authoritative specification is still the .yang itself.  Providing
some guidance for how to represent the tree is good but let's not
over-engineer this; I believe retaining some flexibility is good.
> > Definition of symbols should be precise/consistent, so that readers
can
precisely

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 17 Jan 2018 11:24:57 +0100 (CET)

Hi,

Robert Wilton <[email-masked]> wrote:
> "Arbitrary whitespace is allowed between any of the whitespace
> separated fields (e.g. <opts> and <type>).  Additional whitespace may
> be used to column align fields (e.g. within a list or container) to
> improve readability".

This is fine with me.  It is something in between (1) and (2) which
people preferred.  I will add this text.

> verifying a YANG parser idea.

This is getting off-topic, but if an implementor wants to do this in
order to verify his implementation, go for it!  It doesn't have to be
discussed on this ML.  Speaking from own experience of two different
implementations, I can tell you that it is a useful test to do ;-)

/martin

---

From: Robert Wilton <[email-masked]>
Date: Wed, 17 Jan 2018 10:44:18 +0000

Hi Tom,

> 'In the end, the tree view should be browsed with tooling.'
The text based YANG tree diagram (i.e. covered by this draft) doesn't 
need to be browsable by tooling.  The purpose of these diagrams should 
be to go in text documents to help explain and illustrate (to human 
readers) the structure of a YANG model.

By "In the end, the tree view should be browsed with tooling.", what I 
mean is that I think that tools like YANG catalog will be the long term 
way of interacting with and browsing YANG modules.  For example, the 
link below for the RIP module.

https://www.yangcatalog.org/yang-search/yang_tree.php?module=ietf-rip

This provides an interactive GUI "tree view" of a YANG model, which 
should be structurally equivalent as the text tree diagram, but 
otherwise the information may be represented in a more visual way. This 
will become even more powerful when all of the standard YANG modules are 
available together in a single browsable tree.

Hopefully, that clarifies my previous comment.

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 17 Jan 2018 11:46:26 +0100

> produced for human consumption; not a view I share.

I think they did not say that the tooling should rely on tree views
published in RFCs as input. We should discourage tools to read tree
rendings as input; tools should read YANG modules as input. I doubt
Benoit's tools read tree views as input.

/js

---

From: Benoit Claise <[email-masked]>
Date: Wed, 17 Jan 2018 14:21:53 +0100

Hi Tom,
> mean is that I think that tools like YANG catalog will be the long 
> term way of interacting with and browsing YANG modules. For example, 
> the link below for the RIP module.
>
> otherwise the information may be represented in a more visual way. 
> This will become even more powerful when all of the standard YANG 
> modules are available together in a single browsable tree.
>
Exactly what I meant.
'In the end, the tree view should be browsed with tooling.' doesn't mean 
that the tree diagram, to be inserted in the RFC text,(according to 
draft-ietf-netmod-yang-tree-diagrams-04 
<https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-tree-diagrams/>should 
be browsed with tooling.

Sorry if it was not clear.

Regards, Benoit

---

From: Jeff Tantsura <[email-masked]>
Date: Wed, 17 Jan 2018 09:35:57 -0800

+1 to 2

Cheers,
Jeff

On 1/16/18, 07:41, "netmod on behalf of Martin Bjorklund" <[email-masked] on behalf of [email-masked]> wrote:

    [...]

    

    /martin

---

From: "t.petch" <[email-masked]>
Date: Wed, 17 Jan 2018 17:29:52 -0000

----- Original Message -----
From: "Robert Wilton" <[email-masked]>
Sent: Wednesday, January 17, 2018 10:44 AM

> mean is that I think that tools like YANG catalog will be the long
term
> otherwise the information may be represented in a more visual way.
This
> Hopefully, that clarifies my previous comment.

Yes, thank you for the clarification,

Tom Petch

> >>> guideline to ensure the output is readable, and likely to be
broadly
> > consistent

---

From: joel jaeggli <[email-masked]>
Date: Mon, 22 Jan 2018 14:05:33 -0800

Greetings,

This WGLC is concluded.

We have consensus to advance the document.

The authors should submit an update reflecting the result of the
dicussion on the text representation of tree diagrams not being usable
by machine parsers.

The exchange between Robert Wilton and Martin Bjorkland I think sums
this up succinctly.

(Robert)

(Martin)

Thanks all, looking forward to IETF last call.

joel

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 23 Jan 2018 12:03:51 +0100 (CET)

Hi,

I just posted draft-ietf-netmod-yang-tree-diagrams-05.txt.  It
addressed the issue below, and the other WGLC issues:

  o  the main tree now uses 2 spaces for indentation instead of 4

  o  added example for expanded/unexpanded grouping

  o  fixed errors in the row syntax

  o  aligned all examples to use proper amount of whitespace
     indentation

This document should now be ready to progress.

/martin