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

[Ladislav Lhotka <[e-mail]>]

> On 12 Apr 2017, at 19:59, Andy Bierman <[e-mail]> wrote:
> 
> 
> 
> On Wed, Apr 12, 2017 at 10:39 AM, Ladislav Lhotka <[e-mail]> wrote:
> 
> > On 12 Apr 2017, at 18:44, Andy Bierman <[e-mail]> wrote:
> >
> >
> >
> > 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.
> 
> Why do you think that unprocessed *lightweight* markup such as markdown is not readable by humans? Note that everybody can use it even now without further ado, so this document only allows module authors who want to do so to provide explicit info about the format.
> 
> 
> I think YANG should not place any additional burden on readers.
> Tool-makers are the lowest priority.  Too bad if things are not optimized for them.
>  
> As the draft also tries to explain, some trivial markup is already commonly used in IETF modules (for example, bulleted lists) and inconsistent indentation rules make it difficult for applications to properly format such texts.
> 
> 
> A bullet list is human-readable without any need to reformat and re-render.
> A reader can correctly interpret a bullet list without knowing any markup.
> Tools can figure out what to do on their own.

If you want to ignore the extension proposed by this draft in your tools, you are free to do so. Other people may want to use this extra information.

Lada  

> 
> I do not think this is really needed in YANG.
> If you want to convert YANG to HTML, then just do it.
> We don't need to have a standard for this.
> 
> 
> Lada
> 
> 
> Andy
>  
> >
> >
> > /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
> 
> --
> Ladislav Lhotka, CZ.NIC Labs
> PGP Key ID: 0xB8F92B08A9F76C67

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