Re: [netmod] Reminder: WGLC - draft-ietf-netmod-yang-tree-diagrams

Robert Wilton <rwilton@cisco.com> Mon, 15 January 2018 15:48 UTC

Return-Path: <rwilton@cisco.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 C0E5A12D7F4; Mon, 15 Jan 2018 07:48:43 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -14.51
X-Spam-Level:
X-Spam-Status: No, score=-14.51 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_HI=-5, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01, URIBL_BLOCKED=0.001, USER_IN_DEF_DKIM_WL=-7.5] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=cisco.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 S6M2J2tEEKVf; Mon, 15 Jan 2018 07:48:41 -0800 (PST)
Received: from aer-iport-3.cisco.com (aer-iport-3.cisco.com [173.38.203.53]) (using TLSv1.2 with cipher DHE-RSA-SEED-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id DFDF112DA02; Mon, 15 Jan 2018 07:48:40 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=8513; q=dns/txt; s=iport; t=1516031321; x=1517240921; h=subject:to:cc:references:from:message-id:date: mime-version:in-reply-to:content-transfer-encoding; bh=aIMXhv76kIm0fzT8zH/8F5c92NrVj4QQbBA84fFznVE=; b=ix8iK3FDi8QEc9Ox4W1QPm8+z59tN1rcDr/6bClmHOFxhVEl9cDKWPXy wW79R+7zAbKzvX7NueC9bmS5Vb8hLsawDVdHhajXEE425gv+N7HYviQou /qman72tJNktCExCZIhc8KOGf76bu4JEtFbfwd8Od9xaAcKDycPqUKaod E=;
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: =?us-ascii?q?A0DsAQCSzFxa/xbLJq1UCRoBAQEBAQIBA?= =?us-ascii?q?QEBCAEBAQGEJ3QnhBOLGI9sfJZEggIKGAuESU8ChRQUAQEBAQEBAQEBayiFIwE?= =?us-ascii?q?BAQMBAQEhBAsBBTYLEAsOCgICJgICJzAGDQYCAQEXihAIEKo1gW06iUkBAQEBA?= =?us-ascii?q?QEBAQEBAQEBAQEBAQEBARkFgQ+HGYFpKYF3WDaDLwEBAgEBgToBCAcDAQmDLYJ?= =?us-ascii?q?lBZInkT2IDI0/ghmGHYNvJodFjT6BXogJgTw2ImBwMhoIGxU9giqCVByBZ0E3i?= =?us-ascii?q?lCCPAEBAQ?=
X-IronPort-AV: E=Sophos;i="5.46,364,1511827200"; d="scan'208";a="1417895"
Received: from aer-iport-nat.cisco.com (HELO aer-core-2.cisco.com) ([173.38.203.22]) by aer-iport-3.cisco.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 15 Jan 2018 15:48:38 +0000
Received: from [10.63.23.131] (dhcp-ensft1-uk-vla370-10-63-23-131.cisco.com [10.63.23.131]) by aer-core-2.cisco.com (8.14.5/8.14.5) with ESMTP id w0FFmcM1011231; Mon, 15 Jan 2018 15:48:38 GMT
To: Martin Bjorklund <mbj@tail-f.com>
Cc: joelja@bogus.com, netmod@ietf.org, draft-ietf-netmod-yang-tree-diagrams@ietf.org
References: <66857af8-80b4-8c7c-f952-f04c3f2adaa7@cisco.com> <20180115.153933.1215610340924130656.mbj@tail-f.com> <9a7e9c47-c8bb-afdc-81d2-1799cfd635cf@cisco.com> <20180115.162623.2008313631188177181.mbj@tail-f.com>
From: Robert Wilton <rwilton@cisco.com>
Message-ID: <5bbfb2b8-597c-1d19-0d4f-95f83c0ab4b5@cisco.com>
Date: Mon, 15 Jan 2018 15:48:38 +0000
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.5.0
MIME-Version: 1.0
In-Reply-To: <20180115.162623.2008313631188177181.mbj@tail-f.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Content-Language: en-US
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/OZ9Kzc4_cjClvZzCDsTYFCnA-Qc>
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:48:44 -0000


On 15/01/2018 15:26, Martin Bjorklund wrote:
> 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.
Yes, agree that it is consistent, but personally I would also be happy 
for the nodes to be intended 2 spaces for the main tree, and then 4 
spaces for everything else (effectively 2 spaces beyond the 
augment/rpc/etc).

>
>>   - 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 think that compact is better, if not quite so pretty, so this solution 
is also OK with me.

Personally, I quite like a relative indent, i.e. the tree is intended 2 
spaces more than its parent "thing", e.g.

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!
Ah, yes, OK.  I was assuming that the tree diagram would always be done 
from the augmenting module, but clearly that is not necessarily the case.


>
>>> 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.
That is fine with me, really just raising so that the point could be 
discussed and closed.

Thanks,
Rob


>
>
> /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
>>>>> .
>>>>>
>>> .
>>>
> .
>