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

Michael Richardson <mcr+ietf@sandelman.ca> Fri, 06 November 2020 21:24 UTC

Return-Path: <mcr+ietf@sandelman.ca>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id E5ECF3A0D68; Fri, 6 Nov 2020 13:24:17 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.899
X-Spam-Level:
X-Spam-Status: No, score=-1.899 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id jPkgDiPiyXBu; Fri, 6 Nov 2020 13:24:16 -0800 (PST)
Received: from tuna.sandelman.ca (tuna.sandelman.ca [IPv6:2607:f0b0:f:3:216:3eff:fe7c:d1f3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 2158D3A0D37; Fri, 6 Nov 2020 13:24:15 -0800 (PST)
Received: from localhost (localhost [127.0.0.1]) by tuna.sandelman.ca (Postfix) with ESMTP id 601C538C70; Fri, 6 Nov 2020 16:24:25 -0500 (EST)
Received: from tuna.sandelman.ca ([127.0.0.1]) by localhost (localhost [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 2vDyzsQPcTXB; Fri, 6 Nov 2020 16:24:25 -0500 (EST)
Received: from sandelman.ca (obiwan.sandelman.ca [209.87.249.21]) by tuna.sandelman.ca (Postfix) with ESMTP id C01A738C69; Fri, 6 Nov 2020 16:24:24 -0500 (EST)
Received: from localhost (localhost [IPv6:::1]) by sandelman.ca (Postfix) with ESMTP id D9C73E7; Fri, 6 Nov 2020 16:24:12 -0500 (EST)
From: Michael Richardson <mcr+ietf@sandelman.ca>
To: tools-discuss@ietf.org, netmod@ietf.org
X-Attribution: mcr
X-Mailer: MH-E 8.6+git; nmh 1.7+dev; GNU Emacs 26.1
X-Face: $\n1pF)h^`}$H>Hk{L"x@)JS7<%Az}5RyS@k9X%29-lHB$Ti.V>2bi.~ehC0; <'$9xN5Ub# z!G,p`nR&p7Fz@^UXIn156S8.~^@MJ*mMsD7=QFeq%AL4m<nPbLgmtKK-5dC@#:k
MIME-Version: 1.0
Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature"
Date: Fri, 06 Nov 2020 16:24:12 -0500
Message-ID: <29950.1604697852@localhost>
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/ABHx_hJ7nheOcqawOU-nm6Lfg_o>
Subject: [netmod] reflow of YANG descriptions, and general YANG format annoyances
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Fri, 06 Nov 2020 21:24:18 -0000

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 <mcr+IETF@sandelman.ca>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide