Subject: Question about Codimd for w.g. minutes

From: Bob Hinden <[email-masked]>
Date: Thu, 29 Jul 2021 08:47:55 -0700

What’s the best practice to convert and/or publish minutes taken with codimd?   I have managed to so something in past meetings, but usually try a few things.

Is there a best practice?  What do you do?

Bob

---

From: Bernard Aboba <[email-masked]>
Date: Thu, 29 Jul 2021 08:54:06 -0700

I edit for grammar and then copy/paste it to email and post a draft on the
mailing list. Then apply the corrections if any are suggested and upload it
to the materials site.

On Thu, Jul 29, 2021 at 8:48 AM Bob Hinden <[email-masked]> wrote:

> What’s the best practice to convert and/or publish minutes taken with
> codimd?   I have managed to so something in past meetings, but usually try
> a few things.
>

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 29 Jul 2021 18:09:19 +0200

Similar to Bernard.

When datatracker didn’t allow markdown uploads (or made this ridiculously complicated to set up; I don’t remember), I converted the markdown to HTML locally before uploading (using an app called Marked, but there are hundreds of ways to do this; kramdown (without -rfc) is of course one of them).

Grüße, Carsten

> On 2021-07-29, at 17:47, Bob Hinden <[email-masked]> wrote:
>

---

From: "Deen, Glenn (NBCUniversal)" <[email-masked]>
Date: Thu, 29 Jul 2021 16:15:38 +0000

Bob,

I've done a light cleanup - both for English and markdown - and then upload them.   Since I also create the WG agenda as markdown when making it, this goes as the seed for the cotimd notes ahead of the meeting the result is the notes are then all in markdown along with working links etc.   that live in the notes document and work for future readers. 

-glenn

On 7/29/21, 8:48 AM, "WGChairs on behalf of Bob Hinden" <[email-masked] on behalf of [email-masked]> wrote:

    Bob

---

From: Bob Hinden <[email-masked]>
Date: Thu, 29 Jul 2021 09:42:36 -0700

Glenn,

To clarify, so you download Markdown and then upload that to the Datatracker?

Bob

> On Jul 29, 2021, at 9:15 AM, Deen, Glenn (NBCUniversal) <[email-masked]> wrote:
> 
> Bob,
>

---

From: "Deen, Glenn (NBCUniversal)" <[email-masked]>
Date: Thu, 29 Jul 2021 16:58:55 +0000

Hi Bob,

More cut and paste into a new local notes.md file out of the codimd notepad which are marked up with markdown, but yes.   

-glenn

On 7/29/21, 9:42 AM, "Bob Hinden" <[email-masked]> wrote:

    Glenn,

    Bob

---

From: Kyle Rose <[email-masked]>
Date: Thu, 29 Jul 2021 13:09:38 -0400

I download the markdown and then upload it to the data tracker. The 111
MOPS minutes, for instance:

https://datatracker.ietf.org/doc/minutes-111-mops/

It requires your browser/OS to understand and present the markdown mime
type when uploading, which has led to some frustration (and confused
attempts at helping) in the past.

Kyle

On Thu, Jul 29, 2021 at 12:59 PM Deen, Glenn (NBCUniversal) <
[email-masked]> wrote:

> Hi Bob,
>
> More cut and paste into a new local notes.md file out of the codimd
> notepad which are marked up with markdown, but yes.
>
> -glenn
>
>     > I've done a light cleanup - both for English and markdown - and then
> upload them.   Since I also create the WG agenda as markdown when making
> it, this goes as the seed for the cotimd notes ahead of the meeting the
> result is the notes are then all in markdown along with working links etc.
>  that live in the notes document and work for future readers.
>     >
>     >
>     > -glenn
>     >
>     > On 7/29/21, 8:48 AM, "WGChairs on behalf of Bob Hinden" <
> [email-masked] on behalf of [email-masked]> wrote:
>     >
>     >    What’s the best practice to convert and/or publish minutes taken
> with codimd?   I have managed to so something in past meetings, but usually
> try a few things.
>     >

---

From: Dave Thaler <[email-masked]>
Date: Thu, 29 Jul 2021 17:15:34 +0000

Sounds like a tools team functionality request.

Dave

From: WGChairs <[email-masked]> On Behalf Of Kyle Rose
Sent: Thursday, July 29, 2021 10:10 AM
To: Deen, Glenn (NBCUniversal) <[email-masked]>
Cc: Working Group Chairs <[email-masked]>
Subject: Re: [EXTERNAL] Question about Codimd for w.g. minutes

