[Rfc-markdown] Using kramdown-rfc with v3 (Re: [Tools-discuss] HTML vs HTMLized)

Carsten Bormann <cabo@tzi.org> Thu, 05 December 2019 20:45 UTC

Return-Path: <cabo@tzi.org>
X-Original-To: rfc-markdown@ietfa.amsl.com
Delivered-To: rfc-markdown@ietfa.amsl.com
Received: from localhost (localhost []) by ietfa.amsl.com (Postfix) with ESMTP id 2DE8912083E for <rfc-markdown@ietfa.amsl.com>; Thu, 5 Dec 2019 12:45:47 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.2
X-Spam-Status: No, score=-4.2 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([]) by localhost (ietfa.amsl.com []) (amavisd-new, port 10024) with ESMTP id DhTAR-p7tBhD for <rfc-markdown@ietfa.amsl.com>; Thu, 5 Dec 2019 12:45:45 -0800 (PST)
Received: from gabriel-vm-2.zfn.uni-bremen.de (gabriel-vm-2.zfn.uni-bremen.de []) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id B06A212081B for <rfc-markdown@ietf.org>; Thu, 5 Dec 2019 12:45:44 -0800 (PST)
Received: from [] (p548DC893.dip0.t-ipconnect.de []) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gabriel-vm-2.zfn.uni-bremen.de (Postfix) with ESMTPSA id 47TSRB422bzyhN; Thu, 5 Dec 2019 21:45:42 +0100 (CET)
Content-Type: text/plain; charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 11.5 \(3445.9.1\))
From: Carsten Bormann <cabo@tzi.org>
In-Reply-To: <F202CE4F-8352-438C-8EE7-9D98B9567629@tzi.org>
Date: Thu, 5 Dec 2019 21:45:39 +0100
Cc: RFC Markdown <rfc-markdown@ietf.org>
X-Mao-Original-Outgoing-Id: 597271537.9817981-3ec99188483ce7685658f3404d4c792d
Content-Transfer-Encoding: quoted-printable
Message-Id: <D7D84E44-62D4-4375-8CBC-ACDCF20F9E44@tzi.org>
References: <14533.1575553674@localhost> <91FC73D1-91C5-4155-A249-125F066B5027@levkowetz.com> <fdbac244-694e-cb0a-8019-c4fd0a5b33e1@sandelman.ca> <21497.1575563901@localhost> <418f100b-ee67-35ba-98e5-72eba1cdcf8e@gmx.de> <31220.1575566871@localhost> <F202CE4F-8352-438C-8EE7-9D98B9567629@tzi.org>
To: Michael Richardson <mcr+ietf@sandelman.ca>
X-Mailer: Apple Mail (2.3445.9.1)
Archived-At: <https://mailarchive.ietf.org/arch/msg/rfc-markdown/E9C9aMmjZ19AswocFlBzEIJ9cFg>
Subject: [Rfc-markdown] Using kramdown-rfc with v3 (Re: [Tools-discuss] HTML vs HTMLized)
X-BeenThere: rfc-markdown@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: "rfc-markdown is a discussion list for people writing I-Ds and RFCs in Markdown and the authors of the tools used for that." <rfc-markdown.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/rfc-markdown>, <mailto:rfc-markdown-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/rfc-markdown/>
List-Post: <mailto:rfc-markdown@ietf.org>
List-Help: <mailto:rfc-markdown-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/rfc-markdown>, <mailto:rfc-markdown-request@ietf.org?subject=subscribe>
X-List-Received-Date: Thu, 05 Dec 2019 20:45:50 -0000

Interesting discussion over at tools-discuss, some of which copied at the end.

One thing I didn’t say there is how to mix XML with markdown in kramdown:

Normally, you can just include XML wherever you need it:

Important German politicians usually have ASCII-compatible names, with very few exceptions, e.g., <u>Jürgen Möllemann</u>, and you know where that guy led us.

Now, sometimes you want to use some v3 feature that would envelope some normal text, e.g., the <aside> feature.  To use nested markdown inside manually entered XML markup, add:

<aside markdown="1">

Important German politicians usually have ASCII-compatible names, with very few exceptions, e.g., <u>Jürgen Möllemann</u>, and you know where that guy led us.


The quotes around the 1 in markdown=“1” are needed.  (More on markdown=“1” and some variants in https://kramdown.gettalong.org/syntax.html .)

There are some limitations (trying to avoid the word “bugs” here) of the xml2rfc v2 to v3 conversion.  Most notably, it does not handle beyond-ASCII characters in some of the structured information.  Kramdown-rfc2629 has one workaround for that at the moment:

    name: Carsten Bormann
    org: Universität Bremen TZI
    orgascii: Universitaet Bremen TZI

I’m still considering ways to handle v3’s “ascii” convention in ways that are less intrusive, but for v2 to v3 version, really this limitation im xml2rfc needs to be fixed first.

Grüße, Carsten

> On Dec 5, 2019, at 20:54, Carsten Bormann <cabo@tzi.org> wrote:
> On Dec 5, 2019, at 18:27, Michael Richardson <mcr+ietf@sandelman.ca> wrote:
>> kramdown-rfc2629 version 1.2.13 says:
>> dooku-[~](2.6.5) mcr 10052 %kramdown-rfc2629 -h
>> Usage: kramdown-rfc2629 [options] file.md|file.mkd > file.xml
>>   -v, --[no-]verbose               Run verbosely
>>   -3, --[no-]v3                    Use RFCXML v3 processing rules
>> which is new compared to 1.2.12.  But, maybe it doesn't do very much yet :-)
>> I'm hoping Carsten will educate us...
> Indeed, the route towards v3 goes through v2 at this time.
> As Henrik mentioned, xml2rfc has a compatibility mode and can process v2 and convert v2 to v3.
> For now, this is likely to be a more stable approach than direct v3 generation.
> I admit this is a somewhat lazy way of handling this, but I also believe this is in the best interest of kramdown-rfc’s users: stability is the most important feature of kramdown-rfc.
> If you actually need a new v3 feature (artsets anyone?), you are better off writing the XML on your own, in particular during a period where these features aren’t really stable.  When patterns of usage emerge here that actually can be expressed in markdown, I’ll sure go ahead and implement them.  And when we have an approved document for v3, directly generating v3 is likely to be stable enough. 
> I’m going to stop going into details here.  Note that there is a (very low volume(*)) rfc-markdown list that should be hosting any specific discussions:
> https://www.ietf.org/mailman/listinfo/rfc-markdown
> Grüße, Carsten
> (*) Well, that might change slightly as we embrace v3.