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]
<mailto:kent%[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,
seehttps://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]:
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
<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];[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
inhttps://www.rfc-editor.org/rfc/rfc8340#section-3.3which
(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/
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 [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 [email protected]
<mailto:[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 [email protected]
