Subject: [Rfc-markdown] New kramdown-rfc version 1.1.0 allows replacing reference labels

From: Carsten Bormann <[email-masked]>
Date: Wed, 22 Mar 2017 09:01:44 +0100

I have just pushed kramdown-rfc2629 version 1.1.0.

The major new feature that prompted finally increasing the minor release number is replaceable reference anchors (which then become the labels in the bibliography) for references imported from xml2rfc.ietf.org — you are no longer bound to what the reference file author thought was a good label.

The README.md has this to say about the new feature:

+Since version 1.1, references imported from the [XML2RFC][] databases
+can be supplied with a replacement label (anchor name).  E.g., RFC 793
+could be referenced as `{{!TCP=RFC0793}}, further references then just
+can say `{{TCP}}`; both will get `[TCP]` as the label.  In the
+YAML, the same replacement can be expressed as in the first example:
+
+     normative:
+       TCP: RFC0793
+     informative:
+       SST: DOI.10.1145/1282427.1282421
+
+Notes about this feature:
+
+* At the time of writing, the DOI and IANA repositories are
+  slightly unstable.
+* Thank you, Martin Thomson, for supplying an implementation and
+  insisting this be done.
+* While this feature is now available, you are not forced to use it
+  for everything: readers of documents often benefit from not having
+  to look up references, so continuing to use the draft names and RFC
+  numbers as labels may be the preferrable style in many cases.
+* As a final caveat, renaming anchors does not work in the
+  `stand_alone: no` mode (except for IANA and DOI), as there is no
+  such mechanism in XML entity referencing; exporting to XML while
+  maintaining live references then may require some manual editing to
+  get rid of the custom anchors.

This feature required a bit more code surgery than we usually allow for a release, so doing this in the I-D moratorium might have been a good idea.  Please do run your drafts through this after updating with

	gem update

and let us know about any oddities.

Kudos again to Martin, who not only wrote the initial implementation in a language he is not used to liking but also had to endure my pickiness about this feature and generated many new versions of his pull request in response.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 22 Mar 2017 16:52:28 +0100

> +* At the time of writing, the DOI and IANA repositories are

No longer.  Tony put in some quality time, and we are now all set for the re-opening of the draft submission season...

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 22 Mar 2017 20:24:37 +0100

On 22 Mar 2017, at 09:01, Carsten Bormann <[email-masked]> wrote:
> 
> let us know about any oddities.

One oddity did come up; that oddity may also be considered a bug fix.

In kramdown-rfc 1.0, if you referenced a specific older draft version, e.g.

informative:
  I-D.draft-ietf-core-links-json-05:

that reference received a label (anchor) of

[I-D.ietf-core-links-json]

which led to some confusion (and made it impossible to reference several different versions of a draft in the same document).

With 1.1, the label is now

[I-D.draft-ietf-core-links-json-05]

(Except in `stand_alone: false` mode, oops).

I am happy to consider that changed behavior a bug fix, in particular since you can get the old behavior by being explicit about your desire to confuse:

informative:
  I-D.ietf-core-links-json: I-D.draft-ietf-core-links-json-06

(or {{?I-D.ietf-core-links-json=I-D.draft-ietf-core-links-json-06}} if you prefer that approach.)

Grüße, Carsten

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 23 Mar 2017 09:48:12 +1100

\o/

> On 22 Mar 2017, at 7:01 pm, Carsten Bormann <[email-masked]> wrote:
> 
> _______________________________________________
> Rfc-markdown mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/rfc-markdown

--
Mark Nottingham   https://www.mnot.net/

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Thu, 23 Mar 2017 03:18:43 +0000

This is funny: Wikipedia says that this emoticon means either “Victory” or “Exasperation”. :-)

On 3/22/17, 6:48 PM, "Rfc-markdown on behalf of Mark Nottingham" <[email-masked] on behalf of [email-masked]> wrote:

    \o/

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 23 Mar 2017 14:20:23 +1100

Many use it as a generic "yay!"

> On 23 Mar 2017, at 2:18 pm, HANSEN, TONY L <[email-masked]> wrote:
>