Subject: Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt

From: tom petch <[email-masked]>
Date: Fri, 21 Sep 2018 12:01:51 +0000

Not about tabs!

When I look at YANG modules, which I have done a bit of this year, I
have two problems with line lengths, making it harder for me to review
the I-Ds.

One is the lengthy lines in the YANG tree diagram and that this I-D
clearly addresses.

The other is lines that are too long, for an RFC, in the YANG module,
typically in description clauses and in comment lines.  I don't know
what the editors are doing to get such lines into an I-D but they do so
I would like a paragraph in this I-D to the effect that editors should
take care of this and that this phenomenon is nothing to do with the
technique described here, a sort of non-Applicability statement so that
we do not, in future, get too long lines as

      /* optical interface func needs to expand for Fiber Channel,\
\ SONET and SDH */

instead of turning them into

      /* optical interface func needs to expand
          for Fiber Channel, SONET and SDH */

I tried to explain this to an editor recently and had great difficulty
in getting across that there was a problem, and this is not an isolated
case; hence my wish to have something to point to about it.

Tom Petch

----- Original Message -----
From: "t.petch" <[email-masked]>
To: "Carsten Bormann" <[email-masked]>; "Robert Wilton"
<rwilton=[email-masked]>
Cc: <[email-masked]>
Sent: Tuesday, September 18, 2018 10:53 AM

> ----- Original Message -----
> From: "Carsten Bormann" <[email-masked]>
> Sent: Friday, September 14, 2018 12:14 PM
>
> > On Sep 14, 2018, at 13:05, Robert Wilton
> <rwilton=[email-masked]> wrote:
> > >
> > > If all input files that we might ever want to fold and include in
an
> RFC are guaranteed to never contain tabs then I agree with the
position
> that they can just be rejected.
> >
> > Yep.
> >
> > > But if there is some future file format that we want to fold that
> might contain tabs, then I wonder whether it would not be more robust
to
> look at whether they could be handled in some way.
> >
> > VT characters (colloquially tabs) should not be significant in any
> file format designed in the last couple of decades (i.e., they should
be
> replaceable by spaces).  If they (or any other characters not
> representable in RFCs) are, or preserving byte wise identity is
> important, follow the lead of RFC 6716 and base64-encode.
>
> This confuses me.  This I-D references RFC7991 which clearly defines
tab
> as  9, which RFC20 labels H(orizontal) T(ab).  V(ertical) T(ab) is 11.
>
> I would not expect VT to appear in any recent document but when it
does,
> then replacing it by spaces would be wrong, IMHO.  HT I do see, far
too
> much of, because there is no metadata saying what the Horizontal Tab
> settings should be and while a  value of five is common, there are RFC
> where replacing tab characters with five spaces yields rubbish.
>
> Tom Petch
>
>
>
>
>
>
> >
> > Grüße, Carsten
> >
> > _______________________________________________
> > netmod mailing list
> > [email-masked]
> > https://www.ietf.org/mailman/listinfo/netmod
> >
>

---

From: Kent Watsen <[email-masked]>
Date: Mon, 24 Sep 2018 20:49:15 +0000

Hi Tom,

>         for Fiber Channel, SONET and SDH */

Section 4.2 addresses this.  In particular, the last line says:

  As such, it is RECOMMENDED that authors do as much as possible within
  the selected format to avoid long lines.

Good enough?

Kent // contributor

---

From: tom petch <[email-masked]>
Date: Tue, 25 Sep 2018 09:48:08 +0000

---- Original Message -----
From: "Kent Watsen" <[email-masked]>
Sent: Monday, September 24, 2018 9:49 PM

>   the selected format to avoid long lines.

No:-)  The authors of YANG modules seem not to understand that it
applies to them, or incorrectly use the tools that would apply were they
correctly used.  I had in mind something such as

