Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04

[Bob Harold <[e-mail]>]

On Thu, Jun 28, 2018 at 2:08 AM Martin Bjorklund <[e-mail]> wrote:

> Kent Watsen <[e-mail]> 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 problem is that this does not work in cases where there are a lot of
spaces - particularly where there are more than 'line-length' spaces in a
row, in the middle of the line.

-- 
Bob Harold


>
> > 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
>
>