Re: [netmod] Adam Roach's No Objection on draft-ietf-netmod-artwork-folding-09: (with COMMENT)

[Kent Watsen <[e-mail]>]

Hi Adam,

Thank you for your review.  Comments below.

Update @ https://tools.ietf.org/html/draft-ietf-netmod-artwork-folding-10 <https://tools.ietf.org/html/draft-ietf-netmod-artwork-folding-10>

Kent // as co-author


> On Sep 3, 2019, at 8:34 PM, Adam Roach via Datatracker <[e-mail]> wrote:
> 
> Adam Roach has entered the following ballot position for
> draft-ietf-netmod-artwork-folding-09: No Objection
> 
> When responding, please keep the subject line intact and reply to all
> email addresses included in the To and CC lines. (Feel free to cut this
> introductory paragraph, however.)
> 
> 
> Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
> for more information about IESG DISCUSS and COMMENT positions.
> 
> 
> The document, along with other ballot positions, can be found here:
> https://datatracker.ietf.org/doc/draft-ietf-netmod-artwork-folding/
> 
> 
> 
> ----------------------------------------------------------------------
> COMMENT:
> ----------------------------------------------------------------------
> 
> Thanks for taking on this work to fill a hole in the tools that
> we have for production of RFCs. I have one fairly major comment
> and several editorial suggestions.
> 
> ---------------------------------------------------------------------------
> 
> Abstract:
> 
>> This document defines two strategies for handling long lines in
>> width-bounded text content.  One strategy is based on the historic
>> use of a single backslash ('\') character to indicate where line-
> 
> Nit: "historical"

Fixed.


> ---------------------------------------------------------------------------
> 
> §1:
> 
>> According to the RFC Editor,
>> there is currently no convention in place for how to handle long
>> lines in such inclusions, other than advising authors to clearly
>> indicate what manipulation has occurred.
> 
> This won't age well. Perhaps "Historically, there has been no
> RFC-Editor-recommended convention in place for how to handle..."

Suggested text incorporated.


> ---------------------------------------------------------------------------
>> This document defines two strategies for handling long lines in
>> width-bounded text content.  One strategy is based on the historic
>> use of a single backslash ('\') character to indicate where line-
> 
> Nit: "historical"

Fixed.


> ---------------------------------------------------------------------------
> 
> §7.1.1:
> 
>>  NOTE: '\' line wrapping per BCP XXX (RFC XXXX)
> 
> Using this string as the start of the specially-wrapped section
> seems somewhat problematic, as it forecloses on the possibility
> of also *citing* this BCP at that point in the document. For example,
> if I were to use this format, I would definitely want to use a string
> more of the format:
> 
>    NOTE: '\' line wrapping per BCP XXX ([RFC XXXX])
> 
> (taking note of the added brackets).
> 
> If this has already been debated in the working group and the current text
> is the result of carefully considering this issue and deciding that the
> use of the specified string has benefits that outweigh the drawback of
> not being able to cite the document per ordinary convention, then don't afford
> my suggestion any undue weight. I'm not trying to change a consensus decision.
> 
> But if this is a simple oversight, I think it does need to be given
> significant thought. For example, I personally am rather likely to elect to do
> things "the old way" in my own documents rather than using this format because
> of the awkwardness of properly citing a normative reference.
> 
> This same comment applies to §8.1.1, of course.

Unsure.  To provide context, YANG modules many times include references to RFCs in artwork sections.  I used to put these references inside square brackets, but the RFC Editors would convert them to parentheses.  I have since moved to using parentheses, e.g., "(RFC XXXX)", in artwork and haven't experienced any corrections since.

Leaving as is for now.



> ---------------------------------------------------------------------------
> 
>> Appendix A.  POSIX Shell Script: rfcfold
> 
> Please add [POSIX.1-2017] as a reference.

I've replaced "POSIX" with "Bash", and added a reference for Bash.


Kent // as co-author