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

[Robert Wilton <[e-mail]>]

On 18/04/2017 17:31, Andy Bierman wrote:
>
>
> On Tue, Apr 18, 2017 at 2:32 AM, Robert Wilton <[e-mail] 
> <mailto:[e-mail]>> wrote:
>
>
>
>     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.
>
>
> IMO it is more robust not to assume people never see the real YANG 
> statements.
I don't want the real YANG statements to become unreadable or even less 
readable.  But I think that description formatted as markdown is quite 
readable anyway (which is why people choose to use it).


> What if these tools have bugs?  How would we ever know?
>
>     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.
>
>
>
> This part confuses me.  I've written YANG to HTML tools (e.g., 
> netconfcentral.org <http://netconfcentral.org>).
> The tool has to render the entire module, not individual 
> description-stmts.
> Emphasis is usually formula-driven (like the keywords). The tool has 
> to know about the entire YANG module, not
> just the descriptions.
You render the module exactly as you do today, but allows the 
description statements to be formatted cleanly.

E.g. looking at your tool, the formatting of the description text looks 
a bit clunky in places.  In some places, you have a wide box, but the 
description is rendered in a monospace format, with lines artificially 
wrapping half way across the box.  It seems that the description isn't 
being treated as a string so much as a manual space character formatted 
block of text.

In other places, you have allowed the description statement to re-flow 
to fit the box, but this will be messy/wrong if the author has used 
whitespace to format the description.

Using markup would allow both cases to rendered correctly.

>
>
>     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.
>
>
> This makes sense if
>   (1) the entire document is subject to markup, not little pieces
The rest of YANG is already structured, no markup is required.


>   (2) the only tool that needs to use the raw markup is a browser
It doesn't have to just be a browser, it can be rendered for anything.  
Browser, print, mobile, whatever.


>   (3) the actual markup allowed is strictly controlled and standardized
This I agree with, hence why I proposed that only a small common subset 
of markdown be specified.

>
>
>     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.
>
>
> Good -- work such as the OpenConfig module catalog will have a much 
> bigger impact
> demystifying YANG than bold text or an IMG bullet points instead of *.
>
>
>     Rob
>
>
>
>
>
>
>
> Andy
>
Rob