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

Toerless Eckert <tte@cs.fau.de> Tue, 21 September 2021 16:49 UTC

Return-Path: <eckert@i4.informatik.uni-erlangen.de>
X-Original-To: wgchairs@ietfa.amsl.com
Delivered-To: wgchairs@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 9A8FB3A0A2C for <wgchairs@ietfa.amsl.com>; Tue, 21 Sep 2021 09:49:34 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.118
X-Spam-Level:
X-Spam-Status: No, score=-1.118 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, HEADER_FROM_DIFFERENT_DOMAINS=0.001, SPF_HELO_NONE=0.001, SPF_NEUTRAL=0.779, URIBL_BLOCKED=0.001] autolearn=no autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id kw47lpwRZPHy for <wgchairs@ietfa.amsl.com>; Tue, 21 Sep 2021 09:49:30 -0700 (PDT)
Received: from faui40.informatik.uni-erlangen.de (faui40.informatik.uni-erlangen.de [IPv6:2001:638:a000:4134::ffff:40]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id C9B4D3A0A26 for <wgchairs@ietf.org>; Tue, 21 Sep 2021 09:49:28 -0700 (PDT)
Received: from faui48e.informatik.uni-erlangen.de (faui48e.informatik.uni-erlangen.de [131.188.34.51]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by faui40.informatik.uni-erlangen.de (Postfix) with ESMTPS id 78B02548059; Tue, 21 Sep 2021 18:49:23 +0200 (CEST)
Received: by faui48e.informatik.uni-erlangen.de (Postfix, from userid 10463) id 64E0E4E987E; Tue, 21 Sep 2021 18:49:23 +0200 (CEST)
Date: Tue, 21 Sep 2021 18:49:23 +0200
From: Toerless Eckert <tte@cs.fau.de>
To: Robert Sparks <rjsparks@nostrum.com>
Cc: Lars Eggert <lars@eggert.org>, Working Chairs <wgchairs@ietf.org>
Subject: Re: Please look at your groups' charters rendered through markdown
Message-ID: <YUoNE+WFrQsHbl3c@faui48e.informatik.uni-erlangen.de>
References: <91a7eae6-6752-9c25-648a-69c4b75d600b@nostrum.com> <C7840DDC-D58F-4509-8E35-C260C6B327F3@eggert.org> <4b587a46-6443-a4b1-d532-a47fbc86b39a@nostrum.com>
MIME-Version: 1.0
Content-Type: text/plain; charset="iso-8859-1"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <4b587a46-6443-a4b1-d532-a47fbc86b39a@nostrum.com>
Archived-At: <https://mailarchive.ietf.org/arch/msg/wgchairs/QlyGOiCAkYcI2uxHamwoLBPT0oc>
X-BeenThere: wgchairs@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Working Group Chairs <wgchairs.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/wgchairs>, <mailto:wgchairs-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/wgchairs/>
List-Post: <mailto:wgchairs@ietf.org>
List-Help: <mailto:wgchairs-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/wgchairs>, <mailto:wgchairs-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 21 Sep 2021 16:49:35 -0000

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

On Mon, Sep 20, 2021 at 02:29:38PM -0500, Robert Sparks wrote:
> 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.

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

> 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
> 
> On 9/20/21 2:17 PM, Lars Eggert wrote:
> > On 2021-9-20, at 20:34, Robert Sparks <rjsparks@nostrum.com> 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
> > 

-- 
---
tte@cs.fau.de