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

Ladislav Lhotka <ladislav.lhotka@nic.cz> Mon, 09 November 2020 09:13 UTC

Return-Path: <ladislav.lhotka@nic.cz>
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 2915D3A0D6D; Mon, 9 Nov 2020 01:13:41 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.098
X-Spam-Level:
X-Spam-Status: No, score=-2.098 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=nic.cz
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 JRXc3pLohdoV; Mon, 9 Nov 2020 01:13:39 -0800 (PST)
Received: from mail.nic.cz (mail.nic.cz [IPv6:2001:1488:800:400::400]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id B08463A0D6B; Mon, 9 Nov 2020 01:13:37 -0800 (PST)
Received: from localhost (unknown [IPv6:2001:1488:fffe:6:a88f:7eff:fed2:45f8]) by mail.nic.cz (Postfix) with ESMTPSA id 7139D1408CC; Mon, 9 Nov 2020 10:13:35 +0100 (CET)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=nic.cz; s=default; t=1604913215; bh=mARSR43SUspbBlkAl7oz3aUe2Q4/lWZEHLDV6yBNyJU=; h=From:To:Date; b=iNgeGES9nUBgMsQw4EB4jDOY4D+pxxAsgRw0aHeJdRuq2j6mXhXilJWlpog95PWLz V7KjWYK4ezWmbmQFiSFTh6Zq9I0gpWn5DcMMT4js3RhtK/4MMkr0aq29cUIso7tsBH JQX2J3Dds+SzrZZ3HHZ99j+cWW/o7T9SG3WBNshE=
From: Ladislav Lhotka <ladislav.lhotka@nic.cz>
To: Michael Richardson <mcr+ietf@sandelman.ca>, tools-discuss@ietf.org, netmod@ietf.org
In-Reply-To: <29950.1604697852@localhost>
References: <29950.1604697852@localhost>
Mail-Followup-To: Michael Richardson <mcr+ietf@sandelman.ca>, tools-discuss@ietf.org, netmod@ietf.org
Date: Mon, 09 Nov 2020 10:13:35 +0100
Message-ID: <87zh3qdha8.fsf@nic.cz>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Virus-Scanned: clamav-milter 0.102.2 at mail
X-Virus-Status: Clean
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/SrHhVeQddpyrJB3UU1zX-X5l4dU>
Subject: Re: [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: Mon, 09 Nov 2020 09:13:41 -0000

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 <mcr+ietf@sandelman.ca> 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 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
> _______________________________________________
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod

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