It seems that there are two camps:
1) those that want the tree-diagrams to be as DRY as possible
2) those that want the tree-diagrams to be as WET as possible
DRY = Don't Repeat Yourself
WET = Write Every Time
Tooling can help both cases.
For (1), the tree-diagrams are unexpanded, but surrounding text should point to
where each used-grouping is defined. The better tooling-assisted approach, is
for the used groupings *inside the tree-diagram” to become hyperlinks (only
possible in supporting formats). Extending this idea further, hyperlinks
could be provided for typedefs and identities too.
For (2), for plain-text and PDF formats, a link to where the image can be
accessed would be nice. For the HTML format, inlining the complete (unfolded)
tree-diagram with horizontal-scrolling would be ideal.
Kent
> On Mar 5, 2024, at 3:01 AM, [email protected] wrote:
>
> Hi Italo,
>
> Thanks for sharing your thoughts.
>
> Please see inline.
>
> Cheers,
> Med
>
> De : Italo Busi <[email protected] <mailto:[email protected]>>
> Envoyé : lundi 4 mars 2024 19:38
> À : Qin Wu <[email protected] <mailto:[email protected]>>; Mahesh
> Jethanandani <[email protected] <mailto:[email protected]>>;
> BOUCADAIR Mohamed INNOV/NET <[email protected]
> <mailto:[email protected]>>
> Cc : [email protected] <mailto:[email protected]>
> Objet : RE: [netmod] Long trees RE: Next steps for
> draft-ietf-netmod-rfc8407bis
>
> Hi Med,
>
> In my personal experience, I have found the YANG tree included in the IETF
> RFCs/I-Ds useful only when they are complete, even if they are too long
> [Med] I agree that having readily available full trees is useful, however the
> question is whether it should be embedded in the RFC text or would having
> stable links to access such trees be much more convenient? Note also that
> when the tree is too long, there are better places to display them for better
> user experience (control views, etc.), which we don’t have with the txt
> version.
>
> In RFC8795 you can find an example of a too-long YANG tree which I am using
> quite often
>
> [Med] If the Datatracker includes a link to the tree or 8795 includes a
> stable pointer to the full tree without the editing limitations of IETF docs,
> the experience would be the same, if not better. No?
>
>
> I have found YANG trees with unexpanded grouping almost impossible to use. In
> draft-ietf-teas-yang-te you can find an example of a YANG tree with
> unexpanded grouping which I am not using at all. In this case, I refer to the
> YANG catalog to get the complete tree
>
> [Med] ACK.
>
> I have also found the YANG tree pieces almost useless (even if much better
> than the YANG trees with unexpanded grouping) without some overview.
>
> [Med] Not having an overview to describe the overall structure and help
> readers navigate among all the various levels is a bug of these specs, IMO.
> The narrative part of the spec is supposed to help readers digest the
> structure and zoom in/out when diving into specifics. I think that we need
> collectively to better explain the rationale of a module design and
> articulating the various parts of a module. The use of subtrees for too long
> trees is a means to help structure the description sections.
>
> RFC8348 is an example of YANG tree pieces which I am using very rarely. In
> most of the cases, I refer to the YANG catalog to get the complete tree
> [Med] ACK.
>
> I am wondering whether the issue of YANG tree too-long could be resolved by
> updating the IETF tooling. For example, I have noted that the html-ized
> version of the I-Ds is now working well with artwork exceeding the 72
> characters limit …
>
> Maybe the html or html-ized version of the I-D/RFC might include the jstree
> pyang output instead of the tree pyang output
>
> [Med] Fully agree that tooling is the way to go here. Having a stable pointer
> to the tree (including displaying it from the Datatracker metadata) would
> achieve that objective.
>
> Back to the txt version, here is an updated version of the reco (for further
> discussion):
>
> ==
> NEW:
> YANG tree diagrams provide a concise representation of a YANG module
> and SHOULD be included to help readers understand YANG module
> structure. If the complete tree diagram for a module becomes long
> (more than 2 pages, typically), the diagram SHOULD be split into
> several smaller diagrams (a.k.a subtrees). For the reader's
> convenience, a subtree should fit within a page. If the complete
> tree diagram is too long (more than 5 pages, typically) even with
> groupings unexpanded (Section 2.2 of [RFC8340]), the authors SHOULD
> NOT include it in the document. A stable pointer to retrieve the
> full tree MAY be included.
>
> The document SHOULD include the following note if the full tree is
> not included:
>
> -- If no stable pointer to retrieve the tree is included
>
> The full tree diagram of the module can be generated using,
> e.g., the "pyang" tool. That tree is not included here because
> it is too long (Section 3.4 of [RFCXXXX]). Instead, subtrees
> are provided for the reader's convenience.
>
> -- If a stable pointer to retrieve the tree is included
>
> The full tree diagram of the module can be retrieved at
> <stable_url_ref>. That tree is not included here because it is too
> long (Section 3.4 of [RFCXXXX]). Instead, subtrees are provided
> for the reader's convenience.
>
> These guidelines take precedence over the generic guidance in
> Section 3 of [RFC8340].
> ==
>
> My 2 cents
>
> Italo
>
> From: Qin Wu <[email protected] <mailto:[email protected]>>
> Sent: giovedì 29 febbraio 2024 02:51
> To: Mahesh Jethanandani <[email protected]
> <mailto:[email protected]>>; [email protected]
> <mailto:[email protected]>
> Cc: [email protected] <mailto:[email protected]>
> Subject: Re: [netmod] Long trees RE: Next steps for
> draft-ietf-netmod-rfc8407bis
>
> +1, a few thoughts to share.
>
> I know this is tricky question related to tooling or artifact generation and
> representation.
> I am wondering whether we can make YANG tree diagram in a "collapsed" state
> where all the Leaf nodes and only leaf nodes are hidden from view until its
> parent node is expanded, which can improve readability of the tree diagram,
> In many cases can greatly reduce the size of YANG tree diagram, make it fit
> into one page.
>
> Moving compete tree diagram or artifacts is another option we can pursue.
> Also generating YANG tree along with YANG file
> inhttps://github.com/YangModels/yang/tree/main/standard/ietf
> Is another option we can take a look at.
>
> -Qin
> 发件人: netmod [mailto:[email protected]] 代表 Mahesh Jethanandani
> 发送时间: 2024年2月29日 7:02
> 收件人: [email protected] <mailto:[email protected]>
> 抄送: [email protected] <mailto:[email protected]>
> 主题: Re: [netmod] Long trees RE: Next steps for draft-ietf-netmod-rfc8407bis
>
> I would agree with Andy that it is not clear how long is “too long”.
>
> BGP YANG model, which is perhaps one of the biggest models at 150 pages long,
> has multiple tree diagrams none of which are more than one page long.
>
> If the complete tree diagram is too long, could it moved to the Appendix,
> instead of banishing it from the document completely? Sorry Jan, but I hope
> no one is cutting down trees to read the entire tree diagram. Sometimes,
> albeit rarely, it is helpful to have the complete tree diagram handy to
> reference where a particular node is in the tree.
>
> Cheers.
>
>
> On Feb 28, 2024, at 8:29 AM, [email protected]
> <mailto:[email protected]> wrote:
>
> Hi Jan,
>
> Thanks for the comments.
>
> Here is a first attempt to address the long trees point while taking into
> account expanded/unexpanded uses:
>
> NEW:
> YANG tree diagrams provide a concise representation of a YANG module
> and SHOULD be included to help readers understand YANG module
> structure. If the complete tree diagram for a module becomes too
> long, the diagram SHOULD be split into several smaller diagrams. If
> the complete tree diagram is too long even with groupings unexpanded
> (Section 2.2 of [RFC8340]), authors SHOULD NOT include it in the
> document.
>
> These guidelines take precedence over the generic guidance in
> Section 3 of [RFC8340].
>
> For convenience a diff for the proposed change can be
> seenhttps://author-tools.ietf.org/api/iddiff?url_1=https://boucadair.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://boucadair.github.io/rfc8407bis/long-trees/draft-ietf-netmod-rfc8407bis.txt
>
> Cheers,
> Med
>
> De : Jan Lindblad <[email protected] <mailto:[email protected]>>
> Envoyé : mercredi 28 février 2024 15:21
> À : BOUCADAIR Mohamed INNOV/NET <[email protected]
> <mailto:[email protected]>>
> Cc : [email protected] <mailto:[email protected]>
> Objet : Re: [netmod] Next steps for draft-ietf-netmod-rfc8407bis
>
> Med, author team,
>
> Thank you for taking the time to get this work done, and well done! This is
> one of those fundamental bricks that saves time and improves quality for the
> entire YANG community.
>
> I read the -09 version and like what I see. I have a couple of minor
> suggestions you might consider.
>
> + In section 3.4 about tree diagrams, the section text is already advocating
> intermixing smaller tree snippets with explanations (which is great), but I
> wish we could say that
> tree diagrams of entire modules SHOULD NOT be included. Just a waste of
> forest and attention span, imho.
>
> + In section 4.2 about choice of prefixes, it is said that "Prefix values
> SHOULD be short but are also likely to be unique." I used to say the same
> thing. In recent years, however, I have started to stress the importance of
> uniqueness much more. I'd say something like "Prefix values SHOULD be
> selected carefully to be unique, and ideally not too long." The reason for my
> change is I have met several engineers who have been deeply confused (to the
> point of costing real money) when the same prefix has shown up in multiple
> places. It's just an unnecessary part of the learning curve associated with
> YANG.
>
> In fact, I have started to recommend people to set the prefix to equal the
> module name. This also solves another problem, which is that the "prefixes"
> you see in RESTCONF are module names, and the confusion of what to use where
> is sometimes suffocating. I understand if many think I'm going overboard
> here, but when we pretend that modules don't have prefixes, only module
> names, there is a lot less friction in learning the ropes.
>
> + In section 4.6.2 regarding useless (in YANG Context) functions in the XPath
> function library, it is said that the "YANG compiler" should return false,
> etc. Better wording might be that the XPath execution environment (or
> something) should return false, etc. The YANG compiler is not even running
> when the calls to those functions are happening.
>
> + In section 4.11.5 regarding booleans, it is said that booleans can take
> values true and false. This is true in mathematics :-) but in YANG a boolean
> leaf can additionally take the "value" of "not set". Actually, "not set" is a
> possibility for leafs in general, unless it is declared mandatory true, or
> has a default. In my experience, one of the most common YANG modeling issues
> is when people model a leaf foo, which isn't mandatory, has no default and
> the description statement does not say what happens if the leaf is not set.
> In many cases, there is a sort of natural meaning, but with booleans leafs in
> particular, the absence of the leaf is typically highly ambiguous. I think
> this hole merits a recommendation clause in the I-D.
>
> Best Regards,
> /jan
>
>
>
>
> On 28 Feb 2024, at 10:51, [email protected]
> <mailto:[email protected]> wrote:
>
> Hi all,
>
> I think that this version is ready for the WGLC.
>
> The document fully covers the items promised when requesting adoption [1]. As
> listed in the ACK section, we also solicited and integrated feedback from
> many yangdoctors, solicited SAAG WG to review the security text, etc. Refer
> to 1.1 for a comprehensive list of the changes.
>
> Cheers,
> Med
>
> [1] Slide#7 of
> https://datatracker.ietf.org/meeting/117/materials/slides-117-netmod-7-guidelines-for-authors-and-reviewers-of-documents-containing-yang-data-models-00
>
>
>
> -----Message d'origine-----
> De : I-D-Announce <[email protected]
> <mailto:[email protected]>> De la part de
> [email protected] <mailto:[email protected]>
> Envoyé : mercredi 28 février 2024 10:01
> À : [email protected] <mailto:[email protected]>
> Cc : [email protected] <mailto:[email protected]>
> Objet : I-D Action: draft-ietf-netmod-rfc8407bis-09.txt
>
> Internet-Draft draft-ietf-netmod-rfc8407bis-09.txt is now available.
> It is a work item of the Network Modeling (NETMOD) WG of the IETF.
>
> Title: Guidelines for Authors and Reviewers of Documents
> Containing YANG Data Models
> Authors: Andy Bierman
> Mohamed Boucadair
> Qin Wu
> Name: draft-ietf-netmod-rfc8407bis-09.txt
> Pages: 84
> Dates: 2024-02-28
>
> Abstract:
>
> This memo provides guidelines for authors and reviewers of
> specifications containing YANG modules, including IANA-maintained
> modules. Recommendations and procedures are defined, which are
> intended to increase interoperability and usability of Network
> Configuration Protocol (NETCONF) and RESTCONF protocol
> implementations that utilize YANG modules. This document obsoletes
> RFC 8407.
>
> Also, this document updates RFC 8126 by providing additional
> guidelines for writing the IANA considerations for RFCs that
> specify
> IANA-maintained modules.
>
> The IETF datatracker status page for this Internet-Draft is:
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdata
> <https://data/>
> tracker.ietf.org <http://tracker.ietf.org/>%2Fdoc%2Fdraft-ietf-netmod-
> rfc8407bis%2F&data=05%7C02%7Cmohamed.boucadair%40orange.com
> <http://40orange.com/>%7C51672231
> 30c943a5a4c608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C
> 638447076716455966%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjo
> iV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=s5VX9Hb%2Fl
> P9v5QurysF69syyEyba9yYss7xd7K5E2FE%3D&reserved=0
>
> There is also an HTML version available at:
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
> <https://www/>.
> ietf.org <http://ietf.org/>%2Farchive%2Fid%2Fdraft-ietf-netmod-rfc8407bis-
> 09.html&data=05%7C02%7Cmohamed.boucadair%40orange.com
> <http://40orange.com/>%7C5167223130c943
> a5a4c608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638447
> 076716464395%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=%2Br3nHahSq8OV24f
> hFxBkJaqY43Q0GUxcbPZSFhji4uk%3D&reserved=0
>
> A diff from the previous version is available at:
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fauth
> <https://auth/>
> or-tools.ietf.org
> <http://or-tools.ietf.org/>%2Fiddiff%3Furl2%3Ddraft-ietf-netmod-rfc8407bis-
> 09&data=05%7C02%7Cmohamed.boucadair%40orange.com
> <http://40orange.com/>%7C5167223130c943a5a4c
> 608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C63844707671
> 6470644%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLC
> JBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=zo%2FrtFJrYJkJXOceIpzR
> mlGAQF2c8m9Z%2F0vShl5o8gQ%3D&reserved=0
>
> Internet-Drafts are also available by rsync at:
> rsync.ietf.org <http://rsync.ietf.org/>::internet-drafts
>
>
>
> ____________________________________________________________________________________________________________
> 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.
>
> _______________________________________________
> netmod mailing list
> [email protected] <mailto:[email protected]>
> https://www.ietf.org/mailman/listinfo/netmod
>
>
> ____________________________________________________________________________________________________________
> 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.
> _______________________________________________
> netmod mailing list
> [email protected] <mailto:[email protected]>
> https://www.ietf.org/mailman/listinfo/netmod
>
>
> Mahesh Jethanandani
> [email protected] <mailto:[email protected]>
>
>
>
>
>
>
> ____________________________________________________________________________________________________________
> 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.
> _______________________________________________
> netmod mailing list
> [email protected] <mailto:[email protected]>
> https://www.ietf.org/mailman/listinfo/netmod
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
