[rfc-i] changing [RFC1234] references to [RFC1234-XYZ]

Jim Schaad ietf at augustcellars.com
Tue Aug 13 09:22:18 PDT 2019

Are you looking for a string to type in the reference or just the displayed
output?  A method of changing the string displayed between the brackets has
been incorporated into the v3 vocabulary with 

<displayreference target="RFC7951" to="YANG-JSON"/>
<displayreference target="RFC7152" to="JSON"/>

There is not currently an easy way to change the target/anchor pair.


-----Original Message-----
From: rfc-interest <rfc-interest-bounces at rfc-editor.org> On Behalf Of
Michael Richardson
Sent: Tuesday, August 13, 2019 8:54 AM
To: rfc-interest <rfc-interest at rfc-editor.org>
Subject: [rfc-i] changing [RFC1234] references to [RFC1234-XYZ]

A document I am working on has references to both RFC7951 (JSON encoding of
YANG), and RFC7159 (JSON) [now RFC8259 of course].

RFC7951 is an easy typo of RFC7159!

In XML, if I do all my own <references> sections, I could make up anchors
that might help me remember which one I wanted, and make the distinction
more obvious for others. It's one of the xml2rfc FAQs:

But, since we have the include mechanism, and when using kramdown, even that
part can be short-cutted nicely, this would not be a very scalable thing.

Pretty much all non-trivial documents reference a dozen or more RFCs, all by
numbers. I think that some of this can be quite intimidating to reads new to
that area. (Even after 25 years of IETF work, I doubt I can read a SIP or
OSPF document without looking up every single RFCxxxx number).

I wonder if we should consider including some kind of slug into the []

So that [RFC8259] becomes [RFC8259-JSON] and [RFC7296] becomes
That is, do both.  For this to happen I think that we need a few things.

1) a minimum is that the reference.XYZ.files would have to have their
   changed to include the slug.  But that would be annoying to those who
   didn't know the slug, so we really need an alternate anchor2= or
   something which would also be consulted.

2) we'd want to insert the "slug" part into the XML for new documents.
   The datatracker should probably know this on a per-document basis, and
   defaulting it to the WG name is probably a good first approximation.

3) We'd want to be able to reference <xref target="RFC8259-JSON" />, and
   have it find "RFC8259" if there is no slug, possibly warning us if there
   is a slug, and it isn't "JSON".

Maybe none of this is useful to anyone else.

]               Never tell me the odds!                 | ipv6 mesh networks
]   Michael Richardson, Sandelman Software Works        |    IoT architect
]     mcr at sandelman.ca  http://www.sandelman.ca/        |   ruby on rails

More information about the rfc-interest mailing list