Subject: [netmod] Tree diagram comment lines

From: tom petch <[email-masked]>
Date: Mon, 11 Apr 2022 10:52:07 +0000

Can a YANG tree diagram contain comment lines?

draft-ietf-teas-yang-te has a tree diagram of 40 pages and since the IETF has abolished the page number, then any reference into it could be a challenge.  For a YANG module, this can be ameliorated by inserting comment lines every page or two.

Can this be done with tree diagrams?

Tom Petch

---

From: Lou Berger <[email-masked]>
Date: Mon, 11 Apr 2022 11:02:28 +0000

Yes. See https://datatracker.ietf.org/doc/html/rfc8340#section-2.5

Lou

----------
On April 11, 2022 6:52:27 AM tom petch <[email-masked]> wrote:

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

---

From: Martin Björklund <[email-masked]>
Date: Mon, 11 Apr 2022 13:02:46 +0200 (CEST)

tom petch <[email-masked]> wrote:
> draft-ietf-teas-yang-te has a tree diagram of 40 pages and since the
> IETF has abolished the page number, then any reference into it could
> be a challenge.  For a YANG module, this can be ameliorated by
> inserting comment lines every page or two.
> 

Yes, "//" introduces a (line) comment.  See 2.5 of RFC 8340.

But a 40 page tree diagram isn't very useful anyway, imo.  If I want
the full tree diagram I can run a tool to generate it.  Tree diagrams
are best used in combination with explanatory text to explain certain
aspects of the module design.  Perhaps section 3.4 in RFC 8407 should
be updated to explain this.

/martin

---

From: Benoit Claise <[email-masked]>
Date: Mon, 11 Apr 2022 13:13:48 +0200

Hi Tom,

Martin beat me on this one.
So the famous +1 to his "in combination with explanatory text to explain 
certain aspects of the module design "reply :-)
We got rid a page number for a good reason (in the YANG world).

Regards, Benoit

On 4/11/2022 1:02 PM, Martin Björklund wrote:
> .

---

From: Kent Watsen <[email-masked]>
Date: Mon, 11 Apr 2022 11:21:24 +0000

> aspects of the module design.  Perhaps section 3.4 in RFC 8407 should be updated to explain this.

Agreed.   

The netconf-client-server and restconf-client-server drafts had “full” diagrams that were many pages long.  

Fixed by:

1) Introducing each grouping individually (I wrote a script to extract a particular grouping tree diagram)

2) Convert all diagrams to NOT expand groupings.  I.e., it prints just the grouping’s name. 

3) The text for each grouping includes the hyperlink to the other sections where the each used-grouping is defined. 

4) Remove from the document the mostly-useless super-long diagram. 

K.

---

From: <[email-masked]>
Date: Mon, 11 Apr 2022 11:50:14 +0000

Hi all, 

Agree with Martin.

Here is the note I'm using in some RFCs with long trees:  

   The full tree diagram of the module can be generated using the
   "pyang" tool [PYANG].  That tree is not included here because it is
   too long (Section 3.3 of [RFC8340]).  Instead, subtrees are provided
   for the reader's convenience.

Cheers,
Med

> -----Message d'origine-----
> De : netmod <[email-masked]> De la part de Martin
> Björklund
> Envoyé : lundi 11 avril 2022 13:03
> À : [email-masked]
> Cc : [email-masked]
> Objet : Re: [netmod] Tree diagram comment lines
> 
> But a 40 page tree diagram isn't very useful anyway, imo.  If I
> want the full tree diagram I can run a tool to generate it.  Tree
> diagrams are best used in combination with explanatory text to
> explain certain aspects of the module design.  Perhaps section 3.4
> in RFC 8407 should be updated to explain this.
> 
> 
> /martin
> 
> 
> 
> 
> >
> > Tom Petch

_________________________________________________________________________________________________________________________

Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
Thank you.

---

From: tom petch <[email-masked]>
Date: Mon, 11 Apr 2022 15:44:45 +0000

From: Kent Watsen <[email-masked]>
Sent: 11 April 2022 12:21

<tp>

Thank to you all for the responses.

I do like the full 40 page tree, as an appendix.  If I want to look for the use of e.g. ip-address then the full tree is much easier to riff through than lots of little pieces.  The I-D I mention has pieces as well, alongside text which I think right.  I prefer tree snippet then text as opposed to text then snippet.  The text is more detailed and I want to go from less detail to more detail.  And there have been cases of hand-crafted snippets being out-of-line with the YANG module which is easier to spot with a tool-generated full diagram which I see as more reliable.  (This last got through Last Call and the IESG - I wonder if the RFC Editor would have noticed).

Thinking more, I mostly use the tree as a way into the module especially when the module use many groupings. I often start reading a module and get lost and go back to the overall tree to see the overall structure with 'uses' expanded. What would be really useful would be a comment line in the module (only 38 pages in this instance) which pyang would recognise and turn into a comment line in the tree so that the two could more easily be correlated, YANG to tree or vice versa.

If  have to run my own tools, on a Windows system, then I will look for something more user friendly!

Tom Petch

Agreed.

Fixed by:

K.