[netmod] Re: WGLC on draft-ietf-netmod-rfc8407bis

[Andy Bierman <[e-mail]>]

On Mon, Oct 21, 2024 at 2:38 PM Lou Berger <[e-mail]> 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, [e-mail] 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 <[e-mail]>
> >> Envoyé : lundi 14 octobre 2024 18:24
> >> À : BOUCADAIR Mohamed INNOV/NET <[e-mail]>
> >> Cc : Mahesh Jethanandani <[e-mail]>; Lou Berger
> >> <[e-mail]>; [e-mail]; draft-ietf-netmod-
> >> [e-mail]; Jan Lindblad <[e-mail]>; Kent
> >> Watsen <[e-mail]>
> >> 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 <[e-mail]>
> >> 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 <[e-mail]> *Envoyé :*
> >> samedi
> >>> 12 octobre 2024 01:54 *À :* BOUCADAIR Mohamed INNOV/NET
> >>> <[e-mail]> *Cc :* Lou Berger
> >> <[e-mail]>;
> >>> [e-mail]; [e-mail]; Jan
> >> Lindblad
> >>> <[e-mail]>; Kent Watsen <[e-mail]> *Objet
> >> :* Re:
> >>> [netmod] WGLC on draft-ietf-netmod-rfc8407bis
> >>>
> >>>
> >>>
> >>>
> >>> Hi Med,
> >>>
> >>>
> >>>
> >>> Speaking as a contributor ...
> >>>
> >>>
> >>>
> >>> On Oct 11, 2024, at 8:47 AM, [e-mail] 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'
> >>> <[e-mail]>; [e-mail];
> >>> [e-mail]; Jan Lindblad (jlindbla) <
> >>> [e-mail]> *Cc :* Kent Watsen <[e-mail]>
> >> *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 <[e-mail]>
> >>> *Envoyé :* mardi 1 octobre 2024 13:37
> >>> *À :* BOUCADAIR Mohamed INNOV/NET
> >> <[e-mail]>;
> >>> [e-mail]; [e-mail]; Jan
> >> Lindblad
> >>> (jlindbla) <[e-mail]>
> >>> *Cc :* Kent Watsen <[e-mail]> *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, [e-mail] 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.
>