Change in generated files for SE API docs, caused by change to not generate frames

[mark.reinhold at oracle.com]

2018/6/4 14:17:47 -0700, Martin Buchholz <martinrb at google.com>:
> On Mon, Jun 4, 2018 at 2:11 PM, jonathan.gibbons at oracle.com wrote:
>> ...
>> 
>> So, what are our options.
>> 
>> 0.  Do nothing.  People, and search engines, will learn to use a URL
>> ending in "api/" or "api/index.html"
>> 
>> 1. Back out the change.  This is undesirable, because the plan is to
>> eventually eliminate all support for frames, and this change was one step
>> in that sequence.
>> 
>> 2. Without backing out the change to the tool, we could reverse the effect
>> of the change in the Java SE API documentation, by specifying the use of
>> the --frames options to generate the Java SE API docs. But like #1, this is
>> undesirable because of the plan to remove support for frames.
>> 
>> 3. Generate overview-summary.html instead of index.html.   This will break
>> folk that think that api/index.html is the top level file.
>> 
>> 4. Generate overview-summary.html instead of index.html, and generate
>> index.html with a redirect to overview-summary.html
>> 
>> 5. Leave the current behavior, but add back overview-summary.html as a
>> redirect to index.html.
>> 
>> Long term, of the two names, index.html is a better default for the top
>> level page than overview-summary.html. This suggests that the top two
>> choices are option #0 and option #5, with #5 providing some minor
>> short-term relief for folk who expect to see overview-summary.html.

#5 does seem the best option here.

> I completely agree with your analysis.  The reason I (and presumably many
> others) hard-coded overview-summary.html into my URLs is that I was trained
> by the javadoc tool.  E.g. if I visit
> https://docs.oracle.com/javase/10/docs/api/ today it gets "corrected" in
> the address bar of my browser to
> https://docs.oracle.com/javase/10/docs/api/overview-summary.html and it's
> natural to copy-paste or bookmark that URL.

Naturally.  (For 10, and I assume earlier releases, that “correction” is
helpfully made by a snippet of Javascript in index.html.)

>                                              So overview-summary.html is a
> public interface, not an implementation detail (even if that was the
> original intent).  The jjava se javadocs are important enough that I would
> probably do #5 for 5 years or so, during which time you can train people by
> "correcting" overview-summary.html back to index.html or naked .../api/
> whatever you think should be the "canonical" URL.  I don't know much about
> search engines (!) but maybe there's metadata to tell search engines what
> the canonical URL is (or maybe simply redirects are interpreted that way).

Indeed, there is: https://en.wikipedia.org/wiki/Canonical_link_element .

- Mark