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

tom petch <ietfc@btconnect.com> Tue, 10 November 2020 12:47 UTC

Return-Path: <ietfc@btconnect.com>
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 795513A0DD9; Tue, 10 Nov 2020 04:47:25 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.901
X-Spam-Level:
X-Spam-Status: No, score=-1.901 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_MSPIKE_H2=-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=btconnect.onmicrosoft.com
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 VxJgAijQcyWU; Tue, 10 Nov 2020 04:47:23 -0800 (PST)
Received: from EUR04-VI1-obe.outbound.protection.outlook.com (mail-eopbgr80100.outbound.protection.outlook.com [40.107.8.100]) (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 0CFF13A0D72; Tue, 10 Nov 2020 04:47:22 -0800 (PST)
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=g4H/LaeggckzXMgojnuDpIOqPMbrfbtCj8GzqPCIdsdNtWL25rhtXLdmtwnHOhIioZU10v6ztbeKWMiMu3hZPf8DLdnSoB3eQRiXr/BmproI6lz96eMNqD5EJX0Q6OxX6suq3Ccko46xxN/kdH8F65ezKtgrKWVSTwnZk35eJxZs4MTayiVVwhVu8uGoXzS6lMlmxXN77ptYU8nVMwywX3aNNJhXYz+7fKJLMOpUUq6w2zEEGpHZdc+14CzTrDwGxcPiTGQdba0MYTQefyaRdlBuh8/SZ6bVQ3YBCQOV5VJiEY87zFsUI58V3FbnuVeWJ/u0ggPlgOwrvHfb3T7s4Q==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=el2u4FhBK1oWs/62ksfqGIYmwijL2nHTV9xXgGPRUmQ=; b=J9pH+WrUiKMZyPrEQU6ZH4pMUpthiO0DYaFljHZGzU/LH/Eln0tI+Ct/2IDhD8+TLU4RgueEV+HDv3u9ZyazmDVjVRay21LlmM2EORH6Az18wWn7V1dy3+JWmSMJhjVrzHo0/tWo7C7bfYBpOZcQiP04QQKztcaVA8YsJRFW318JF5om/+/925YOVDSxF+JjlqXYmD4As2YjBzL58Dr53QAIPM9TVoRsiskhUYqUTp8R2NkunT0jUXW9HBTvQWkIqQPF+qXZkFPP4RBkEZnqTaBjnQ6i8+JUSjSaM8TBmufGUK7hAWPY/eenXQpLZAYaoKv3cF1dk3iECONHlXaZ0Q==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=btconnect.com; dmarc=pass action=none header.from=btconnect.com; dkim=pass header.d=btconnect.com; arc=none
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=btconnect.onmicrosoft.com; s=selector2-btconnect-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=el2u4FhBK1oWs/62ksfqGIYmwijL2nHTV9xXgGPRUmQ=; b=xk/005YF64MpWiLTud2OF94QmWULrw2qUoByBpqEVvChiMVkFKBxoaw9tg6kkedPYQ+zmM5UZKfQbFvK+bwGRUmdPfUAtuLGadclvolycgmotkQ2n/WWzl3LGfTGGxPOFnsG2nPZUq5t8cTnXjTgdh1dW2mowLDFq4Vj+IC6dRQ=
Received: from AM7PR07MB6248.eurprd07.prod.outlook.com (2603:10a6:20b:134::11) by AM7PR07MB6706.eurprd07.prod.outlook.com (2603:10a6:20b:1a6::13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3564.21; Tue, 10 Nov 2020 12:47:19 +0000
Received: from AM7PR07MB6248.eurprd07.prod.outlook.com ([fe80::ad44:1086:3767:a804]) by AM7PR07MB6248.eurprd07.prod.outlook.com ([fe80::ad44:1086:3767:a804%8]) with mapi id 15.20.3564.021; Tue, 10 Nov 2020 12:47:19 +0000
From: tom petch <ietfc@btconnect.com>
To: William Lupton <wlupton@broadband-forum.org>, NetMod WG <netmod@ietf.org>
CC: "tools-discuss@ietf.org" <tools-discuss@ietf.org>
Thread-Topic: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances
Thread-Index: AQHWtIVPFZocxuJGgUeW6JxdvypooKm7yosAgABUQICAA3BPAIABxEr2
Date: Tue, 10 Nov 2020 12:47:18 +0000
Message-ID: <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>
In-Reply-To: <CAEe_xxhNEPuMhg0i14J=0+hW-3+NgknEDG99qyMRdR59q8OM_Q@mail.gmail.com>
Accept-Language: en-GB, en-US
Content-Language: en-GB
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
authentication-results: broadband-forum.org; dkim=none (message not signed) header.d=none;broadband-forum.org; dmarc=none action=none header.from=btconnect.com;
x-originating-ip: [86.146.121.140]
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: 97abc7aa-ef6e-4556-73d5-08d88576c29f
x-ms-traffictypediagnostic: AM7PR07MB6706:
x-microsoft-antispam-prvs: <AM7PR07MB67062DC61A02A797B0F3A76AA0E90@AM7PR07MB6706.eurprd07.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:10000;
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: e2f+Y+ekR5oHzpsXmMUjebnGAIxeOBix2oqIgO4xg8SRlD5iaklsSR5EL6e3JZXxNUjwUaQ4UXzuw1sae++MUk6oddwVkLn/AZSaqZYBUMN8Z4kNoJaNZ+JpGeO+qeSb6BuMtP3OympuXzRDdXIL/DRGx+ZY0nY+WtI8gLdiXVixwTXFAWphH8lXuc9BX1+7WRNvXKuAS6Nun4pp+xJHOrWCbQbOlnqj7Q58NqUjCmSgnskCeEMdbKm0kVS59RC+GH5RyHQs+G8OtxIBPZjA4c5XXLsrLzsMb3Ra/RHChCZKSEHsR2I5IWUYSjHC/pVqfOY4Gf0On0ZVeHRZe0Z01xscjQw/Vtd3w2OEI9R9x44bIx9bVOshXezSlxTU5XAkpplcmQa8Aks/grZWooBUMg==
x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:AM7PR07MB6248.eurprd07.prod.outlook.com; PTR:; CAT:NONE; SFS:(366004)(39860400002)(376002)(396003)(136003)(346002)(52536014)(55016002)(53546011)(66946007)(186003)(91956017)(64756008)(76116006)(4326008)(9686003)(7696005)(8936002)(86362001)(8676002)(66446008)(110136005)(71200400001)(33656002)(966005)(2906002)(478600001)(316002)(6506007)(66556008)(66476007)(26005)(5660300002); DIR:OUT; SFP:1102;
x-ms-exchange-antispam-messagedata: DdBnzcJsdHR30+1oU3VBE1PiWEf8Cpzh9TuSKeeSAykgfMRc7KmUG5bazK3GVmloP7iXonHdX21MTXa2sJmNUcv6Kq9ErpcGprdJLtEgGen1bmHeQUFO3tsGKDwo0i1vrcmgBZGy5mQElv1XLBUziB0bYGMOTQAjcCcMwfBHnOa7WJdieUrvyM7sCEeIhNX238O1LvblwWXKQxWxJ15HkCYsbufXydiPfEgkT4ZcVxFPZo82YiyE/WriNOlISY1mBuvw+Potz6BapqxzZlOJL+9tH9ljp59wvegxYkyg0CdCGKY/+2QqeY33gxcHK3MRRNHsXe3tZxjLb11YJVZQKWv7sGnbdcz556fu9naCQ1Q1hcxSY6U9wElz+dTaUe13k4kaiRG7rzrg/UuaWicOQp48OixdHEF9gwnWqLK0pK4MgbGS9eiesmzLrvT5w3WxzNwgOO50DLuxMoLX88l8pKDaMmKzINwu6OrO5aFuwrEIF1jg5f7isbCSUecJgmBKf8Yj7JboX0cSA8EItxhtd3/l/tn76Nfr9F8XmdOJZ8+4SYRfk2Z34FQu3/zbHUmWTeRx+jlXnpFwwtTrDRveLzBOdifyWDm59PhU05oq12rDHtm0e5hg06tprFDihRrjhMnQ25e1MiGI3Hi15rP4VlmnFc44Ra0pX3Nsm5+AglnP/tloiCYgQ+oSH81coDFAfLU/HJ0kNSvoY2+eiNr2v/vvhfU9EKRPZ5NQ91rUUv6I6mwM2nyou2OZNKeGJXUbu8TJSQLviHe9KkBR18LUcP2clRE52aAuP6EC6/jvIxe9IDwuZ6ToGOXk0cpQKFHPI+eXuXz9fFI2UaVIGvkeEYWHaBvKzxfdChua52YqHUbyPjb/bMYJG2vG+Iw0gSaY66fGxIHs3zlXBB6nf7TQVw==
x-ms-exchange-transport-forked: True
Content-Type: text/plain; charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-OriginatorOrg: btconnect.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-AuthSource: AM7PR07MB6248.eurprd07.prod.outlook.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 97abc7aa-ef6e-4556-73d5-08d88576c29f
X-MS-Exchange-CrossTenant-originalarrivaltime: 10 Nov 2020 12:47:18.9874 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: cf8853ed-96e5-465b-9185-806bfe185e30
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: r5tEnLxguERCktjsEu8S2AfMQaIToGu/Zvgp6nUzSb5tH8A1+H+DXZ2g05ZTB9Vc3tQ1fOV2299bq5pRNnmStQ==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM7PR07MB6706
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/6YXQq8e4Tc-WGYJ2YdMbAylGIV4>
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: Tue, 10 Nov 2020 12:47:32 -0000

From: netmod <netmod-bounces@ietf.org> on behalf of William Lupton <wlupton@broadband-forum.org>
Sent: 09 November 2020 09:38
To: NetMod WG
Cc: tools-discuss@ietf.org
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 <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