On Tue, Mar 5, 2024 at 1:47 PM Kent Watsen <[email protected]> wrote:
> In addition to improving IETF-published artifacts, it would be nice if > there were a module-browser that acted a little bit like an IDE, jumping to > where in other modules imported bits are defined. Perhaps in > NetconfCentral or YANG Catalog. This jumping behavior could exist in both > the text and tree-diagram views. > > I like the plain-text full tree diagram that is usually present before the YANG module. Often the groupings and typedefs are from external modules, and/or are difficult to figure out. Yet the groupings and typedefs must be found and read to understand the model. It would be nice if the HTML version of the draft/RFC had links in the tree diagram to the actual YANG statements. DRY vs. WET: the structure of a YANG module (i.e. dividing into sections) is too complex have strict rules. A tree diagram for the definitions relevant to each section is usually helpful, in addition to the full tree diagram. I would avoid SHOULD and SHOULD NOT for this issue. > K. > Andy > > > On Mar 5, 2024, at 11:21 AM, Italo Busi <Italo.Busi= > [email protected]> wrote: > > I like the idea of relying on tooling with hyperlinks > > > > For txt and pdf, I agree that a link is the best option since these > formats are not optimized for including YANG trees > > Italo > > > > *From:* Kent Watsen <[email protected]> > *Sent:* martedì 5 marzo 2024 16:02 > *To:* [email protected] > *Cc:* Italo Busi <[email protected]>; Qin Wu <[email protected]>; > Mahesh Jethanandani <[email protected]>; [email protected] > *Subject:* Re: [netmod] Long trees RE: Next steps for > draft-ietf-netmod-rfc8407bis > > > > > > 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]> > *Envoyé :* lundi 4 mars 2024 19:38 > *À :* Qin Wu <[email protected]>; Mahesh Jethanandani < > [email protected]>; BOUCADAIR Mohamed INNOV/NET < > [email protected]> > *Cc :* [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]> > *Sent:* giovedì 29 febbraio 2024 02:51 > *To:* Mahesh Jethanandani <[email protected]>; > [email protected] > *Cc:* [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 in > https://github.com/YangModels/yang/tree/main/standard/ietf > > Is another option we can take a look at. > > > > -Qin > > *发件人**:* netmod [mailto:[email protected] <[email protected]>] > *代表 *Mahesh Jethanandani > *发送时间:* 2024年2月29日 7:02 > *收件人:* [email protected] > *抄送:* [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] 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 seen > https://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]> > *Envoyé :* mercredi 28 février 2024 15:21 > *À :* BOUCADAIR Mohamed INNOV/NET <[email protected]> > *Cc :* [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] 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]> De la part de > [email protected] > Envoyé : mercredi 28 février 2024 10:01 > À : [email protected] > Cc : [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%2Fdoc%2Fdraft-ietf-netmod- > rfc8407bis%2F&data=05%7C02%7Cmohamed.boucadair%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%2Farchive%2Fid%2Fdraft-ietf-netmod-rfc8407bis- > 09.html&data=05%7C02%7Cmohamed.boucadair%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%2Fiddiff%3Furl2%3Ddraft-ietf-netmod-rfc8407bis- > 09&data=05%7C02%7Cmohamed.boucadair%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::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] > 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] > https://www.ietf.org/mailman/listinfo/netmod > > > > > Mahesh Jethanandani > > [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] > https://www.ietf.org/mailman/listinfo/netmod > > > _______________________________________________ > netmod mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/netmod > > > _______________________________________________ > netmod mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/netmod >
_______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
