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

[Martin Buchholz]

On Mon, Jun 4, 2018 at 2:11 PM, Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> 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.
>

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.  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).
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180604/1914ca92/attachment.html>