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

Michael Richardson mcr+ietf at sandelman.ca
Tue Aug 13 08:53:46 PDT 2019


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:
    https://xml2rfc.tools.ietf.org/xml2rfcFAQ.html#anchor13

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 []
reference.

So that [RFC8259] becomes [RFC8259-JSON] and [RFC7296] becomes [RFC7296-IKEv2].
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 anchor=
   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    [


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 487 bytes
Desc: not available
URL: <http://www.rfc-editor.org/pipermail/rfc-interest/attachments/20190813/079d94d4/attachment.asc>


More information about the rfc-interest mailing list