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 (CET)
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
> >>> .
> >>>
> > .
> >
>