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://author-tools.ietf.org/api/iddiff?url_1=https://netmod-wg.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://netmod-wg.github.io/rfc8407bis/long-trees/draft-ietf-netmod-rfc8407bis.txt> > > > > 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://author-tools.ietf.org/api/iddiff?url_1=https://netmod-wg.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://netmod-wg.github.io/rfc8407bis/long-trees/draft-ietf-netmod-rfc8407bis.txt> > - PR: https://github.com/netmod-wg/rfc8407bis/pull/70/files > > > > 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://mailarchive.ietf.org/arch/msg/netmod/0Q0YiyNi15V-Szzf5awLVh-15_c/ > > 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://mailarchive.ietf.org/arch/msg/netmod/-b2HX0XUK49qJB19LHu6MC0D9zc/. > > > > Please note that for html version can still include the long tree, > > > > The tooling may evolve in the future to provide better rendering > > of too long trees. This tooling may offer (but not limited to), > > unfold trees, control of expanded views, ease navigation among > > various levels of a tree, support of hyperlinks, etc. When such a > > tooling is available, too long trees can be displayed in the HTML > > version of documents that include such trees. > > > > 1. The candidate change was shared with the WG prior to IETF#119: > https://mailarchive.ietf.org/arch/msg/netmod/x9aex0PO-KARyg5FtzjLNYrIpLY/ > 2. The thread was open for almost 1 month and a half: > > https://author-tools.ietf.org/iddiff?url1=draft-ietf-netmod-rfc8407bis-09&url2=draft-ietf-netmod-rfc8407bis-10&difftype=--html > > > > Cheers, > > Med > > > > *De :* Lou Berger <[email protected]> <[email protected]> > *Envoyé :* mardi 1 octobre 2024 00:24 > *À :* [email protected]; [email protected] > *Cc :* Kent Watsen <[email protected]> <[email protected]> > *Objet :* Re: [netmod] Re: WGLC on draft-ietf-netmod-rfc8407bis > > > > Hi, > > I have a late comment as contributor on this draft (based on a co-chair > discussion). > > Looking at the diff relative of section 3.4 to the original document, I > think the idea of referencing a URL versus an appendix is a bad idea. The > new text in question: > > " 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." > > I prefer the original in > https://www.rfc-editor.org/rfc/rfc8340#section-3.3 which > > (a) does not have conformance language and > > (b) keeps the information as available as the document itself by including > the long diagram in an appendix. > > I would like to see this section reverted to the original. > > Authors, > > What is the motivation for the change to URLs and making this a "SHOULD > NOT"? > > Thanks, > > Lou > ¶ > <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-rfc8407bis-17#section-3.4-1> > > On 9/20/2024 4:03 PM, Kent Watsen wrote: > > This WGLC has successfully closed. The document has moved to the WG State > "WG Consensus: Waiting for Write-Up”. > > > > Thank you everyone, especially Med, for your diligence in resolving issues! > > > > The next step is the Shepherd write-up. Would anyone in the WG be willing > to volunteer to help out with it? > > > > Thanks, > > Kent and Lou (chairs) > > > > > > > On May 6, 2024, at 9:57 AM, Kent Watsen <[email protected]> > <[email protected]> wrote: > > > > This email begins a two-week WGLC on: > > > > Guidelines for Authors and Reviewers of Documents Containing > YANG Data Models > > > https://datatracker.ietf.org/doc/draft-ietf-netmod-rfc8407bis/ > > > > Please take time to review this draft and post comments by May 20. > > Favorable comments are especially welcomed. > > > > No IPR has been declared for this document: > > https://mailarchive.ietf.org/arch/msg/netmod/1LDpkPi_C8cqktc7HXSZgyPDCBE/ > > > > Kent & Lou (as co-chairs) > > > > > > > > > > > > _______________________________________________ > netmod mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/netmod > > > > > > > _______________________________________________ > > netmod mailing list -- [email protected] > > To unsubscribe send an email to [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. > > ____________________________________________________________________________________________________________ > > 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] > > > > 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] To unsubscribe send an email to [email protected]