I download the markdown and then upload it to the data tracker. The 111 MOPS minutes, for instance:

https://datatracker.ietf.org/doc/minutes-111-mops/<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdatatracker.ietf.org%2Fdoc%2Fminutes-111-mops%2F&data=04%7C01%7Cdthaler%40microsoft.com%7C88a5b39373f54d6195b508d952b3baa2%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631754166239845%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=plHvYtyqvoUtR8jpUmfkdBt9j6laWcw5NpcPwnOWBFA%3D&reserved=0>

It requires your browser/OS to understand and present the markdown mime type when uploading, which has led to some frustration (and confused attempts at helping) in the past.

Kyle

On Thu, Jul 29, 2021 at 12:59 PM Deen, Glenn (NBCUniversal) <[email-masked]<mailto:[email-masked]>> wrote:
Hi Bob,

-glenn

On 7/29/21, 9:42 AM, "Bob Hinden" <[email-masked]<mailto:[email-masked]>> wrote:

    Glenn,

    Bob

    > On Jul 29, 2021, at 9:15 AM, Deen, Glenn (NBCUniversal) <[email-masked]<mailto:[email-masked]>> wrote:
    >
    > Bob,
    >
    > On 7/29/21, 8:48 AM, "WGChairs on behalf of Bob Hinden" <[email-masked]<mailto:[email-masked]> on behalf of [email-masked]<mailto:[email-masked]>> wrote:
    >

---

From: Bob Hinden <[email-masked]>
Date: Thu, 29 Jul 2021 10:38:11 -0700

Kyle, Glenn,

I gave downloading the markdown and uploading that to the Datatracker.  That works, but the discussion are getting wrapped when I open the link in Safari and Crome.  For example:

Toerless Eckert: Very nice. Any experience from ECN experimental? Gorry Fairhurst: ECN is standards. Second generation of ECN. Unable to help. Gorry Fairhurst: Original is currently proposed standards. Toerless Eckert: I think we could be consistent on that. You made it experimental because you don't want to explore some things? Gorry Fairhurst: Original ecn appears to be more unexperimental. We can do whatever 6man wants us to. Geoff Huston: Not everybody can do it overnight. It effects every router along the path. The real question is that how partial deployment will impact. Bob Hinden: We expect there will be mixed implementations for a while. Gorry do you want to say more? Gorry Fairhurst: Not replace the PMTU discovery. If you have some routers that can discover, then

In Codimd it displays fine with appropriate line breaks.

I have tried several ways to capture the markdown (download, copy and paste), all have the same results.

Suggestions?   I could do an editing pass to fix this, but would prefer to avoid that.

Bob

> On Jul 29, 2021, at 10:09 AM, Kyle Rose <[email-masked]> wrote:
> 
> On Thu, Jul 29, 2021 at 12:59 PM Deen, Glenn (NBCUniversal) <[email-masked]> wrote:
> Hi Bob,
>

---

From: "Deen, Glenn (NBCUniversal)" <[email-masked]>
Date: Thu, 29 Jul 2021 17:46:58 +0000

Bob,

I see the wrapping problem at times as well when reading the minutes from datatracker.

Here'e the raw ADD@110 minutes from CODIMD.  https://codimd.ietf.org/notes-ietf-110-add  which formats fine.

Here's the datatracker version: https://datatracker.ietf.org/meeting/110/materials/minutes-110-add-202103091530-00.md which has wrap problems.

The Datatracker version does preserve markdown coded links correctly, but the text lines are being wrapped together.

Could this be a typing problem coming out of datatracker?     Datatracker does recognize that it's a markdown file as I'm accessing it via the "markdown" version link in tracker and it has a .md extension.

-glenn

On 7/29/21, 10:38 AM, "Bob Hinden" <[email-masked]> wrote:

    Kyle, Glenn,

    Bob

---

From: Kyle Rose <[email-masked]>
Date: Thu, 29 Jul 2021 14:10:40 -0400

Interesting. I think CodiMD is rendering incorrectly, because markdown
intentionally ignores single newlines: if CodiMD wants a line break, it
should insert *two* newlines (a paragraph break) or two spaces at the end
of a line (line break) to get that effect. I would avoid the issue entirely
by using bullets to delineate elements.

Kyle

On Thu, Jul 29, 2021 at 1:47 PM Deen, Glenn (NBCUniversal) <
[email-masked]> wrote:

