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

On Thu, Apr 13, 2017 at 5:45 AM, Ladislav Lhotka <lhotka@nic.cz> wrote:

>
> > On 13 Apr 2017, at 13:34, t.petch <ietfc@btconnect.com> wrote:
> >
> >
> > ----- Original Message -----
> > From: "Andy Bierman" <andy@yumaworks.com>
> > Sent: Wednesday, April 12, 2017 5:44 PM
> >
> >> On Wed, Apr 12, 2017 at 6:02 AM, Juergen Schoenwaelder <
> >> j.schoenwaelder@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.

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 <rwilton@cisco.com> 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 <kwatsen@juniper.net> 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
> >>>>>>> netmod@ietf.org
> >>>>>>> https://www.ietf.org/mailman/listinfo/netmod
> >>>>>
> >>>>
> >>>> --
> >>>> Ladislav Lhotka, CZ.NIC Labs
> >>>> PGP Key ID: 0xB8F92B08A9F76C67
> >>>>
> >>>> _______________________________________________
> >>>> netmod mailing list
> >>>> netmod@ietf.org
> >>>> 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
> >>> netmod@ietf.org
> >>> https://www.ietf.org/mailman/listinfo/netmod
> >>>
> >>
> >
> >
> > ------------------------------------------------------------------------
> > --------
> >
> >
> >> _______________________________________________
> >> netmod mailing list
> >> netmod@ietf.org
> >> https://www.ietf.org/mailman/listinfo/netmod
>
> --
> Ladislav Lhotka, CZ.NIC Labs
> PGP Key ID: 0xB8F92B08A9F76C67
>
>
>
>
>
>