[Rfc-markdown] 1.7.2: Handle section references into referencegroups

Carsten Bormann <cabo@tzi.org> Sat, 28 October 2023 19:50 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 090F3C14F726 for <rfc-markdown@ietfa.amsl.com>; Sat, 28 Oct 2023 12:50:51 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.898
X-Spam-Level:
X-Spam-Status: No, score=-1.898 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_ZEN_BLOCKED_OPENDNS=0.001, SPF_HELO_NONE=0.001, T_SCC_BODY_TEXT_LINE=-0.01, T_SPF_TEMPERROR=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 uUOUPFvBO8TD for <rfc-markdown@ietfa.amsl.com>; Sat, 28 Oct 2023 12:50:44 -0700 (PDT)
Received: from smtp.zfn.uni-bremen.de (smtp.zfn.uni-bremen.de [134.102.50.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 BE577C14F738 for <rfc-markdown@ietf.org>; Sat, 28 Oct 2023 12:50:42 -0700 (PDT)
Received: from eduroam-pool10-182.wlan.uni-bremen.de (eduroam-pool10-182.wlan.uni-bremen.de [134.102.90.181]) (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 4SHqrw1q7jzDCgR; Sat, 28 Oct 2023 21:50:40 +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: 720215436.764091-957472ecd626559fab2ba12bfa887399
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.120.23.2.7\))
Date: Sat, 28 Oct 2023 21:50:36 +0200
Message-Id: <DE3DA412-FB62-4AF2-9C01-1B2F9BD9A8F6@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/XZQ5f7YHQJ58e7sUfGHBWJ14xe8>
Subject: [Rfc-markdown] 1.7.2: Handle section references into referencegroups
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: Sat, 28 Oct 2023 19:50:51 -0000

Up to now, it was really hard to reference into a referencegroup (STD
or BCP reference), as that reference could possibly contain multiple
RFCs, and one would need to be explicit which one was meant with the
section reference.

For RFC 9485, the RPC devised a way to express in RFCXML section
references into RFCs that are in reference groups.  
This convention is now supported by kramdown-rfc.

New syntax: RFC8949@STD94
(Single RFC @ Reference Group)

This can be used for section references:

See {{Section 10 of RFC8996@BCP195}}.
See {{Section 10 ("Security Considerations") and 11 ("Privacy Considerations") of RFC8996@BCP195}}.

Nicknames (-xxx) and norm/inform flags only work to the right side of an @:

See {{Appendix D of RFC8949@!STD94}}.
See {{Appendix D of RFC8949@-cbor}}.

The left hand side of an @ MUST be an RFC number; breakage otherwise.
(Indirection would be great for the left hand side; 
this is for further study.)

For completeness, the @ syntax somewhat redundantly also works for
non-section references into reference groups:

See {{RFC8949@?STD94}}.
See {{RFC8949@STD94}}.

As usual, to get 1.7.2:

  gem update kramdown-rfc

(with the same options you used for installing).

Enjoy!

Grüße, Carsten