Daniel et al -
Please avoid using ietf.org as the cite location for RFCs
The preferred cite for RFCs is generally via
www.rfc-editor.org/info/rfc<number> - that will get you to the info
page, but with links to pdf, html, and a clean .txt.
Cf https://www.rfc-editor.org/info/rfc4180 - "Cite this RFC" -
Shafranovich, Y., "Common Format and MIME Type for Comma-Separated Values (CSV)
Files", RFC 4180, DOI 10.17487/RFC4180, October
2005,<https://www.rfc-editor.org/info/rfc4180>.
Note that the most stable cite might be the DOI cite, but the above is
going to be fairly useful for a long time to come.
Mike
On 11/10/2022 6:34 AM, Daniel Fuchs wrote:
On Thu, 10 Nov 2022 01:10:13 GMT, Jonathan Gibbons<j...@openjdk.org> wrote:
Please review a "somewhat automated" change to insert `@spec` tags into doc
comments, as appropriate, to leverage the recent new javadoc feature to generate a new
page listing the references to all external specifications listed in the `@spec` tags.
"Somewhat automated" means that I wrote and used a temporary utility to scan doc comments
looking for HTML links to selected sites, such as `ietf.org`, `unicode.org`, `w3.org`. These links
may be in the main description of a doc comment, or in `@see` tags. For each link, the URL is
examined, and "normalized", and inserted into the doc comment with a new `@spec` tag,
giving the link and tile for the spec.
"Normalized" means...
* Use `https:` where possible (includes pretty much all cases)
* Use a single consistent host name for all URLs coming from the same spec site
(i.e. don't use different aliases for the same site)
* Point to the root page of a multi-page spec
* Use a consistent form of the spec, preferring HTML over plain text where both
are available (this mostly applies to IETF specs)
In addition, a "standard" title is determined for all specs, determined either
from the content of the (main) spec page or from site index pages.
The net effect is (or should be) that **all** the changes are to just **add**
new `@spec` tags, based on the links found in each doc comment. There should be
no other changes to the doc comments, or to the implementation of any classes
and interfaces.
That being said, the utility I wrote does have additional abilities, to update the links
that it finds (e.g. changing to use `https:` etc,) but those features are _not_ being
used here, but could be used in followup PRs if component teams so desired. I did notice
while working on this overall feature that many of our links do point to
"outdated" pages, some with eye-catching notices declaring that the spec has
been superseded. Determining how, when and where to update such links is beyond the scope
of this PR.
Going forward, it is to be hoped that component teams will maintain the
underlying links, and the URLs in `@spec` tags, such that if references to
external specifications are updated, this will include updating the `@spec`
tags.
To see the effect of all these new `@spec` tags,
seehttp://cr.openjdk.java.net/~jjg/8296546/api.00/
In particular, see the new [External
Specifications](http://cr.openjdk.java.net/~jjg/8296546/api.00/external-specs.html)
page, which you can also find via the new link near the top of the
[Index](http://cr.openjdk.java.net/~jjg/8296546/api.00/index-files/index-1.html)
pages.
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.
-------------
PR:https://git.openjdk.org/jdk/pull/11073
