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

[Lou Berger]

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.

Thanks,

Lou

On 10/15/2024 2:22 AM, mohamed.boucad...@orange.com 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 <a...@yumaworks.com>
Envoyé : lundi 14 octobre 2024 18:24
À : BOUCADAIR Mohamed INNOV/NET <mohamed.boucad...@orange.com>
Cc : Mahesh Jethanandani <mjethanand...@gmail.com>; Lou Berger
<lber...@labn.net>; netmod@ietf.org; draft-ietf-netmod-
rfc8407...@ietf.org; Jan Lindblad <jlind...@cisco.com>; Kent
Watsen <kent+i...@watsen.net>
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 <mohamed.boucad...@orange.com>
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 <mjethanand...@gmail.com> *Envoyé :*
samedi
12 octobre 2024 01:54 *À :* BOUCADAIR Mohamed INNOV/NET
<mohamed.boucad...@orange.com> *Cc :* Lou Berger
<lber...@labn.net>;
netmod@ietf.org; draft-ietf-netmod-rfc8407...@ietf.org; Jan
Lindblad
<jlind...@cisco.com>; Kent Watsen <kent+i...@watsen.net> *Objet
:* Re:
[netmod] WGLC on draft-ietf-netmod-rfc8407bis




Hi Med,



Speaking as a contributor ...



On Oct 11, 2024, at 8:47 AM, mohamed.boucad...@orange.com 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'
<lber...@labn.net>; netmod@ietf.org;
draft-ietf-netmod-rfc8407...@ietf.org; Jan Lindblad (jlindbla) <
jlind...@cisco.com> *Cc :* Kent Watsen <kent+i...@watsen.net>
*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 <lber...@labn.net>
*Envoyé :* mardi 1 octobre 2024 13:37
*À :* BOUCADAIR Mohamed INNOV/NET
<mohamed.boucad...@orange.com>;
netmod@ietf.org; draft-ietf-netmod-rfc8407...@ietf.org; Jan
Lindblad
(jlindbla) <jlind...@cisco.com>
*Cc :* Kent Watsen <kent+i...@watsen.net> *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, mohamed.boucad...@orange.com 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 -- netmod@ietf.org
To unsubscribe send an email to netmod-le...@ietf.org