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

From: Kent Watsen <[email-masked]>
Date: Fri, 7 Apr 2017 23:24:23 +0000

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

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 10 Apr 2017 13:45:53 +0200

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-masked]> writes:

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

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

---

From: William Lupton <[email-masked]>
Date: Mon, 10 Apr 2017 12:49:31 +0100

yes/support

my https://www.ietf.org/mail-archive/web/netmod/current/msg17899.html comments still apply; in summary:
* support use of markdown, with the principle that descriptions (etc) remain readable as plain text
* support defining conventions for formally referencing enums, bits, nodes etc (allows validation and rendering as links)

william

> On 8 Apr 2017, at 00:24, Kent Watsen <[email-masked]> wrote:
> 
> All,
>

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 10 Apr 2017 13:59:41 +0200

> On 10 Apr 2017, at 13:49, William Lupton <[email-masked]> wrote:
> 
> yes/support
> 

I think a proper approach to this would be to define such markup conventions as a markdown variant (in a separate document).

Lada

---

From: Robert Wilton <[email-masked]>
Date: Mon, 10 Apr 2017 14:29:59 +0100

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.

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.

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

Thanks,
Rob

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 12 Apr 2017 14:53:08 +0200

> that it would be better to use an existing markdown language, but 

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.

> hence generic tools would not be able to reliably render the markup for 

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.

> 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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 12 Apr 2017 15:02:07 +0200

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.

/js

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

---

From: Andy Bierman <[email-masked]>
Date: Wed, 12 Apr 2017 09:44:28 -0700

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

> /js
Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 12 Apr 2017 19:39:11 +0200

> On 12 Apr 2017, at 18:44, Andy Bierman <[email-masked]> wrote:
> 
> 
> 
> On Wed, Apr 12, 2017 at 6:02 AM, Juergen Schoenwaelder <[email-masked]> wrote:

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

---

From: Andy Bierman <[email-masked]>
Date: Wed, 12 Apr 2017 10:59:46 -0700

On Wed, Apr 12, 2017 at 10:39 AM, Ladislav Lhotka <[email-masked]> wrote:

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

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

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 13 Apr 2017 08:13:50 +0200

> On 12 Apr 2017, at 19:59, Andy Bierman <[email-masked]> wrote:
> 
> 
> 
> Tool-makers are the lowest priority.  Too bad if things are not optimized for them.
>  

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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 13 Apr 2017 08:22:30 +0200

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

As a human, I can't ignore markup thrown at my eyes.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 13 Apr 2017 08:28:08 +0200

> On 13 Apr 2017, at 08:22, Juergen Schoenwaelder <[email-masked]> wrote:
> 

We are talking past each other. Are you willing to admit that my draft has nothing to do with the *presence* of markup in a description text, as long as it remains a valid YANG string?

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 13 Apr 2017 09:14:22 +0200

> We are talking past each other. Are you willing to admit that my draft has nothing to do with the *presence* of markup in a description text, as long as it remains a valid YANG string?

I think you do not understand what I am saying. The main purpose of
description statements etc. is that they are easily to read by humans.

7.21.3.  The "description" Statement

   The "description" statement takes as an argument a string that
   contains a human-readable textual description of this definition.

I disagree with your claim that human-readable text is markup. The
whole RFC series is formatted human-readable text, not markup. I
believe this work is heading in the wrong direction, it will lead to
endless discussions of many different flavors of markup used in
description clauses, and it will harm interoperability at the human
eye level.

I believe there are way more important problems to work on. I am out
of this thread (since there is more important work to do).

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 13 Apr 2017 09:21:27 +0200

> On 13 Apr 2017, at 09:14, Juergen Schoenwaelder <[email-masked]> wrote:
> 

I believe your discussion habits are sometimes aggressive and unacceptable.

Lada

---

From: t.petch <[email-masked]>
Date: Thu, 13 Apr 2017 12:34:31 +0100

----- Original Message -----
From: "Andy Bierman" <[email-masked]>
Sent: Wednesday, April 12, 2017 5:44 PM

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

Tom Petch

> > > > suggesting that the draft should define a new markdown language,
I
> > think

------------------------------------------------------------------------
--------

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 13 Apr 2017 14:45:05 +0200

> On 13 Apr 2017, at 13:34, t.petch <[email-masked]> wrote:
> 
> 

OK, so if somebody writes

leaf foo {
    description "This is my *favourite* leaf.";
    type string;
}

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.

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

---

From: Andy Bierman <[email-masked]>
Date: Thu, 13 Apr 2017 09:08:52 -0700

>     description "This is my *favourite* leaf.";
Your premise is that the description-stmt is for the
benefit of the model writer, not the model reader.
Since YANG explicitly states this statement contains a human-readable
string, it seems clear the benefit to the readers is more important.

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.

