Subject: [netmod] WG adoption poll draft-kwatsen-netmod-artwork-folding-08

From: Lou Berger <[email-masked]>
Date: Thu, 18 Oct 2018 09:03:42 -0400

All,

This is start of a two week poll on making
draft-kwatsen-netmod-artwork-folding-08 a working group
document. Please send email to the list indicating "yes/support" or
"no/do not support".  If indicating no, please state your reservations
with the document.  If yes, please also feel free to provide comments
you'd like to see addressed once the document is a WG document.

The poll ends Oct 1.

Thanks,

Lou (and co-chairs)

---

From: Lou Berger <[email-masked]>
Date: Thu, 18 Oct 2018 09:13:18 -0400

Poll ends Nov 1 - sorry about that...

On 10/18/2018 9:03 AM, Lou Berger wrote:
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: Kent Watsen <[email-masked]>
Date: Thu, 18 Oct 2018 14:40:35 +0000

[fixed the date in Lou's message below]

No objection.

Kent // contributor

-----Original Message-----
From: Lou Berger <[email-masked]>
Date: Thursday, October 18, 2018 at 9:11 AM
To: "[email-masked]" <[email-masked]>
Cc: "[email-masked]" <[email-masked]>
Subject: WG adoption poll draft-kwatsen-netmod-artwork-folding-08
Resent-From: <[email-masked]>
Resent-To: <[email-masked]>, <[email-masked]>, <[email-masked]>
Resent-Date: Thursday, October 18, 2018 at 9:11 AM

All,

The poll ends Nov 1.

Thanks,

Lou (and co-chairs)

---

From: Robert Wilton <[email-masked]>
Date: Thu, 18 Oct 2018 16:20:41 +0100

Yes/support.

Thanks,
Rob

On 18/10/2018 14:03, Lou Berger wrote:
> .

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 18 Oct 2018 10:47:03 -0700

Support.

> On Oct 18, 2018, at 6:03 AM, Lou Berger <[email-masked]> wrote:
> 
> All,
> 

Mahesh Jethanandani
[email-masked]

---

From: "Adrian Farrel" <[email-masked]>
Date: Fri, 19 Oct 2018 11:12:28 +0100

Hey Lou,

As an author, I support adoption and would particularly welcome feedback from
the WG to know whether this approach addresses the needs of those writing drafts
for YANG models.

Thanks,
Adrian

> From: netmod [mailto:[email-masked]] On Behalf Of Lou Berger
> Sent: 18 October 2018 14:04
> To: NetMod WG
> Cc: NetMod WG Chairs
> Subject: [netmod] WG adoption poll draft-kwatsen-netmod-artwork-folding-08
> 
> All,
>

---

From: Robert Wilton <[email-masked]>
Date: Fri, 19 Oct 2018 11:41:04 +0100

Hi Adrian, all,

What is the intended scope?

1) Is it just for examples of YANG requests/replies, or in future, 
instance data.  If so, then I think that the solution is useful for this.

2) Or should the WG consider allowing a longer line length for YANG 
modules?  Currently they are limited to something like 69 characters so 
that they can be inserted into the RFC, but possibly with line folding 
we could possibly consider increasing that, but perhaps that would make 
them harder to read/review.

3) I think that there are also cases where tree diagrams wrap and need 
to be constrained to 69 characters.  Although I don't think that 
applying the folding algorithm to tree diagrams directly is necessarily 
a great idea, it might be that tools like pyang could be modified with 
an option to generate output that is consistent with the definition of 
the folded output so that it can be unfolded if required.

To give an example of 3:

Rather than this:

    module: ietf-if-l3-vlan
      augment /if:interfaces/if:interface/if-cmn:encapsulation/
                                                     if-cmn:encaps-type:
        +--:(dot1q-vlan)
           +--rw dot1q-vlan
              +--rw outer-tag!
              |  +--rw tag-type    dot1q-tag-type
              |  +--rw vlan-id     ieee:vlanid
              +--rw second-tag!
                 +--rw tag-type    dot1q-tag-type
                 +--rw vlan-id     ieee:vlanid

the tooling could be modified to optionally generate this instead:

========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) ===========
  
   module: ietf-if-l3-vlan
      augment /if:interfaces/if:interface/if-cmn:encapsulation/\
                                                    \if-cmn:encaps-type:
        +--:(dot1q-vlan)
           +--rw dot1q-vlan
              +--rw outer-tag!
              |  +--rw tag-type    dot1q-tag-type
              |  +--rw vlan-id     ieee:vlanid
              +--rw second-tag!
                 +--rw tag-type    dot1q-tag-type
                 +--rw vlan-id     ieee:vlanid

One other question:

How does the algorithm know it has reached the end of the artwork?  I.e. 
should there also be an end line marker?

Thanks,
Rob

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 23 Oct 2018 10:16:05 +0200 (CEST)

