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

[William Lupton]

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

On Sat, 7 Nov 2020 at 05:07, Carsten Bormann  wrote:

> On 2020-11-07, at 01:06, Michael Richardson  wrote:
> >
> > 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
>
> ___
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod
>
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

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

[Ladislav Lhotka]

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  writes:

> 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 MMDD version
> references.
>
> While I like YANG as executable "code", it sure feels like it is not smart to
> be authoring in it.
>
> --
> Michael Richardson. o O ( IPv6 IøT consulting )
>Sandelman Software Works Inc, Ottawa and Worldwide
> ___
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod

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

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod