Robert Wilton <[email protected]> writes: > 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. > > 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 _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
