Subject: Please look at your groups' charters rendered through markdown

From: Robert Sparks <[email-masked]>
Date: Mon, 20 Sep 2021 12:34:38 -0500

Chairs -

I have added a page that shows how the current charter for a group 
renders with markdown, comparing side-by-side with the current rendering.

See, for example, https://datatracker.ietf.org/group/stir/about/rendertest/

Please look the variant of that page for all of the groups you are 
responsible for (and feel free to explore others).

Bring any issues with the markdown rendering of the current charter text 
to me.

If we don't have major issues to address with any existing charter text, 
I plan to switch the main /about page (and the charter document view 
page) to render through markdown with the next datatracker release.

RjS

---

From: "Salz, Rich" <[email-masked]>
Date: Mon, 20 Sep 2021 17:43:28 +0000

Curdle's linkfest at the end of the page doesn't show up well.

Any chance of some pattern-matches to do auto-linkification?  (Not just for that, but for text like "RFC xxxxx" etc)

Either way, this is good,  I'll fix the curdle page if necessary.

---

From: Lars Eggert <[email-masked]>
Date: Mon, 20 Sep 2021 22:17:34 +0300

On 2021-9-20, at 20:34, Robert Sparks <[email-masked]> wrote:
> Bring any issues with the markdown rendering of the current charter text to me.

Not my group anymore, but QUIC looks a bit odd: https://datatracker.ietf.org/group/quic/about/rendertest/

That should be an indented bullet list under 1., as shown on https://github.com/quicwg/wg-materials/blob/main/charter/charter.md

Thanks,
Lars

---

From: Robert Sparks <[email-masked]>
Date: Mon, 20 Sep 2021 14:29:38 -0500

And here we hit the issues with the different versions of markdown at 
different sites.

Github markdown treats leading space differently than Gruber's markdown.

The relevant part of the source for the thing ending up with a different 
rendering looks like this (via hexdump -C). Best viewed in fixed width.

00000100  6c 65 64 20 62 65 6c 6f  77 3a 0a 0a 20 20 20 31  |led 
below:..   1|
00000110  2e 20 54 68 65 20 66 69  72 73 74 20 61 72 65 61  |. The first 
area|
00000120  20 6f 66 20 77 6f 72 6b  20 69 73 20 6d 61 69 6e  | of work is 
main|
00000130  74 65 6e 61 6e 63 65 20  61 6e 64 20 65 76 6f 6c |tenance and 
evol|
00000140  75 74 69 6f 6e 20 6f 66  20 74 68 65 20 65 78 69 |ution of the 
exi|
00000150  73 74 69 6e 67 20 51 55  49 43 20 73 70 65 63 69 |sting QUIC 
speci|
00000160  66 69 63 61 74 69 6f 6e  73 3a 0a 0a 20 20 20 20 
|fications:..    |
00000170  20 20 20 20 20 2a 20 4d  61 69 6e 74 65 6e 61 6e |     * 
Maintenan|
00000180  63 65 20 61 6e 64 20 65  76 6f 6c 75 74 69 6f 6e  |ce and 
evolution|
00000190  20 6f 66 20 74 68 65 20  51 55 49 43 20 62 61 73  | of the 
QUIC bas|
000001a0  65 20 73 70 65 63 69 66  69 63 61 74 69 6f 6e 73  |e 
specifications|

That is, there are 9 spaces before what you intend to be a bullet mark.

For what's at https://pypi.org/project/Markdown/ (implementing 
https://daringfireball.net/projects/markdown/), anything that starts 
with 4 or more spaces or a tab is a blockquote.

Do you easily see a single input file that gets the desired output out 
of both renderers?

RjS

---

From: Fred Baker <[email-masked]>
Date: Mon, 20 Sep 2021 12:31:22 -0700

My first comment is on rendering. I am looking at the stir page you sent on my phone, and I would it to render correctly there. It doesn’t; it has lines that are had again as long as the page witdth, and wrap accordingly.

