<Swing Dev> [12] RFR JDK-8213049:Invalid HTML5 in javax.swing files

[Alexey Ivanov]

Hi Sergey,

Thank you for additional details on handling ‘summary’ attribute and 
<caption> element.

HTML 5 recommendation has a section “Techniques for describing tables” [1].
Description of <caption> element [2] provides some additional details.


Hi Prasanta,

*properties.html*

 From accessibility point of view, properties.html could benefit from 
additional text introducing the tables. Currently <caption> element of 
the table repeats the preceding header in <h1> element with additional 
word “Nimbus”.

Header row should be in <thead> element:
<table>
<caption>Nimbus primary colors</caption>
<thead>
<tr><th>Key</th><th>Value</th><th>Preview</th></tr>
</thead>
<tbody>
…
</tbody></table>

Closing tags for both <thead> and <tbody> can be omitted.

The first column in the table is essentially row header, so <th> element 
seems more appropriate.

Attributes ‘width’ and ‘bgcolor’ are obsolete in HTML5. This could be 
addressed in a separate bug. I'll submit a bug to clean this up.


*multi_tsc.html*

254 <a id="dosanddonts"></a>
255   <h3>Dos and Don'ts</h3>

‘id’ can be added to <h3> element without using additional <a>.
I guess using <a> element is the preferred way to declare anchors since 
it's done this way in other places throughout the document. Unless other 
places are updated, let's keep it this way for consistency.


267 </p> this is the wrong way to address “Warning: trimming empty <p>”. 
You should remove the opening <p>:
262 <p>

It's immediately followed by <h4> element which automatically closes 
<p>. By adding </p> after <h4></h4>, you create a dangling </p> closing 
tag which has no corresponding opening tag.


*componentProperties.html*

The new version duplicates the table title both in the preceding header 
and in the table caption.

I think one of these should be removed. I'm for removing the header 
(<h3>) because caption more closely relates to the table.

The following tables have this problem:
ArrowButton Specific Properties
JButton Specific Properties
JCheckBox Specific Properties
JComboBox Specific Properties
JFileChooser Specific Properties
JFileChooser Specific Properties
JInternalFrame Specific Properties
JInternalFrameTitlePane Specific Properties
JList Specific Properties
JOptionPane Specific Properties
JProgressBar Specific Properties
JRadioButton Specific Properties
JScrollBar Specific Properties
JScrollPane Specific Properties
JSplitPane Specific Properties
JSlider Specific Properties
JTabbedPane Specific Properties
JTable Specific Properties
JTree Specific Properties
JToggleButton Specific Properties
Text Properties†

Pretty much each table.
† It's better to keep “Text Properties” header to avoid confusion, and 
drop <caption>. Alternatively, you can add some introductory text.


*synthFileFormat.html*

The file 
java.desktop/javax/swing/plaf/synth/doc-files/synthFileFormat.html is 
also referenced in the bug description [3]:
build/linux-x86_64-server-release/images/docs/./api/java.desktop/javax/swing/plaf/synth/doc-files/synthFileFormat.html:779:5: 
Warning: The summary attribute on the <table> element is obsolete in HTML5

I think ‘summary’ attribute should be converted to <caption> element too.


Regards,
Alexey

[1] 
https://www.w3.org/TR/html52/tabular-data.html#sec-techniques-for-describing-tables
[2] https://www.w3.org/TR/html52/tabular-data.html#the-caption-element
[3] https://bugs.openjdk.java.net/browse/JDK-8213049

On 03/12/2018 05:25, Prasanta Sadhukhan wrote:
> Hi Sergey,
>
> OK. Replaced summary by caption
> http://cr.openjdk.java.net/~psadhukhan/8213049/webrev.1/
>
> Regards
> Prasanta
> On 01-Dec-18 3:56 AM, Sergey Bylokhov wrote:
>> Hi, Prasanta.
>>
>> The "summary" attr in our tables was used for accessibility purpose:
>> https://bugs.java.com/bugdatabase/view_bug.do?bug_id=4637604
>>
>> But since this attr is unsupported in html5 it was replaced
>> by the <caption> with appropriate text:
>>
>> http://mail.openjdk.java.net/pipermail/swing-dev/2017-May/007355.html
>> http://mail.openjdk.java.net/pipermail/swing-dev/2017-May/007356.html
>>
>> On 29/11/2018 22:44, Prasanta Sadhukhan wrote:
>>> Hi All,
>>>
>>> Please review a doc-fix to comply with HTML5 standard,mainly 
>>> removing the obsolete "summary" attributes.
>>>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8213049
>>> webrev: http://cr.openjdk.java.net/~psadhukhan/8213049/webrev.0/
>>>
>>> Regards
>>> Prasanta