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

[[e-mail]]

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]>
Envoyé : mardi 10 septembre 2024 17:07
À : Joe Clarke (jclarke) <jclarke=[e-mail]>
Cc : [e-mail]; [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 issue https://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.