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

From: tom petch <[email-masked]>
Date: Mon, 1 Oct 2018 11:46:42 +0000

----- Original Message -----
From: "Adrian Farrel" <[email-masked]>
Sent: Saturday, September 29, 2018 12:51 AM

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.

<tp>

Adrian

That sounds like a good way forward; it calls for a number of changes,
tightening the applicability in sections 1, 2, 3 and 4 IMO.

Tom Petch

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,
>
> 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
>
> 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
>
>
>
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Kent Watsen <[email-masked]>
Date: Mon, 1 Oct 2018 18:25:07 +0000

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

I'm unsure what the problem at hand is, but there is nothing NETMOD
specific about this, and we (the IETF) wouldn't want each WG rolling
their own solution.  Also, note Martin's strong objection to seeing
this being used for tree-diagrams and yang modules, so even less 
NETMOD specific...

Adrian previously wrote "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."  I agree, the ultimate
goal would be to integrate this with `xml2rfc`, but it should be free
to do so without regard for what kind of artwork it is, or from which
WG it came from.

Where in our rather liberal NETMOD charter sanctions this work?

Kent // pick a hat

---

From: Kent Watsen <[email-masked]>
Date: Mon, 1 Oct 2018 20:15:36 +0000

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

Removed "YANG" and s/(e.g., tree diagrams)/, using a tool that doesn't
observe line lengths.  FWIW, pyang's --tree-line-length sometimes 
produces results worse than folded artwork.

> Also remove YANG from 4.1

Done.

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

You mean, as anti-examples?

Kent // contributor