On Thu, 10 Nov 2022 11:30:51 GMT, Daniel Fuchs <dfu...@openjdk.org> wrote:
> Hi Jon, > > When referencing an RFC, it might be good to keep the RFC number in the text > link. For instance I see that java.net.URL now has this: > > http://cr.openjdk.java.net/~jjg/8296546/api.00/java.base/java/net/URL.html > > External Specifications [Format for Literal IPv6 Addresses in > URL's](https://www.ietf.org/rfc/rfc2732.html), [Uniform Resource Identifier > (URI): Generic Syntax](https://www.ietf.org/rfc/rfc3986.html), [Uniform > Resource Identifiers (URI): Generic > Syntax](https://www.ietf.org/rfc/rfc2396.html) > > You will see that two of the RFC links have the same text but link to > different RFCs, which I am finding confusing. Also I do hope it's clear that > if a specification is referenced it doesn't mean it's being implemented. On keeping RFC in the title, I'll go with the team preference. I note that not all spec authorities have such a well-defined naming/numbering scheme, so it does make the summary page a bit inconsistent. Also, the entries under "R" dominate the list, which may not be what you want. On the same text but linking to different RFCs: that's tantamount to a bug somewhere. The spec for `@spec` dictates that the URLs and titles should be in 1-1 correspondence, and this is supposed to be enforced in the docket. In other words, specs should have unique titles, and any title should only be used for one spec. ------------- PR: https://git.openjdk.org/jdk/pull/11073
