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