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