JDK-8215578 : Remove javadoc support for HTML 4.
  • Type: CSR
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 13
  • Submitted: 2018-12-18
  • Updated: 2020-07-17
  • Resolved: 2019-01-25
Related Reports
CSR :  
JDK-8215577 - Remove javadoc support for HTML 4.
Relates :  
JDK-8194955 - Warn when default HTML version is used
Relates :  
JDK-8182765 - HTML5 must be the default javadoc codegen mode in the near future
Relates :  
JDK-8072945 - Javadoc should generate valid and compliant HTML5 output
Description
Summary
-------

Remove the `-html4` option.

Problem
-------

The world is moving to HTML 5; javadoc has supported HTML 5 since JDK 9, and warned about the use of HTML 4 since JDK 11. It is a maintenance overhead to support both versions, and there is little reason to do so.

Solution
--------

Remove support for HTML 4, and with it the `-html4` option.

The `html5` option will remain, but will become a no-op, since HTML 5 is the only output format used. The command-line help and man page should be updated to note the option is just retained for compatibility and is no longer necessary to be used.

`javac` supports a related option:

````
  --doclint-format {html4,html5}
        Specify the format for documentation comments
````
We should remove `html4` from the set of applicable values, and update the command-line help and man page.


Specification
-------------

The `html4` option for the standard doclet will be removed.

The `html4` value for the `javac` `--doclet-format` option will be removed.

Attached diff of Javac and Javadoc man pages.
Comments
[~darcy] yeah, it looks like we need to pay attention to the man page! Thanks for the quotes.
29-01-2019
[~jjg], the attached patch includes: +++ b/closed/src/jdk.javadoc/share/man/javadoc.md Mon Jan 21 11:47:23 2019 +0530 @@ -489,13 +489,8 @@ > `javadoc -helpfile C:\user\myhelp.html java.awt.` -`-html4` -: Generates HTML 4.0.1 output. If the option is not used, `-html4` is the - default - `-html5` -: Generates HTML 5 output. If the option is not used, `-html4` is the - default. +: Generates HTML 5 output. This option is no longer required. from which I inferred HTML 4.0.1 is the current default. However, perhaps that is a case of the docs and the implementation not being in sync.
29-01-2019
[~darcy] There are 4 features being planned for removal in JDK 13. The intent is to create a single release note detailing all of the removals. To that end, this work is a subtask of an umbrella bug that will have the release note. I guess we could start on the release note for the umbrella bug. Separately, we have been following the less aggressive path that you recommend. We've supported both options for a while, given warnings, changed the default. We are now at the final step in that less aggressive path you talk about! (See the Problem statement in the Description.) I'll cross-link the issue to some of the earlier issues related to the HTML 4/5 transition.
25-01-2019
I'm voting to approve this request conditional on a release note being created for it. Also, a less aggressive position would be to change the default to HTML 5 in one release, still supporting HTML 4 and 5, and then remove HTML 4 support in the following release. I encourage the javadoc team to monitor user reaction to see of such a less aggressive path is more appropriate for transitioning away from HTML 4 support.
25-01-2019