RFR: [Updated] Update tables in java.base to be HTML5-friendly.

[Kumar Srinivasan]

Hi Jon,

I looked at the stylesheet can the descriptive comments for each of the
classes be moved closer to the class itself, ie. just before the 
definition  ?

Kumar

> This is an updated review for the changes to improve tables in java.base.
>
> The changes incorporate earlier review feedback, and also address a 
> problem that was discovered with nested tables.
>
> The summary of the set of changes since the previous round is:
>
> * A new style class is added for borderless tables, to be used in 
> preference to a table tag with no class.
>
> * The style classes are now named:
>         borderless
>         plain
>         striped
>     The longer form using a suffix `-table` was considered, but 
> generally, there should not be so many style classes that such a level 
> of discrimination is needed. The names `borderless` and `striped` are 
> most likely to only apply to tables anyway, and `plain` could 
> reasonably be used for other elements without conflict.
>
> * Comments are added to the stylesheet regarding these new classes, as 
> a placeholder until a better specification for the styles in these 
> stylesheets is created.
>
> * Within java.base, all uses of the `altrows` class have been updated 
> to use `striped`, and tables with no class attribute have been changed 
> to explicitly use `borderless`.
>
>
> Webrevs:
>
> langtools (the stylesheet):
> http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev.01/
>
> jdk (changes to java.base):
> http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev.01/
>
> API showing the combined effect of these cahnges:
> http://cr.openjdk.java.net/~jjg/8179479-8179592/api.01/java.base-summary.html 
>
>
>
> -- Jon
>
>
>
>
> On 05/03/2017 03:06 PM, Jonathan Gibbons wrote:
>> This is a review request for two co-dependent fixes.
>>
>> JDK-8179592: Update tables in java.base to be HTML 5-friendly.
>> JDK-8179479: Add new styles to enable HTML 5 tables
>>
>> In doc comments, some of the HTML 4.01 attributes for tables are no 
>> longer available in HTML 5, and CSS should be used instead.
>> To this end, some updates have been made to the main/default 
>> stylesheet used by javadoc, to define two new CSS classes for tables.
>>
>> The new classes are:
>>     <table class="plain">
>>     Just puts plain borders around each cell, with no background 
>> coloring.
>>
>>     <table class="altrows">
>>     Horizontal borders are not used between cells in the table body; 
>> instead, alternating backgrounds are used to help distinguish the 
>> separate rows.
>>
>> In addition, there is still the default
>>     <table>
>>     No borders.
>>
>> These styles are in the langtools webrev, here:
>> http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev/
>>
>> The changes to the doc comments in java.base are in the jdk webrev, 
>> here:
>> http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev/
>>
>> summary vs. <caption>
>>
>>    The ARIA recommendations are to use the summary attribute or 
>> <caption> tag ... but the summary attribute is no longer allowed in 
>> HTML 5.  In general, the text that has been provided for a summary is 
>> not suitable for direct use as a caption. The temporary workaround is 
>> to use a caption that is not displayed. In time, the appropriate API 
>> owners should update the use of these undisplayed table captions, to 
>> modify the text of the caption and make the caption displayed (by 
>> removing style="display:none").
>>
>> Doc comments were changed in files in the following packages:
>>
>> java.io
>> java.lang
>> java.lang.invoke
>> java.lang.reflect
>> java.math
>> java.net
>> java.nio.channels
>> java.nio.charset
>> java.nio.file
>> java.nio.file.attribute
>> java.nio.file.spi
>> java.security
>> java.security.cert
>> java.text
>> java.time.chrono
>> java.time.format
>> java.time.temporal
>> java.util
>> java.util.concurrent
>> java.util.regex
>> java.util.spi
>> javax.net.ssl
>>
>> The intent is that the only changes in this webrev are to the HTML 5 
>> markup. There should be no significant changes to the text in any doc 
>> comment.
>>
>> The decision to add the styles to the default stylesheet at this late 
>> stage in the release is not taken lightly, and is seen as a temporary 
>> measure. JDK-8177283 is a wishlist enhancement for updates to javadoc 
>> support of stylesheets, which includes the desire to move 
>> JDK-specific styles to a JDK-specific stylesheet.
>>
>> This review is primarily about continuing the ongoing effort to make 
>> our docs be HTML 5 compliant. I would prefer not to get into extended 
>> discussions about which style class to use for each table, and what 
>> the exact definition of the styleclasses should be at this time.  But 
>> appropriate review feedback is obviously welcome.
>>
>> -- Jon
>