Subject: [netmod] comments on tree diagrams draft

From: Andy Bierman <[email-masked]>
Date: Sun, 23 Apr 2017 13:55:10 -0700

Hi,

https://tools.ietf.org/html/draft-bjorklund-netmod-yang-tree-diagrams-00

The introduction in this draft does not really reflect the goals that need
to
be addressed. Perhaps:

sec 1, para 1:
OLD:

   This document
   provides the syntax used in YANG Tree Diagrams.  It is expected that
   this document will be updated or replaced as changes to the YANG
   language, see [RFC7950 <https://tools.ietf.org/html/rfc7950>], necessitate.

NEW:

   This document provides the syntax used in YANG Tree Diagrams

   for version 1.1 of the YANG data modeling language [RFC7950
<https://tools.ietf.org/html/rfc7950>].

   It is expected that this document will be updated or replaced

   for future versions of YANG. It should be possible for

   multiple independent tools to generate the same YANG tree diagrams,

   using this specification.

Sec. 2:

The vertical bar (|) and indentation is not defined.

The tab alignment is not defined

The general recursive algorithm is not defined.

The mandatory vs. optional parts of the diagram are not defined.

(e.g., groupings, notifications, rpcs)

Examples of all field types should be provided (e.g if-features)

An ABNF for the grammar should be provided.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 24 Apr 2017 17:25:27 +0200 (CEST)

Hi,

>    using this specification.

Ok.

> The vertical bar (|) and indentation is not defined.

Ok.

> The tab alignment is not defined

Isn't this covered by indentation above?

> The general recursive algorithm is not defined.

Yes, on the TODO list.

> The mandatory vs. optional parts of the diagram are not defined.

Nothing is mandatory; this will be an Informational document.

> (e.g., groupings, notifications, rpcs)

Yes, on the TODO list.

> Examples of all field types should be provided (e.g if-features)

Ok.

> An ABNF for the grammar should be provided.

I don't understand what you refer to?

/martin

---

From: Andy Bierman <[email-masked]>
Date: Mon, 24 Apr 2017 09:16:38 -0700

> Isn't this covered by indentation above?

no -- the type names are not printed a fixed distance from the last field
but
rather they align with some column (not sure the rule for picking the
column)

> Nothing is mandatory; this will be an Informational document.

So 6087bis is expected to define guidelines on what IETF documents should
contain?
OK I guess, but it would be better if the guidelines were for all diagrams
(in the same draft).

> I don't understand what you refer to?
Perhaps a grammar (in ABNF) that matches the recursive algorithm, but maybe
this is not possible.

More issues:

 - node order.  Document order needs to be defined.  Need to construct
subtrees from submodules
    in "include-stmt" order.

- can a tree diagram ever include augmenting nodes from external modules?
  If so there is no real document order for multiple imported modules.
  Also no syntax to support it.  (I would say no, this is out of scope)

 - is the module name line part of the diagram?

Andy