On Tue, Apr 18, 2017 at 2:32 AM, Robert Wilton <rwil...@cisco.com> wrote:
> > > On 13/04/2017 17:08, Andy Bierman wrote: > > > > On Thu, Apr 13, 2017 at 5:45 AM, Ladislav Lhotka <lho...@nic.cz> wrote: > >> >> > On 13 Apr 2017, at 13:34, t.petch <ie...@btconnect.com> wrote: >> > >> > >> > ----- Original Message ----- >> > From: "Andy Bierman" <a...@yumaworks.com> >> > Sent: Wednesday, April 12, 2017 5:44 PM >> > >> >> On Wed, Apr 12, 2017 at 6:02 AM, Juergen Schoenwaelder < >> >> j.schoenwael...@jacobs-university.de> 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
_______________________________________________ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod