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

Kent Watsen <kent@watsen.net> Wed, 11 November 2020 18:54 UTC

Return-Path: <01000175b8a8c97a-da2bdc7c-435a-425d-9b45-8eeb581bdeea-000000@amazonses.watsen.net>
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 EE9DF3A0D20; Wed, 11 Nov 2020 10:54:33 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.898
X-Spam-Level:
X-Spam-Status: No, score=-1.898 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_HELO_NONE=0.001, SPF_NONE=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=amazonses.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 MLv5Yfchx7XP; Wed, 11 Nov 2020 10:54:32 -0800 (PST)
Received: from a8-96.smtp-out.amazonses.com (a8-96.smtp-out.amazonses.com [54.240.8.96]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 7BEDB3A0D45; Wed, 11 Nov 2020 10:54:32 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/simple; s=224i4yxa5dv7c2xz3womw6peuasteono; d=amazonses.com; t=1605120870; h=Content-Type:Mime-Version:Subject:From:In-Reply-To:Date:Cc:Content-Transfer-Encoding:Message-Id:References:To:Feedback-ID; bh=iijLOijHdWtIHFv735btoFgrW/xlzMIA8OamyABbjtU=; b=K9zkj0p1DPIf8cBx+gNTWKcXbX/EqBjhwHnW1eF5rJrib+dNgConJrC67QvdFcUk Sb7qrqq+3lByNcMHJeTKQi8S39Obt4lUMRlyvmg1vEv9OTM2Uuti2VgABNiFnAZL7yJ c2O9mC0wRnr3iDkoi7kvtPQey9gSaSpn+kUbzuxs=
Content-Type: text/plain; charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.80.23.2.2\))
From: Kent Watsen <kent@watsen.net>
In-Reply-To: <87tutwj906.fsf@nic.cz>
Date: Wed, 11 Nov 2020 18:54:30 +0000
Cc: tom petch <ietfc@btconnect.com>, William Lupton <wlupton@broadband-forum.org>, "netmod@ietf.org" <netmod@ietf.org>, "tools-discuss@ietf.org" <tools-discuss@ietf.org>
Content-Transfer-Encoding: quoted-printable
Message-ID: <01000175b8a8c97a-da2bdc7c-435a-425d-9b45-8eeb581bdeea-000000@email.amazonses.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> <87tutwj906.fsf@nic.cz>
To: Ladislav Lhotka <ladislav.lhotka@nic.cz>
X-Mailer: Apple Mail (2.3608.80.23.2.2)
X-SES-Outgoing: 2020.11.11-54.240.8.96
Feedback-ID: 1.us-east-1.DKmIRZFhhsBhtmFMNikgwZUWVrODEw9qVcPhqJEI2DA=:AmazonSES
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/vQkMP_STnjTbetRc98aFflrX2SI>
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 18:54:34 -0000

As a contributor:

I don’t like the YIN format, but Lada makes some good points below.

I don’t understand the "extraction code should not be needed any more” comment, but know that Shepherds and, to a lesser extent, Copy Editors, rely on being able to extract the YANG modules and/or instance examples from the `xml2rfc` XML files.

K.


> On Nov 11, 2020, at 8:52 AM, Ladislav Lhotka <ladislav.lhotka@nic.cz> wrote:
> 
> 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