Subject: [netmod] Alissa Cooper's Abstain on draft-ietf-netmod-artwork-folding-09: (with COMMENT)

From: Alissa Cooper via Datatracker <[email-masked]>
Date: Wed, 04 Sep 2019 11:56:17 -0700

Alissa Cooper has entered the following ballot position for
draft-ietf-netmod-artwork-folding-09: Abstain

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

RFC 7994 is not a product of IETF consensus, so it seems inappropriate to
publish a consensus BCP predicated on requirements defined in RFC 7994 which
themselves do not have IETF consensus. This would be the only document related
to the RFC format in the last 10 years that I'm aware of that would be
published on the IETF stream.

There has been discussion about how embedding YANG models in RFCs seems like a
poor fit for a number of reasons. By standardizing line-folding mechanisms and
claiming them as a best practice, this document reinforces the root of that
problem rather than trying to fix it.

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 05 Sep 2019 08:42:06 +0200

> https://datatracker.ietf.org/doc/draft-ietf-netmod-artwork-folding/

Well said, I agree with Alissa's conclusion.

Lada

> 
> 
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Kent Watsen <[email-masked]>
Date: Thu, 5 Sep 2019 15:08:52 +0000

> Well said, I agree with Alissa's conclusion.

Assuming 'a', yes, 'b' follows 'a'.  That said, the concern is nebulous
and how to address it more so.  Proposals?

Assuming the concern is process-overhead for minor spins, perhaps we
could leverage the module-versioning work as follows:

  * Initial and NBC modules go thru standard RFC publishing process (i.e.,
    there is still a need to publish YANG modules in RFCs).

  * BC modules can skip standard publishing process but, to be an "IETF"
    product (not some random fork), they would need to be released via an
    IETF-owned mechanism (e.g., an Git repo) with restricted write-access.

Thoughts?

Kent

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 05 Sep 2019 17:17:30 +0200 (CEST)

> > Well said, I agree with Alissa's conclusion.

But the algorithm in the document isn't supposed to be used for YANG
modules.  It is supposed to be used primarily for XML and JSON
snippets (etc).

> Assuming the concern is process-overhead for minor spins

I think we need to understand what the "number of reasons" Alissa
refers to really are, before we try to come up with solutions.

/martin

> , perhaps we

---

From: Erik Auerswald <[email-masked]>
Date: Thu, 5 Sep 2019 18:32:16 +0200

Hi Martin,

> modules.  It is supposed to be used primarily for XML and JSON

Technically, XML and JSON are whitespace-agnostic and often can be
"folded" manually without any folding indicators.  That seems to be
true for YANG as well.  Even Python code usually can be kept under any
reasonable line length.

Very long names or values could require algorithmic folding, i.e.,
a generic line-folding mechanism.

I personally would try to keep the line length of any code inside an
RFC short enough to not need additional algorithmic folding.  But if
this does not work, e.g., because some name or value is just too long,
having a recommended algorithm seems to be better than every author
making up another ad-hoc folding scheme.

The I-D.ietf-netmod-artwork-folding seems to try to provide a recommended
algorithm for the case where a generic line-folding mechanism is needed.

Overly long lines sometimes result in lost information in HTML or PDF
documents, if a complex layout is used, but no mechanism for dealing with
unexpectedly long lines is included.  I have seen too many examples of
this to believe that this cannot happen with RFCs.

Thanks,
Erik

---

From: Kent Watsen <[email-masked]>
Date: Thu, 5 Sep 2019 16:46:25 +0000

Hi Alissa,

Thank you for your review.  Comments below.

Kent // as co-author

> On Sep 4, 2019, at 2:56 PM, Alissa Cooper via Datatracker <[email-masked]> wrote:
> 

Agreed.   Should the draft re-run through the IAB stream?

> problem rather than trying to fix it.

FWIW, YANG modules are themselves never expected to be folded.  Per Section 5.2 of the draft, authors should do as much as possible within the YANG format to avoid long lines.  From the NETMOD WG's perspective, this draft is primarily targeting the XML and JSON examples that should accompany a draft publishing a YANG module.

That said, while I'm aware of the concern, it remains unclear, and how to address it more so.  In the meanwhile, there are real and immediate issues with the ability to use automation to validate structural content in drafts (e.g.,  https://tools.ietf.org/html/draft-kwatsen-git-xiax-automation-01#section-6 <https://tools.ietf.org/html/draft-kwatsen-git-xiax-automation-01#section-6>).  This is not just a YANG issue, it is an issue that spans the IETF, and a solution for it might be considered best practice.

Regarding the BCP attribution, I don't have a preference.  Actually, I think it was the WG that pushed for it.  I only think the IETF should label it right, re-running it thru IAB stream if need be.   As I see it, the "best practice" is that draft authors SHOULD stitch pre-folded inclusions so as to enable automated verification.  The format itself is not best practice.  That said, a better solution would be for IETF to 1) only support XML-based uploads and 2) have Datatracker auto-fold inclusions as needed for plain-text and PDF outputs (note that folding is NOT needed, or desired, for HTML output).

Kent // as co-author

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 05 Sep 2019 21:13:44 +0200

> and how to address it more so.  Proposals?

First, one can ask whether it is a good idea to have RFCs as the authoritative
source of YANG modules. I don't think so.

Otherwise, if the practice of including YANG modules in RFCs continues, I would
suggest to include YANG modules unchanged in xml2rfc and leave the presentation
issues to the RFC Editor (or their tools). With the upcoming RFC format change
there will be more publication formats (HTML, TXT, PDF, EPUB), so it is IMO
ridiculous to modify the source code in order to suit one of them. For example,
I don't want to see folded lines in HTML-formatted RFCs.

>     there is still a need to publish YANG modules in RFCs).

Why? The RFC could include a link to an external module resource (possibly with
a hash to guarantee that the referred resource hasn't been modified).

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 05 Sep 2019 21:30:45 +0200

> modules.  It is supposed to be used primarily for XML and JSON

My main concern is YANG, or any other code that is supposed to be both read in
the RFC and extracted from it.

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 06 Sep 2019 09:25:15 +0200 (CEST)

Erik Auerswald <[email-masked]> wrote:
> Technically, XML and JSON are whitespace-agnostic

Whitespaces are significant in XML element values, which means that we
have to write e.g.

    <discontinuity-time>2013-04-01T03:00:00+00:00</discontinuity-time>

With indentation for readability we quickly run out of horizontal
space.

> and often can be
> true for YANG as well.

It is true for YANG, which is why I wrote that this algorithm isn't
supposed to be used for YANG.  In fact, the document says:

   It is RECOMMENDED that authors do as much as possible within the
   selected format to avoid long lines.

> Even Python code usually can be kept under any
> reasonable line length.
> 

Exactly!

/martin