Hi,

I support the adoption of this document, and I intend to help by
reviewing it.

(one quick comment; the header used in the examples in section 8 isn't
equal to the header defined in section 5.1)

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 23 Oct 2018 14:40:57 +0200

Hi,

I support the adoption.

Comments:

1. My general feeling is that such technicalities should be handled by
   the RFC editor and/or tools rather than YANG module and RFC authors.

2. xml2rfc v3 introduced a new element, <sourcecode>, that is intended
   for source code inclusion. This document should therefore cover this
   element as well (primarily?). One problem with it is that the xml2rfc
   tool automatically adds the <CODE BEGINS> and <CODE ENDS> markers,
   which interferes with YANG convention specified in RFC 8407,
   sec. 3.2. I have already raised a question about this in the
   xml2rfc-dev mailing list.

Lada

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 23 Oct 2018 15:23:53 +0200

>    xml2rfc-dev mailing list.

Update: using the "name" attribute with <sourcecode> does the right thing.

    <sourcecode name="[email-masked]">
    ...
    </sourcecode>

results in

    <CODE BEGINS> file "[email-masked]"
    ...
    <CODE ENDS>

Lada

---

From: "Adrian Farrel" <[email-masked]>
Date: Tue, 23 Oct 2018 14:45:49 +0100

Hi,

1. I think you miss the point. While example XML/JSON YANG is included in
drafts, and while the authors are allowed to produce those drafts as txt files,
or while the authors want to achieve pretty-to-read formatting, this work falls
into the scope of those authors.

2. Yes, the authors discussed the <sourcecode> element and agreed that it will
be in scope.

However, we are all sort of waiting for xml2rfc v3 and pending completion, we
want to move this forward for v2 that is in use today.

(More than) Happy to come back and revisit this issue when v3 is deployed.

Thanks,
Adrian

> From: netmod [mailto:[email-masked]] On Behalf Of Ladislav Lhotka
> Sent: 23 October 2018 14:24
> To: [email-masked]
> Subject: Re: [netmod] WG adoption poll draft-kwatsen-netmod-artwork-folding-
> 08
>

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 23 Oct 2018 16:19:17 +0200

> into the scope of those authors.

The folding of long lines should be done as the very last (automatic) step
before the document gets published. Doing it earlier means that the source code
in this folded form can be (accidentally) further edited, which can lead to
inconsistencies.

As long as the document is being moved around and edited, it would be better to
keep the source code untouched.

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 23 Oct 2018 16:27:48 +0200 (CEST)

> in this folded form can be (accidentally) further edited, which can lead to

I will use folding e.g. for instance document examples in XML and
JSON.

My plan is to keep the example files with manually added breaks in my
repo, and as part of validation run a script that unfolds the
examples, and then validate the result.  The reason for this is that I
think readbility of the examples is important.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 23 Oct 2018 17:51:15 +0200

> think readbility of the examples is important.

This seems backwards to me. If you need to edit such an example, you may have to
remove the backslashes, reformat and insert them again.

If it's not possible to fold lines according to the syntax of a given language,
I'd prefer to keep the original lines as long as possible and rely on an
automatic procedure just before the final document is rolled out. 

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 23 Oct 2018 18:03:34 +0200 (CEST)

> automatic procedure just before the final document is rolled out. 

Fortunately, the draft allows us both to work the way we prefer.

/martin

---

From: "Adrian Farrel" <[email-masked]>
Date: Tue, 23 Oct 2018 17:57:27 +0100

Nicely said, Martin.
The intention is that if, like Ladislav, you like to work in some long-line
format, then it works as documented and the tools can wrap.
If, like me, and maybe like Martin, you think pretty formatting is something
that improves readability, the draft also lets you do that.

A

> From: Martin Bjorklund [mailto:[email-masked]]
> Sent: 23 October 2018 17:04
> To: [email-masked]
> Cc: [email-masked]; [email-masked]
> > > > > drafts, and while the authors are allowed to produce those drafts as
txt
> > > > > files,
> > > > > or while the authors want to achieve pretty-to-read formatting, this
work
> > > > > falls
> > > > before the document gets published. Doing it earlier means that the
source
> > > code
> > > > As long as the document is being moved around and edited, it would be
> better
> > > to
> > > > > 2. Yes, the authors discussed the <sourcecode> element and agreed that
> it
> > > will
> > > > > be in scope.
> > > > >
> > > > > However, we are all sort of waiting for xml2rfc v3 and pending
completion,
> > > we
> > > > > > Subject: Re: [netmod] WG adoption poll draft-kwatsen-netmod-
> artwork-
> > > folding-
> > > > > > 08
> > > > > >

---

From: Kent Watsen <[email-masked]>
Date: Tue, 23 Oct 2018 18:06:35 +0000

Correct, this document only defines a file format.

