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
Labels
Documentation FeatureRequest FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done. pkgsite

Comments

@audiolion
Copy link

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
@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
Contributor

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 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

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

@dmitshur
Copy link
Contributor

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 The path to resolution is known, but the work has not been done. label Jun 23, 2020
@shaqque
Copy link
Contributor

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."

@shaqque shaqque self-assigned this Jun 26, 2020
@golang golang locked and limited conversation to collaborators Jul 29, 2021
@rsc rsc unassigned shaqque Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FeatureRequest FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done. pkgsite
Projects
None yet
Development

No branches or pull requests

6 participants