OLD
 [RFC7994][RFC7994]sets out the requirements for plain-text RFCs and
   states that each line of an RFC (and hence of an Internet-Draft) must
   be limited to 72 characters followed by the character sequence that
   denotes an end-of-line (EOL).

NEW
[RFC7994]sets out the requirements for plain-text RFCs and
   states that each line of an RFC (and hence of an Internet-Draft) must
   be limited to 72 characters followed by the character sequence that
   denotes an end-of-line (EOL).  This applies to all of an RFC,
including,
   for example, the comments or description clauses in a YANG module,
   and to artwork.

Not sure why you have [RFC7994] twice.

Tom Petch

---

From: Kent Watsen <[email-masked]>
Date: Wed, 26 Sep 2018 20:08:33 +0000

Hi Tom,

> applies to them, or incorrectly use the tools that would apply 
> were they correctly used.  

This seems to be a problem outside the scope of this draft.  I was 
thinking to strengthen Section 4.2 some, but this sentence really
seems to say it right:

   As such, it is RECOMMENDED that authors do as much as possible
   within the selected format to avoid long lines.

>   including, for example, the comments or description clauses in a YANG
>   module, and to artwork.

First, I'd recommend simplifying the last sentence to just "This applies
to all of an RFC, including any artwork.", but then it seems to step on
what the next paragraph says.  Perhaps the next paragraph could be 
simplified? - suggestions welcomed.

> Not sure why you have [RFC7994] twice.

Fixed in my local copy.

PS: folded YANG-modules will break tooling (e.g., module validation) until
extraction tools (i.e., `xym`) are updated to be folding aware.  Even after
this draft becomes an RFC, authors need to ensure that YANG modules are not
folded until such tools are updated.  Other artwork (tree diagrams, instance
examples, etc.) being folded is not a problem, as no automated tooling acts
on them currently.

Kent // contributor

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 26 Sep 2018 22:46:27 +0200 (CEST)

Hi,

>    within the selected format to avoid long lines.

I think you also should change the first paragraph in section 3.1:

   Automated folding of long lines is needed in order to support draft
   compilations that entail a) validation of source input files (e.g.,
   YANG, XML, JSON, ABNF, ASN.1) and/or b) dynamic generation of output
   (e.g., tree diagrams) that are stitched into the final document to be
   submitted.

At least remove YANG from the example, and I also think that
auto-folding of tree diagrams should be strongly discouraged, so find
a better example for (b).

Also remove YANG from 4.1

To further emphasize this, I think you should add YANG and tree
diagrams as examples in section 4.2.

/martin

---

From: tom petch <[email-masked]>
Date: Fri, 28 Sep 2018 12:08:02 +0000

Kent

Stepping back, I think that there is a problem of applicability.

You have labelled this I-D draft..netmod.. and are discussing it on the
netmod WG list.  Therefore I apply it to YANG I-D - to me, that is the
obvious connection - and the problem I keep seeing with YANG I-D is
lines too long - comment, description - in the YANG module so that is
the problem for which I want a solution (I see no problem with code
snippets).  This has something to do with, I know not what, the
processing cycle of YANG modules, of the module being generated outside
the I-D/RFC process and then being inserted without the constraints that
the I-D/RFC process normally apply; I recall Benoit giving an
explanation.

However, when I ignore the I-D name and the list we are on, and take the
text in isolation, then I wonder what are we doing here.  This should be
on a different list, art perhaps or the main ietf list, since what you
are proposing has nothing to do with netmod, YANG or any of the topics
that this list discusses; rather it seeks to change the whole of the
IETF.

So, put this up for adoption and I will oppose; this is outside our
remit.

Tom Petch

---

From: Kent Watsen <[email-masked]>
Date: Fri, 28 Sep 2018 22:04:38 +0000

Hi Tom,

As contributor, I agree with you.  The only reason that it is here
now is because draft-wu-netmod-yang-xml-doc-conventions did.

As chair, let me discuss with my co-chairs.  Meanwhile, would love
to hear others opinions.

