[Rfc-markdown] new kramdown-rfc2629 feature in 1.5.13

Martin Thomson <mt@lowentropy.net> Fri, 29 October 2021 01:58 UTC

Return-Path: <mt@lowentropy.net>
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 8D6953A08BD for <rfc-markdown@ietfa.amsl.com>; Thu, 28 Oct 2021 18:58:29 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.101
X-Spam-Level:
X-Spam-Status: No, score=-2.101 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_MSPIKE_H2=-0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=lowentropy.net header.b=irUmlZ1q; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=GhgCxg2B
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 YVpJXDe4PslI for <rfc-markdown@ietfa.amsl.com>; Thu, 28 Oct 2021 18:58:26 -0700 (PDT)
Received: from wout1-smtp.messagingengine.com (wout1-smtp.messagingengine.com [64.147.123.24]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 08AA03A08B8 for <rfc-markdown@ietf.org>; Thu, 28 Oct 2021 18:58:26 -0700 (PDT)
Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailout.west.internal (Postfix) with ESMTP id AD5323201CCC for <rfc-markdown@ietf.org>; Thu, 28 Oct 2021 21:58:23 -0400 (EDT)
Received: from imap41 ([10.202.2.91]) by compute5.internal (MEProxy); Thu, 28 Oct 2021 21:58:23 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lowentropy.net; h=mime-version:message-id:date:from:to:subject:content-type; s= fm3; bh=+X70MeYXrtS00gI44vbhOQKBBqQ7ZiSNSsdVs1t6z0A=; b=irUmlZ1q LExUqABjx9JYs9ZwQHRwvuc0EqPoEFC+Rfb68En7qZ3dB6BrlaD0BeZKQKqbk9vE GrLpJkMw/hwsNOj4gpz0SucPrl6/MTUh10zVmozkoHed6Y3oOL37oWjl204yXjBd ppDqgtkoU/Y1QE9bxSPP/dvHQw3ZbTVEaAnuuGEhF25ZOnpCXxZ3n84/60D7tDdV n6b7Z2yqdO81tQSHROQ/XN2JzmUlJgtzOo2mQQyul17HpwcSBELYYBN1JxJ5cdJB Js+UwzmjtqsmU2UYRThaJSZRNztKr+lIcHuKcq1M3qmc/8d5Xb/CXxVI08SRTCbz a6nOf+kVQbnU5g==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-type:date:from:message-id :mime-version:subject:to:x-me-proxy:x-me-proxy:x-me-sender :x-me-sender:x-sasl-enc; s=fm1; bh=+X70MeYXrtS00gI44vbhOQKBBqQ7Z iSNSsdVs1t6z0A=; b=GhgCxg2BHG8IwUQIyk3Bz5PCliCHgG8ywZxEajmEi+v8w aWBt4RlrarXZdQy+V+zwZMx4bNS615Z0xwuWGbOCXx4q0CU60MNOEpspE7zEOAMu /KSr3mSjOKnf86Tmeh8nzTl5XCSZ3uzMr//wpq/mG6/JWwYyJEecFSu+P8WZJetg wdUO5thK4UaGkjlH1izBnJenxM6/fEoJfUOX1iTabrYu88Hfni57IBPe0fKpAS3v wAxj42g/ooehXzrIOv1p03XwqVoY1H7CrO/c5uMls8qkpoAVnqInVZckAZMGpEc9 kjT5XwVYCv2cgbvqxjuQ3l4qE5cWvCKBTjjEkhCZA==
X-ME-Sender: <xms:P1V7YdLiLswCrsNDeN9lCyYLSz8cJkr7VD2Vgpa44Hecd3NE10FJOg> <xme:P1V7YZJbTY2n9-TDfGckjRsjwrc-snDTerOj50-IjZPVXdl7W4by_FMAGn8ox-f2Y e7bdCEzhxLLXlkYWFY>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvtddrvdeggedggeelucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefofgggkfffhffvufgtsehttdertd erredtnecuhfhrohhmpedfofgrrhhtihhnucfvhhhomhhsohhnfdcuoehmtheslhhofigv nhhtrhhophihrdhnvghtqeenucggtffrrghtthgvrhhnpeevgfdutdfgjeefudeuheekhe ekudeugeehfeegveekkeegleevveffueduffehheenucevlhhushhtvghrufhiiigvpedt necurfgrrhgrmhepmhgrihhlfhhrohhmpehmtheslhhofigvnhhtrhhophihrdhnvght
X-ME-Proxy: <xmx:P1V7YVuBLagRXasRBUFZQcT2xYPWnEBtBuMIrsDnf2rRus4ICshAdA> <xmx:P1V7YeZBX-zEV47MPcXcoBnEoskw4iTSHBB96V3EIO-PuLUlcR-nxg> <xmx:P1V7YUZ3D6pqWQZKYf1oPmCAQlShbfejllgymtnR6zNfoqdJjaKzhA> <xmx:P1V7YdkVljNNugV1GBS5lD7v_uFCHMShQ23GQr9TEYhmk6GKa9Mr9w>
Received: by mailuser.nyi.internal (Postfix, from userid 501) id F3BF53C0146; Thu, 28 Oct 2021 21:58:22 -0400 (EDT)
X-Mailer: MessagingEngine.com Webmail Interface
User-Agent: Cyrus-JMAP/3.5.0-alpha0-1369-gd055fb5e7c-fm-20211018.002-gd055fb5e
Mime-Version: 1.0
Message-Id: <a1849958-8325-4474-9578-ce1f093cc49c@www.fastmail.com>
Date: Fri, 29 Oct 2021 12:58:03 +1100
From: Martin Thomson <mt@lowentropy.net>
To: rfc-markdown@ietf.org
Content-Type: text/plain
Archived-At: <https://mailarchive.ietf.org/arch/msg/rfc-markdown/ZyKoGmIfK0oIfe_HrRpA2NcOTlk>
Subject: [Rfc-markdown] new kramdown-rfc2629 feature in 1.5.13
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: Fri, 29 Oct 2021 01:58:30 -0000

Hey folks,

With Carsten's help I've added a new feature to kramdown-rfc2629 that supports auto-linking of key concepts.

If you have a special term, it is already possible to (ab)use kramdown's "abbreviations" syntax to have that term indexed.  For example:

```
*[IMPORTANT CONCEPT]:
```

This turns all uses of the string "IMPORTANT CONCEPT" in the text to be marked with an <iref> element.  The result is that all instances of the concept are put into your index for easy reference.

The feature that I've added also turns those uses into links like so:

```
*[KEYWORD]: #
```

All instances of KEYWORD then become:

```
<xref target="KEYWORD" format="none">KEYWORD</xref><iref item="KEYWORD"/>
```

If you have an anchor in the document, all instances of "KEYWORD" will now be linked to that anchor.  This uses the format="none" decoration on links so that hyperlinks will be added to HTML, but you won't pollute your document with " (Section 4.7)" throughout.

You can control the target of the link by targeting an anchor as follows:

```
*[KEYWORD]: #sec-keyword
```

Note that the keyword will still be indexed, but you can control that indexing using the existing syntax for abbreviations and indexing.
```
<!-- "CONCEPT A" is indexed as item="idea" subitem="alpha" -->
*[CONCEPT A]: #concept-a (((idea,alpha)))
<!-- "IMPORTANT" is indexed as item="important" subitem="note" -->
*[IMPORTANT]: #sec-important note
```

These "abbreviation" instructions can be added to a new line anywhere in the body of a document, so you can put them next to their definition or at the end as you see fit.