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/>
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