Kent

----- Original Message -----

Kent

Tom Petch

---

From: "Adrian Farrel" <[email-masked]>
Date: Sat, 29 Sep 2018 00:51:52 +0100

All, the scope has become elastic over time.

When we first wrote draft-wu-netmod-yang-xml-doc-conventions we were addressing a very specific problem: drafts and RFCs contain fragments (examples) of YANG (not the YANG modules themselves, but examples with actual values). Those fragments often extend over 73 columns and so have to be wrapped from presentation in the draft/RFC, but this creates invalid YANG. So some form of documentation convention is needed to indicate that the examples should not be treated as valid YANG and to help someone map them to valid YANG.

Most documents that encountered this problem either dodged it (hoping a reviewer would not complain) or defined their own line wrapping rules. We thought it would be helpful to have a common approach and that was what we focused on.

We also noticed that (probably for formatting reasons) the examples were often being produced using the <artwork> construct in the source XML. So it seemed that there would be value in defining how that artwork could be automatically wrapped allowing the authors to not worry about line wrapping.

We recognised that wrapping figures would probably be confusing and counter-productive so we recommend against it. And we made it an explicit thing not a default.

Conversely, we noted that other "sample code" might benefit from wrapping, so we thought that should be in scope.

Then we merged our efforts with Kent's.

That's how we got here.

Now, to take it forward, I would like to constrain our efforts to solving the problem at hand. If our solution has wider applicability, that's great. But can we recognise that the overwhelming bulk of case we see today are in YANG documents and that's up to us to solve.

Thanks,
Adrian

> -----Original Message-----
> From: netmod [mailto:[email-masked]] On Behalf Of Kent Watsen
> Sent: 28 September 2018 23:05
> To: tom petch
> Cc: [email-masked]
> Subject: Re: [netmod] New Version Notification for draft-kwatsen-netmod-
> artwork-folding-07.txt
> 
> 
> Hi Tom,
>

---

From: Qin Wu <[email-masked]>
Date: Sat, 29 Sep 2018 01:33:59 +0000

+1, boiling ocean and making a common solution to address some various use cases beyond scope of netmod, YANG is not our intention.
We have already tried to come up with complicate solutions (e.g., format aware folding)before and unfortunately it adds a lot of complexity 
and has a lot of limitations.

-Qin
-----邮件原件-----
发件人: netmod [mailto:[email-masked]] 代表 Adrian Farrel
发送时间: 2018年9月29日 7:52
收件人: 'Kent Watsen'; 'tom petch'
抄送: [email-masked]
主题: Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt

That's how we got here.

Thanks,
Adrian

> Subject: Re: [netmod] New Version Notification for 
> draft-kwatsen-netmod- artwork-folding-07.txt
> 
> 
> Hi Tom,
> 
> As contributor, I agree with you.  The only reason that it is here now 
> is because draft-wu-netmod-yang-xml-doc-conventions did.
> 
> As chair, let me discuss with my co-chairs. Meanwhile, would love to 
> hear others opinions.
> 
> Kent
> 
> 
> You have labelled this I-D draft..netmod.. and are discussing it on 
> the netmod WG list.  Therefore I apply it to YANG I-D - to me, that is 
> the obvious connection - and the problem I keep seeing with YANG I-D 
> is lines too long - comment, description - in the YANG module so that 
> is the problem for which I want a solution (I see no problem with code 
> processing cycle of YANG modules, of the module being generated 
> outside the I-D/RFC process and then being inserted without the 
> constraints that the I-D/RFC process normally apply; I recall Benoit 
> giving an explanation.
> 
> However, when I ignore the I-D name and the list we are on, and take 
> the text in isolation, then I wonder what are we doing here.  This 
> should be on a different list, art perhaps or the main ietf list, 
> since what you are proposing has nothing to do with netmod, YANG or 
> any of the topics that this list discusses; rather it seeks to change 
> the whole of the IETF.
>