Re: [netmod] Tree diagram comment lines

[tom petch <[e-mail]>]

From: Kent Watsen <[e-mail]>
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

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

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.