> 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

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 13 Apr 2017 20:41:55 +0200

> On 13 Apr 2017, at 18:08, Andy Bierman <[email-masked]> wrote:
> 
> 
> 

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.

And I explicitly want to avoid standardizing a particular markup format, at this stage at least.

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

> 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

---

From: Andy Bierman <[email-masked]>
Date: Thu, 13 Apr 2017 16:42:27 -0700

On Thu, Apr 13, 2017 at 11:41 AM, Ladislav Lhotka <[email-masked]> wrote:

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

Andy

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

---

From: heasley <[email-masked]>
Date: Fri, 14 Apr 2017 00:34:26 +0000

> I believe your discussion habits are sometimes aggressive and unacceptable.

I think that Juergen is to the point - and along with Andy is quite correct
that this seems like a distraction and unnecessary.

---

From: Phil Shafer <[email-masked]>
Date: Thu, 13 Apr 2017 23:59:42 -0400

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

1) I think there's a difference between people using our ancient
ascii-based conventions that help the reader grok the author's
meaning, and supporting markdown (plus other syntaxes) that allow
ascii documents to produce HTML.

2) It's not something where one can say "don't use it if you don't
like it", because we will have to read these description statements
for review, etc.

3) Markdown is a class of tools, not a common tool.  CommonMark
works to standardize this, but I've no clue how "common" it is.

4) Consider that github supports >9 formats.  Are we expecting
readers/reviewers to become knowledgable about each of these?

Thanks,
 Phil

---

From: Robert Wilton <[email-masked]>
Date: Tue, 18 Apr 2017 10:32:03 +0100

On 13/04/2017 17:08, Andy Bierman wrote:
>
>
> On Thu, Apr 13, 2017 at 5:45 AM, Ladislav Lhotka <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>
>     > On 13 Apr 2017, at 13:34, t.petch <[email-masked]
>     <mailto:[email-masked]>> wrote:
>     >
>     >
>     > From: "Andy Bierman" <[email-masked]
>     <mailto:[email-masked]>>
>     >> [email-masked]
>     <mailto:[email-masked]>> wrote:
>     >>
>     >> on the specific markup supported. A YANG module should be
>     readable by
>     > humans

I see that the benefit of allowing markdown really is for the model 
reader.  Longer term, I assume that operators using YANG models probably 
won't interact so much with the raw YANG models themselves, but will be 
much more likely to interact with the constructed tree structure through 
a web browser, or generated APIs.

Allowing markup, e.g. so a paragraph of text can re-flow to fill a box 
seems useful to me, as does some sort of emphasis and lists.

I also note that quite a lot (most?) language API documentation tools 
generally take some form of structured text, rather than relying on 
text/plain.

But I do agree to the point that this work seems less urgent than some 
of other items that are being worked on in NETMOD.

Rob

---

From: Andy Bierman <[email-masked]>
Date: Tue, 18 Apr 2017 09:31:51 -0700

On Tue, Apr 18, 2017 at 2:32 AM, Robert Wilton <[email-masked]> wrote:

> much more likely to interact with the constructed tree structure through a
> web browser, or generated APIs.
>
>
IMO it is more robust not to assume people never see the real YANG
statements.
What if these tools have bugs?  How would we ever know?

> seems useful to me, as does some sort of emphasis and lists.

This part confuses me.  I've written YANG to HTML tools (e.g.,
netconfcentral.org).
The tool has to render the entire module, not individual description-stmts.
Emphasis is usually formula-driven (like the keywords). The tool has to
know about the entire YANG module, not
just the descriptions.

> generally take some form of structured text, rather than relying on

This makes sense if
  (1) the entire document is subject to markup, not little pieces
  (2) the only tool that needs to use the raw markup is a browser
  (3) the actual markup allowed is strictly controlled and standardized

> But I do agree to the point that this work seems less urgent than some of
> other items that are being worked on in NETMOD.
>

Good -- work such as the OpenConfig module catalog will have a much bigger
impact
demystifying YANG than bold text or an IMG bullet points instead of *.

Andy

---

From: Robert Wilton <[email-masked]>
Date: Tue, 18 Apr 2017 18:08:32 +0100

On 18/04/2017 17:31, Andy Bierman wrote:
>
>
> On Tue, Apr 18, 2017 at 2:32 AM, Robert Wilton <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>
>
>>         >>> of descriptions etc. would be a big failure and things
>>         are even
>>         > worse
>>         >>> 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
>     I see that the benefit of allowing markdown really is for the
>     model reader.  Longer term, I assume that operators using YANG
>     models probably won't interact so much with the raw YANG models
>     themselves, but will be much more likely to interact with the
>     constructed tree structure through a web browser, or generated APIs.
>
>
I don't want the real YANG statements to become unreadable or even less 
readable.  But I think that description formatted as markdown is quite 
readable anyway (which is why people choose to use it).

