> On 21 Apr 2017, at 13:14, Jonathan Hansford <[email protected]> wrote: > > I understand the primary need is to make the YANG modules accessible to > readers, but some simple markup is identical to how text might be formatted > when only raw ASCII is available (e.g. when using a simple email client) yet, > when rendered as markup, the resulting text is easier on the eyes of the > reader.
Right, the key term really is "lightweight markup" [1]: "A lightweight markup language (LML), also termed a simple or humane markup language, is a markup language with simple, unobtrusive syntax. It is designed to be easy to create using any generic text editor, as well as easy to read in its raw form. Lightweight markup languages are used in applications where it may be necessary to read the raw document as well as the final rendered output." Many tools might at least want to be able to reliably re-flow paragraphs and lists to fit a desired text width, or render some constructs as HTML. > > I agree that some examples may better sell the idea. Some examples are in the "ietf-yang-text-media-type" module: https://tools.ietf.org/html/draft-lhotka-netmod-yang-markup-00#section-4 > > Also, if some YANG authors are already including markup, wouldn't it be > better to standardise rather than allow for a free-for-all resulting in > multiple styles that would impose a significant burden on any tool trying to > render the text. My idea has been that 6087bis could recommend to use a (subset of) specific LML, e.g. markdown or its variant, in IETF modules and indicate it in them with the "text-media-type" extension. The advantage of doing so is that it will be easier to use something else later and/or combine IETF modules with others that may use something else. For instance, if somebody wanted YANG-specific markup (similar to what is used in TR-069 schemas, e.g. [2]), reStructuredText might be a better choice than markdown. Lada [1] https://en.wikipedia.org/wiki/Lightweight_markup_language [2] https://www.broadband-forum.org/cwmp/tr-181-2-11-0.xml > > Jonathan > > =O) > > > On 19 Apr 2017, 22:05 +0100, Kent Watsen <[email protected]>, wrote: >> >> All, >> >> We're a couple days away from the 2-week window. As of now, the >> majority does not support adopting this draft. Any remaining >> opinions? >> >> >> Lada, >> >> The objections seem to be concern for net readability, and for the >> importance of the problem relative to other activities. For the >> former case, it may help if you posted some examples. For the >> latter case, we may want to keep this draft cooking in the >> background. >> >> >> Kent // as co-chair and potential shepherd >> >> >> >> Phil Shafer <[email protected]> writes: >> >>> Andy Bierman writes: >>>> IMO it is more robust not to assume people never see the real YANG >>>> statements. >>> >>> Exactly. We made YANG readable so that we wouldn't _need_ to view >>> it using tools. This was one of the "insta-death" factors for UML. >> >> I have to reiterate that the idea is to continue to be able to view YANG >> modules *without* using tools, but provide some aid to tools that can make >> use of certain well-defined lightweight markup conventions. >> >> Everybody with a practical experience of converting YANG automatically >> to something else (not only to HTML, it starts already with YIN) knows >> that transferring descriptions and other similar texts is tricky. >> >> Lada >> >>> >>> Thanks, >>> Phil >>> >>> _______________________________________________ >>> 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 >> >> >> _______________________________________________ >> 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
