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

[Kent Watsen <[e-mail]>]

Hi Martin,

First, I just posted -05 to address the missing artwork:
https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-05.

See below for more comments.

Kent // contributor


===== original message =====

> Hi,
>
> I support this work.   See below for some comments.
>
> Qin Wu <[e-mail]> wrote:
>> Dear WG,
>> 
>> As you may recall I presented yang-xml-doc-conventions in London.
>> There was strong support for trying to solve the problem and mixed
>> views on the solution, other than that we should do it fast.  In the
>> meanwhile, Kent submitted artwork-folding as an alternative solution.
>> 
>> The authors of the two drafts decided to combine efforts.  After
>> several internal iterations on both drafts, the drafts were becoming
>> more alike than different(both support auto wrapping or auto folding).
>> The artwork-folding draft was selected as a preferred offering basis
>> (i.e., draft-kwatsen-netmod-artwork-folding-04) to the working group
>> to consider for adoption.
>> 
>> The primary feature differences remained are:
>>   - all folded lines continue of column 0 without two character
>>     indentation, i.e., whether auto indentation should be supported.
>
> 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.

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.



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



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

For what it's worth, I originally had the actually fold-column 
(e.g., 69) printed in the header, but it was realized that it was 
noise to the reader (humans don't care about the fold column number),
whereas padding the line out provides visually meaningful information
(e.g., one can hover the cursor over the end and then scroll the
document to find all the folds).



> Also, in section 5.2, the first sentence is:
>
>  Scan the artwork to see if any line exceeds the desired maximum.
>
> But what is the desired maximum?   I assume that the idea is that the
> author first selects a desired max?  Maybe add a line that explains
> this, and again write that 69 is a reasonable value for use in I-Ds
> and RFCs.

Right, the idea is that the author has a target fold-column in mind.
It's an input parameter to the script in the appendix.  The max value
defaults to 69.

I added the following sentence before the "scan" line above:

   Determine the desired maximum line length from input.  If no
   value is explicitly specified, the value "69" SHOULD be used.



> /martin

Kent // contributor