RFR: 8253117: Replace HTML tables in javadoc summaries with CSS grid elements

[Hannes Wallnöfer]

On Fri, 25 Sep 2020 17:52:57 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This changes the output of the `html.markup.Table` class to plain `div` elements, using CSS Grid Layout to display them
>> in a tabular format.
>> I decided against renaming the Table class and related identifiers even though it does no longer emit an HTML <table>
>> element. I admit this results in a somewhat odd mismatch in a few places, but on the other hand the generated HTML
>> still represents tabular data. Also, the changes are much easier to understand and review this way. I'm open to
>> renaming things if we can find a better terminology.  I simplified the existing code in quite a few places:
>>  - Removed the setters for table tab ids and the browser tab script. The ids are now derived from the main table id which
>>    makes them unique even with multiple tables per page (provided the tables have different ids), and the browser script
>>    will always work for the used ids.
>>  
>>  - Removed the complex tab selection scheme based on bitwise operations and replaced it with one CSS class per tab. The
>>    elements making up a table row will have a CSS class for each tab they belong to. The CSS class names are derived from
>>    the table id as well.
>> 
>>  - Reduced per usage style classes for summary tables, thereby simplifying the style sheet. Instead of having a CSS class
>>    for each useage of a table (e.g. `member-summary`, `type-summary` etc) there is only one common CSS class for summary
>>    tables as well as one specifying the number of columns to use, e.g. `two-column-summary`, `three-column-summary` etc.
>> 
>> The rendering and spacing of the tables should be the same as previously. There are a few exceptions:
>> 
>>  - The style sheet has additional media queries to switch the layout of tables when the width of the browser window
>>    becomes very narrow. This happens at different thresholds for tables with two, three, or four columns. Note that these
>>    theresholds are based on heuristics, it is what I have found to work well under most circumstances.
>> 
>>  - The new grid never grow larger than the width available in the browser. When a table cell becomes too narrow to contain
>>    its content, the cell becomes scrollable. This happens very rarely and is not too disturbing IMO.
>> 
>>  - Spacing of columns is usually a bit different than previously. Grids offers very complex layout options, and the
>>    setting I came to use partitions space depending on the width of cell contents.
>> 
>> Here are the API docs for java.base rendered with these changes:
>> http://cr.openjdk.java.net/~hannesw/8253117/api.00/
>> 
>> Here are the API docs with these changes and additionally the patch for JDK-8248566 (mobile browser optimizations)
>> applied: http://cr.openjdk.java.net/~hannesw/8253117/api.00.mobile/
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 459:
> 
>> 457: }
>> 458: .provides-summary .col-first, .provides-summary .col-last, .provides-summary .col-first,
>> 459: .provides-summary .col-last {
> 
> Hmm, I thought the `*-summary` names were going away?

Many of these `*-summary` classes are still used in other parts, e.g. as first argument to
`SubHolderWriter.addSummary(...)`. That said, a few of these are indeed unused and can be removed. This will be
included in next changeset.

-------------

PR: https://git.openjdk.java.net/jdk/pull/253