Sent using a machine that autocorrects in interesting ways...

> On Sep 20, 2021, at 12:18 PM, Lars Eggert <[email-masked]> wrote:
>

---

From: Robert Sparks <[email-masked]>
Date: Mon, 20 Sep 2021 14:43:01 -0500

Fred -

Notice that on a phone, instead of a side-by-side comparison, you get 
the "current" version first, followed by the "markdown" version later. 
Look for the blue headers.

The current version, of course, renders just as badly as /about does on 
a phone.

Scroll down and see what the section you'll find below the "Markdown 
rendering" header looks like.

RjS

---

From: Russ Housley <[email-masked]>
Date: Mon, 20 Sep 2021 15:53:15 -0400

> Bring any issues with the markdown rendering of the current charter text to me.

https://datatracker.ietf.org/group/suit/about/rendertest/

The new rendering dues not recognize what was supposed to be bullets.

Russ

---

From: "MORTON JR., AL" <[email-masked]>
Date: Mon, 20 Sep 2021 20:25:06 +0000

Hi Robert,

> Bring any issues with the markdown rendering of the current charter text

I saw a minor issue with the BMWG page [0], an unexpected line break in the second paragraph of the MD rendering.

Not a big deal,
Al

[0] https://datatracker.ietf.org/group/bmwg/about/rendertest/

---

From: Robert Sparks <[email-masked]>
Date: Mon, 20 Sep 2021 15:28:15 -0500

Fascinating. Trailing space led to this one:

00000370  66 20 20 0a 4e 65 74 77  6f 72 6b 20 46 75 6e 63  |f .Network 
Func|

RjS

---

From: Henk Birkholz <[email-masked]>
Date: Mon, 20 Sep 2021 23:02:28 +0200

Surprisingly, bullet points do not work. But the numbered items do.

> https://datatracker.ietf.org/group/rats/about/rendertest/

Viele Grüße,

Henk

---

From: Robert Sparks <[email-masked]>
Date: Mon, 20 Sep 2021 16:08:31 -0500

Right - variants of this are on several pages - they _would_ be 
recognized as lists if there were a blank line before them.

RjS

---

From: Warren Kumari <[email-masked]>
Date: Mon, 20 Sep 2021 18:09:42 -0400

GROW had attempted to add some sort of formatting, with  '----' to break
things up.

These have (unsurprisingly) turned into horizontal rules. There was also a
"list" of URLs which has been munged.

Neither of these are really major issues, but perhaps we should try and
figure out some method for chairs to make formatting only charter updates
after the change?
It seems like it would be silly to have a "real" recharter to change:

Some Relevant References:
-------------------------
http://www.routeviews.org
http://bgp.potaroo.net
...

into:
## Some Relevant References:
  * http://www.routeviews.org
  * http://bgp.potaroo.net

W

On Mon, Sep 20, 2021 at 1:34 PM Robert Sparks <[email-masked]> wrote:

> See, for example,
> https://datatracker.ietf.org/group/stir/about/rendertest/
>

-- 
The computing scientist’s main challenge is not to get confused by the
complexities of his own making.
  -- E. W. Dijkstra

---

From: "MORTON JR., AL" <[email-masked]>
Date: Mon, 20 Sep 2021 22:19:18 +0000

Hey Warren, I was hoping for this...

you wrote:
Neither of these are really major issues, but perhaps we should try and figure out some method for chairs to make formatting only charter updates after the change?
It seems like it would be silly to have a "real" recharter to change...

+1

BMWG’s text charter has a single trailing whitespace that resulted in an unexpected line-break in the MD. I don’t want to re-charter to fix it, and I will really appreciate a “trust the editor” solution.

Al

From: WGChairs <[email-masked]> On Behalf Of Warren Kumari
Sent: Monday, September 20, 2021 6:10 PM
To: Robert Sparks <[email-masked]>
Cc: Working Chairs <[email-masked]>
Subject: Re: Please look at your groups' charters rendered through markdown

