Subject: Re: [Rfc-markdown] [netmod] too long lines from IANA module inclusion

From: Carsten Bormann <[email-masked]>
Date: Fri, 17 Dec 2021 16:38:07 +0100

Now you made me curious.
No RFCs use RFC 8792 encoding yet (except for RFC 8792 itself), as you said.

I-Ds:

  "Grant Negotiation and Authorization Protocol", Justin Richer, Aaron
  Parecki, Fabien Imbault, 2021-10-25, <draft-ietf-gnap-core-protocol-08.txt>

(Using this for JSON text.)

  "Problem Details for HTTP APIs", Mark Nottingham, Erik Wilde, Sanjay Dalal,
  2021-10-13, <draft-ietf-httpapi-rfc7807bis-01.txt>

(Using this for JSON text containing a json-schema.org description.)

  "HTTP Message Signatures", Annabelle Backman, Justin Richer, Manu Sporny,
  2021-08-13, <draft-ietf-httpbis-message-signatures-06.txt>

(Using this for examples of Signature-Input, Signature.)

  draft-ietf-netconf-crypto-types-21.txt, draft-ietf-netconf-http-client-server-08.txt, draft-ietf-netconf-https-notif-09.txt, draft-ietf-netconf-keystore-23.txt, draft-ietf-netconf-netconf-client-server-24.txt, draft-ietf-netconf-notification-capabilities-21.txt, draft-ietf-netconf-restconf-client-server-24.txt, draft-ietf-netconf-ssh-client-server-26.txt, draft-ietf-netconf-tls-client-server-26.txt, draft-ietf-netconf-trust-anchors-16.txt, draft-ietf-netmod-yang-instance-file-format-21.txt)

(Tons of netconf drafts, apparently using this mainly for XML examples — I didn’t check all of those.)

  "Conveying a Certificate Signing Request (CSR) in a Secure Zero Touch
  Provisioning (SZTP) Bootstrapping Request", Kent Watsen, Russ Housley, Sean
  Turner, 2021-12-03, <draft-ietf-netconf-sztp-csr-12.txt>

(As mentioned, for a YANG tree, HTTP requests, JSON text.)

  "A Layer 2 VPN Network YANG Model", samier barguil, Oscar de Dios, Mohamed
  Boucadair, Luis Munoz, 2021-11-22, <draft-ietf-opsawg-l2nm-12.txt>

(YANG JSON instances, again.)

  "A Layer 3 VPN Network YANG Model", samier barguil, Oscar de Dios, Mohamed
  Boucadair, Luis Munoz, Alejandro Aguado, 2021-10-08,
  <draft-ietf-opsawg-l3sm-l3nm-18.txt>

(Overly long HTTP requests.)

  "Structured Data for Filtered DNS", Dan Wing, Tirumaleswar Reddy.K, Neil
  Cook, Mohamed Boucadair, 2021-10-13,
  <draft-wing-dnsop-structured-dns-error-page-01.txt>

(JSON.)

  "List Pagination for YANG-driven Protocols", Kent Watsen, Qin WU, Olof
  Hagsand, Hongwei Li, Per Andersson, 2021-10-25,
  <draft-wwlh-netconf-list-pagination-00.txt>

  "NETCONF Extensions to Support List Pagination", Kent Watsen, Qin WU, Olof
  Hagsand, Hongwei Li, Per Andersson, 2021-10-25,
  <draft-wwlh-netconf-list-pagination-nc-02.txt>

  "RESTCONF Extensions to Support List Pagination", Kent Watsen, Qin WU, Olof
  Hagsand, Hongwei Li, Per Andersson, 2021-10-25,
  <draft-wwlh-netconf-list-pagination-rc-02.txt>

(HTTP requests, some XML.)

And, crucially for an implementer, no ‘\\’ wrapping, except (unnecessarily!) in draft-ietf-netconf-ssh-client-server-21.txt (apparently fixed in later versions.)

The form

   =============== NOTE: '\' line wrapping per RFC 8792 ================

(15 equals signs left, 16 equals signs right) seems to be the favorite lead-in; however, draft-wing-dnsop-structured-dns-error-page-01.txt had a version indented by 2 characters that has 14+15 accordingly.  About 5 % 10+11, apparently before RFC 8792 was published so there was less space.)

Examples from the HTTP ecosystem (GNAP, HTTPAPI, HTTPBIS) didn’t have any “===“ decoration, though.  (Why the heck was this left open as a choice for the author?  I like “%%%” decoration instead, should I use that as a personal fashion statement?)

Grüße, Carsten

---

From: Kent Watsen <[email-masked]>
Date: Fri, 17 Dec 2021 16:31:24 +0000

> (15 equals signs left, 16 equals signs right) seems to be the favorite lead-in; however, draft-wing-dnsop-structured-dns-error-page-01.txt had a version indented by 2 characters that has 14+15 acco…

Undoubtedly because it is the rfcfold (https://github.com/ietf-tools/rfcfold) default.  The goal is to hit column-69 so as to provide a visual scanning aid.

> Examples from the HTTP ecosystem (GNAP, HTTPAPI, HTTPBIS) didn’t have any “===“ decoration, though.  (Why the heck was this left open as a choice for the author?  I like “%%%” decoration instead, s…

Because sometimes it is desirable for the bracketing to match the native file commenting syntax (e.g., “#“ for shell/Python, “//“ for C++, “;” for ABNF, etc.)

K.

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 17 Dec 2021 18:12:43 +0100

> Because sometimes it is desirable for the bracketing to match the native file commenting syntax (e.g., “#“ for shell/Python, “//“ for C++, “;” for ABNF, etc.)

But those tools never see that header.
(Or are there examples where you can safely feed a folded block to a tool?)

Grüße, Carsten

---

From: Kent Watsen <[email-masked]>
Date: Fri, 17 Dec 2021 17:21:26 +0000

Hi Carsten,

> (Or are there examples where you can safely feed a folded block to a tool?)

Not always.  The draft specifically allows for manual/smart folding to give better results than simple automation:  See https://datatracker.ietf.org/doc/html/rfc8792#section-9.3 for more examples.

K.

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 19 Dec 2021 18:13:53 +1100

> Examples from the HTTP ecosystem (GNAP, HTTPAPI, HTTPBIS) didn’t have any “===“ decoration, though.  (Why the heck was this left open as a choice for the author?  I like “%%%” decoration instead, s…

Textual decoration around features like this makes sense in an ASCII-only RFC format. They're anachronistic in a HTML view of the spec.

Cheers,

--
Mark Nottingham   https://www.mnot.net/

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 19 Dec 2021 08:28:00 +0100

> Textual decoration around features like this makes sense in an ASCII-only RFC format. They're anachronistic in a HTML view of the spec.

I’d say features like this should not be visible in the XML at all but should be applied during rendering.
But that’s not what we have today; we need to live with a common form for the various renderings.

So what are the functions of the decoration?

— alert to the fact that the line-breaking is happening (so the final backslashes are not actually part of the example)
— provide a visual reference for the right margin of the line breaking

That said, I’ll probably provide a “dry” folding option to accommodate your preference of no decoration.

Another option is whether the broken-off parts are left-aligned (and with which indent then) or right-aligned.

Grüße, Carsten