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

[Kent Watsen <[e-mail]>]

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


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.


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



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



> 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