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

From: Adam Roach via Datatracker <[email-masked]>
Date: Tue, 03 Sep 2019 17:34:19 -0700

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"

---------------------------------------------------------------------------

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

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

---------------------------------------------------------------------------

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

---------------------------------------------------------------------------

> Appendix A.  POSIX Shell Script: rfcfold

Please add [POSIX.1-2017] as a reference.

---

From: Erik Auerswald <[email-masked]>
Date: Wed, 4 Sep 2019 11:12:05 +0200

Hi Adam,

please see below (inline).

On Tue, Sep 03, 2019 at 05:34:19PM -0700, Adam Roach via Datatracker wrote:
> [...]
> [...]

The script is not strictly POSIX compatible, as it uses, e.g., the Bash
contruct "[[ ... ]]". Thus I would suggest to change the appendix name
instead: s/POSIX Shell/Bash/

Please note that I did not audit the script for additional non-POSIX
shell constructs.

The script uses non-POSIX tools as well, and sometimes uses tools that
are part of POSIX in a non-portable way, i.e., relying on (common,
but non-standard) extensions to POSIX.

Thanks,
Erik

---

From: Kent Watsen <[email-masked]>
Date: Thu, 5 Sep 2019 22:03:35 +0000

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 <[email-masked]> wrote:
> 

Fixed.

Suggested text incorporated.

Fixed.

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.

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

Kent // as co-author