Hi Kent,
On 28/06/2018 01:53, Kent Watsen 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".
OK, thanks.
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 ;)
They are just right indented, so it is pretty easy to figure out? E.g.
start at (Max line length - number of wrapped chars)
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.
There other ways to solve this, at a slight increase in complexity.
E.g. You could use two marker characters, e.g. as below, where
everything between and including the two '\' characters is stripped.
Simple folding tools could just put the second '\' at the beginning of
the next line, or at a fixed column, more sophisticated tools could put
more effort into making it more readable, but still preserve the ability
to get the exact source back out again.
| | +--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
Thanks,
Rob
Rob
Kent // contributor
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
