Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: automatically link RFCs in package documentation #38056

Closed
audiolion opened this issue Mar 25, 2020 · 4 comments
Closed

x/pkgsite: automatically link RFCs in package documentation #38056

audiolion opened this issue Mar 25, 2020 · 4 comments

Comments

@audiolion
Copy link

@audiolion audiolion commented Mar 25, 2020

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!

@gopherbot gopherbot added this to the Unreleased milestone Mar 25, 2020
@gopherbot gopherbot added the pkgsite label Mar 25, 2020
@dmitshur dmitshur changed the title go.dev: RFCs are not automatically linked go.dev: automatically link RFCs in package documentation Mar 25, 2020
@FiloSottile
Copy link
Member

@FiloSottile FiloSottile commented Apr 28, 2020

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

@julieqiu julieqiu added help wanted and removed Documentation labels Jun 15, 2020
@julieqiu julieqiu changed the title go.dev: automatically link RFCs in package documentation x/pkgsite: automatically link RFCs in package documentation Jun 15, 2020
@gopherbot
Copy link

@gopherbot gopherbot commented Jun 23, 2020

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

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Jun 23, 2020

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.

@dmitshur dmitshur added the NeedsFix label Jun 23, 2020
@shaqque
Copy link
Contributor

@shaqque shaqque commented Jun 23, 2020

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."
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants