Subject: notes.ietf.org markdown rendering inconsistencies?

From: Jeffrey Haas <[email-masked]>
Date: Mon, 14 Feb 2022 16:21:21 -0500

Since this might be a known issue, I figured I'd start here:

https://datatracker.ietf.org/meeting/interim-2022-idr-02/session/idr

The minutes were done in the notes site.  They display nicely there.  (See
link via tiny icon at top of meeting.)

The minutes generated from the notes site render improperly for some of the
lists.  This results in difficult to read minutes.  In particular, bullet
lists after a statement with a colon.

Any suggestions on best way to generally address this?

And should the bug for this go to tools-discuss or a different alias?

-- Jeff

---

From: Robert Sparks <[email-masked]>
Date: Mon, 14 Feb 2022 15:54:02 -0600

> And should the bug for this go to tools-discuss or a different alias?

Yes - tools discuss.

(preview of the conversation that will ensue: the markdown renderers are 
necessarily different, and some adjustment as things are imported will 
be required. The best thing to do is to keep your markdown simple to 
keep it portable.)

---

From: Jeffrey Haas <[email-masked]>
Date: Mon, 14 Feb 2022 17:03:54 -0500

> >And should the bug for this go to tools-discuss or a different alias?

Thanks.  I'll generate the mail soon.

> (preview of the conversation that will ensue: the markdown renderers
> are necessarily different, and some adjustment as things are
> imported will be required. The best thing to do is to keep your
> markdown simple to keep it portable.)

With some snark:
If plain bullet lists are too complicated for .md to handle in a graceful
fashion, we're using the wrong tool.

But I'm sure we'll figure out what's going on and move on from there.

-- Jeff

---

From: Robert Sparks <[email-masked]>
Date: Mon, 14 Feb 2022 16:08:12 -0600

> But I'm sure we'll figure out what's going on and move on from there.
If you're not yet familiar with the "what do you mean by markdown wars", 
you're in for a `treat`.

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 15 Feb 2022 09:13:23 +1100

> you're in for a `treat`.

Don't you mean **treat**, or was that *treat* or _treat_ ?

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 15 Feb 2022 00:11:22 +0100

Hi Jeffrey,

welcome to the wonderful world of humane markup.

> On 14. Feb 2022, at 22:21, Jeffrey Haas <[email-masked]> wrote:
> 

The notes site uses the tool hedgedoc, which defaults to a variant of markdown that uses hard newlines.

This variant used to be called “GitHub-flavored markdown” (GFM), until GitHub decided it really wanted to get with the program and switched to the more common soft-newline markdown.

For a note-taking tool, I can understand why hedgedoc went for hard newlines:  It is just more natural to take notes that way.

> lists after a statement with a colon.

In markdown, you need to start a new “paragraph” at the end of the paragraph that precedes a list.
In the more common soft-newline markdown, you have an empty line between them.
In hard-newline markdown, a single line break does this.
So what looked like a paragraph followed by a list in hedgedoc (notes.ietf.org), looks like a single paragraph in more common markdown.

> Any suggestions on best way to generally address this?

Yes.  
I wrote a tool called “de-gfm” (= take the GitHub flavor out).
That should really be a part of the upload interface for markdown (well, it *really* should be part of the download interface for hedgedoc).
The minutes upload should ask whether the uploaded markdown was generated by hedgedoc (notes.ietf.org) or from a more common markdown tool.
But you can run de-gfm locally as well (*).

> And should the bug for this go to tools-discuss or a different alias?

It should go to John Gruber, who invented markdown with Aaron Swartz and then completely abandoned the project, causing a proliferation of markdown variants.

(Markdown is not my personal favorite of the humane markup systems; it is just the one that everybody speaks, like the Python of programming languages, so it’s still best for collaborating in.)

Grüße, Carsten

(*) de-gfm is part of kramdown-rfc, see https://rfc.space for the line to install it.

---

From: Jeffrey Haas <[email-masked]>
Date: Mon, 14 Feb 2022 20:31:40 -0500

> On Feb 14, 2022, at 6:11 PM, Carsten Bormann <[email-masked]> wrote:
> 
> Hi Jeffrey,
> 

It's certainly not my first visit.  I've been through about 20 different flavors of similar "fun" over my career.  I simply hoped that I could stop worrying about this sort of thing.

> For a note-taking tool, I can understand why hedgedoc went for hard newlines:  It is just more natural to take notes that way.

Thanks for the history here.

> So what looked like a paragraph followed by a list in hedgedoc (notes.ietf.org), looks like a single paragraph in more common markdown.

Therefore, the "fix" is to go back to the minutes and force the extra blank space.  Good enough for the current problem.

> It should go to John Gruber, who invented markdown with Aaron Swartz and then completely abandoned the project, causing a proliferation of markdown variants.

No thank you.  Life is too short for me to join another religion.

That said, it's pretty unfortunate that the IETF toolchain runs two not-quite-compatible dialects.  It would be ideal if it's consistent.

That will be the bulk of my note to tools-discuss.

> (Markdown is not my personal favorite of the humane markup systems; it is just the one that everybody speaks, like the Python of programming languages, so it’s still best for collaborating in.)

I try to stick to .rst at work because it mostly behaves well.

But only mostly.

-- Jeff

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 15 Feb 2022 02:53:32 +0100

> That said, it's pretty unfortunate that the IETF toolchain runs two not-quite-compatible dialects.  It would be ideal if it's consistent.

Actually, I don’t agree that the experience of real-time note taking needs to be made worse just to achieve this unneeded consistency.
Two dialects do make sense here.

What is needed is a clean way to transition between the two.
(And it is unfortunate that both are called “markdown” without qualification.)

Grüße, Carsten

---

From: Jeffrey Haas <[email-masked]>
Date: Tue, 15 Feb 2022 07:33:53 -0500

Carsten,

> Two dialects do make sense here.

I think you've filtered this comment through your pain of the different dialects.

What I am requesting is that the GUI tool should function such that IETF
toolchains consistently can produce its output.  Whether this means an
upgrade to the GUI tool to change dialect or the rendered minutes tool isn't
important for me.

> What is needed is a clean way to transition between the two.

This is a reasonable second option.

> (And it is unfortunate that both are called “markdown” without qualification.)

https://xkcd.com/927/

-- Jeff

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 15 Feb 2022 13:45:26 +0100

> I think you've filtered this comment through your pain of the different dialects.

It’s more like:

A: Your bike should have a steering wheel, for consistency with your car.
B: I don’t think that consistency is needed, or even useful.

But yes, I agree that something needs to be done with the tools we are using to make this situation more seamless.  Asking the user to run a command line tool to translate between dialects is not it.

Grüße, Carsten

---

From: Robert Sparks <[email-masked]>
Date: Tue, 15 Feb 2022 08:55:37 -0600

> The minutes upload should ask whether the uploaded markdown was generated by hedgedoc (notes.ietf.org) or from a more common markdown tool.
If you use the relatively new feature in the datatracker that lets you 
pull minutes directly from the notes linked tot he session, de-gfm is 
run on it automatically.