Re: [netmod] stable reference for tree diagram notation

Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> Wed, 08 March 2017 18:02 UTC

Return-Path: <j.schoenwaelder@jacobs-university.de>
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 7132B12944E for <netmod@ietfa.amsl.com>; Wed, 8 Mar 2017 10:02:10 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.201
X-Spam-Level:
X-Spam-Status: No, score=-4.201 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, RP_MATCHES_RCVD=-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 A3HZQNvgPabn for <netmod@ietfa.amsl.com>; Wed, 8 Mar 2017 10:02:08 -0800 (PST)
Received: from atlas3.jacobs-university.de (atlas3.jacobs-university.de [212.201.44.18]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 5EFE41270B4 for <netmod@ietf.org>; Wed, 8 Mar 2017 10:02:08 -0800 (PST)
Received: from localhost (demetrius5.irc-it.jacobs-university.de [10.70.0.222]) by atlas3.jacobs-university.de (Postfix) with ESMTP id 396547D9; Wed, 8 Mar 2017 19:02:07 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from atlas3.jacobs-university.de ([10.70.0.205]) by localhost (demetrius5.jacobs-university.de [10.70.0.222]) (amavisd-new, port 10030) with ESMTP id ashqt4xjgWTn; Wed, 8 Mar 2017 19:02:06 +0100 (CET)
Received: from hermes.jacobs-university.de (hermes.jacobs-university.de [212.201.44.23]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "hermes.jacobs-university.de", Issuer "Jacobs University CA - G01" (verified OK)) by atlas3.jacobs-university.de (Postfix) with ESMTPS; Wed, 8 Mar 2017 19:02:06 +0100 (CET)
Received: from localhost (demetrius3.jacobs-university.de [212.201.44.48]) by hermes.jacobs-university.de (Postfix) with ESMTP id 8770020035; Wed, 8 Mar 2017 19:02:06 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from hermes.jacobs-university.de ([212.201.44.23]) by localhost (demetrius3.jacobs-university.de [212.201.44.32]) (amavisd-new, port 10024) with ESMTP id XyVDV0Lf-aE0; Wed, 8 Mar 2017 19:02:06 +0100 (CET)
Received: from elstar.local (elstar.jacobs.jacobs-university.de [10.50.231.133]) by hermes.jacobs-university.de (Postfix) with ESMTP id 0A98520039; Wed, 8 Mar 2017 19:02:06 +0100 (CET)
Received: by elstar.local (Postfix, from userid 501) id 6C90E3E9C16B; Wed, 8 Mar 2017 19:02:11 +0100 (CET)
Date: Wed, 8 Mar 2017 19:02:11 +0100
From: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
To: Andy Bierman <andy@yumaworks.com>
Message-ID: <20170308180211.GA9937@elstar.local>
Mail-Followup-To: Andy Bierman <andy@yumaworks.com>, Ladislav Lhotka <lhotka@nic.cz>, "netmod@ietf.org" <netmod@ietf.org>
References: <EE43C03C-4660-4492-B40A-BAA17FD99A39@juniper.net> <20170303170233.GB3345@elstar.local> <20170307.185637.67261051570590747.mbj@tail-f.com> <82703e36-26f9-d459-c36a-c274861c5386@labn.net> <84583EEA-C7FE-4BB0-8D16-744E3768AB5C@nic.cz> <CABCOCHQaEAs039Tim6CWGg0h_cK1rcZo5DBS-Kko8j05UosZwQ@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <CABCOCHQaEAs039Tim6CWGg0h_cK1rcZo5DBS-Kko8j05UosZwQ@mail.gmail.com>
User-Agent: Mutt/1.6.0 (2016-04-01)
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/EqhWGQkalmRfgnHMvAzjNZAYubI>
Cc: "netmod@ietf.org" <netmod@ietf.org>
Subject: Re: [netmod] stable reference for tree diagram notation
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.17
Precedence: list
Reply-To: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
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, 08 Mar 2017 18:02:10 -0000

On Wed, Mar 08, 2017 at 09:15:48AM -0800, Andy Bierman wrote:
> Suggested Text:
> 
> OLD:
> 
>    If YANG tree diagrams are used, then a sub-section explaining the
>    YANG tree diagram syntax MUST be present, containing the following
>    text:
> 
>      A simplified graphical representation of the data model is used in
>      this document.  The meaning of the symbols in these diagrams is
>      defined in [RFCXXXX].
> 
> NEW:
> 
>    If YANG tree diagrams are used, then a sub-section explaining the
>    YANG tree diagram syntax MUST be present, explaining the symbols
>    in the diagram.  The actual text will depend on the version of
>    the YANG tree diagram syntax used in the document.
>

I think we can allow both and leave it to the document author. Either
the author uses a well known tree format and refers to its definition
or the author usees a not yet well known tree format and then it has
to be defined inline:

    If YANG tree diagrams are used, then a sub-section explaining the
    YANG tree diagram syntax MUST be present, explaining the symbols
    used in the tree diagram. This sub-section can either explain the
    tree diagram format inline or it can refer to an external
    specification of the tree diagram format that is used.

    A specification using the tree diagram format defined in this
    document may simply state:

       The meaning of the symbols in these diagrams is defined in [RFCXXXX].

The way bigger issue I think is how to make sure that the text in this
sub-section is actually inline with the tree diagram itself since it
is easy for this to get out of sync (I admit that I generally do not
read the tree diagram blurb and I would not be surprised if people
cut'n'paste tree diagram blurbs). In other words, what we may want is
a short label _in_ the tree format itself that uniquely identifies the
format and is generated by the tool producing the tree format.

  pyang -f tree --tree-RFCWXYZ foo.yang

format: RFCWXYZ
module: foo
   ....

I personally would trust such an inline label way more than any tree
diagram sections because the label is likely created by the tool that
created the diagram. We have seen I-Ds where the tree diagram is out
of sync with the YANG definitions. Perhaps the idea to have tools for
checking tree diagrams is not that far fetched. (Even though I first
thought the idea of checking tree diagrams is somewhat ridiculous.)

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>