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

[Andy Bierman <[e-mail]>]

On Tue, Apr 18, 2017 at 2:32 AM, Robert Wilton <[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]> wrote:
>
>>
>> > On 13 Apr 2017, at 13:34, t.petch <[e-mail]> wrote:
>> >
>> >
>> > ----- Original Message -----
>> > From: "Andy Bierman" <[e-mail]>
>> > Sent: Wednesday, April 12, 2017 5:44 PM
>> >
>> >> On Wed, Apr 12, 2017 at 6:02 AM, Juergen Schoenwaelder <
>> >> [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.
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).
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.



>
> 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
  (2) the only tool that needs to use the raw markup is a browser
  (3) the actual markup allowed is strictly controlled and standardized


> 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