[Rfc-markdown] kramdown-rfc-extract-sourcecode: Provide better names to the extracted files

Carsten Bormann <cabo@tzi.org> Mon, 25 September 2023 15:12 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 E5FE9C152561 for <rfc-markdown@ietfa.amsl.com>; Mon, 25 Sep 2023 08:12:46 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.909
X-Spam-Level:
X-Spam-Status: No, score=-1.909 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_ZEN_BLOCKED_OPENDNS=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([50.223.129.194]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id h1MkelVua_CQ for <rfc-markdown@ietfa.amsl.com>; Mon, 25 Sep 2023 08:12:43 -0700 (PDT)
Received: from smtp.zfn.uni-bremen.de (smtp.zfn.uni-bremen.de [IPv6:2001:638:708:32::21]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 7A9A8C1522DB for <rfc-markdown@ietf.org>; Mon, 25 Sep 2023 08:12:41 -0700 (PDT)
Received: from eduroam-pool10-331.wlan.uni-bremen.de (eduroam-pool10-331.wlan.uni-bremen.de [134.102.91.74]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.zfn.uni-bremen.de (Postfix) with ESMTPSA id 4RvRFK2JJPzDCg6; Mon, 25 Sep 2023 17:12:37 +0200 (CEST)
From: Carsten Bormann <cabo@tzi.org>
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
X-Mao-Original-Outgoing-Id: 717347556.916108-997c23561aa1d8ddedad4792331cbb9e
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.120.23.2.7\))
Date: Mon, 25 Sep 2023 17:12:36 +0200
Message-Id: <70B4AB74-4BC7-476A-B88A-B7A5DE5AADBD@tzi.org>
To: rfc-markdown@ietf.org
X-Mailer: Apple Mail (2.3608.120.23.2.7)
Archived-At: <https://mailarchive.ietf.org/arch/msg/rfc-markdown/5yz4LoSko5jTc2OnbRj8WVDib8k>
Subject: [Rfc-markdown] kramdown-rfc-extract-sourcecode: Provide better names to the extracted files
X-BeenThere: rfc-markdown@ietf.org
X-Mailman-Version: 2.1.39
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: Mon, 25 Sep 2023 15:12:47 -0000

PR #208 [1] proposes to improve the way kramdown-rfc-extract-sourcecode generates the filenames for sourcecode extracted by it:

> * sourcecode-name values are less heavily mangled; the characters "-" and "." are now allowed (except at the start) and no longer converted into underscores.
> 
> * unnamed files now have their sourcecode type attached (e.g., if the sourcecode type is abnf, unnamed-123 ➔ unnamed-123.abnf)
> 
> This update will, unfortunately, be a flag day for those using this feature from Makefiles or includes in the markdown.
> 
> close #206

I believe this will be a net win for most applications.

But, as mentioned in the PR, it means there will be a flag day (probably in 1.6.44):
E.g., in draft-ietf-jsonpath-base.md, we’ll have to change:

OLD: {::include sourcecode/abnf/jsonpath_collected_abnf}
NEW: {::include sourcecode/abnf/jsonpath-collected.abnf}

I apologize for this nuisance; we normally don’t do flag day changes, but it seems expedient to not introduce tedious gating mechanisms for this specific change in a quite young tool.

If you are using kramdown-rfc-extract-sourcecode today and see a problem with this flag day change (or any other problem, of course), please comment to the PR [1].

Grüße, Carsten

[1]: https://github.com/cabo/kramdown-rfc/pull/208