GROW had attempted to add some sort of formatting, with  '----' to break things up.

These have (unsurprisingly) turned into horizontal rules. There was also a "list" of URLs which has been munged.

Neither of these are really major issues, but perhaps we should try and figure out some method for chairs to make formatting only charter updates after the change?
It seems like it would be silly to have a "real" recharter to change:

Some Relevant References:
-------------------------
http://www.routeviews.org<https://urldefense.com/v3/__http:/www.routeviews.org__;!!BhdT!1aPBPwwT6Qrl6vjwUAH68fAxjt8Bm5_4vLvgFunlTIKB6eZUKMLKOgEklEx7GPM$>
http://bgp.potaroo.net<https://urldefense.com/v3/__http:/bgp.potaroo.net__;!!BhdT!1aPBPwwT6Qrl6vjwUAH68fAxjt8Bm5_4vLvgFunlTIKB6eZUKMLKOgEktGWOaMs$>
...

into:
## Some Relevant References:
  * http://www.routeviews.org<https://urldefense.com/v3/__http:/www.routeviews.org__;!!BhdT!1aPBPwwT6Qrl6vjwUAH68fAxjt8Bm5_4vLvgFunlTIKB6eZUKMLKOgEklEx7GPM$>
  * http://bgp.potaroo.net<https://urldefense.com/v3/__http:/bgp.potaroo.net__;!!BhdT!1aPBPwwT6Qrl6vjwUAH68fAxjt8Bm5_4vLvgFunlTIKB6eZUKMLKOgEktGWOaMs$>

W

On Mon, Sep 20, 2021 at 1:34 PM Robert Sparks <[email-masked]<mailto:[email-masked]>> wrote:
Chairs -

See, for example, https://datatracker.ietf.org/group/stir/about/rendertest/<https://urldefense.com/v3/__https:/datatracker.ietf.org/group/stir/about/rendertest/__;!!BhdT!1aPBPwwT6Qrl6vjwUAH68fAxjt8Bm5_4vLvgFunlTIKB6eZUKMLKOgEk8zxmeFI$>

RjS

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 21 Sep 2021 08:54:14 +1000

> page) to render through markdown with the next datatracker release.

I've seen a bunch of minor issues in the thread, none of which would be a problem if chairs were able to edit the charters (ideally with a preview in the edit flow).

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 21 Sep 2021 10:05:37 +1000

This looks great!

The only thing I see that might be worth considering is adjusting so that when a level-1 header is used in a charter, it's appropriately sized (smaller than currently), because it's not the top-level header on the page.

IMO we should avoid lots of one-off hacks / pre-processing in the markdown -- instead, we should fix the source files.

