Hi Lou, et. al.
> On Oct 1, 2024, at 7:36 AM, Lou Berger <[email protected]> wrote:
>
> 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.
>
Agreed, at least not as a sole option (see "Options" at bottom)
> 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.
>
I’m unsure as well. Something to ask RFC Editor about? Presumably RFC Editor
would have to archive the linked artifacts as well - right?
In any case, RFC’s can/do have hyperlinks and, if not normative, it seems
technically possible to link an external artifact, as one of a few options
(again, see “Options" at bottom)
> 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.)
>
RFC 8340 says:
When long diagrams are included in a document,
authors should consider whether to include the long diagram in the
main body of the document or in an appendix.
Which I think is fine, and I don’t see a reason to change.
That said, I find that full/long diagrams sometimes exceed the 69-column limit,
thus requiring RFC 8792 folding, which (for me) usually comes out looking like
an absolute mess ;)
Options:
Guide the reader how to use `rfcstrip` and `rfcfold` to unfold the folded
diagram found in the Appendix of the plain-text version of the document.
Guild the reader how to use `rfcstrip` and `pyang` to generate the full/long
diagram on their local system.
Include a pointer to a stable URL for the unfolded version of the full/long
diagram
Do not include any guidance or the full/long diagrams in the Appendix. This
assumes that the document did a good job linking the unexpanded groupings in
the tree diagrams.
Some combination of the above?
Kent / contributor
> 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/.
>>
>> 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/
>> 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]> <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
>> 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/
>>
>> 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] <mailto:[email protected]>
>> 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.
> _______________________________________________
> netmod mailing list -- [email protected] <mailto:[email protected]>
> To unsubscribe send an email to [email protected]
> <mailto:[email protected]>
_______________________________________________
netmod mailing list -- [email protected]
To unsubscribe send an email to [email protected]
