Re: [netmod] Reminder: WGLC - draft-ietf-netmod-yang-tree-diagrams
Martin Bjorklund <mbj@tail-f.com> Mon, 15 January 2018 15:26 UTC
Return-Path: <mbj@tail-f.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 2279D12D963; Mon, 15 Jan 2018 07:26:32 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.91
X-Spam-Level:
X-Spam-Status: No, score=-1.91 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01, 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 nLLPMaXbMNnM; Mon, 15 Jan 2018 07:26:25 -0800 (PST)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id 4780A12D965; Mon, 15 Jan 2018 07:26:25 -0800 (PST)
Received: from localhost (unknown [173.38.220.56]) by mail.tail-f.com (Postfix) with ESMTPSA id 20F331AE03DD; Mon, 15 Jan 2018 16:26:24 +0100 (CET)
Date: Mon, 15 Jan 2018 16:26:23 +0100
Message-Id: <20180115.162623.2008313631188177181.mbj@tail-f.com>
To: rwilton@cisco.com
Cc: joelja@bogus.com, netmod@ietf.org, draft-ietf-netmod-yang-tree-diagrams@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <9a7e9c47-c8bb-afdc-81d2-1799cfd635cf@cisco.com>
References: <66857af8-80b4-8c7c-f952-f04c3f2adaa7@cisco.com> <20180115.153933.1215610340924130656.mbj@tail-f.com> <9a7e9c47-c8bb-afdc-81d2-1799cfd635cf@cisco.com>
X-Mailer: Mew version 6.7 on Emacs 24.5 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/R6E2YiMMo-gJ8OiG1RPVgD0ivu0>
Subject: Re: [netmod] Reminder: WGLC - draft-ietf-netmod-yang-tree-diagrams
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.22
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, 15 Jan 2018 15:26:32 -0000
Robert Wilton <rwilton@cisco.com> wrote: > Hi Martin, > > All OK with me except where I have further comments/questions inline > below: > > On 15/01/2018 14:39, Martin Bjorklund wrote: > > Hi, > > > > Thanks for the review! Comments inline. > > > > Robert Wilton <rwilton@cisco.com> wrote: > >> Hi Lou, Martin > >> > >> I've done a quick review of draft -04. > >> > >> It looks well written to me. > >> > >> I have a spotted a few minor nits/questions. > >> > >> Section 1: > >> > >> (i) "Such diagrams are commonly used to provided " => "Such diagrams > >> are used to provide"? > > Ok. > > > >> (ii) "This document provides the syntax used in YANG Tree Diagrams." > >> => "This document describes the syntax used in YANG Tree Diagrams", or > >> if not "describes", perhaps "specifies"? > > I changed to "describes". > > > >> (iii) "common practice is include" => "common practice is to include" > > Ok. > > > >> Section 2: > >> (iv) Are the top level data nodes really offset by 4 spaces, or should > >> this be 2 spaces? The example in section 2, and section 4 seem to > >> differ here. The submodule example in Sec 2.1 looks like it is using > >> 2 spaces. > > It should be 4 spaces. I fixed the example in 2.1. > Hum, OK. Is this the right choice? > - It means that the tree is indented 2 spaces further than everything > else (e.g. groupings, augments, etc). Well, I think it is consistent as it is now: module: <module-name> +--<node> | +--<node> | +--<node> +--<node> +--<node> +--<node> augment <target-node>: +--<node> +--<node> +--<node> +--<node> Nodes are always intended 4 spaces. > - YANG modules in RFC's already struggle with line length anyway, > hence wouldn't the use of 2 spaces give the model a bit more space. This is a good argument. I'm happy to save spaces by using 2 instead: module: <module-name> +--<node> | +--<node> | +--<node> +--<node> +--<node> +--<node> augment <target-node>: +--<node> +--<node> +--<node> +--<node> > I also think that it would be good to check the indent of all the tree > diagram snippets in the doc, it looks like they may be using somewhat > varying levels of indents (between 2 and 6 spaces). Ok. > >> (v) "is prefaces with" => "is prefaced with" > > Ok. > > > >> (vi) Section 2.2, should there be an example of an unexpanded uses > >> statement? I was wondering if this section was under specified? > > I have added: > > > > For example, the following diagram shows the "tls-transport" grouping > > from [RFC7407] unexpanded: > > > > +--rw tls > > +---u tls-transport > > > > If the grouping is expanded, it could be printed as: > > > > +--rw tls > > +--rw port? inet:port-number > > +--rw client-fingerprint? x509c2n:tls-fingerprint > > +--rw server-fingerprint? x509c2n:tls-fingerprint > > +--rw server-identity? snmp:admin-string > Yes, looks good. > > > > >> Section 2.6: > >> (vii) "If the node is augmented into the tree from another module, its > >> name is printed as <prefix>:<name>." Does there need to be a > >> clarification that the prefix name used is the one used by the > >> module's import statement? Or does it use the prefix statement from > >> the imported modules instead (I know that these should normally be the > >> same, but this is not guaranteed). > > Since this is used when a node is augmented *into* the main tree, it > > can't be the prefix in import, since the augmenting module is not > > imported from the augmented module. I did: > But the YANG module must import the module that it is augmenting. If a > local import prefix is used in the actual YANG module then it would be > slightly harder to relate the tree output back to local import > prefixes used in the YANG module. Here's an example: module: ietf-interfaces +--rw interfaces | +--rw interface* [name] | +--rw name string ... | +--rw ip:ipv4! ietf-interfaces doesn't import ietf-ip, so there is no other prefix to use for "ipv4" than the one defined in ietf-ip! > > OLD: > > > > If the node is augmented into the tree from another module, > > its name is printed as <prefix>:<name>. > > > > NEW: > > > > If the node is augmented into the tree from another module, > > its name is printed as <prefix>:<name>, where <prefix> is the > > prefix defined in the module where the node is defined. > This is OK with me, but there is still a potential for a prefix > namespace clash (since prefixes are not guaranteed to be unique). > > An alternative solution would be for the YANG tree diagram to list (at > the beginning or the end of the diagram) the mappings from prefix -> > module name used. The tree diagram is supposed to give a simplified overview of the structure of a module. I agree with your statemenet below that such a mappig adds noise... I prefer to keep the diagram as is. /martin > This has the bonus that it also explicitly lists > the YANG modules that are being augmented, but conversely, this might > end up just adding unnecessary noise to a diagram that should be short > and simple ... > > A second alternative would be to add some vague text to state that the > prefix to module mapping should be explicitly listed in any cases > where the prefix name alone is not obvious. > > Thanks, > Rob > > > > > >> Section 3.2. > >> (viii) It would be slightly easier to read if there wasn't a linebreak > >> between "--" and "tree-print-groupings", not sure if that is feasible > >> to force this. > > I don't think I can enforce this, but I'll look into it. If nothing > > else, the RFC editor will fix this. > > > > > > /martin > > > > > >> Thanks, > >> Rob > >> > >> On 10/01/2018 16:16, joel jaeggli wrote: > >>> Just a reminder given the date that this was posted. This last call is > >>> expected to complete Monday 1/15/18. > >>> > >>> Thanks > >>> > >>> joel > >>> > >>> > >>> On 1/1/18 2:01 PM, joel jaeggli wrote: > >>>> Greetings, > >>>> > >>>> We hope the new year is a time to make great progess on outstanding > >>>> documents before preparation for the London IETF begins in earnest. > >>>> > >>>> This starts a two-week working group last call on: > >>>> > >>>> YANG Tree Diagrams > >>>> draft-ietf-netmod-yang-tree-diagrams > >>>> > >>>> https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-tree-diagrams/ > >>>> > >>>> Please send email to the list indicating your support or concerns. > >>>> > >>>> We are particularly interested in statements of the form: > >>>> > >>>> * I have reviewed this draft and found no issues. > >>>> * I have reviewed this draft and found the following issues: ... > >>>> > >>>> > >>>> Thank you, > >>>> NETMOD WG Chairs > >>>> > >>>> > >>>> > >>>> > >>> _______________________________________________ > >>> netmod mailing list > >>> netmod@ietf.org > >>> https://www.ietf.org/mailman/listinfo/netmod > >>> . > >>> > > . > > >
- [netmod] WGLC - draft-ietf-netmod-yang-tree-diagr… joel jaeggli
- [netmod] Reminder: WGLC - draft-ietf-netmod-yang-… joel jaeggli
- [netmod] 答复: Reminder: WGLC - draft-ietf-netmod-y… Qin Wu
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… t.petch
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Benoit Claise
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Robert Wilton
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Robert Wilton
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Martin Bjorklund
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Robert Wilton
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Acee Lindem (acee)
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Lou Berger
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Martin Bjorklund
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Robert Wilton
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Vladimir Vassilev
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Martin Bjorklund
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Vladimir Vassilev
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… Benoit Claise
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Martin Bjorklund
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Vladimir Vassilev
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Robert Wilton
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Martin Bjorklund
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Lou Berger
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Robert Wilton
- Re: [netmod] Reminder: WGLC - draft-ietf-netmod-y… joel jaeggli
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… joel jaeggli
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Vladimir Vassilev
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Juergen Schoenwaelder
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Alexander Clemm
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Martin Bjorklund
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Juergen Schoenwaelder
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Vladimir Vassilev
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Juergen Schoenwaelder
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Robert Wilton
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… t.petch
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Martin Bjorklund
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Robert Wilton
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Juergen Schoenwaelder
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Benoit Claise
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… Jeff Tantsura
- Re: [netmod] WGLC - draft-ietf-netmod-yang-tree-d… t.petch
- [netmod] Closure - : WGLC - draft-ietf-netmod-yan… joel jaeggli
- Re: [netmod] Closure - : WGLC - draft-ietf-netmod… Martin Bjorklund