Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[Kent Watsen <[e-mail]>]

As a contributor:

I don’t like the YIN format, but Lada makes some good points below.

I don’t understand the "extraction code should not be needed any more” comment, but know that Shepherds and, to a lesser extent, Copy Editors, rely on being able to extract the YANG modules and/or instance examples from the `xml2rfc` XML files.

K.


> On Nov 11, 2020, at 8:52 AM, Ladislav Lhotka <[e-mail]> wrote:
> 
> tom petch <[e-mail]> writes:
> 
>> 
>> <tp>
>> In the category of general annoyance, rather than the points above, the IETF has abolished the page number.  Look at recent RFC and pagination has vanished.  The justification is that RFC are now available in different format and that page numbers are not consistent across the format so they must be eliminated.
>> 
>> This came up on RFC Interest and I asked how to reference a piece of text and was told that you include lots of section numbers.  I asked about 50-page YANG modules with no sections but this is a requirement that has escaped the tool-makers.  One suggestion was to include lots of numbered sub-headings, another to include separate sourcecode elements with an anchor for each.
> 
> I share your concerns, but these developments are hard to avoid - people want to read the documents on the small screens of their phones, and a fixed format isn't well suited for that.
> 
>> One passing comment was that with v3 xml the extraction code should not be needed any more.  I do not understand but expect that there will be interesting times.
> 
> I don't know what the plan is, but in the recent survey on IETF authoring tools, I suggested the option of including YANG modules in xml2rfc sources as foreign-namespace blocks in the YIN format. This could solve most of these issues and, in particular, allow for safely reflowing text in descriptions etc. along with the rest of the RFC.
> 
> Regarding markup inside description/contact/reference/error-message, I think XML is in fact still the best option. Light-weight choices such as markdown are too brittle for these purposes.
> 
> Lada