On Mon, Oct 21, 2024 at 2:38 PM Lou Berger <[email protected]> wrote:
> Hi. > > Looking at today's (-20) version of the document, I still see stable > pointers as an option. I really don't see the support for this in the > overall discussion and I personally think such is a *bad* idea. > > I'd prefer that any references to the "stable pointer" option be removed > from the document. > > +1 Still do not understand the problem caused by YANG trees over 5 pages. > Thanks, > > Lou > Andy > > On 10/15/2024 2:22 AM, [email protected] wrote: > > Hi Andy, > > > > RFC8340 leaves it to the authors to include it or not. It uses > statements such as "When long diagrams are included in a document, .." > > > > An outcome of the discussion is that we can't impose one option here. > For example, the current situation is that we do already have RFCs > (RFC7407, RFC9182, RFC9291, etc.) that do not include the full trees > because these are too long, the narrative text is good enough, the document > itself is +150 pages, etc. Also, including pages and pages of text that > exceeds the max line is not convenient for readers. > > > > The new guidelines include a provision for when the full tree is not > included for better consistency among published documents. > > > > Cheers, > > Med > > > >> -----Message d'origine----- > >> De : Andy Bierman <[email protected]> > >> Envoyé : lundi 14 octobre 2024 18:24 > >> À : BOUCADAIR Mohamed INNOV/NET <[email protected]> > >> Cc : Mahesh Jethanandani <[email protected]>; Lou Berger > >> <[email protected]>; [email protected]; draft-ietf-netmod- > >> [email protected]; Jan Lindblad <[email protected]>; Kent > >> Watsen <[email protected]> > >> Objet : Re: [netmod] WGLC on draft-ietf-netmod-rfc8407bis > >> > >> > >> Hi, > >> > >> IMO we do not need new procedures to save the reader from a few > >> extra pages of YANG tree diagram text. > >> > >> This is the only option that makes sense to me: > >> > >> * Include the full tree in an appendix. > >> > >> Andy > >> > >> On Sun, Oct 13, 2024 at 10:19 PM <[email protected]> > >> wrote: > >> > >>> Hi Mahesh, > >>> > >>> > >>> > >>> Yes, this refers to the main body per the structure in > >> rfc7322#section-4. > >>> Updated accordingly. > >>> > >>> > >>> > >>> The diff is available using the same link: Diff: > >>> draft-ietf-netmod-rfc8407bis.txt - draft-ietf-netmod- > >> rfc8407bis.txt > >> <https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2 > >> Faut > >>> hor- > >> tools.ietf.org%2Fapi%2Fiddiff%3Furl_1%3Dhttps%3A%2F%2Fnetmod-wg.gi > >>> thub.io%2Frfc8407bis%2Fdraft-ietf-netmod- > >> rfc8407bis.txt%26url_2%3Dhttp > >>> s%3A%2F%2Fnetmod-wg.github.io%2Frfc8407bis%2Flong-trees%2Fdraft- > >> ietf-n > >>> etmod- > >> rfc8407bis.txt&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C3 > >> 60a053d61314c7851bc08dcec6c99f5%7C90c7a20af34b40bfbc48b9253b6f5d20 > >> %7C0 > >> %7C0%7C638645198411517106%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAw > >> MDAi > >> LCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata= > >> PUXU > >>> FFa2G1oGYjtnRYtC9hFJkRu5Nx%2FISQob3izoYds%3D&reserved=0> > >>> > >>> > >>> > >>> Thanks. > >>> > >>> > >>> > >>> Cheers, > >>> > >>> Med > >>> > >>> > >>> > >>> *De :* Mahesh Jethanandani <[email protected]> *Envoyé :* > >> samedi > >>> 12 octobre 2024 01:54 *À :* BOUCADAIR Mohamed INNOV/NET > >>> <[email protected]> *Cc :* Lou Berger > >> <[email protected]>; > >>> [email protected]; [email protected]; Jan > >> Lindblad > >>> <[email protected]>; Kent Watsen <[email protected]> *Objet > >> :* Re: > >>> [netmod] WGLC on draft-ietf-netmod-rfc8407bis > >>> > >>> > >>> > >>> > >>> Hi Med, > >>> > >>> > >>> > >>> Speaking as a contributor ... > >>> > >>> > >>> > >>> On Oct 11, 2024, at 8:47 AM, [email protected] wrote: > >>> > >>> > >>> > >>> Hi Lou, Kent, all, > >>> > >>> > >>> > >>> Taking into account the feedback received so far, I suggest the > >>> following > >>> change: > >>> > >>> > >>> > >>> OLD: > >>> > >>> 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. > >>> > >>> > >>> > >>> 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 main document. Instead, authors MAY > >> consider > >>> the following options: > >>> > >>> > >>> > >>> [mj] Not clear what you mean by “main document”. Do you mean the > >>> normative section of the document? If so, please edit it to say > >> that. > >>> > >>> > >>> Thanks > >>> > >>> > >>> > >>> > >>> > >>> * Provide only a stable pointer to retrieve the full tree. > >> The > >>> full > >>> > >>> tree is thus not provided at all. > >>> > >>> > >>> > >>> * Include a note about how to generate the full tree. > >>> > >>> > >>> > >>> * A combination of the first and second bullets. > >>> > >>> > >>> > >>> * Include the full tree in an appendix. > >>> > >>> > >>> > >>> For convenience: > >>> > >>> - Diff: Diff: draft-ietf-netmod-rfc8407bis.txt - > >>> draft-ietf-netmod-rfc8407bis.txt > >>> > >> <https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2 > >> Fauthor- > >> tools.ietf.org%2Fapi%2Fiddiff%3Furl_1%3Dhttps%3A%2F%2Fnetmod- > >> wg.github.io%2Frfc8407bis%2Fdraft-ietf-netmod- > >> rfc8407bis.txt%26url_2%3Dhttps%3A%2F%2Fnetmod- > >> wg.github.io%2Frfc8407bis%2Flong-trees%2Fdraft-ietf-netmod- > >> rfc8407bis.txt&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C360 > >> a053d61314c7851bc08dcec6c99f5%7C90c7a20af34b40bfbc48b9253b6f5d20%7 > >> C0%7C0%7C638645198411540339%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLj > >> AwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C& > >> sdata=68CtKMDgxzWjl4IsKqxJlSLpvOHAflb0Cv5TQFwExN0%3D&reserved=0> > >>> - PR: > >>> > >> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2F > >> gith > >>> ub.com%2Fnetmod- > >> wg%2Frfc8407bis%2Fpull%2F70%2Ffiles&data=05%7C02%7Cmoh > >> amed.boucadair%40orange.com%7C360a053d61314c7851bc08dcec6c99f5%7C9 > >> 0c7a > >> 20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638645198411557810%7CUnknown > >> %7CT > >> WFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJ > >> XVCI > >> 6Mn0%3D%7C0%7C%7C%7C&sdata=%2BkYIcnZV7Wwi4tUS6uOObRMUMcdt4xxyiNBOW > >> QXGp > >>> wE%3D&reserved=0 > >>> > >>> > >>> > >>> Better? > >>> > >>> > >>> > >>> Cheers, > >>> > >>> Med > >>> > >>> > >>> > >>> *De :* BOUCADAIR Mohamed INNOV/NET > >>> *Envoyé :* mercredi 2 octobre 2024 11:13 *À :* 'Lou Berger' > >>> <[email protected]>; [email protected]; > >>> [email protected]; Jan Lindblad (jlindbla) < > >>> [email protected]> *Cc :* Kent Watsen <[email protected]> > >> *Objet > >>> :* RE: [netmod] Re: WGLC on draft-ietf-netmod-rfc8407bis > >>> > >>> > >>> > >>> Hi Lou, > >>> > >>> > >>> > >>> - Keeping long trees in the main document is really not > >> helpful to > >>> digest a module. I also know by experience that this raises > >> comments, > >>> including from the IESG. > >>> - Keeping long trees that exceed 69 line max in the main or > >> as an > >>> appendix is really hard to follow. > >>> - There are already RFCs out there do not include long trees, > >> but a > >>> note about how to generate it. The narrative text uses small > >> snippets to > >>> help readers walk through the model. > >>> - Some consistency is needed in how we document our modules + > >> help > >>> authors with clear guidance (e.g., characterize what is a > >> long > >>> tree) > >>> > >>> > >>> > >>> I’m afraid that we can’t simply leave the OLD 8407 as it is. > >>> > >>> > >>> > >>> That’s said, I’m only the pen holder and will implement whatever > >> the > >>> WG decides here. > >>> > >>> > >>> > >>> Cheers, > >>> > >>> Med > >>> > >>> > >>> > >>> *De :* Lou Berger <[email protected]> > >>> *Envoyé :* mardi 1 octobre 2024 13:37 > >>> *À :* BOUCADAIR Mohamed INNOV/NET > >> <[email protected]>; > >>> [email protected]; [email protected]; Jan > >> Lindblad > >>> (jlindbla) <[email protected]> > >>> *Cc :* Kent Watsen <[email protected]> *Objet :* Re: [netmod] > >> Re: > >>> WGLC on draft-ietf-netmod-rfc8407bis > >>> > >>> > >>> > >>> Med, Jan, WG, > >>> > >>> I have to say that I read the discussion concluding with to NOT > >> change > >>> the current recommendation, see > >>> > >> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2F > >> mail > >>> archive.ietf.org%2Farch%2Fmsg%2Fnetmod%2F0Q0YiyNi15V-Szzf5awLVh- > >> 15_c%2 > >> F&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C360a053d61314c78 > >> 51bc > >> 08dcec6c99f5%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C63864519 > >> 8411 > >> 573595%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzI > >> iLCJ > >> BTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=FuJbQGSOk7%2FkMXATR > >> 1fn3 > >>> YScP4MBfkRWYvYXz90NyNI%3D&reserved=0 > >>> > >>> I personally use an ereader (or computer) more than paper and > >> having > >>> to go to a static URL -- probably when I'm off line -- does NOT > >> seem > >>> like something we should be recommending. Furthermore, I'm not > >> sure > >>> what our process has to say about having the HTML include *text > >>> content* that is not in the text version. > >>> > >>> Again just my perspective. > >>> > >>> What do others think? do they feel strongly that this change > >> from the > >>> current recommendation (in RFC8340) of having long trees in > >> appendixes > >>> is a good or bad idea? (Yes, I'm in the strongly against camp.) > >>> > >>> Thanks, > >>> > >>> Lou > >>> > >>> On 10/1/2024 4:24 AM, [email protected] wrote: > >>> > >>> Hi Lou, > >>> > >>> > >>> > >>> 1. The comment that triggered the change and companion thread > >> where > >>> this was discussed and changes proposed can be seen at: > >>> > >>> > >> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2F > >> mail > >>> archive.ietf.org%2Farch%2Fmsg%2Fnetmod%2F- > >> b2HX0XUK49qJB19LHu6MC0D9zc%2F&data=05%7C02%7Cmohamed.boucadair%40o > >> range.com%7C360a053d61314c7851bc08dcec6c99f5%7C90c7a20af34b40bfbc4 > >> 8b9253b6f5d20%7C0%7C0%7C638645198411584985%7CUnknown%7CTWFpbGZsb3d > >> 8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3 > >> D%7C0%7C%7C%7C&sdata=r4xdN4asqklRHaI%2BIixWX29CCw7i1QBlmAHlNXrKjng > >> %3D&reserved=0 > > > ____________________________________________________________________________________________________________ > > 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] To unsubscribe send an email to [email protected]
