RFR: 8294074: Make other specs more discoverable from the API docs [v3]

[John R Rose]

On Wed, 30 Jul 2025 19:55:18 GMT, Mark Reinhold <mr at openjdk.org> wrote:

>> Minimally, I would not refer to the narrative specs which are part of the platform as "Related documents" since that makes them sound weakly advisory/informational.  Perhaps something like "[Additional specifications][../specs/index.html] for the Java language...".
>> 
>> Also, if you're going to provide a link to the narrative specs, I'd also consider adding a reference to the external spec page (https://download.java.net/java/early_access/jdk25/docs/api/external-specs.html).
>
> The first word after “related documents” is “specify,” which doesn’t sound advisory to me.
> 
> I don’t think the external spec page is of sufficiently broad interest to highlight it here.
> 
> (To imply that our tool man pages are “specifications” is a bit much, but making that distinction isn’t worth the trouble here.)

TIL about that external spec page. Thanks!

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/26547#discussion_r2246108261