Kent Watsen <[email protected]> wrote:
> All, I just posted -06 that addresses some comments from Rob, Martin,
> and Jonathan. I realize that there are still open issues, but a rapid
> iteration for some of these things seems like it might be good:
> https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-06.
>
>
> Hi Robert,
>
> > A couple of comments:
> >
> > 1) Section 4.2 suggests using groupings to presumably avoid folding. I
> > don't really support this as a strategy, since I think that groupings
> > are overused and I think that they obfuscate the true structure of a
> > YANG module, that can only be recovered by recompiling the module with
> > the groupings expanded, or looking at the tree output. Really, I think
> > that an ideal solution would be to somehow have RFCs support longer
> > lines for files like YANG - e.g. if I could choose any value without
> > regard for backwards compatibility I would probably choose 120
> > characters instead.
>
> I removed the word "grouping" from the text. Now it says "...call outs,
> such as functions".
>
>
>
> > 2) The proposed solution always left indents the wrapped line. Often for
> > artwork (e.g. a YANG tree diagram), where whitespace is not significant,
> > and the wrapping is relatively minor, then right indenting the wrapped
> > line can make the results look more visually readable.
> >
> > E.g. I think that this is slightly easier to read:
> >
> > module: ietf-flexible-encapsulation
> > augment /if:interfaces/if:interface/if-cmn:encapsulation\
> > /if-cmn:encaps-type:
> > +--:(flexible)
> > +--rw flexible
> > +--rw match
> > | +--rw (match-type)
> > | +--:(default)
> > | | +--rw default? empty
> > | +--:(untagged)
> > | | +--rw untagged? empty
> > | +--:(dot1q-priority-tagged)
> > | | +--rw dot1q-priority-tagged
> > | | +--rw tag-type? dot1q-types:dot1q-\
> > tag-type
> > | +--:(dot1q-vlan-tagged)
> > | +--rw dot1q-vlan-tagged
> >
> > rather than:
> >
> > module: ietf-flexible-encapsulation
> > augment /if:interfaces/if:interface/if-cmn:encapsulation\
> >/if-cmn:encaps-type:
> > +--:(flexible)
> > +--rw flexible
> > +--rw match
> > | +--rw (match-type)
> > | +--:(default)
> > | | +--rw default? empty
> > | +--:(untagged)
> > | | +--rw untagged? empty
> > | +--:(dot1q-priority-tagged)
> > | | +--rw dot1q-priority-tagged
> > | | +--rw tag-type? dot1q-types:dot1q-\
> >tag-type
> > | +--:(dot1q-vlan-tagged)
> > | +--rw dot1q-vlan-tagged
>
>
>
> The placement of the indents in the example above would be impossible
> to automate - they're too artsy ;) However, it should be possible
> to automate a variable indent that lines up with the first printable
> character on the previous line. Something like this:
>
> module: ietf-flexible-encapsulation
> augment /if:interfaces/if:interface/if-cmn:encapsulation\
> /if-cmn:encaps-type:
> +--:(flexible)
> +--rw flexible
> +--rw match
> | +--rw (match-type)
> | +--:(default)
> | | +--rw default? empty
> | +--:(untagged)
> | | +--rw untagged? empty
> | +--:(dot1q-priority-tagged)
> | | +--rw dot1q-priority-tagged
> | | +--rw tag-type? dot1q-types:dot1q-\
> tag-type
> | +--:(dot1q-vlan-tagged)
> | +--rw dot1q-vlan-tagged
>
> [note: previous line indent matching is beyond what can be accomplished
> via a simple `sed` or `awk` one-liner].
>
> Regardless if automated or manual, I think the indent rule needs to be
> rather strict. In particular, arbitrary per-line indent can lead to
> lossy round-tripping (unfolding errors), unless we introduce a rule
> saying that the source artwork MUST NOT have a space (' ') character
> that occurring on a fold column. Otherwise the following might happen.
>
> ORIG:
>
> example:
> This very long line happens to have a space character immediately
> after the fold column.";
>
>
> FOLDED: *** doesn't matter the indentation strategy ***
>
> ===== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =====
> example:
> This very long line happens to have a space character\
> immediately after the fold column.";
>
>
> UNFOLDED (using alg that chomps all leading whitespace):
>
> example:
> This very long line happens to have a space characterimmediately
> after the fold column.";
>
>
> Note the error in the unfolded version. I think disallowing
> whitespace characters on the fold column in the source artwork is
> overly limiting, spaces being so commonly used.
But with variable placement of the '\' character you can do:
This very long line happens to have a space character \
immediately after the fold column.";
or
This very long line happens to have a space \
character immediately after the fold column.";
so I'm not sure that disallowing space at the fold column is a
problem.
Note that even with this, your original "one-liner sed" still produces
valid results, so if you just want a simple folding program you can
use that.
/martin
> The only way I
> can think to preserve the space character is to have a fixed
> indent rule (e.g., some hardcoded column number, or always use
> the same indent as previous line, or the same as the previous
> line plus some fixed offset). Given a clear rule, the unfolding
> alg can chomp just the right amount of whitespace out, leaving
> the any remaining whitespace, so the round-trip result is loss-less.
>
>
> > Rob
>
> Kent // contributor
>
>
>
> _______________________________________________
> netmod mailing list
> [email protected]
> https://www.ietf.org/mailman/listinfo/netmod
>
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
