> On 12 Apr 2017, at 18:44, Andy Bierman <[email protected]> wrote: > > > > 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.
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. 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. Lada > > > /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 -- Ladislav Lhotka, CZ.NIC Labs PGP Key ID: 0xB8F92B08A9F76C67 _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