I think you hit the nail on the head of the real issue underlying this: what flavour of md to use. Lots of people are familiar with GFM, as well as kramdown (thanks to cabo's tooling). It'd be nice not to have to mode switch to a third variety, so a subset of one of those would probably be best (assuming we're eventually going to use the same flavour across charters, minutes, agendas, etc.).

Cheers,

> On 21 Sep 2021, at 3:34 am, Robert Sparks <[email-masked]> wrote:
> 
> Chairs -
> 
> I have added a page that shows how the current charter for a group renders with markdown, comparing side-by-side with the current rendering.
> 
> Please look the variant of that page for all of the groups you are responsible for (and feel free to explore others).
> 
> If we don't have major issues to address with any existing charter text, I plan to switch the main /about page (and the charter document view page) to render through markdown with the next datatracker release.
> 
> RjS
> 

--
Mark Nottingham   https://www.mnot.net/

---

From: "Black, David" <[email-masked]>
Date: Tue, 21 Sep 2021 02:07:11 +0000

TSVWG has a variant of this problem with the numbered list at the bottom of the page.

Inserting the blank lines needed to correct this should be acceptable.

Thanks, --David

-----Original Message-----
From: WGChairs <[email-masked]> On Behalf Of Robert Sparks
Sent: Monday, September 20, 2021 5:09 PM
To: Henk Birkholz; Russ Housley
Cc: IETF WG Chairs
Subject: Re: Please look at your groups' charters rendered through markdown

[EXTERNAL EMAIL] 

RjS

On 9/20/21 4:02 PM, Henk Birkholz wrote:
>> https://urldefense.com/v3/__https://datatracker.ietf.org/group/rats/about/rendertest/__;!!LpKI!xyoKta1FZihpdd7MH-e27TloZncRioDnQYMEMTdui-5GnkBVTsMHzyFvhalM1ho$ [datatracker[.]ietf[.]org]
>
> Viele Grüße,
>
> Henk
>
>> https://urldefense.com/v3/__https://datatracker.ietf.org/group/suit/about/rendertest/__;!!LpKI!xyoKta1FZihpdd7MH-e27TloZncRioDnQYMEMTdui-5GnkBVTsMHzyFvPOikYLg$ [datatracker[.]ietf[.]org]
>>

---

From: Henk Birkholz <[email-masked]>
Date: Tue, 21 Sep 2021 09:17:42 +0200

+1

---

From: Bob Hinden <[email-masked]>
Date: Tue, 21 Sep 2021 09:10:39 -0700

Robert,

6man looks fine, as it should given its only two paragraphs of straight text.

What is going to happen with the milestones in this conversion?

Bob

> On Sep 20, 2021, at 10:34 AM, Robert Sparks <[email-masked]> wrote:
> 
> Chairs -
>

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 21 Sep 2021 18:49:23 +0200

Nice job already, thanks a lot, Robert & team!

> Github markdown treats leading space differently than Gruber's markdown.

Can we please have an authoritative documentation of the markup used 
and a web page that will render an input text ?

That way chairs can see how a version of a charter will look that
they have fixed up with the best rendering options for their charter text.
That should minimize work for the tools team to enhance/fixup the markup.

If we need fixups, they should be in the way of wrappers to
avoid local versioning of an actual markup, such as done with
kramdown-rfc2629. For example to convert markup for
well known names such as RFC* and draft-* into URLs.

Cheers
    Toerless

> 00000100  6c 65 64 20 62 65 6c 6f  77 3a 0a 0a 20 20 20 31  |led below:..  
> 1|
> 00000160  66 69 63 61 74 69 6f 6e  73 3a 0a 0a 20 20 20 20 |fications:..   
> |
> 00000190  20 6f 66 20 74 68 65 20  51 55 49 43 20 62 61 73  | of the QUIC
> bas|
> https://daringfireball.net/projects/markdown/), anything that starts with 4
> or more spaces or a tab is a blockquote.
> 
> Do you easily see a single input file that gets the desired output out of
> both renderers?
> 
> RjS
> 

-- 
---
[email-masked]

---

From: Robert Sparks <[email-masked]>
Date: Tue, 21 Sep 2021 12:43:20 -0500

> Can we please have an authoritative documentation of the markup used

Right now, the authoritative documentation is at the links I sent below 
(into Pypi and at daringfireball).

To save you a little digging, very relevant spots are at

https://python-markdown.github.io/#Features

and

https://daringfireball.net/projects/markdown/syntax

(and because I've turned on "extra"

https://python-markdown.github.io/extensions/extra/

> and a web page that will render an input text ?

As a workaround for now, you can do this locally as documented here:

https://python-markdown.github.io/cli/

for example: (env) rjsparks@unformal markdown % python -m markdown -x 
extra src.md

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Tue, 21 Sep 2021 14:20:34 -0500

Robert,

Top-posting to say "thank you for the clues".

Best,

Spencer

On Tue, Sep 21, 2021 at 12:44 PM Robert Sparks <[email-masked]> wrote:

> below:..
> QUIC
> of
> >>> Not my group anymore, but QUIC looks a bit odd:
> https://datatracker.ietf.org/group/quic/about/rendertest/
> >>>
> >>> That should be an indented bullet list under 1., as shown on
> https://github.com/quicwg/wg-materials/blob/main/charter/charter.md
> >>>
> >>> Thanks,
> >>> Lars
> >>>
>
>

---

From: Ron Bonica <[email-masked]>
Date: Tue, 21 Sep 2021 20:19:03 +0000

OPSEC and V6OPS look good.

                            Ron

Juniper Business Use Only

-----Original Message-----
From: WGChairs <[email-masked]> On Behalf Of Robert Sparks
Sent: Monday, September 20, 2021 3:30 PM
To: Lars Eggert <[email-masked]>
Cc: Working Chairs <[email-masked]>
Subject: Re: Please look at your groups' charters rendered through markdown

[External Email. Be cautious of content]

And here we hit the issues with the different versions of markdown at different sites.

The relevant part of the source for the thing ending up with a different rendering looks like this (via hexdump -C). Best viewed in fixed width.

00000190  20 6f 66 20 74 68 65 20  51 55 49 43 20 62 61 73  | of the QUIC bas|

For what's at https://urldefense.com/v3/__https://pypi.org/project/Markdown/__;!!NEt6yMaO-gk!Wbkj_S1LW2ra5oUCdzK9c2hHyue4WjZhEX1ZbA3-w30DOPUPyy68AcDlp1zM0qpf$  (implementing https://urldefense.com/v3/__https://daringfireball.net/projects/markdown/__;!!NEt6yMaO-gk!Wbkj_S1LW2ra5oUCdzK9c2hHyue4WjZhEX1ZbA3-w30DOPUPyy68AcDlp-7_4vXx$ ), anything that starts with 4 or more spaces or a tab is a blockquote.

Do you easily see a single input file that gets the desired output out of both renderers?

RjS

On 9/20/21 2:17 PM, Lars Eggert wrote:
> https://urldefense.com/v3/__https://datatracker.ietf.org/group/quic/ab
> out/rendertest/__;!!NEt6yMaO-gk!Wbkj_S1LW2ra5oUCdzK9c2hHyue4WjZhEX1ZbA
> 3-w30DOPUPyy68AcDlp-DG3jEz$
>
> https://urldefense.com/v3/__https://github.com/quicwg/wg-materials/blo
> b/main/charter/charter.md__;!!NEt6yMaO-gk!Wbkj_S1LW2ra5oUCdzK9c2hHyue4
> WjZhEX1ZbA3-w30DOPUPyy68AcDlpwcavq2C$
>
> Thanks,
> Lars
>

---

From: "Bron Gondwana" <[email-masked]>
Date: Wed, 22 Sep 2021 08:09:36 +1000

Both extra and calext have minor issues with having put things on individual lines without dot-pointing them, but it's not unreadable.

Is there going to be an easy path to request minor whitespace and dotpoint changes to correct charter display as part of this process?

Thanks,

Bron.

--
  Bron Gondwana, CEO, Fastmail Pty Ltd
  [email-masked]

---

From: "Pascal Thubert (pthubert)" <[email-masked]>
Date: Wed, 22 Sep 2021 08:18:40 +0000

LPWAN is similar and 6TiSCH is actually improved 😊

From: WGChairs <[email-masked]> On Behalf Of Bron Gondwana
Sent: mercredi 22 septembre 2021 0:10
To: [email-masked]
Subject: Re: Please look at your groups' charters rendered through markdown

Thanks,

Bron.

RjS

--
  Bron Gondwana, CEO, Fastmail Pty Ltd
  [email-masked]<mailto:[email-masked]>

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 22 Sep 2021 12:42:22 -0400

RUM is fine. It appears the vertical whitespace is somewhat different so 
that in the end it appears a bit shorter. That is fine.

---

From: Barry Leiba <[email-masked]>
Date: Thu, 23 Sep 2021 10:14:03 -0400

Two issues for DMARC:

The merging of the bullet lists and the numbered list items is odd.

The "References" section is completely messed up, as it was meant to
be a list with no bullets.

Barry