2018/6/4 14:17:47 -0700, Martin Buchholz <marti...@google.com>: > On Mon, Jun 4, 2018 at 2:11 PM, jonathan.gibb...@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