[Rfc-markdown] 1.3.34: map most codeblock classes to <sourcecode> instead of <artwork>

Carsten Bormann <cabo@tzi.org> Thu, 18 February 2021 17:27 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 [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id BB1F53A14B0 for <rfc-markdown@ietfa.amsl.com>; Thu, 18 Feb 2021 09:27:08 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.897
X-Spam-Level:
X-Spam-Status: No, score=-1.897 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham 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 W8b64jwnz5-Z for <rfc-markdown@ietfa.amsl.com>; Thu, 18 Feb 2021 09:27:05 -0800 (PST)
Received: from gabriel-vm-2.zfn.uni-bremen.de (gabriel-vm-2.zfn.uni-bremen.de [134.102.50.17]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id D786E3A14AD for <rfc-markdown@ietf.org>; Thu, 18 Feb 2021 09:27:04 -0800 (PST)
Received: from [192.168.217.118] (p5089a828.dip0.t-ipconnect.de [80.137.168.40]) (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 4DhM8Q1gQtz1060; Thu, 18 Feb 2021 18:27:02 +0100 (CET)
From: Carsten Bormann <cabo@tzi.org>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Mao-Original-Outgoing-Id: 635362021.591537-b2eeaeb2e0743b5cd0123247bb1abec3
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.120.23.2.4\))
Date: Thu, 18 Feb 2021 18:27:01 +0100
Message-Id: <4E1735EC-A5DD-4201-A6EA-2285D5CC9C21@tzi.org>
To: rfc-markdown@ietf.org
X-Mailer: Apple Mail (2.3608.120.23.2.4)
Archived-At: <https://mailarchive.ietf.org/arch/msg/rfc-markdown/CQ67vpdwEbjWQjQasIJdvFzbS1M>
Subject: [Rfc-markdown] 1.3.34: map most codeblock classes to <sourcecode> instead of <artwork>
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, 18 Feb 2021 17:27:09 -0000

RFCXMLv3 introduces a second element for verbatim text beyond
<artwork>, the <sourcecode> element.
So kramdown-rfc needs to decide whether a codeblock turns into
<sourcecode> or into <artwork>.

1.3.34 now maps all code blocks with a language given to sourcecode,
except if the language is one of (ascii-art binary-art call-flow
hex-dump svg).
(This exception list was appropriated from RFC 7991; the current
xml2rfc documentation doesn't mention call-flow or hex-dump.)

So

~~~
/\
\/
~~~

still turns into <artwork>, while

~~~ c
int dezigzag(unsigned int i) {return (i>>1) ^ -(i&1)}
~~~

turns into <sourcecode> (with type="c").

Using the "gi" pseudo-attribute, this automatic choice can be
overridden (use gi="artwork" or gi="sourcecode" in an inline attribute
list).

Note that for both artwork and sourcecode, additional attributes need
to be notated as "artwork-foo" (or "sourcecode-foo") in an inline
attribute list, as the codeblock itself turns into a
<figure> around the artwork/sourcecode, so you can have title etc.

An example with an inline attribute list (IAL):

~~~ c
main() { return 1; }
~~~
{: #my-little-c-program artwork-name="myli.c" title="My little C program"}

or, to keep the actual source outside the markdown

~~~ c
{::include myli.c}
~~~
{: #my-little-c-program artwork-name="myli.c" title="My little C program"}

(kdrfc -c will generate a .v2v3.xml that includes the text, so it can
be directly submitted to the datatracker.)

Note that the conventional type strings listed in [0] are all
lower-case; I'm sorry if this violates your sense of aesthetics as
much as mine :-)

Over at the github issue [77], which this release resolves, we also
discussed using media-type-names (or content-types [1]) as types --
this strikes me as a great convention.

Grüße, Carsten

[0]: https://www.rfc-editor.org/materials/sourcecode-types.txt
[77]: https://github.com/cabo/kramdown-rfc2629/issues/77
[1]: https://www.ietf.org/archive/id/draft-bormann-core-media-content-type-format-02.html