<i18n dev> RFR: JDK-8296546: Add @spec tags to API

[Jonathan Gibbons]

On Thu, 10 Nov 2022 11:30:51 GMT, Daniel Fuchs <dfuchs at 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