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

From: Michael Richardson <[email-masked]>
Date: Fri, 06 Nov 2020 16:24:12 -0500

As people do more YANG modules, more and more logic and description moves
from regular text into the YANG module.  Where it is awkward and annoying to
edit.

And references from YANG modules don't get counted/resolved/updated, and
all sorts things that the XML format was designed to solve have basically
reverted to 1996 era (without even nroff) when it comes text in the YANG module.

In one of my drafts, I guess some minor wording tweaks in one draft leads to
some lines exceeding 72 characters (by one). Argh. Change from C-mode to
text-mode. reflow.

It seems like we should be thinking about what to do here.
I was introduced to the SED method of fixing yang YYYYMMDD version
references.

While I like YANG as executable "code", it sure feels like it is not smart to
be authoring in it.

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 6 Nov 2020 22:39:15 +0100

> some lines exceeding 72 characters (by one). Argh. Change from C-mode to

https://www.emacswiki.org/emacs/yang-mode.el
https://www.emacswiki.org/emacs/download/yang-mode.el

Grüße, Carsten

---

From: Michael Richardson <[email-masked]>
Date: Fri, 06 Nov 2020 19:06:08 -0500

> https://www.emacswiki.org/emacs/download/yang-mode.el

Yes, turns out I already have used this, but forgot I had it.
I don't see anything that helps.
M-q reflowed a paragraph, but made it too long with 76 columns wide.

And that still doesn't help get the references in the description right.

---

From: Julian Reschke <[email-masked]>
Date: Sat, 7 Nov 2020 05:55:56 +0100

Am 06.11.2020 um 22:24 schrieb Michael Richardson:
> ...

Suggestions:

- find a way to break down the YANG code into smaller pieces
- explore whether xml2rfc should allow limited markup in
<artwork>/<sourcecode> (for references, for instance)

(the latter I've been doing in rfc2629.xslt for years, see, for
instance: <https://greenbytes.de/tech/webdav/rfc7230.html#rfc.section.3.2>

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 7 Nov 2020 06:07:41 +0100

> M-q reflowed a paragraph, but made it too long with 76 columns wide.

Is your .emacs setting fill-column to a non-standard value?

C-x f 69 RET

or put

// -*- fill-column: 69 -*-

into the first line of your YANG file (in a comment)
or better

(add-hook 'yang-mode-hook
	  '(lambda () (set-fill-column 69)))

in your .emacs.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 7 Nov 2020 06:09:32 +0100

> instance: <https://greenbytes.de/tech/webdav/rfc7230.html#rfc.section.3.2>

Better suggestion:
Create an authoring language for YANG.

(The problem is unrelated to the one xml2rfc solves.)

Grüße, Carsten

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 09 Nov 2020 10:13:35 +0100

Hi,

my solution that I've been using for years is to write YANG modules in the YIN syntax. With the nXML mode of emacs this is actually rather effective (statement completion, on-the-fly validation).

I also extended the YIN syntax with a few XML elements from the XHTML namespace. This helps me to handle paragraphs and lists in a safe way.

Descriptions etc. are then reflowed automatically as a part of XSLT transform to the compact YANG syntax.

Here are the details:

https://gitlab.nic.cz/labs/yang-tools/-/wikis/editing_yang

See also https://github.com/llhotka/YANG-I-D

Lada

Michael Richardson <[email-masked]> writes:

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

-- 
Ladislav Lhotka 
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: William Lupton <[email-masked]>
Date: Mon, 9 Nov 2020 09:38:26 +0000

I ensured that I have the latest version of the Emacs YANG mode, and find
that M-q works well to wrap description strings, but...

   1. Should I expect intelligent behaviour of RET and TAB when within a
   description (or other) string? I find that (in this context) RET positions
   the cursor at the start of the line, and TAB does nothing. Ideally RET
   might position the cursor at the indentation point of the previous line, or
   one character past the opening quote if this was the first line.
   2. Wrapping (quite reasonably) can't handle cases where the author
   didn't in fact intend line breaks to be inserted. The most common cases are
   probably (a) not using a blank line as a paragraph break, (b) text was
   further indented (which often implies literal text), or (c) text started
   with * (or -, ...) and was to be interpreted as a list item.

I don't believe that RFCs 7950 and 8407 say anything about paragraph
formatting, but most NETMOD YANG does seem to adhere to the convention that
paragraphs should be separated by blank lines. Perhaps this could be made
into a stronger convention?

As for the other cases (further indentation -> literal, and */- mean list
items), of course this is getting back to the markdown discussion. I
believe that when this has come up before the discussion has died for want
of clear standards. However I do believe that it would be very useful to
define some layout conventions (or rules) that allow automated reflow and
other formatting, and personally I would take it further than just the
three points that I have mentioned! It doesn't have to be called
'markdown'...

William

---

From: tom petch <[email-masked]>
Date: Tue, 10 Nov 2020 12:47:18 +0000

From: netmod <[email-masked]> on behalf of William Lupton <[email-masked]>
Sent: 09 November 2020 09:38
To: NetMod WG
Cc: [email-masked]
Subject: Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

I ensured that I have the latest version of the Emacs YANG mode, and find that M-q works well to wrap description strings, but...

  1.  Should I expect intelligent behaviour of RET and TAB when within a description (or other) string? I find that (in this context) RET positions the cursor at the start of the line, and TAB does nothing. Ideally RET might position the cursor at the indentation point of the previous line, or one character past the opening quote if this was the first line.
  2.  Wrapping (quite reasonably) can't handle cases where the author didn't in fact intend line breaks to be inserted. The most common cases are probably (a) not using a blank line as a paragraph break, (b) text was further indented (which often implies literal text), or (c) text started with * (or -, ...) and was to be interpreted as a list item.

I don't believe that RFCs 7950 and 8407 say anything about paragraph formatting, but most NETMOD YANG does seem to adhere to the convention that paragraphs should be separated by blank lines. Perhaps this could be made into a stronger convention?

As for the other cases (further indentation -> literal, and */- mean list items), of course this is getting back to the markdown discussion. I believe that when this has come up before the discussion has died for want of clear standards. However I do believe that it would be very useful to define some layout conventions (or rules) that allow automated reflow and other formatting, and personally I would take it further than just the three points that I have mentioned! It doesn't have to be called 'markdown'...

<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.
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.

Tom Petch

William

On Sat, 7 Nov 2020 at 05:07, Carsten Bormann <[email-masked]<mailto:[email-masked]>> wrote:

C-x f 69 RET

or put

in your .emacs.

Grüße, Carsten

_______________________________________________
netmod mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/netmod

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 11 Nov 2020 14:52:41 +0100

> 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 r…

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

---

From: Kent Watsen <[email-masked]>
Date: Wed, 11 Nov 2020 18:54:30 +0000

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 <[email-masked]> wrote:
>

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 11 Nov 2020 21:01:45 +0100

> 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…

Once you have the XML for the RFC:
See https://tools.ietf.org/html/rfc8152#page-7
for the right way to do this.

Grüße, Carsten