> Here'e the raw ADD@110 minutes from CODIMD.
> https://codimd.ietf.org/notes-ietf-110-add  which formats fine.
>
> Here's the datatracker version:
> https://datatracker.ietf.org/meeting/110/materials/minutes-110-add-202103091530-00.md
> which has wrap problems.
>
>
> The Datatracker version does preserve markdown coded links correctly, but
> the text lines are being wrapped together.
>
> Could this be a typing problem coming out of datatracker?     Datatracker
> does recognize that it's a markdown file as I'm accessing it via the
> "markdown" version link in tracker and it has a .md extension.
>
> -glenn
>
>
>     I gave downloading the markdown and uploading that to the
> Datatracker.  That works, but the discussion are getting wrapped when I
> open the link in Safari and Crome.  For example:
>
>     Toerless Eckert: Very nice. Any experience from ECN experimental?
> Gorry Fairhurst: ECN is standards. Second generation of ECN. Unable to
> help. Gorry Fairhurst: Original is currently proposed standards. Toerless
> Eckert: I think we could be consistent on that. You made it experimental
> because you don't want to explore some things? Gorry Fairhurst: Original
> ecn appears to be more unexperimental. We can do whatever 6man wants us to.
> Geoff Huston: Not everybody can do it overnight. It effects every router
> along the path. The real question is that how partial deployment will
> impact. Bob Hinden: We expect there will be mixed implementations for a
> while. Gorry do you want to say more? Gorry Fairhurst: Not replace the PMTU
> discovery. If you have some routers that can discover, then
>
>     > It requires your browser/OS to understand and present the markdown
> mime type when uploading, which has led to some frustration (and confused
>     >     > I've done a light cleanup - both for English and markdown -
> and then upload them.   Since I also create the WG agenda as markdown when
> making it, this goes as the seed for the cotimd notes ahead of the meeting
> the result is the notes are then all in markdown along with working links
> etc.   that live in the notes document and work for future readers.
>     >     >
>     >     >
>     >     > -glenn
>     >     >
>     >     >    What’s the best practice to convert and/or publish minutes
> taken with codimd?   I have managed to so something in past meetings, but
> usually try a few things.
>     >     >

---

From: "Deen, Glenn (NBCUniversal)" <[email-masked]>
Date: Thu, 29 Jul 2021 18:30:05 +0000

I think Codimd is doing it right as it displays the same for me in Atom using the github md viewer as it does in Codimd.

On 7/29/21, 11:11 AM, "Kyle Rose" <[email-masked]<mailto:[email-masked]>> wrote:

Interesting. I think CodiMD is rendering incorrectly, because markdown intentionally ignores single newlines: if CodiMD wants a line break, it should insert *two* newlines (a paragraph break) or two spaces at the end of a line (line break) to get that effect. I would avoid the issue entirely by using bullets to delineate elements.

Kyle

On Thu, Jul 29, 2021 at 1:47 PM Deen, Glenn (NBCUniversal) <[email-masked]<mailto:[email-masked]>> wrote:
Bob,

Here'e the raw ADD@110 minutes from CODIMD.  https://codimd.ietf.org/notes-ietf-110-add<https://urldefense.com/v3/__https:/codimd.ietf.org/notes-ietf-110-add__;!!PIZeeW5wscynRQ!7dCPc4ALRp1e7ZHTSPvwFn1TbrTMyOARu2RnYaOg66xtOpr1GdpI0eyw8Hk7YevJ$>  which formats fine.

Here's the datatracker version: https://datatracker.ietf.org/meeting/110/materials/minutes-110-add-202103091530-00.md<https://urldefense.com/v3/__https:/datatracker.ietf.org/meeting/110/materials/minutes-110-add-202103091530-00.md__;!!PIZeeW5wscynRQ!7dCPc4ALRp1e7ZHTSPvwFn1TbrTMyOARu2RnYaOg66xtOpr1GdpI0eyw8PRfbGoT$> which has wrap problems.

-glenn

On 7/29/21, 10:38 AM, "Bob Hinden" <[email-masked]<mailto:[email-masked]>> wrote:

    Kyle, Glenn,

    Bob

    > On Jul 29, 2021, at 10:09 AM, Kyle Rose <[email-masked]<mailto:[email-masked]>> wrote:
    >
    > https://datatracker.ietf.org/doc/minutes-111-mops/<https://urldefense.com/v3/__https:/datatracker.ietf.org/doc/minutes-111-mops/__;!!PIZeeW5wscynRQ!7dCPc4ALRp1e7ZHTSPvwFn1TbrTMyOARu2RnYaOg66xtOpr1GdpI0eyw8HhprQl0$>
    >

---

From: Bob Hinden <[email-masked]>
Date: Thu, 29 Jul 2021 11:30:33 -0700

Kyle,

> On Jul 29, 2021, at 11:10 AM, Kyle Rose <[email-masked]> wrote:
> 

According to this:  https://www.markdownguide.org/basic-syntax/

Two blank lines creates a paragraph.   Two spaces creates a line break.   As it says, hard to see in a editor.

Also, there doesn’t seem to be a to create bullet lists without a symbol before the text.   I will turn everthing into paragraphs.

Bob

p.s. Now I know more about markdown than I wanted to know.

> 
> Kyle
> 
> On Thu, Jul 29, 2021 at 1:47 PM Deen, Glenn (NBCUniversal) <[email-masked]> wrote:
> Bob,
>

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 29 Jul 2021 20:32:15 +0200

> Interesting. I think CodiMD is rendering incorrectly, because markdown intentionally ignores single newlines: if CodiMD wants a line break, it should insert *two* newlines (a paragraph break) or tw…

That is a well-known problem with markdown:
Implementations differ in how “hard” newlines are.
(There is also a difference on where a bullet is recognized after a paragraph.)

CodiMD’s markdown is very friendly to the online notes crowd.
Github flavored markdown (GFM) was until they reverted to Gruber’s definition of what a newline means.
Most other markdown implementations have the Gruber-like soft newlines and “lazy” syntax that gives even less notice to newlines.

That’s a bummer, indeed.
I’m not aware of a tool that converts hard-newline markdown like CodiMD’s to soft-newline ones (well, maybe kramdown can do that in its GFM mode; need to check).

Grüße, Carsten

---

From: Kyle Rose <[email-masked]>
Date: Thu, 29 Jul 2021 14:43:45 -0400

On Thu, Jul 29, 2021 at 2:32 PM Carsten Bormann <[email-masked]> wrote:

> Most other markdown implementations have the Gruber-like soft newlines and
> “lazy” syntax that gives even less notice to newlines.
>
> That’s a bummer, indeed.
>

If I had to guess, the preference for single newlines to be ignored for
rendering purposes is a result of desiring to support people who edit docs
in tools that automatically wrap long lines.

I personally find this behavior extremely helpful in simplifying diffs when
working on I-Ds: my MO is to put each sentence (approximately) on its own
line, avoiding either a small edit within a paragraph-length line (what
would be required if single newlines were rendered as line breaks) or a
complex diff from a paragraph whose length is changed and then re-flowed at
the editor's chosen line length.

Kyle

---

From: Bob Hinden <[email-masked]>
Date: Thu, 29 Jul 2021 11:47:58 -0700

Carsten,

> On Jul 29, 2021, at 11:32 AM, Carsten Bormann <[email-masked]> wrote:
> 

:-(

Especially given is growing use in the IETF.

Bob

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Thu, 29 Jul 2021 20:13:48 +0000

> intentionally ignores single newlines: if CodiMD wants a line break, it should
> insert *two* newlines (a paragraph break) or two spaces at the end of a line
> (line break) to get that effect. I would avoid the issue entirely by using bullets to
> delineate elements.
> 
> Implementations differ in how "hard" newlines are.
> CodiMD's markdown is very friendly to the online notes crowd.
> Github flavored markdown (GFM) was until they reverted to Gruber's definition
> of what a newline means.
> "lazy" syntax that gives even less notice to newlines.
> 
> That's a bummer, indeed.
> I'm not aware of a tool that converts hard-newline markdown like CodiMD's to
> soft-newline ones (well, maybe kramdown can do that in its GFM mode; need to
> check).

Right, CodiMD render markdown *differently* than datatracker. My strategy is to download the markdown to an Ubuntu laptop and edit using the Ubuntu Text Editor. I can also copy/paste from CodiMD into Text Editor. Text Editor is fabulous in its ability to recognize markdown and save as markdown.  

The main edit I do is to put blank lines between all paragraphs. Then I upload the .md file to datatracker.

Really, I suspect at least one of your 2 notetakers was either too lazy to insert those extra blank lines while typing or didn't want to impact the experience of people who might be following the discussion using the rendered CodiMD notes (because the additional blank lines create blank lines in the CodiMD rendering). I had an eerily similar experience with DNSSD WG. But adding those blank lines before uploading to datatracker is simple -- if using the Ubuntu Text Editor. There may be other such magical editors, but I don't know about them.
Barbara

---

From: Bob Hinden <[email-masked]>
Date: Thu, 29 Jul 2021 14:08:55 -0700

Barbara,

> On Jul 29, 2021, at 1:13 PM, STARK, BARBARA H <[email-masked]> wrote:
> 

That about what I ended up doing too.  A little painful, but not too bad.

Bob

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 29 Jul 2021 23:37:19 +0200

> The main edit I do is to put blank lines between all paragraphs. Then I upload the .md file to datatracker.

I might throw a little tool that does that into the next kramdown-rfc revision.  Maybe just in time for other people’s minutes…

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 30 Jul 2021 02:06:02 +0200

> I might throw a little tool that does that into the next kramdown-rfc revision.  Maybe just in time for other people’s minutes…

Done.

1.5.6: New command: de-gfm

Convert GFM-style (hard-wrap) markdown to standard markdown

(no option:) use brittle end-of-line spaces
-b: use <br/>
-c: use \
-k: use \\

As usual:
gem update

Get the codimd markdown, and run

de-gfm foo.md > foo-soft.md

The result has brittle end-of-line spaces, so you need to edit the file with care.  -b, -c, -k use various other ways to indicate line breaks; it seems datatracker only knows the brittle ones and the -b ones.

Comments welcome.

Grüße, Carsten

---

From: Kyle Rose <[email-masked]>
Date: Fri, 30 Jul 2021 03:46:39 -0400

On Thu, Jul 29, 2021 at 4:14 PM STARK, BARBARA H <[email-masked]> wrote:

> Really, I suspect at least one of your 2 notetakers was either too lazy to
> insert those extra blank lines while typing or didn't want to impact the
> experience of people who might be following the discussion using the
> rendered CodiMD notes (because the additional blank lines create blank
> lines in the CodiMD rendering).
>

I think it's probably less laziness than unfamiliarity with the quirks of
markdown, combined with the fact that CodiMD renders those single newlines
as line breaks, so it "LGTM"  in the side-by-side or rendered view. It's
only when processed through other tools in what is ostensibly the same
ecosystem that the faulty assumption is revealed.

This is a fairly benign version of a more general problem of
under-specification of semantics. (JSON and YAML come to mind.)

Kyle

---

From: Christian Amsüss <[email-masked]>
Date: Fri, 30 Jul 2021 11:47:47 +0200

Hi chairs,

On Thu, Jul 29, 2021 at 01:09:38PM -0400, Kyle Rose wrote:
> I download the markdown and then upload it to the data tracker.

I usually just export the raw HTML from the CodiMD menu and upload that.

This sidesteps both lacking markdown detection on the browser side, and
differing interpretations and features sets of markdown (of which
newline handling is just one aspect).

BR
Christian

-- 
Most people would leave. Not us. We're Vikings. We have stubbornness
issues.
  -- Hiccup, son of Stoic

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Fri, 30 Jul 2021 14:44:31 +0000

Really, I suspect at least one of your 2 notetakers was either too lazy to insert those extra blank lines while typing or didn't want to impact the experience of people who might be following the discussion using the rendered CodiMD notes (because the additional blank lines create blank lines in the CodiMD rendering).

I think it's probably less laziness than unfamiliarity with the quirks of markdown, combined with the fact that CodiMD renders those single newlines as line breaks, so it "LGTM"  in the side-by-side or rendered view. It's only when processed through other tools in what is ostensibly the same ecosystem that the faulty assumption is revealed.

This is a fairly benign version of a more general problem of under-specification of semantics. (JSON and YAML come to mind.)

<bhs> I wouldn't discount laziness so quickly. Though Carsten pointed out another reason that probably influenced me (I'm the self-accused lazy one of Bob's notetakers) not to add the extra lines while taking notes: blank lines in the markdown mean less of the typed notes are visible to the notetaker. That's a feature I hadn't consciously recognized but now agree was probably quite influential in my thought process. I did notice that the CodiMD markdown was rendering each line of typed text as a separate line of rendered text and thought this was unexpected and wondered if datatracker would do this, too. I will admit that I wasn't familiar with the convention of using 2 spaces at end of a line to create a <br/>. I'm still thinking I'll edit minutes I publish (as chair) to give each speaker their own paragraph rather than just format everyone's comments into a big paragraph with lots of line breaks. But I won't judge others' choices. - Barbara