-----邮件原件----- 发件人: Kent Watsen [mailto:[email protected]] 发送时间: 2018年6月28日 8:54 收件人: Robert Wilton; Qin Wu; [email protected] 主题: Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04
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. [Qin]: we can handle whitespace at any position and any line using code proposed in another draft. Unfolded text will not be distorted by the whitespace in the above example. 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. [Qin]: Agree with Kent, this is exactly what we proposed in another draft, i.e., add fixed indentation, which doesn't require tool to understand the artwork format. add left indentation or right indentation seems to indicate the tool must understand the format of artwork and may introduce a lot of complexity. > Rob Kent // contributor _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