>     Allowing markup, e.g. so a paragraph of text can re-flow to fill a
>     box seems useful to me, as does some sort of emphasis and lists.
>
>
>
> netconfcentral.org <http://netconfcentral.org>).
> Emphasis is usually formula-driven (like the keywords). The tool has 
> to know about the entire YANG module, not
> just the descriptions.
You render the module exactly as you do today, but allows the 
description statements to be formatted cleanly.

E.g. looking at your tool, the formatting of the description text looks 
a bit clunky in places.  In some places, you have a wide box, but the 
description is rendered in a monospace format, with lines artificially 
wrapping half way across the box.  It seems that the description isn't 
being treated as a string so much as a manual space character formatted 
block of text.

In other places, you have allowed the description statement to re-flow 
to fit the box, but this will be messy/wrong if the author has used 
whitespace to format the description.

Using markup would allow both cases to rendered correctly.

>
>
>     I also note that quite a lot (most?) language API documentation
>     tools generally take some form of structured text, rather than
>     relying on text/plain.
>
>
> This makes sense if
The rest of YANG is already structured, no markup is required.

>   (2) the only tool that needs to use the raw markup is a browser
It doesn't have to just be a browser, it can be rendered for anything.  
Browser, print, mobile, whatever.

>   (3) the actual markup allowed is strictly controlled and standardized
This I agree with, hence why I proposed that only a small common subset 
of markdown be specified.

>
>
>     But I do agree to the point that this work seems less urgent than
>     some of other items that are being worked on in NETMOD.
>
>
> Good -- work such as the OpenConfig module catalog will have a much 
> bigger impact
Rob

---

From: Phil Shafer <[email-masked]>
Date: Tue, 18 Apr 2017 13:20:11 -0400

>IMO it is more robust not to assume people never see the real YANG

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.

Thanks,
 Phil

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 19 Apr 2017 10:30:28 +0200

> You mean there are YANG RFCs that contain markup in

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

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

> 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

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 19 Apr 2017 10:50:10 +0200

> that this seems like a distraction and unnecessary.

Neither I nor the draft propose anything that would be difficult to read
in an unprocessed form. The draft says it quite clearly:

   It is RECOMMENDED to use only media types representing "lightweight"
   markup that is easy to read even in the unprocessed source form, such
   as "text/markdown".

I don't mind adding another recommendation that even lightweight markup
be used sparingly but, on the other hand, I don't see any reason to ban
it. Those who think it is uinmportant or unnecessary can simply avoid it
in their YANG modules and ignore this document and the extension defined
therein.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 19 Apr 2017 11:09:09 +0200

> seems useful to me, as does some sort of emphasis and lists.

Absolutely. People are converting YANG modules to UML and other formats.

> of other items that are being worked on in NETMOD.

Of course, I am far from claiming that this is urgent or terribly
important, I just realized in my recent work that lightweight markup can
make life of tool makers easier without significantly complicating the
reading of module source text.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 19 Apr 2017 11:35:09 +0200

> 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

---

From: Kent Watsen <[email-masked]>
Date: Wed, 19 Apr 2017 21:05:36 +0000

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

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 20 Apr 2017 14:28:05 +0200

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

> latter case, we may want to keep this draft cooking in the 

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.

Lada

---

From: Jonathan Hansford <[email-masked]>
Date: Fri, 21 Apr 2017 12:14:33 +0100

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.

I agree that some examples may better sell the idea.

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.

Jonathan

=O)

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 21 Apr 2017 14:53:41 +0200

> On 21 Apr 2017, at 13:14, Jonathan Hansford <[email-masked]> wrote:
> 

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

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

---

From: Robert Wilton <[email-masked]>
Date: Fri, 21 Apr 2017 14:03:49 +0100

Hi Lada,

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

> 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

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 21 Apr 2017 15:19:50 +0200

> On 21 Apr 2017, at 15:03, Robert Wilton <[email-masked]> wrote:
> 
> Hi Lada,
> 
> 
> 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.

Yes, this is the essential minimum that would immediately help implementors of some tools and that also means no extra burden to module authors and readers.

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

OK, I will do that.

Thanks, Lada

---

From: Andy Bierman <[email-masked]>
Date: Fri, 21 Apr 2017 10:17:26 -0700

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

Tools that expect the description-stmt to be plain text may break if
markdown is added.
The ability to translate the description to other languages is lost (for
example).

Andy

On Fri, Apr 21, 2017 at 6:03 AM, Robert Wilton <[email-masked]> wrote:

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

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 22 Apr 2017 08:55:28 +0200

> On 21 Apr 2017, at 19:17, Andy Bierman <[email-masked]> wrote:
> 
> Hi,
> 
> 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

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