[netmod] Re: Paul Wouters' Discuss on draft-ietf-netmod-syslog-model-32: (with DISCUSS and COMMENT)

[Kent Watsen <[e-mail]>]

Hi Med,

The issue here isn’t how *long* the examples are, but how *wide* they are.

The syslog model itself is relatively small, but the tree diagrams blow up (in both length and width) just by using the TCP/TLS-client-server draft’s groupings.  There really isn’t a way for the syslog model to be broken into smaller pieces to get around this.

Regarding "The tree as displayed in the draft does not actually adhere with this part in 8407bis”, I got curious and looked.  Assuming the groupings are NOT expanded (which the rfc8407bis text below allows), I’m unsure what issue triggers.  Can you say?

Separately, I noticed that the document does not seem to use the `rfcfold` utility (RFC 8792), which may be a different issue that could be fixed.

Kent // as author


> On Sep 10, 2024, at 11:37 AM, [e-mail] wrote:
> 
> Re-,
>  
> The tree as displayed in the draft does not actually adhere with this part in 8407bis:
>  
>    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.
>  
> On the tooling side, we do have the following in the 8407bis:
>  
>       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.
>  
> I know that Italo tried to have a discussion in 121 with Carsten for md(?), but I don’t know if that discussion actually happened. Italo can clarify this.
>  
> Cheers,
> Med
>  
> De : Kent Watsen <[e-mail] <mailto:[e-mail]>>
> Envoyé : mardi 10 septembre 2024 17:07
> À : Joe Clarke (jclarke) <jclarke=[e-mail] <mailto:jclarke=[e-mail]>>
> Cc : [e-mail] <mailto:[e-mail]>; [e-mail] <mailto:[e-mail]>
> Objet : [netmod] Re: Paul Wouters' Discuss on draft-ietf-netmod-syslog-model-32: (with DISCUSS and COMMENT)
>  
> [removing the IESG]
>  
>  
> Hi Joe, authors, and NETMOD.
>  
> On Sep 10, 2024, at 10:04 AM, Joe Clarke (jclarke) <jclarke=[e-mail] <mailto:jclarke=[e-mail]>> wrote:
>  
> Thanks for the comments and feedback, Paul.  I’ve opened GitHub issuehttps://github.com/netmod-wg/syslog-model/issues/14 so Mahesh and I can track the necessary changes on our end.  See below for some initial responses.
>  
> The layout is completely broken / wrapped, making the document fairly
> unreadable. Can this be fixed somehow ?
> 
>  
> 
> [JMC] Éric had the same comment, and I thought we’d be good just expanding the full tree.  However, it seems this is causing readability and confusion problems. 
> 
> I ran into a similar “wrapping tree diagrams is ugly" comment in the suite of client-server drafts.   Not expanding the groupings in the tree diagrams helps, but still may not be enough - you just need to try and see how it looks.  That said, there is still one thing that can be done to improve the appearance of *folded” tree diagrams, which is epitomized by the following RFC Editor comment put into the documents:
>  
>          <t>Tree-diagrams in this draft may use the '&#92;' line-folding mode defined in RFC 8792.
>            However, nicer-to-the-eye is when the '&#92;&#92;' line-folding mode is used.  The AD suggested
>            suggested putting a request here for the RFC Editor to help convert "ugly" '&#92;' folded
>            examples to use the '&#92;&#92;' folding mode.  "Help convert" may be interpreted as, identify
>            what looks ugly and ask the authors to make the adjustment.</t>
>  
> PS: there is a desire to have Datatracker *unfold* folded artwork/sourcecode for document output formats that can support horizontal scrolling.  Specifically, for an HTML-rendered document, the ideal is for examples to be unfolded and placed into a textbox that causes a browser to create a textbox with horizontal scrolling.   I’m unsure if there is an open-ticket for this work to get done.
>  
> Kent // as contributor
>  
>  
>  
> ____________________________________________________________________________________________________________
> 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.