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 > <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] <mailto:[email protected]>>; > [email protected] <mailto:[email protected]>; > [email protected] > <mailto:[email protected]>; Jan Lindblad (jlindbla) > <[email protected] <mailto:[email protected]>> > Cc : Kent Watsen <[email protected] <mailto:[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] <mailto:[email protected]>> > Envoyé : mardi 1 octobre 2024 13:37 > À : BOUCADAIR Mohamed INNOV/NET <[email protected] > <mailto:[email protected]>>; [email protected] > <mailto:[email protected]>; [email protected] > <mailto:[email protected]>; Jan Lindblad (jlindbla) > <[email protected] <mailto:[email protected]>> > Cc : Kent Watsen <[email protected] <mailto:[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/ > <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] > <mailto:[email protected]> wrote: > Hi Lou, > > 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/ > <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. > > The candidate change was shared with the WG prior to > IETF#119:https://mailarchive.ietf.org/arch/msg/netmod/x9aex0PO-KARyg5FtzjLNYrIpLY/ > <https://mailarchive.ietf.org/arch/msg/netmod/x9aex0PO-KARyg5FtzjLNYrIpLY/> > 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 > > <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]> <mailto:[email protected]> > Envoyé : mardi 1 octobre 2024 00:24 > À : [email protected] <mailto:[email protected]>; > [email protected] > <mailto:[email protected]> > Cc : Kent Watsen <[email protected]> <mailto:[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 > <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]> > <mailto:[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/ > <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/ > <https://mailarchive.ietf.org/arch/msg/netmod/1LDpkPi_C8cqktc7HXSZgyPDCBE/> > > Kent & Lou (as co-chairs) > > > > > > _______________________________________________ > netmod mailing list > [email protected] <mailto:[email protected]> > https://www.ietf.org/mailman/listinfo/netmod > <https://www.ietf.org/mailman/listinfo/netmod> > > > > > _______________________________________________ > netmod mailing list -- [email protected] <mailto:[email protected]> > To unsubscribe send an email to [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. > ____________________________________________________________________________________________________________ > 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]> > To unsubscribe send an email to [email protected] > <mailto:[email protected]> Mahesh Jethanandani [email protected]
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
