Hi,
[email protected] (Dale R. Worley) wrote:
> (This is the first part of my response, which I am sending seperately to
> speed things up.)
>
> Martin Bjorklund <[email protected]> wrote:
> > [email protected] (Dale R. Worley) wrote:
> > > Martin Bjorklund <[email protected]> wrote on Mon, 23 May 2016 15:43:09
> > > +0200 (CEST):
> > > > [email protected] (Dale R. Worley) wrote:
> > >
> > > Almost all of these points I'm happy with the authors fixing in the
> > > manner they suggest. The points where I have further comment are:
> > >
> > > > > The incompatibilities should be marked whether the old, incompatible
> > > > > usage always causes an error "at compile time", "at run time", or
> > > > > changed behavior.
> > > >
> > > > Ok, but I'd like to avoid the term "compile-time" here.
> > >
> > > True... The distinction I'm looking for is "Incompatible usage will
> > > cause an error report before the software is put into operation."
> > > vs. "Incompatible usage will cause an error report when the software is
> > > in operation." vs. "Incompatible usage will cause a difference in
> > > behavior without an error report."
> >
> > The spec defines what is legal YANG. How this is enforced by tools
> > must be up to the tools, right?
>
> It depends. When reading about incompatibilities, it's really nice to
> be informed what will happen. E.g., if the compiler will catch it,
> you just recompile the code and watch for error messages. If it will
> cause incompatible run-time behavior, you have to inspect the code,
> which is a lot of work.
>
> > > > How about:
> > > >
> > > > The following changes are not backwards compatible with YANG version
> > > > 1:
> > > >
> > > > o Changed the rules for the interpretation of escaped characters in
> > > > double quoted strings. This is an backwards incompatible change
> > > > from YANG version 1. A module that uses a character sequence that
> > > > is now illegal must change the string to match the new rules. See
> > > > Section 6.1.3 for details.
> > > >
> > > > o An unquoted string cannot contain any single or double quote
> > > > characters. This is an backwards incompatible change from YANG
> > > > version 1. A module that uses such quote characters must change
> > > > the string to match the new rules. See Section 6.1.3 for details.
> > >
> > > I assume that the first two situations will cause an error report before
> > > the module is put into production.
> > >
> > > > o Made noncharacters illegal in the built-in type "string". This
> > > > change affects the run-time behavior of YANG-based protocols.
> > >
> > > What happens if you attempt to use a noncharacter in a string?
> >
> > This depends on the protocol. noncharacters are illegal. Maybe in
> > protocol A you can't even encode noncharacters, but in protocol B
> > you'll get a protocol error from the other side if you send
> > noncharacters.
>
> Really, the question is "What does 'illegal' mean?" Of course, it
> means that you shouldn't do it, but does it also contain assertions
> that some particular stage of processing will explicitly flag it?
>
> > > It might be worth inserting a definition of "node" as shorthand for
> > > "data node", as there seems to be no definition of "node" alone, but it
> > > is commonly used to mean "data node". In particular, the reader needs
> > > to be fully aware that "node" is a node in the schema tree, not an
> > > instantiation thereof.
> >
> > But saying that "node" means "data node" is not correct. Sometimes
> > the text talk about "schema nodes" etc. I think it is better to
> > qualify the usage of "node" where necessary to avoid the ambiguity.
>
> OK, I see. But since I was getting confused, it suggests that there
> are various places where "node" is used where it wasn't clear from
> context whether it was a data node or a schema node.
>
> > > > > It would be useful to insert a note somewhere that all data is either
> > > > > "configuration" or "state" data. It's hard to learn that now, because
> > > > > the terms "configuration data" and "state data" are defined only by
> > > > > reference to RFC 6241.
> > > >
> > > > But this is not strictly correct. For example RPC input is neither
> > > > config nor state. Section 3 has:
> > > >
> > > > o data tree: An instantiated tree of any data modeled with YANG,
> > > > e.g., configuration data, state data, combined configuration and
> > > > state data, RPC or action input, RPC or action output, or
> > > > notification.
> > >
> > > Section 4.1 contains a similar statement.
> > >
> > > I think the problem I'm having is with the first sentences of 4.2.3:
> > >
> > > YANG can model state data, as well as configuration data, based on
> > > the "config" statement.
> > >
> > > At first read, this suggests that data is partitioned into
> > > "configuration data" and "state data". What's really happening is that
> > > there are various sorts of data, but some contexts admit a mixture of
> > > configuration and state data, so the data model definitions of those
> > > contexts requires that individual data items can be flagged as
> > > configuration vs. data. Maybe starting 4.2.3 like this would work:
> > >
> > > In some contexts, data modeled by YANG can contain mixtures of state
> > > data and configuration data, based on the "config" statement. When a
> > > node is tagged with "config false", its subhierarchy is flagged as
> > > state data.
> >
> > I think that this might be a bit confusing (which contexts? what
> > exacyly is this mixture?) and too detailed for this introductory
> > section. I would perfer to keep the original text.
>
> That leaves the problem that there are forms that are neither state
> data nor configuration data.
>
> Also, the phrasing is odd in that it seems to assume that
> configuration data is sort of a default condition and state data is an
> exception. I think what was intended is
>
> YANG can differentiate state data and configuration data within
> one instantiated tree, based on the "config" statement.
>
> > > > > - section 5.1.2
> > > > >
> > > > > YANG allows modeling of data in multiple hierarchies, where data
> > > > > may
> > > > > have more than one top-level node. Models that have multiple top-
> > > > > level nodes are sometimes convenient, and are supported by YANG.
> > > > >
> > > > > Any single module seems to define only one data structure, the one
> > > > > whose elements are the items listed in the module, and Yang doesn't
> > > > > seem to provide for any sort of "model" definition other than a
> > > > > module. Or are the nodes at the top level within the module all
> > > > > usable as independent data structures?
> > > >
> > > > The term "data structure" isn't used in the document. YANG allows
> > > > a module to define more than one subtree.
> > >
> > > OK, I think I see where I was confused. I think that would have been
> > > avoided if the 5.1.2 started:
> > >
> > > YANG allows modeling of data in multiple hierarchies. Each top-level
> > > data node in a module defines an independent hierarchy. Models that
> > > have ...
> >
> > What does "independent" imply? They are not necessarily semantically
> > independent. Maybe s/independent/separate/ ?
>
> Yes, "separate" would work well.
Ok, I'll add this.
> Here, I'll mention again this point from another e-mail: The second
> sentence of section 4.1 suggests that a Yang module defines *one*
> hierarchy of data, whereas it seems like any top-level data node in a
> module has meaning separately and can be instantiated seperately.
I'll s/hierarchy/hierarchies/.
> > > > > - section 5.5
> > > > >
> > > > > This section talks a great deal about why scoping is done, but isn't
> > > > > specifically clear what the rules are. (Traditionally, the rule is
> > > > > stated as either what range of source text a particular definition is
> > > > > visible in, or given an identifier use, how the matching definition is
> > > > > found.)
> > > > >
> > > > > Scoped definitions MUST NOT shadow definitions at a higher scope.
> > > > > A
> > > > > type or grouping cannot be defined if a higher level in the schema
> > > > > hierarchy has a definition with a matching identifier.
> > > > >
> > > > > I think the second sentence is confusing, because (to me) the term
> > > > > "schema hierarchy" implies the data tree structure, whereas the
> > > > > scoping rule seems to be intended to be entirely lexical. In either
> > > > > case, this needs to be clarified.
> > > >
> > > > The first sentence says:
> > > >
> > > > Typedefs and groupings may appear nested under many YANG statements,
> > > > allowing these to be lexically scoped by the hierarchy under which
> > > > they appear.
> > > >
> > > > Maybe it would help to move paragraph 2 and 3 to the end, so that the
> > > > motivational text is at the end of the section?
> > >
> > > It looks like current paragraphs 1, 4, and 5 are prescriptive, and 2 and
> > > 3 are motivational. Putting 1, 4, and 5 together should make them
> > > clearer. But since paragraph 2 starts with "Scoping...", it really
> > > needs to be after 1. So, yes, moving 2 and 3 to the end seems like the
> > > clearest order. Does it make sense to you to put all of the motivation
> > > at the end of this section?
> >
> > I prefer to have motivational text before the rules ("why" before
> > "how"). Hmm. The preferred order is "what", "why", "how", and that
> > is really the order we currently have (1 is "what", 2 + 3 is "why" and
> > 4 +5 is "how").
> >
> > But obviously this was confusing to you, so we probably need to make
> > some clarification.
> >
> > Since the problem was with the term "schema hierarchy", maybe we could
> > change this to "statement hierarchy" instead, to stress the fact that
> > it is lexical scoping?
> >
> > [sorry for missing your original point]
>
> Yes, I think that will do it. There are two instances of "hierarchy"
> in para. 1, and at least the first one would be clearer if it was
> "statement hierarchy". And in para. 4, it seems like "schema
> hierarchy" is actually incorrect, and should be "statement hierarchy".
Fixed.
> > > > > - section 5.6.5
> > > > >
> > > > > I suspect that if a server implements module A, and A imports B, the
> > > > > server is not required to implement B. (Even if A references
> > > > > groupings in B.) The answer to that should probably be stated
> > > > > explicitly.
> > > >
> > > > It is not so simple. The rest of the text defines the rules for when
> > > > the server is required to implement B.
> > >
> > > Yes, I was wrong there. (I can't see why I made that mistake.)
> > >
> > > > > Is this the correct way to specify multiple revisions of this module?
> > > > > Or is this an informal notation for the two module definitions:
> > > > >
> > > > > module b {
> > > > > yang-version 1.1;
> > > > > namespace "urn:example:b";
> > > > > prefix "b";
> > > > >
> > > > > revision 2015-04-04;
> > > > > revision 2015-01-01;
> > > > >
> > > > > typedef myenum {
> > > > > type enumeration {
> > > > > enum zero; // added in 2015-01-01
> > > > > enum one; // added in 2015-04-04
> > > > > }
> > > > > }
> > > > >
> > > > > container x { // added in 2015-01-01
> > > > > container y; // added in 2015-04-04
> > > > > }
> > > > > }
> > > > >
> > > > > module b {
> > > > > yang-version 1.1;
> > > > > namespace "urn:example:b";
> > > > > prefix "b";
> > > > >
> > > > > revision 2015-01-01;
> > > > >
> > > > > typedef myenum {
> > > > > type enumeration {
> > > > > enum zero; // added in 2015-01-01
> > > > > }
> > > > > }
> > > > >
> > > > > container x { // added in 2015-01-01
> > > > > }
> > > > > }
> > > > >
> > > > > If it is the latter, it would help the new reader to explain the
> > > > > convention (as no example of a multi-revision module is given in the
> > > > > document).
> > > >
> > > > The comments are not required. There is no correct (mandated) way to
> > > > specify which changes are done in a new revision.
> > >
> > > What I was concerned with is what does the above module statement do?
> > > If I understand correctly, it defines the 2015-04-04 revision of b, and
> > > also tells us that a 2015-01-01 revision exists, but does not define
> > > that revision. Implicitly, there must be a .yang file somewhere
> > > containing the module statement that defines the 2015-01-01 revision of
> > > b.
> > >
> > > But despite that the text talks about the 2015-01-01 revision ('can
> > > implement revision "2015-01-01" or "2015-04-04" of module "b"'), that
> > > file is not included in the example, which is not what I expected, which
> > > led me to wonder if the 2015-01-01 revision was somehow also defined by
> > > the presented "module b" statement. I would have had less trouble with
> > > the example if the definition of the earlier revision of b was also
> > > given.
> >
> > Ok, I see what you mean. This makes sense. I'll add
> >
> > module b {
> > yang-version 1.1;
> > namespace "urn:example:b";
> > prefix "b";
> >
> > revision 2015-01-01;
> >
> > typedef myenum {
> > type enumeration {
> > enum zero;
> > }
> > }
> >
> > container x {
> > }
> > }
> >
> > and
> >
> > module c {
> > yang-version 1.1;
> > namespace "urn:example:c";
> > prefix "c";
> >
> > revision 2015-02-02;
> >
> > typedef bar {
> > ...
> > }
> > }
> >
> >
> > to the example.
>
> Yes, I think that will make it all clear.
>
> > > > > It is worth noting (either here or in 6.1.3) how line-breaks inside
> > > > > quoted strings are transcribed into the string's value. As now
> > > > > written, it seems that the line-break is transcribed identically to
> > > > > how it is represented in the source. That means (1) If the source is
> > > > > recoded with the other type of line break, the semantics of the Yang
> > > > > code change; and (2) if the source uses line-breaks of one type (CRLF
> > > > > or LF), only that type can be directly transcribed into string values.
> > > > > (But regardless of the source line-breaks, an LF can be transcribed
> > > > > into a double-quoted string with "\n". But a CRLF cannot be
> > > > > transcribed into a double-quoted string with escape sequences. Was
> > > > > that intended, or was "\r" intended to be legal?)
> > >
> > > Don't forget this.
>
> I was wondering that (as the text is written) the value of a quoted
> string that includes a line end will change if the line ends are
> changed (say, by moving the Yang file to a different host). Normally
> computer languages are defined so that changing how the program is
> "represented", e.g., by transforming it into a form with different
> line-ends, won't change the semantics of the program.
>
> But if it's true, I seems desirable to provide an explicit warning
> about it.
>
> > Adding "\r" would be backwards incompatible with YANG 1.
>
> I don't see why that is. As far as I can tell from RFC 6020, "\r" is
> not a defined escape in Yang 1, so existing Yang 1 code can't use it.
> True, the new draft explicitly states "It is an error if any other
> character follows the backslash character.", but RFC 6020 doesn't seem
> to allow "\r" to mean anything. Or is it that in practice, Yang 1
> allows people to write "\r", which is interpreted as backslash-r?
I think there are implementations that reject \r, and I know that
there are implementations that allow \r.
> > You can always get the same effect by using single quoted strings.
>
> I don't see how you can get a single CR using single-quoted strings,
> because line ends are only allowed to be LF and CR-LF; writing a CR
> without an LF following it isn't allowed. Or is it that in practice,
> Yang 1 allows people to use CR alone, and it is not interpreted as a
> line-end?
If the module has a string like this:
0x27 0x0d 0x27
it is a string with a single CR.
/martin
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
