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

[Martin Bjorklund <[e-mail]>]

Kent Watsen <[e-mail]> wrote:
> 
> Hi Martin,
> 
> First, I just posted -05 to address the missing artwork:
> https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-05.

Thanks!

(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 ;-)


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

Hmm, I thought it had variable-length indentation.

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

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.

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

> >> 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 '='.

But if we adopt the algorithm in the other draft, we don't need a
maximum line length like this.


/martin



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