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

[Ladislav Lhotka <[e-mail]>]

Robert Wilton <[e-mail]> writes:

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

Absolutely. People are converting YANG modules to UML and other formats.

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

Of course, I am far from claiming that this is urgent or terribly
important, I just realized in my recent work that lightweight markup can
make life of tool makers easier without significantly complicating the
reading of module source text.

Lada

>
> Rob
>
>
>
>
>
>

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67