On 18/04/2017 17:31, Andy Bierman wrote:
On Tue, Apr 18, 2017 at 2:32 AM, Robert Wilton <[email protected]
<mailto:[email protected]>> wrote:
On 13/04/2017 17:08, Andy Bierman wrote:
On Thu, Apr 13, 2017 at 5:45 AM, Ladislav Lhotka <[email protected]
<mailto:[email protected]>> wrote:
> On 13 Apr 2017, at 13:34, t.petch <[email protected]
<mailto:[email protected]>> wrote:
>
>
> ----- Original Message -----
> From: "Andy Bierman" <[email protected]
<mailto:[email protected]>>
> Sent: Wednesday, April 12, 2017 5:44 PM
>
>> On Wed, Apr 12, 2017 at 6:02 AM, Juergen Schoenwaelder <
>> [email protected]
<mailto:[email protected]>> 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
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
