Subject: [Tools-discuss] what revision of markdown for IETF?

From: Michael Richardson <[email-masked]>
Date: Tue, 22 Jun 2021 15:00:36 -0400

I know that markdown has many flavours/versions. I have no idea how to name
them.

Comparing:
        https://datatracker.ietf.org/doc/agenda-interim-2021-cellar-06-cellar-01/

and:
        https://codimd.ietf.org/notes-ietf-interim-2021-cellar-06-cellar

you'll see that our nice table is not rendered as such on the DT.

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 22 Jun 2021 21:15:26 +0200

Revision is a word that can be used to describe steps in an orderly, linear editing process.
I don’t know how that word got into the same mail as the word markdown…

Tables weren’t part of the original markdown spec.
This was quickly fixed in the then dominant PHP markdown implementation (the name of which I forget), but other tools have implemented deviant versions of that.
Most notorious is github, which requires all-pipe vertical lines for detection (no plus signs as with everyone else).
John Gruber abandoned markdown, and commonmark came a bit late.
The rest is history.

I don’t think we should try to be the guy that cleans up all the kids’ rooms in the whole neighborhood.

But here the problem is a different one:

> On 2021-06-22, at 21:00, Michael Richardson <[email-masked]> wrote:
> 
> Signed PGP part
> 

Because the thing isn’t rendering markdown at all!

(Oh, and looking at the uploaded media type is a procedure that may seem justifiable from the letter of the standards but given the reality of browser implementations really is just torturing the user base.  In this century, we have file name endings (“extensions”) for that.)

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 22 Jun 2021 21:19:25 +0200

> On 2021-06-22, at 21:15, Carsten Bormann <[email-masked]> wrote:
> 

Oh, you mean

https://datatracker.ietf.org/meeting/interim-2021-cellar-06/materials/agenda-interim-2021-cellar-06-cellar-01-01.md

and not the one that you linked.

Unfortunately, the renderer employed there does not leave a signature, so I don’t know which one was used.

(I simply convert my markdown before uploading, but that is cheating.)

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 22 Jun 2021 21:44:09 +0200

> Unfortunately, the renderer employed there does not leave a signature, so I don’t know which one was used.

If it’s Python markdown (I have had no way to mine the ietfdb source properly since git-svn gave its last gasp on my machine), that considers tables to be an “extension” that needs to be switched on explicitly.

The same seems to be true for Python markdown2, which the silver searcher does find in the belly of the datatracker.

https://github.com/trentm/python-markdown2/wiki/Extras

… would need, say,
tables
fenced-code-blocks
strike
cuddled-lists

strike because of our propensity to change agenda lists at the last moment :-)
cuddled-lists because many of us are lazy.

Grüße, Carsten

---

From: Michael Richardson <[email-masked]>
Date: Tue, 22 Jun 2021 20:41:26 -0400

Carsten Bormann <[email-masked]> wrote:
    > Revision is a word that can be used to describe steps in an orderly,
    > linear editing process.  I don’t know how that word got into the same
    > mail as the word markdown…

Sorry, I should have used the word "version" here.
I wrote the email while charing a meeting.

    > Tables weren’t part of the original markdown spec.  This was quickly
    > fixed in the then dominant PHP markdown implementation (the name of
    > which I forget), but other tools have implemented deviant versions of
    > that.  Most notorious is github, which requires all-pipe vertical lines
    > for detection (no plus signs as with everyone else).  John Gruber
    > abandoned markdown, and commonmark came a bit late.  The rest is
    > history.

    > rooms in the whole neighborhood.

I'm just thinking that codimd.ietf.org and datatracker.ietf.org (and our new
wiki) should use compatible versions, whichever we think is best.

    >> I know that markdown has many flavours/versions. I have no idea how to
    >> name them.
    >>
    >> Comparing:
    >> and: https://codimd.ietf.org/notes-ietf-interim-2021-cellar-06-cellar
    >>

    > Because the thing isn’t rendering markdown at all!

I also clicked on the "markdown" link in the datatracker, btw, and I thought
that it did render it.  I just copied the wrong thing into email:

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 23 Jun 2021 09:18:39 +0200

> wiki) should use compatible versions, whichever we think is best.

While this is fine as an aspirational goal, I don’t think it really can be achieved.
CodiMD (now HedgeDoc) is a significant piece of software that is moving forward quickly, and it is probably too expensive to try to keep up a modified local variant.

We could, however, update the datatracker markdown rendering feature to at least have approximate feature parity with CodiMD, by enabling the “extras” that are in common use today; see my previous message about that.

Grüße, Carsten