A separate effort will be needed to extend `xml2rfc` and `xym` and the like.

For those that wish to pre-fold their artwork prior to submitting the XML (hand-crafted folding --> max readability), the `xml2rfc` will not fold it again.

For those that prefer to submit the original artwork in the XML (which allows the unfolded artwork in other formats, e.g., HTML), `xml2rfc` will use an automatedly folding solution (for plain-text output only), most likely using the script in the appendix.

K.

-----Original Message-----
From: netmod <[email-masked]> on behalf of Adrian Farrel <[email-masked]>
Reply-To: "[email-masked]" <[email-masked]>
Date: Tuesday, October 23, 2018 at 12:57 PM
To: 'Martin Bjorklund' <[email-masked]>, "[email-masked]" <[email-masked]>
Cc: "[email-masked]" <[email-masked]>
Subject: Re: [netmod] WG adoption poll draft-kwatsen-netmod-artwork-folding-08

Nicely said, Martin.

A

txt
work
source
completion,
> > > > > > > > https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=KrZPO3Tm-CjeazvOlMCBP13ykv6EmeVWfaImRisTaJ4&s=M_IklytIh6SMhSQPIOsqdywCxwuMgIt5tUJ7wXhdysM&e=
> > > > > > --
> > > > > > Ladislav Lhotka
> > > > > > Head, CZ.NIC Labs
> > > > > > https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=KrZPO3Tm-CjeazvOlMCBP13ykv6EmeVWfaImRisTaJ4&s=M_IklytIh6SMhSQPIOsqdywCxwuMgIt5tUJ7wXhdysM&e=
> > > > --
> > > > Ladislav Lhotka
> > > > Head, CZ.NIC Labs
> > > > https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=KrZPO3Tm-CjeazvOlMCBP13ykv6EmeVWfaImRisTaJ4&s=M_IklytIh6SMhSQPIOsqdywCxwuMgIt5tUJ7wXhdysM&e=
> > > >
> > --
> > Ladislav Lhotka
> > Head, CZ.NIC Labs

_______________________________________________
netmod mailing list
[email-masked]
https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=KrZPO3Tm-CjeazvOlMCBP13ykv6EmeVWfaImRisTaJ4&s=M_IklytIh6SMhSQPIOsqdywCxwuMgIt5tUJ7wXhdysM&e=

---

From: Kent Watsen <[email-masked]>
Date: Tue, 23 Oct 2018 18:13:41 +0000

Hi Martin,

> one quick comment; the header used in the examples in
> section 8 isn't equal to the header defined in section 5.1

This is intentional.  Section 5.1 says:

   The first line is the following 46-character string that MAY be
   surrounded by any number of printable characters.

The rationalization here is:

  - scripts can easily center the text with equal amounts of some
    chosen character.  The script in the Appendix, which was used
    to fold examples 8.1 thru 8.4, uses '=' characters.

  - manual folding is difficult to center, and hence other framing
    is more suitable.  For instance, the example in Section 8.5.

Kent // contributor

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 23 Oct 2018 20:39:22 +0200 (CEST)

>    surrounded by any number of printable characters.

Ok.

>     is more suitable.  For instance, the example in Section 8.5.

Ok, but what's the point?  Why not use a fixed header?  IMO it might
also improve readability by have a common well-known header.

/martin

---

From: Jeff Tantsura <[email-masked]>
Date: Tue, 23 Oct 2018 11:55:16 -0700

Yes/support

Cheers,
Jeff

---

From: Robert Wilton <[email-masked]>
Date: Wed, 24 Oct 2018 09:40:28 +0100

> also improve readability by have a common well-known header.
I'm on the fence on this one. I like the idea of having a fixed header 
(and perhaps footer as well), but if they are padded to 72 characters 
then the header may be quite jarring to the surrounding text (e.g. the 
YANG tree diagram example that I provided previously, and reproduced below):

   module: ietf-if-l3-vlan

Thanks,
Rob

---

From: Joel Jaeggli <[email-masked]>
Date: Thu, 25 Oct 2018 00:11:39 -0700

Suupport

   Scan the artwork for horizontal tab characters.  If any horizontal
   tab characters appear, either resolve them to space characters or
   exit, forcing the input provider to convert them to space characters
   themselves first.

Support this only more strongly, e.g.  the general prohibition against tabs is fine. it is hard if not impossible to get 4 implementers in a room  to agree  how many spaces a tab should be.

> On Oct 18, 2018, at 06:03, Lou Berger <[email-masked]> wrote:
> 
> All,
>

---

From: Italo Busi <[email-masked]>
Date: Mon, 29 Oct 2018 11:01:09 +0000

Yes/support

We have appreciated this tool and used it to fold JSON code examples in our draft:

https://tools.ietf.org/html/draft-ietf-ccamp-transport-nbi-app-statement-03

Italo