x/pkgsite: automatically link RFCs in package documentation

[audiolion]

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/audiolion/ipip?tab=doc

Compared to:

https://godoc.org/github.com/audiolion/ipip

godoc.org would automatically link to RFCs

What did you expect to see?

RFCs automatically linked

What did you see instead?

RFCs were not automatically linked

This was a really nice feature of godoc!

[FiloSottile]

I'd love this! BTW, the new official home of RFC is rfc-editor.org, with links like

https://www.rfc-editor.org/rfc/rfc5536.html#section-3.1.3

[gopherbot]

Change https://golang.org/cl/239497 mentions this issue: x/pkgsite: link RFCs in package documentation.

[dmitshur]

In https://go-review.googlesource.com/c/pkgsite/+/239497/2#message-28fcd23ae3ef481ce5643c7439d214e06f36f313, @shaqque asked:

Currently does not support RFCxxxx (i.e. without space/s between "RFC" and the number). Should we also consider linking that?

I think we want to strike a good balance of being opinionated, so that it incentivizes people to write higher quality, consistent documentation, but not too opinionated where we are unnecessarily strict in a way that isn't helpful to humans.

The Go tree is heavily consistent at preferring including a space. There are 700 matches for [\s]RFC[\s][\d] (with space), and 55 for [\s]RFC[\d] (no space), many of which are references to time package's RFC3339 and such.

In my opinion, based on data I see now, it would be safe to start with requiring a space, but if we learn over time that it would be net positive to also accept the no-space version, we can add that later.

@FiloSottile may know if there's a spec that requires a space to be present or provides other guidance on what syntax to match precisely.

[shaqque]

This appears to be documented in RFC 7322, Section 3.5 which states:

A citation/reference tag must not contain spaces.

Example: "[RFC2119]" rather than "[RFC 2119]"

However, the proper textual naming of an RFC contains a space.

Example: "See RFC 2119 [BCP14] for more information."