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

[Jonathan Gibbons]

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