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

[Ladislav Lhotka <[e-mail]>]

Andy Bierman <[e-mail]> writes:

> 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?

A trivial one is, for example, bulleted lists are quite common. So
it would be helpful to add

ymt:text-media-type "text/markdown; charset=UTF-8";

even to these RFCs because then processing tools can expect bulleted
lists to be formatted according to markdown rules, e.g. [1]

    List items may consist of multiple paragraphs. Each subsequent
    paragraph in a list item must be indented by either 4 spaces or one
    tab.

Another example are hyperlinks that sometimes occur, e.g., in
"reference" statements. They are formatted in various different ways,
and there is IMO nothing wrong (or unreadable) on using markdown
conventions, for example

[ISO9834-1](https://www.iso.org/standard/58055.html "Information
technology -- Open Systems Interconnection -- Procedures for the
operation of OSI Registration Authorities: General procedures and top
arcs of the ASN.1 Object Identifier tree")

Moreover, not all YANG modules are being produced in the IETF. William
Lupton noted proviously that mediawiki-like markup is supported in
TR-069 data model description strings.

And finally, I do believe (as William also suggested) that YANG could
benefit from YANG-specific markup constructs, especially in error
messages. For example, it might be useful to be able to include
incorrect values taken from actual instance data. This is not a topic of
this draft but it provides a straightforward way to realize this extension. 

[1] https://daringfireball.net/projects/markdown/syntax#list

> 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

The basic assumption is that the text can be left unprocessed without
being difficult to read and understand. Lightweight markup syntaxes such
as markdown are unobtrusive by design.

> 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.

The reader can look up the rules if necessary.

I am not against standardizing something but it can be difficult to
agree on a format that works for everybody and is sufficiently
future-proof.

Lada

>
>
> 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
>>
>>
>>
>>
>>
>>

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67