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

Paul Kyzivat pkyzivat at alum.mit.edu
Tue Aug 13 09:23:32 PDT 2019


On 8/13/19 11:53 AM, Michael Richardson wrote:
> 
> 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".

I would much prefer to have the visible anchor in the text be [JSON] 
rather than [[RFC8259-JSON].

I think the key here is to decouple the visible anchor from the target 
used for reference in the xml.

But if that was all, then every document that uses include for 
references would be forced to use the anchor used when the reference 
file is created. That might not always be desirable. Ideally I would 
like a way to include the definition of a reference but override the 
visible anchor.

	Thanks,
	Paul


More information about the rfc-interest mailing list