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

[Andy Bierman <[e-mail]>]

On Thu, Apr 13, 2017 at 11:41 AM, Ladislav Lhotka <[e-mail]> wrote:

>
> > On 13 Apr 2017, at 18:08, Andy Bierman <[e-mail]> wrote:
> >
> >
> >
> > On Thu, Apr 13, 2017 at 5:45 AM, Ladislav Lhotka <[e-mail]> wrote:
> >
> > > On 13 Apr 2017, at 13:34, t.petch <[e-mail]> wrote:
> > >
> > >
> > > ----- Original Message -----
> > > From: "Andy Bierman" <[e-mail]>
> > > Sent: Wednesday, April 12, 2017 5:44 PM
> > >
> > >> On Wed, Apr 12, 2017 at 6:02 AM, Juergen Schoenwaelder <
> > >> [e-mail]> 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.
>
> My premise is that such *lightweight* markup is being used and will be
> used. So it is better to be prepared, and accomodate it in an acceptable
> form, rather than fight it.
>


You mean there are YANG RFCs that contain markup in  description-stmts?
Indicating that both the IESG and RFC Editor have approved this practice?
If not, then such markup is not actually being used in published YANG
modules.



> And I explicitly want to avoid standardizing a particular markup format,
> at this stage at least.
>
>
>
That means the burden is on the YANG reader to be aware of every possible
markup variant anybody might want to use.  Of course the user must
understand
the "extra" chars thrown in with the plain English. One cannot assume it
will
be obvious to every reader which chars are extra, especially with no
constraints
at all on the markup syntax and semantics.


Andy




> > Since YANG explicitly states this statement contains a human-readable
> > string, it seems clear the benefit to the readers is more important.
>
> What exactly is non-human-readable in my example?
>
> Moreover, different communities may want to add e.g. metadata in a certain
> formalized format. To some extent, we already do it in the initial
> decription of our modules. IMO there is nothing wrong on specifying the
> format that is being used.
>
> >
> >
> > 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.
>
> My draft doesn't propose anything like this. Lightweight markup such as
> markdown doesn't require parsing, and is as human-readable as anything else.
>
> Lada
>
> >
> >
> > 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 <[e-mail]> 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 <[e-mail]> 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
> > >>>>>>> [e-mail]
> > >>>>>>> https://www.ietf.org/mailman/listinfo/netmod
> > >>>>>
> > >>>>
> > >>>> --
> > >>>> Ladislav Lhotka, CZ.NIC Labs
> > >>>> PGP Key ID: 0xB8F92B08A9F76C67
> > >>>>
> > >>>> _______________________________________________
> > >>>> netmod mailing list
> > >>>> [e-mail]
> > >>>> https://www.ietf.org/mailman/listinfo/netmod
> > >>>
> > >>> --
> > >>> Juergen Schoenwaelder           Jacobs University Bremen gGmbH
> > >>> Phone: [phone]         Campus Ring 1 | 28759 Bremen |
> > > Germany
> > >>> Fax:   [phone]         <http://www.jacobs-university.de/>
> > >>>
> > >>> _______________________________________________
> > >>> netmod mailing list
> > >>> [e-mail]
> > >>> https://www.ietf.org/mailman/listinfo/netmod
> > >>>
> > >>
> > >
> > >
> > > ------------------------------------------------------------
> ------------
> > > --------
> > >
> > >
> > >> _______________________________________________
> > >> netmod mailing list
> > >> [e-mail]
> > >> https://www.ietf.org/mailman/listinfo/netmod
> >
> > --
> > Ladislav Lhotka, CZ.NIC Labs
> > PGP Key ID: 0xB8F92B08A9F76C67
>
> --
> Ladislav Lhotka, CZ.NIC Labs
> PGP Key ID: 0xB8F92B08A9F76C67
>
>
>
>
>
>