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

[tom petch <[e-mail]>]

----- Original Message -----
From: "Adrian Farrel" <[e-mail]>
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:[e-mail]] On Behalf Of Kent Watsen
> Sent: 28 September 2018 23:05
> To: tom petch
> Cc: [e-mail]
> 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
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod