Re: [Tools-discuss] [rfc-i] Recommendation 9 from Results and analysis of the survey of I-D authors on formats and tools

[Carsten Bormann <[e-mail]>]

On 4. Feb 2021, at 22:02, Leonard Rosenthol <lrosenth=[e-mail]> wrote:
> 
> Supporting Markdown as an input option is a good idea - but why would you support a non-standard version of it?   CommonMark (https://commonmark.org/ <https://commonmark.org/>) is the relevant "specification" for markdown.  Kramdown, on the other hand, is a specific tool that promotes its own flavor…


Hi Leonard,

the short answer is that in 2010, when kramdown-rfc was created, commonmark wasn’t even on the horizon.

From my point of view, the most important requirement for an authoring language to be used in the IETF is that it remains stable.
Drafts often have a 3-5 year lifetime before they finally get published as an RFC.  People are working on, and text is moving back and forth between, drafts in various of these stages.
So compatibility timelines on the order of a decade or more are required.

Of course, we could decide to “upgrade” to commonmark after kramdown-rfc now has been around for a decade.
With migration aids, this could be palatable (if enough development resources are poured into those; maybe we want to use those for completing the RFXMLv3 migration instead).
But what would be the upside?

Let’s ignore for the moment that commonmark is missing tables, definition lists, anchors, attributes, and a few more things that I forget because one might take them for granted.
A move to commonmark would not be addressing the larger problem with markdown interoperability, which is that RFCXML needs more from an authoring language than markdown provides.
Few of the various features that needed to be invented for kramdown-rfc [1] are provided by commonmark.
One of the most important contributions by kramdown-rfc, painless reference management in the context of IETF documents, is situated to our usage.
I would also chalk up the input of structured data (“metadata”) using YAML as one of the successes.

The underlying kramdown library is run by a developer that shares the goal of compatibility for decades.
Only recently, a mild cleanup was made in the form of kramdown 2.x (adoption of which is still on the to-do list for kramdown-rfc because kramdown recently dropped PI support).
This of course meant that the author couldn’t wholesale adopt the changes made to markdown’s core by commonmark.
But, in reality, kramdown syntax is rather close to commonmark, outside of pathological cases (and the cases where commonmark is just missing needed functionality).

One of the less obvious sources of strength of kramdown-rfc is that it is implemented in less than 1800 lines of code.
This was possible because the kramdown library (an about an order of magnitude larger effort) is doing the heavy lifting.
(The first version of kramdown-rfc was done in less than a day.)
This means kramdown-rfc can be a community project, without the need for support staff.
This is something we might want to change at some point, but not without a really good reason.

Grüße, Carsten

[1]: https://github.com/cabo/kramdown-rfc2629/wiki/Syntax