> On 21 Apr 2017, at 19:17, Andy Bierman <[email protected]> wrote: > > Hi, > > You can put whatever text you want in a draft, and see it gets approved > for the RFC version. You can put whatever text you want in non-IETF modules. > But consider the impact carefully of turning a plain text string into source > code. > > There is no agreement on the markdown that is "lightweight" and needs to be > supported.
By the same token, there is no agreement on what plain text is. Moreover, descriptions in the existing modules do use some unwritten formatting conventions and elementary markup (e.g. enclosing YANG names in quotes or email addresses in chevrons). The main purpose of my I-D is to help module authors adhere to certain *written* rules. > This seems like a significant amount of work to resolve. The NETMOD WG > already has a full plate > of high-priority work. We should not slow that work down for anything. I've heard similar dismissive statements in the past against some of my previous work, such as the JSON encoding. Fortunately, this is voluntary work and I am just scratching my own itches. Ultimately, it is running code that counts. > > Tools that expect the description-stmt to be plain text may break if markdown > is added. How this could be if the strings follow YANG rules? My only explaination is that such tools already rely on those unwritten rules. As Rob pointed out, your tools also sometimes produce suboptimal results on descriptions in existing YANG modules. > The ability to translate the description to other languages is lost (for > example). > Why? Wikipedia articles use lightweight markup and they are being routinely translated to many languages. With a decent markup, the translation can actualy be easier and more robust: for example, the translator can recognize YANG identifiers in the text and avoid translating them. Lada > > Andy > > > On Fri, Apr 21, 2017 at 6:03 AM, Robert Wilton <[email protected]> wrote: > Hi Lada, > > > On 20/04/2017 13:28, Ladislav Lhotka wrote: > Kent Watsen <[email protected]> writes: > > 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 > A typical lightweight markup language is markdown, and I believe most > people are familiar with it - if not, examples are easy to find. > > The bare minimum of markdown features from which even existing modules > could benefit may be this: > > - multiple paragraphs (separated by one or more blank lines) that can be > re-flowed > > - bulleted and numbered lists, possibly with multiple levels and > multiple paragraphs per list item > > - hyperlinks, such as [RFC 7950](https://tools.ietf.org/html/rfc7950) > > and perhaps also > > - *emphasis* and **strong emphasis** > > - code blocks for showing example snippets where line breaks need to be > retained. > For what it is worth, this is effective what I was recommending goes in the > draft. > > I.e. you say that default markdown language is markdown, but implementations > are expected to at least support xxx, where xxx is something like that list > above. > > That way at least implementors can know what they need to support, and > authors can know what markdown they can reasonably expect to use. > > > latter case, we may want to keep this draft cooking in the > background. > I am going to use the above conventions in my modules, and support them > in my tools. That's basically all what I need for the time being. > If you have the spare time, perhaps it is worth updating the ID with that > list above, at least as a record in case this gets picked up again in future. > > Thanks, > Rob > > > Lada > > > 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 > > > > -- Ladislav Lhotka, CZ.NIC Labs PGP Key ID: 0xB8F92B08A9F76C67 _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
