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

[Qin Wu <[e-mail]>]

-----邮件原件-----
发件人: Martin Bjorklund [mailto:[e-mail]] 
发送时间: 2018年6月27日 4:08
收件人: [e-mail]
抄送: Qin Wu; [e-mail]
主题: Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04

Kent Watsen <[e-mail]> wrote:
> 
> 
> 
> > (The exmaples with just a string of '\' are highy confusing.  
> > Unclear what they try to tell me... probably that the alg is much 
> > more difficult than I originally thought ;-)
> 
> Those are torture tests, but they due illustrate the one case where 
> having the '\\n' on the fold column would've been illegal input (and hence the '\'
> was replaced with a 'x').  Great for internal algorithm validation, 
> but perhaps unnecessary for the example in the text.  Or maybe enhance 
> the comments above these lines to explain why they're there?

I suggest you remove this.

> See below for more comments.
> 
> 
> 
> >>> I really liked the flexible indentation in the other draft.  I 
> >>> suggest it is added to this draft.  It enhances readability (if 
> >>> the author wants it).
> >> 
> >> Variable indentation, when the folded-line starts on same column as 
> >> the previous line, looks nice.  The current 
> >> yang-xml-doc-conventions draft has a fixed two-space indent, which 
> >> would only look nice sometimes while introducing a surprise factor other times.
> >
> > Hmm, I thought it had variable-length indentation.
> 
> It was, but removed later, I think from WG comments.   Qin may know more.
> 
> 
> >> Variable indent introduces significant complexity; at least, it's 
> >> beyond what can be accomplished by a `sed` one-liner, such as in 
> >> the current draft.  A fixed two-space indent is possible (easy), 
> >> but zero-space indent is more common (less surprising) than a fixed indent.
> >
> > I like the algorithm in the other draft better - it had variable 
> > placement of the line break ("\\n" sequence), and variable 
> > indentation.
> 
> How can you automated variable placement of the line-break, assuming 
> no awareness of the file format?  Additionally, be aware that variable '\n'
> placement would necessitate pre-scanning the file to ensure *no* line 
> ends in a '\\n', as opposed to just the lines that need folding.

I envision this format being used not just by a program, but also by humans trying to construct nice looking examples.

Also, I would prefer a description of the format, rather than of one algorithm that produces the format.

[Qin]: Tend to agree with this.

> > Note that your proposed format is just a special case of the format 
> > in the other draft, so you can still use your "one-liner" sed to 
> > produce your result.
> 
> True.
> 
> 
> >> >>   - handle two special case on backslash and space at the end of broken
> >> >>     line in yang-xml-doc-conventions.
> >> >>   - propose to use <WRAPPED TEXT BEGIN><WRAPPED TEXT END> to extract
> >> >>     artwork from I-Ds.
> >> >
> >> > The artwork draft proposes only a header, which means that it is 
> >> > not quite clear where the artwork ends.
> >> 
> >> Interesting point, but I think that artwork-framing is a different 
> >> problem from artwork-folding.  If the goal is to support extracting 
> >> artwork from txt-based RFC scripts, regardless if the artwork is 
> >> folded or not, then we could level-up this draft to that role, while still supporting folding.
> >> 
> >> If we were to add a footer, maybe something like this:
> >> 
> >>   ===padding=== End Folding per BCP XX (RFC XXXX) ===padding===
> >> 
> >> where the "padding" fills in '=' characters until the max-line 
> >> width is reached (same as how the header is done).
> >
> > Ok.
> 
> I assume that you're okay-ing the proposed footer, but the real 
> question is if we should expand the scope of this draft to include artwork-framing also?

I think I would prefer if there is also a footer.

> >> >> In the artwork draft, section 5.3, you write:
> >> >>
> >> >>   This line is self-describing in
> >> >>   three ways: use of '\' character, identification of BCP/RFC, and
> >> >>   identification of what the maximum line length is for the artwork.
> >> >>
> >> > I was confused about this maximum line length; it seems you 
> >> > define the maximum line length ot be 53, but that seems too 
> >> > limiting, and indeed in the example in 5.4 the max line length is 69.  (BTW, the example is
> >> > missing in the draft, as is the shell script in Appendix A).   In any
> >> > case, I don't see how the header identifies the max line length.
> >> 
> >> The draft says that the *minimal* header string is 53-characters).  
> >> We can make it less if needed, but it involves needing to fold the 
> >> header itself, which could become messy.  Thoughts?
> >> 
> >> Per the line just before the one quoted above, this line is '=' 
> >> padded on both sides until reaching the max value.  Apparently, 
> >> this isn't clear enough in the text, or do you think it's okay now?
> >
> > The draft says:
> >
> >  The header is two lines long.
> >
> >  The first line is the following 53-character string
> >
> > This is what made me confused.  I now understand that the idea is to 
> > pad with '='.
> 
> Right, the full sentence is:
> 
>    The first line is the following 53-character string that has been
>    padded with roughly equal numbers of equal ('=') characters to reach
>    the artwork's maximum line length.
> 
> So, leave as is for now?

Well ... I don't think this text is even correct...  The section describes the header with the first line being 53 characters.  But that is just an example.  Maybe:

    The first line is an N-character string on the following form:

    === NOTE: '\' line wrapping per BCP XX (RFC XXXX) ===

    where N is the artwork's maximum length (the minimum length is
    53).  The string is padded with roughly equal numbers of equal
    ('=') characters in the beginning and end to reach the artwork's
    maximum line length.



... but as I wrote, I'd prefer a variable-length format.

[Qin]: Good, Variable-length format can be supported by the script provided by draft-wu-netmod-yang-xml-doc-conventions-05.

/martin


> 
> 
> 
> > But if we adopt the algorithm in the other draft, we don't need a 
> > maximum line length like this.
> 
> There still needs to be a maximum line length, whether it's identified 
> in the header could be discussed.
> 
> 
> 
> > /martin
> 
> Kent
> 
> 
>