[Rfc-markdown] 1.3.21: Section references (v3)

Carsten Bormann <cabo@tzi.org> Thu, 17 December 2020 13:54 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 9F9873A0AC1 for <rfc-markdown@ietfa.amsl.com>; Thu, 17 Dec 2020 05:54:36 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.597
X-Spam-Status: No, score=-2.597 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, 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 ([]) by localhost (ietfa.amsl.com []) (amavisd-new, port 10024) with ESMTP id HNY6UJoc67cA for <rfc-markdown@ietfa.amsl.com>; Thu, 17 Dec 2020 05:54:32 -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 A139A3A09B5 for <rfc-markdown@ietf.org>; Thu, 17 Dec 2020 05:54:29 -0800 (PST)
Received: from [] (p548dca87.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 4CxYQC6yY2zySR; Thu, 17 Dec 2020 14:54:27 +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: 629906067.470493-f8845287fa24567253707e24d162d1b7
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.\))
Date: Thu, 17 Dec 2020 14:54:27 +0100
Message-Id: <16C9A633-B117-42DB-BD06-C5F442B1546A@tzi.org>
To: rfc-markdown@ietf.org
X-Mailer: Apple Mail (2.3608.
Archived-At: <https://mailarchive.ietf.org/arch/msg/rfc-markdown/DvG3W4pmeApsE52RVnCDs1M6wsY>
Subject: [Rfc-markdown] 1.3.21: Section references (v3)
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, 17 Dec 2020 13:54:42 -0000

1.3.21 supports clickable section references with RFCXMLv3,
i.e., if the --v3 (kdrfc -3) flag is given.

Since there is no existing markdown syntax for that, something had to invented.
In the spirit of markdown, this was supposed to be mostly natural keyboarding.
Of course, clickable section references always were possible using IALs, as in:

{{RFC3986}}{: section="3.1”}

Too much noise.  So why not just say:

{{Section 3.1 of RFC3986}}?

Which is exactly what happened.
RFCXMLv3 supports three styles (“of”, “comma”, and “parens”), and so does kramdown-rfc.

Reminder: this is the usual syntax for a whole-document reference:
* {{RFC8949}}

“of” syntax:
* {{Section 1 of RFC8949}} ➔ Section 1 of [RFC8949]
* {{Section E.5 of RFC8949}} ➔ Appendix E.5 of [RFC8949]

“comma” syntax:
* {{RFC8949, Section E.5}} ➔ [RFC8949], Appendix E.5

“parens” syntax:
* {{RFC8949 (Section E.5)}} ➔ [RFC8949] (Appendix E.5)

There also is a “bare” style, which is usually used only in multi-section references and therefore gets a bit more noisy syntax:

* {{E.5<RFC8949}} ➔ E.5 (which does point to E.5 of RFC 8949)

Kramdown-rfc also includes some basic support for multi-section references (based on the “bare” style above), with limitations:

* {{Sections 1 and E.5 of RFC8949}}
* {{Sections 1, 2, and E.5 of RFC8949}}
* {{RFC8949 (Sections 1 and E.5)}} ➔ Sections 1 and E.5 of [RFC8949]
* {{RFC8949, Sections 1, A, and E.5}} ➔ Sections 1, A, and E.5 of [RFC8949]

Limitations for now:

* Only recognizes “Section”/“Sections" in the reference syntax 
  (even when talking about Sections in the Appendix); could be fixed
* There is an inconsistency in xml2rfc’s appendix reference handling:
  This means that in practice appendix references do not work 
  until xml2rfc is fixed.
* Interactions with the !/? normative/informative signifiers 
  have not been implemented; TODO.

Limitations in multi-section references for now:

* Does not use “appendix” for references to sections in the appendix,
  or form proper English for mixtures of Sections and Appendices
  (But appendix references don’t work right now, anyway); this is a TODO
* Only can do "of” format for multi-section references 
  (recognizes the input syntaxes other forms, but shows them as "of" form); 
  for implementation reasons this may stay a WONTFIX
  (unless people really want that feature)

TLDR: Just write between the double braces what you think, and it is likely that kramdown-rfc can translate that into something useful.

(The fun thing is that this description is longer than the code that implements it :-)

Grüße, Carsten