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

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:netmod-bounces@ietf.org] On Behalf Of Kent Watsen
> Sent: 28 September 2018 23:05
> To: tom petch
> Cc: netmod@ietf.org
> 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
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod