Summary

Provide a new option for the standard javadoc doclet to allow the user to provide additional stylesheets to be included in the generated documentation.

Problem

The generated documentation contains content that is either generated by the standard doclet, or which comes from user-provided documentation comments. Both sets of contents may use CSS styles, but currently there is only support for a single stylesheet. This makes it difficult to just specify styles for use in the user-provided documentation comments, since any user-provided stylesheet must currently contain definitions for all the styles used in the content generated by the doclet.

Javadoc provides a default stylesheet for the generated documentation. Using the existing command-line option -stylesheetfile, the default stylesheet can be replaced with a used-defined stylesheet file, which should contain definitions for all required styles. However, there is no way to specify additional stylesheets to just provide definitions for styles used in user-provided documentation comments.

Solution

Add a new command-line option to the standard doclet to provide additional stylesheets to be included in the generated documentation. The doclet will copy the specified stylesheet files to the output directory and add HTML elements pointing to the stylesheets to all appropriate generated pages.

The existing -stylesheetfile option will have an alias --main-stylesheet to help distinguish the main stylesheet from any additional stylesheets.

Note: There is no significant consensus on whether "stylesheet" is one word or two. There are significant precedents for each form. This proposal goes with the one-word form, following the historical usage in the Javadoc Tool Reference Guide.

Specification

--add-stylesheet <path>

The option can be used one or more times to specify additional stylesheets to be included in the documentation.

Javadoc command-line example:

javadoc --add-stylesheet new_stylesheet_1.css --add-stylesheet new_stylesheet_2.css pkg_foo

-stylesheetfile <path> or --main-stylesheet <path>

In addition, the existing -stylesheetfile option will have an alias --main-stylesheet, with --main-stylesheet being the preferred form.

Javadoc command-line example:

javadoc --main-stylesheet main_stylesheet.css pkg_foo