Re: [netmod] WG Last Call: draft-ietf-netmod-artwork-folding-02

[Kent Watsen <[e-mail]>]

Hi Rob,

Thanks for your review.  Comments below.



> 1) Abstract:
> I wasn't sure whether the abstract is still entirely accurate, given that the document describes two strategies rather than one, only one of those strategies is time proven ('\'), and only one of those strategies works on *any* text-based content ('\\').

True, how about this (with a similar change in the Introduction)?

   This document defines two strategies for handling long lines in
   width-bounded text content.  One strategy is based on the time-proven
   use of a single backslash ('\') character to indicate where line-
   folding has occurred, with the continuation occurring with the first
   non-space (' ') character on the next line.  The second strategy
   extends the first strategy by adding a second backslash character to
   identify where the continuation begins and thereby able to handle
   cases not supported by the first strategy.  Both strategies use a
   self-describing header enabling automated reconstitution of the
   original content.




> 2) Section 4. Goals:
> Is one of the goals to *exactly* reproduce the input text to the folding algorithm?  If so, this might be worth explicitly stating (e.g. because of the whitespace handling when using the single backslash strategy).

This is what the second goal (4.2.) means by "reconstitution of the original text content".   The below is slightly modified, is it okay?

  4.2.  Automated Reconstitution of the Original Text Content

     Automated reconstitution of the original text content is needed to
     support validation of text-based content extracted from documents.

     For instance, already YANG [RFC7950] modules are extracted from
     Internet-Drafts and validated as part of the draft-submission
     process.  Additionally, the desire to validate instance examples
     (i.e., XML/JSON documents) contained within Internet-Drafts has
     been discussed ([yang-doctors-thread]).



> 3) Section 5.1
> Nit: will work -> works.

Fixed.


> 4) Section 5.2, 4th paragraph about functions.
> I'm not sure this paragraph really adds anything to the document, so I would suggest removing it.  E.g. does this means that we should use YANG groupings to avoid line length indentation issues, if so, I would question whether that makes the resulting YANG model more readable.

Removed.  I agree that the (unfolded) YANG module's readability is more important and, besides, these are just examples and don't preclude anything.


> 5) Section 5.2, last paragraph.
> I think that the RECOMMENDED is perhaps a bit strong, hence I would prefer "suggested" or "encouraged" over "RECOMMENDED".  I think that some/many of the input formats do have ways that the input can be modified such that folding isn't required, but I'm not sure that we necessarily advocate that should always be done.

Disagree.  We do want to advocate authors do what they can.  It was a SHOULD before, but downgraded to a RECOMMENDED to be less overt.


> 6) 7.2.1. '\' folding algorithm:
> It should also check if the line contains more than "max line length space" characters and if so it cannot be folded using this strategy.

You're correct that this is a problem case, but isn't it covered already by the following sentence?

   1.  Determine where the fold will occur.  This location MUST be
       before or at the desired maximum column, and MUST NOT be on top
       of a space (' ') character.  If no such location can be found,
       then exit (this text content cannot be folded)



> 7) 8.2.1. '\\' folding algorithm, 6th paragraph:
> Does this have to abort if it finds a '\' character at the end of the line, and start at next?  I think that this could still be handled by folding again at that same point, which when unfolded should go back to the same input again.  Of course, such a tool might also warn that the input might already be folded input.  One of the advantages of the '\\' method is that it should be able to deterministically work on any input.

Good point, how about this?

   Scan the text content to ensure no existing lines already end with a
   backslash ('\') character while the subsequent line starts with a
   backslash ('\') character as the first non-space (' ') character, as
   this could lead to an ambiguous result.  If such a line is found, and
   its width is less than the desired maximum, then it SHOULD be flagged
   for forced folding (folding even though unnecessary).  If the folding
   implementation doesn't support forced foldings, it MUST exit.

   <snip>

   For each line in the text content, from top-to-bottom, if the line
   exceeds the desired maximum, or requires a forced folding, then fold
   the line by:



> Final comment, and it is probably a bit late for this, but rather than having two separate schemes, I have one quick idea for merging the two.
> 
<snip>

Yes, too late for that kind of change I think, at least I'm not interested in investing the time to see if its viable.


Kent // author