Re: [rfc-i] What the text version is used for (was Re: The <tt> train wreck)

[tom petch <[e-mail]>]

On 23/08/2021 20:38, Carsten Bormann wrote:
> On 23. Aug 2021, at 18:33, tom petch <[e-mail]> wrote:
>>
>> On 23/08/2021 17:09, Carsten Bormann wrote:
>>> How about inserting schema tree identifiers?
>>> Much more stable.
>>
>> I do not understand.  The YANG is the schema, those 41 pages are the structure of the tree, the identifiers, their syntax and semantics.
>
> Yes, this was a bit terse.
>
> What we essentially are discussing here is a way to point into a YANG specification.
> Line numbers have been mentioned as one such way.
> We do have a fragment identifier syntax for lines in (at least a plain) text file (RFC 5147).
> But these are brittle.  Adding a line number every, say, 70 lines would also be disruptive.
>
> However, a YANG spec is a structured document.  So why not employ the structure of that document as a fragment identifier syntax?

Mmm, later last night I thought that that was what you meant.  It would 
be fine with SMI, a single root, world-wide tree with compact 
identifiers for every node (1.3.6.1. ....)

YANG is different.  It can have multiple top level nodes in every module 
while also, in a sense, having none as when the module augments 50 or 
more nodes in another module.  Thus in CCAMP and TEAS modules such as
  draft-ietf-ccamp-flexigrid-media-channel-yang-03
(an author who makes good use of comment statements)
you get
      augment "/te:te/te:tunnels/te:tunnel/"
            + "te:p2p-primary-paths/te:p2p-primary-path/"
            + "te:p2p-primary-reverse-path/"
            + "te:optimizations/te:algorithm/te:metric/"
            + "te:optimization-metric/te:explicit-route-exclude-objects/"
            + "te:route-object-exclude-object/te:type/te:label/"
            + "te:label-hop/te:te-label/te:technology" {
or
      augment "/te:te/te:tunnels/te:tunnel/"
            + "te:p2p-primary-paths/te:p2p-primary-path/"
            + "te:p2p-primary-reverse-path/"
            + "te:optimizations/te:algorithm/te:metric/"
            + "te:optimization-metric/te:explicit-route-include-objects/"
            + "te:route-object-include-object/te:type/te:label/"
            + "te:label-hop/te:te-label/te:technology" {
(spot the difference between the two) and the same augment can appear 
more than once so for uniqueness you need to know what comes next which 
may be an import from another module (as it is here); and you need to 
know the mapping of prefix (te:) to module name since it is module name 
that uniquely identifies the namespace.   Some authors think that they 
know better and invent their own prefix to refer to the module of 
another author so identifying a node in the tree can take 10 or more 
lines of text, the path, the mapping of prefix to module and so on.

And it gets worse.  You may have mastered the multi-root tree with 10 or 
more depths and inconsistent identifiers to arrive at a single node in 
the schema tree but then you need to find its definition in the 
documents. YANG allows 'subroutines', groupings which can be used 
anywhere and just as some programmers grossly overuse subroutines there 
is a growing fashion to make everything a grouping and place them at the 
start of a module, or in a separate common module, so you have to scroll 
back and forth multiple documents in order to locate the definition of 
this one leaf in the tree.

(In the module I cite there is a comment line for each augment and, like 
a page number, that provides a clear and quick locator but other authors 
have no comment lines.)

Like any language, YANG offers much scope for misuse.

Tom Petch

> Adding a full schema tree identifier in certain places (left as exercise for the reader) would provide a nice way to point into the YANG spec.
> (Of course, that identifier is also known when it is not added to the YANG spec, but with it added simple text searching would work.)
> So what I’m proposing is defining a fragment identifier syntax for YANG specs plus a convention to include these (typically as part of a pretty-printing step) to enable text-based searching.
>
> (And, as a side effect, having the full schema tree identifier handy would also help with reading through 40-page YANG specs.)
>
> Grüße, Carsten
>
> .
>
_______________________________________________
rfc-interest mailing list
[e-mail]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest