Re: [netmod] WG adoption poll draft-lhotka-netmod-yang-markup-00

[Robert Wilton <[e-mail]>]

On 13/04/2017 17:08, Andy Bierman wrote:
>
>
> On Thu, Apr 13, 2017 at 5:45 AM, Ladislav Lhotka <[e-mail] 
> <mailto:[e-mail]>> wrote:
>
>
>     > On 13 Apr 2017, at 13:34, t.petch <[e-mail]
>     <mailto:[e-mail]>> wrote:
>     >
>     >
>     > ----- Original Message -----
>     > From: "Andy Bierman" <[e-mail]
>     <mailto:[e-mail]>>
>     > Sent: Wednesday, April 12, 2017 5:44 PM
>     >
>     >> On Wed, Apr 12, 2017 at 6:02 AM, Juergen Schoenwaelder <
>     >> [e-mail]
>     <mailto:[e-mail]>> wrote:
>     >>
>     >>> I think it is crucial that descriptions etc. remain human readable
>     >>> using plain text readers. Having to run a renderer to make
>     sense out
>     >>> of descriptions etc. would be a big failure and things are even
>     > worse
>     >>> if modules use different dialects all over the place.
>     >>>
>     >>> I believe there is way more important work to get done than this
>     > (and
>     >>> I fear endless discussions about which adapted subsets of markdown
>     > or
>     >>> (whatever comes next) to use). I do not object this work, but
>     I also
>     >>> do not support it at this point in time.
>     >>>
>     >>>
>     >> +1
>     >>
>     >> IMO this makes YANG less readable, especially without any agreement
>     >> on the specific markup supported. A YANG module should be
>     readable by
>     > humans
>     >> without any special tools required.
>     >
>     > I agree.  I would say that if you cannot say it in text/plain,
>     then you
>     > probably should not be saying it (something I would extend to
>     e-mail but
>     > realise that I am less likely to get support there:-)
>
>     OK, so if somebody writes
>
>     leaf foo {
>         description "This is my *favourite* leaf.";
>         type string;
>     }
>
>
> Your premise is that the description-stmt is for the
> benefit of the model writer, not the model reader.
> Since YANG explicitly states this statement contains a human-readable
> string, it seems clear the benefit to the readers is more important.

I see that the benefit of allowing markdown really is for the model 
reader.  Longer term, I assume that operators using YANG models probably 
won't interact so much with the raw YANG models themselves, but will be 
much more likely to interact with the constructed tree structure through 
a web browser, or generated APIs.

Allowing markup, e.g. so a paragraph of text can re-flow to fill a box 
seems useful to me, as does some sort of emphasis and lists.

I also note that quite a lot (most?) language API documentation tools 
generally take some form of structured text, rather than relying on 
text/plain.

But I do agree to the point that this work seems less urgent than some 
of other items that are being worked on in NETMOD.

Rob