Re: [netmod] stable reference for tree diagram notation

[Juergen Schoenwaelder <[e-mail]>]

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: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <http://www.jacobs-university.de/>