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

Ladislav Lhotka <ladislav.lhotka@nic.cz> Wed, 11 November 2020 13:52 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 E4A9E3A08BD; Wed, 11 Nov 2020 05:52:46 -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 qvYwlgaXdYxx; Wed, 11 Nov 2020 05:52:45 -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 A31EB3A0D94; Wed, 11 Nov 2020 05:52:44 -0800 (PST)
Received: from localhost (unknown [IPv6:2a01:5e0:29:ffff:fc73:fa64:57e6:2115]) by mail.nic.cz (Postfix) with ESMTPSA id 7FB54140A24; Wed, 11 Nov 2020 14:52:41 +0100 (CET)
From: Ladislav Lhotka <ladislav.lhotka@nic.cz>
To: tom petch <ietfc@btconnect.com>, William Lupton <wlupton@broadband-forum.org>, NetMod WG <netmod@ietf.org>
Cc: "tools-discuss@ietf.org" <tools-discuss@ietf.org>
In-Reply-To: <AM7PR07MB624894667774FE0C7C94DCD1A0E90@AM7PR07MB6248.eurprd07.prod.outlook.com>
References: <29950.1604697852@localhost> <008B882D-102D-4AEA-AF59-E259F07089CB@tzi.org> <6712.1604707568@localhost> <4BC302A5-D990-45EE-85C2-196BBC1D09DF@tzi.org> <CAEe_xxhNEPuMhg0i14J=0+hW-3+NgknEDG99qyMRdR59q8OM_Q@mail.gmail.com> <AM7PR07MB624894667774FE0C7C94DCD1A0E90@AM7PR07MB6248.eurprd07.prod.outlook.com>
Mail-Followup-To: tom petch <ietfc@btconnect.com>, William Lupton <wlupton@broadband-forum.org>, NetMod WG <netmod@ietf.org>, "tools-discuss@ietf.org" <tools-discuss@ietf.org>
Date: Wed, 11 Nov 2020 14:52:41 +0100
Message-ID: <87tutwj906.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/QNJAK2bYO94bTsiGaJcUGrnJmo4>
Subject: Re: [netmod] [Tools-discuss] 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: Wed, 11 Nov 2020 13:52:47 -0000

tom petch <ietfc@btconnect.com> 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

>
> Tom Petch
>
> William
>
> On Sat, 7 Nov 2020 at 05:07, Carsten Bormann <cabo@tzi.org<mailto:cabo@tzi.org>> wrote:
> On 2020-11-07, at 01:06, Michael Richardson <mcr+ietf@sandelman.ca<mailto:mcr%2Bietf@sandelman.ca>> 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<mailto:netmod@ietf.org>
> https://www.ietf.org/mailman/listinfo/netmod
>
> _______________________________________________
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod

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