[Rfc-markdown] 1.2.12: use ?anchor= feature for bibxml with stand_alone: false as well

Carsten Bormann <cabo@tzi.org> Fri, 17 May 2019 20:14 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 D644D12016F for <rfc-markdown@ietfa.amsl.com>; Fri, 17 May 2019 13:14:55 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.2
X-Spam-Level:
X-Spam-Status: No, score=-4.2 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3] 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 GxkDLraI6ouq for <rfc-markdown@ietfa.amsl.com>; Fri, 17 May 2019 13:14:53 -0700 (PDT)
Received: from smtp.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 AC1B412021B for <rfc-markdown@ietf.org>; Fri, 17 May 2019 13:14:53 -0700 (PDT)
Received: from [192.168.217.106] (p54A6CC75.dip0.t-ipconnect.de [84.166.204.117]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.uni-bremen.de (Postfix) with ESMTPSA id 455KJq54GNz108y; Fri, 17 May 2019 22:14:51 +0200 (CEST)
From: Carsten Bormann <cabo@tzi.org>
Content-Type: text/plain; charset=utf-8
X-Mao-Original-Outgoing-Id: 579816888.88622-d665473f90b78196a795d1ea6d424b48
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (Mac OS X Mail 11.5 \(3445.9.1\))
Date: Fri, 17 May 2019 22:14:51 +0200
Message-Id: <7E962765-D743-42C9-92FB-B2DC979FBE4E@tzi.org>
To: RFC Markdown <rfc-markdown@ietf.org>
X-Mailer: Apple Mail (2.3445.9.1)
Archived-At: <https://mailarchive.ietf.org/arch/msg/rfc-markdown/LOMxJNannb1DQ6iejwTB0B-Cy5A>
Subject: [Rfc-markdown] 1.2.12: use ?anchor= feature for bibxml with stand_alone: false as well
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, 17 May 2019 20:14:56 -0000

I just pushed version 1.2.12 of kramdown-rfc2629 that can use reference anchor renaming for `stand_alone: false` as well.

Update as usual:

	gem update

If you are using `stand_alone: true` as I’d recommend, you can stop reading here.

Grüße, Carsten

.oOo.

Recap:  With stand_alone: true (the setting you will want to use), kramdown-rfc embeds bibxml entries into the xml, so xml2rfc does not have to do any lookup.  This allows kramdown-rfc to freely change the labels (anchors) of those references.  Label replacement is particularly useful for DOI references, as their default labels are unwieldy.

With 1.2.12, a similar feature is now available for documents using `stand_alone: false`, by making use of the server side renaming available for DOI and IANA references (bibxml7 and bibxml8) only.

For stand_alone: false, replacement labels of the form

informative:
  foo: DOI.10.1145_1282427.1282421

now allow you to reference the document as {{foo}}, which will also be the label used in the references section(*).  (That was already possible for `stand_alone: true` before.)   The server-side mechanics needed for this only works for DOI and IANA references, though (no such limitation exists for `stand_alone: true`, where it is becoming popular to do things like

informative:
  OSCORE: I-D.ietf-core-object-security

to change the unwieldy I-D label to the readable reference label OSCORE — as a side effect, it is then a local change to put in the RFC number instead, once that is known:

informative:
  OSCORE: RFCabcd

).

This is a slightly user-visible change, because the functionality now applies in a wider set of cases, but also because of a limitation in the way in which xml2rfc performs reference caching:  You may need to clean out cached references in ~/.cache/xml2rfc if you introduce a replacement label or change it.

By the way, I have not repaired the slight inconsistency that 

informative:
  DOI.10.1145_1282427.1282421:

leads to a label called {{DOI.10.1145_1282427.1282421}} for `stand_alone: true` while the server-supplied label is {{DOI_10.1145_1282427.1282421}} for `stand_alone: false` — fixing that might invalidate too many documents, and people will move to replacement labels on these kinds of references anyway.  If that hurts, fudge it by being specific on the form you want:

informative:
  DOI.10.1145_1282427.1282421: DOI.10.1145_1282427.1282421


(*) RFC 7322 does not say so outright, but it seems the RFC editor prefers upper case for symbolic citation tags, except where the tag includes (parts of) a lower case document name, so you may want to do:

informative:
  FOO: DOI.10.1145_1282427.1282421