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

[Jonathan Gibbons]

JDK-8196202 [1] introduced a change to the javadoc tool (and because of 
that, to the Java SE API documentation) such that frames are not 
generated by default.

This has had a deliberate but somewhat unexpected consequence on the 
Java SE API docs, of getting "404: Not found" on URLs that explicitly 
referenced the .../api/overview-summary.html page.

Here is what happened:

The issue is that previously there were two pages:

  * index.html (contained the frame definitions)
  * overview-summary.html (contained the content for the main top-level
    user-visible page)

Now that we are not generating frames by default, we only need one 
page.  The tool is generating the content for the main top-level 
user-visible page in index.html, and there is no need for 
overview-summary.html page, which is therefore not generated.

This behavior has been the behavior since the javadoc option --no-frames 
was added a year ago. In other words, the recent change [2]  was just to 
flip the default, not to substantially change the behavior of the 
--frames and --no-frames options.

@@ -197,13 +197,13 @@
       */
      public boolean createoverview = false;
  
      /**
       * Specifies whether or not frames should be generated.
-     * Defaults to true; can be set by --frames; can be set to false by --no-frames; last one wins.
+     * Defaults to false; can be set to true by --frames; can be set to false by --no-frames; last one wins.
       */
-    public boolean frames = true;
+    public boolean frames = false;
  
      /**
       * This is the HTML version of the generated pages.
       * The default value is determined later.
       */


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.


-- Jon



[1] https://bugs.openjdk.java.net/browse/JDK-8196202
[2] http://cr.openjdk.java.net/~jjg/8196202/webrev.00/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180604/36fdd482/attachment.html>