On Thu, Apr 13, 2017 at 5:45 AM, Ladislav Lhotka <[email protected]> wrote:
> > > On 13 Apr 2017, at 13:34, t.petch <[email protected]> wrote: > > > > > > ----- Original Message ----- > > From: "Andy Bierman" <[email protected]> > > Sent: Wednesday, April 12, 2017 5:44 PM > > > >> On Wed, Apr 12, 2017 at 6:02 AM, Juergen Schoenwaelder < > >> [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. you may not like it, but it is absolutely legal and IMO also readable by > humans. As William previously mentioned, some communities are already doing > similar things. The principal aim of my I-D is to allow module authors to > explicitly state that they adhere to some rules, which helps authors of > tools reduce guesswork. > > You may decide to ignore the intent of the description-stmt. That doesn't mean we should change the definition in the standard. IMO plain text is human-readable. Anything that requires parsing, reinterpreting and re-rendering is not human friendly. > The example with email is actually very relevant. I would also love if > people and MUAs only used plain text but, as you say, this is not going to > happen. If we accept this as a fact, is it better or worse for > interoperability that MUAs provide media type in mail headers? > > Lada > Andy > > > > > Tom Petch > > > >>> /js > >>> > >>> > >> Andy > >> > >> > >>> On Wed, Apr 12, 2017 at 02:53:08PM +0200, Ladislav Lhotka wrote: > >>>> Robert Wilton <[email protected]> writes: > >>>> > >>>>> Yes/support. But with the condition that I would still like the > > draft > >>>>> to define a basic common subset of markdown fields/annotations > > that > >>>>> implementations would be expected to support. For clarity, I'm > > not > >>>>> suggesting that the draft should define a new markdown language, > > I > >>> think > >>>>> that it would be better to use an existing markdown language, > > but > >>>>> perhaps simplified. > >>>> > >>>> In my view, this needs to remain purely optional, so > > implementations > >>>> won't be expected to support anything. It should be perfectly fine > > to > >>>> leave description texts unprocessed, or process only selected > >>>> constructs. > >>>> > >>>>> > >>>>> I want to avoid the scenario where each group of YANG modelers > > could > >>>>> decide to use a different incompatible variant of text/markdown, > > and > >>>>> hence generic tools would not be able to reliably render the > > markup for > >>>>> a generic YANG module. > >>>> > >>>> On the other hand, particular markup conventions might be dictated > > by > >>>> external circumstances. For example, for modules hosted at GitHub, > > the > >>>> GFM variant of text/markdown looks like a natural choice but > > elsewhere > >>>> it can be something different. William also suggested that certain > >>>> YANG-specific constructs may also be introduced. > >>>> > >>>>> > >>>>> Care would need to be taken with which variant of the Markdown > > language > >>>>> is chosen as a base (RFC 7764 may be of use) . E.g. the github > > markup > >>>>> language has been previously suggested, but the specification > > document > >>>>> for that variant is long (approx 120 pages). > >>>> > >>>> RFC 7763 also notes that markdown itself by design has no concept > > of > >>>> validity, so I think it is appropriate to take it easy and avoid > >>>> overspecifying things. > >>>> > >>>> I guess the key point here is "lighweight markup": if and > > implementation > >>>> can make use of it, then fine, but module readers should have > > little > >>>> difficulty if not. > >>>> > >>>> Thanks, Lada > >>>> > >>>>> > >>>>> Thanks, > >>>>> Rob > >>>>> > >>>>> > >>>>> On 10/04/2017 12:45, Ladislav Lhotka wrote: > >>>>>> As the author: yes/support. > >>>>>> > >>>>>> Two changes seemed to have support in IETF 98 audience: > >>>>>> > >>>>>> 1. Apart from text/plain, the media type SHOULD be > > text/markdown > >>>>>> (variants permitted). > >>>>>> > >>>>>> 2. The "text-media-type" extension can appear anywhere in a > >>> (sub)module, > >>>>>> and will be scoped to the parent statement and its substaments > > (unless > >>>>>> overriden). > >>>>>> > >>>>>> Lada > >>>>>> > >>>>>> Kent Watsen <[email protected]> writes: > >>>>>> > >>>>>>> All, > >>>>>>> > >>>>>>> This is start of a two-week poll on making the following draft > > a > >>>>>>> NETMOD working group document: > >>>>>>> > >>>>>>> draft-lhotka-netmod-yang-markup-00 > >>>>>>> > >>>>>>> Please send email to the list indicating "yes/support" or > > "no/do not > >>>>>>> support". If indicating no, please state your reservations > > with the > >>>>>>> document. If yes, please also feel free to provide comments > > you'd > >>>>>>> like to see addressed once the document is a WG document. > >>>>>>> > >>>>>>> Thank you, > >>>>>>> NETMOD WG Chairs > >>>>>>> > >>>>>>> > >>>>>>> _______________________________________________ > >>>>>>> netmod mailing list > >>>>>>> [email protected] > >>>>>>> https://www.ietf.org/mailman/listinfo/netmod > >>>>> > >>>> > >>>> -- > >>>> Ladislav Lhotka, CZ.NIC Labs > >>>> PGP Key ID: 0xB8F92B08A9F76C67 > >>>> > >>>> _______________________________________________ > >>>> netmod mailing list > >>>> [email protected] > >>>> https://www.ietf.org/mailman/listinfo/netmod > >>> > >>> -- > >>> Juergen Schoenwaelder Jacobs University Bremen gGmbH > >>> Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | > > Germany > >>> Fax: +49 421 200 3103 <http://www.jacobs-university.de/> > >>> > >>> _______________________________________________ > >>> netmod mailing list > >>> [email protected] > >>> https://www.ietf.org/mailman/listinfo/netmod > >>> > >> > > > > > > ------------------------------------------------------------------------ > > -------- > > > > > >> _______________________________________________ > >> netmod mailing list > >> [email protected] > >> https://www.ietf.org/mailman/listinfo/netmod > > -- > Ladislav Lhotka, CZ.NIC Labs > PGP Key ID: 0xB8F92B08A9F76C67 > > > > > >
_______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
