new lines in descriptions

[raetsch]

Hi,

i use pyang with flatten to create an export of yang-files with a subset of data. One of the fields is "description". In the description fields are sometimes new lines that should not be there. Example: grouping NH-INFO-SPECIAL-PUNT-DETAIL-HARDWARE-INGRESS { description "Common node of nh-info-special-detail-hardware-ingress, nh-info-special-mpls-detail-hardware-ingress"; container nh-info-special-punt-detail-hardware-ingress { description "Detail hardware ingress info for special-punt NHInfo entry"; uses FIB-SH-NHINFO; } } in vendor/cisco/xr/781/Cisco-IOS-XR-fib-common-oper.yang

I can imagine that this is nice for some people as it rises the readability inside yang-models, but it would be good to remove them (at least in newer releases from now on).

regards raetsch

[einarnn]

@raetsch, this is really an IETF or vendor issue. This repo only publishes what the vendors and the IETF publish, so they will see this comment. However, what I will add is that when processing description fields an embedded \n is a completely valid character, as are leading spaces or tabs.

And it is pretty simple to take strings and, in Python, use packages like textwrap, textwrap.dedent in particular, and create single-line strings if that is what you need.

[raetsch]

@einarnn , thx for your reply. i understood that this is a vendor issue, but as far as i know is this here the somehow official place (at least for cisco) for documenting yang models, so i gave it a try. i already fix this "issue" with a script, but sometimes scripts don't age well and as i am not exporting files for every release, i need this twice or thrice a year. and as everyone needs to deal with it (decentrally so to say), i thought i give it a try to centralise the "solution".

regards raetsch

[einarnn]

@raetsch, I just took a look across multiple vendors' models and those from the IETF and IEEE. from that brief review I can confidently say that there is no single style of description that wins out. There are even differences within single vendors when it comes to styling of descriptions. The IETF model exhibit what I would term "best practice". For example:

      leaf description {
        type string;
        description
          "A textual description of the interface.

           A server implementation MAY map this leaf to the ifAlias
           MIB object.  Such an implementation needs to use some
           mechanism to handle the differences in size and characters
           allowed between this leaf and ifAlias.  The definition of
           such a mechanism is outside the scope of this document.

           Since ifAlias is defined to be stored in non-volatile
           storage, the MIB implementation MUST map ifAlias to the
           value of 'description' in the persistently stored
           configuration.";
        reference
          "RFC 2863: The Interfaces Group MIB - ifAlias";
      }

Why I say this is that:

• each line is consistently indented
• each line keeps within a fixed maximum length
• extra new lines are inserted to signify new paragraphs of the description

This approach promotes readability of the model itself (which is one of the goals the IETF had) and allows for consistent reformatting to be performed by automated tooling. Writing as an employee of one vendor (Cisco), I can say that our comments in YANG files are automatically formatted into YANG from a variety of non-YANG source formats, and we attempted (imperfectly) to conform to the IETF style. Because our development teams are distributed across the OSes we use on our platforms, we have slightly different tooling and thus slightly different description formats 😕

However, this is still not an issue for the YangModels/yang team, and so I'll close off this issue.