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

[Jonathan Gibbons]

Kumar,

The nature of CSS is such that there is generally no one single definition.

The descriptive comments are just before the shared/common parts of the 
definitions.
If I grouped the comment and class definition, someone else would point 
out that I could be
sharing common properties.

The better long term solution is a separate document, with examples.

-- Jon

On 05/08/2017 03:12 PM, Kumar Srinivasan wrote:
>
> 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
>>
>