<Swing Dev> [9] Review Request: 8180326 Update the tables in java.desktop to be HTML-5 friendly

Wed May 17 21:41:17 UTC 2017

Phil,

I have no evidence one way or the other whether screen readers pay 
attention
to undisplayed or invisible captions. It seemed safest to assume that 
they would
read a visible caption, and that we should head in that general direction.

-- Jon

On 05/17/2017 11:58 AM, Phil Race wrote:
> And PS I was not saying anything to contradict
> > tables should not have a summary attribute and should have a caption.
>
> However that the docs I read on the web did seem to imply that
> summary was very much intended for ATs but it was not at all clear this
> is the point of caption. I'm sure they can read it, but I don't get 
> how making
> it visible matters to them so how it making it visible relates to 
> accessibility
> requirements is not an obvious connection to me. So why do we have
> to make it visible for ATs ?
>
> -phil.
>
> On 05/17/2017 11:54 AM, Phil Race wrote:
>> I will leave the decision on whether to do that now up to Sergey 
>> although
>> it seems all he has to do here is remove "invisible".
>> Many of the "summary" ones had wrong or misleading text but they
>> seem to have been all fixed.
>>
>> I'd want to see what the new HTML looks like with a visible title of 
>> course ..
>>
>> -phil.
>>
>> On 05/17/2017 11:52 AM, Jonathan Gibbons wrote:
>>> Phil,
>>>
>>> The bottom line is that in the JDK docs, tables should not have a 
>>> summary attribute and should have a caption. This comes down to 
>>> accessibility requirements, where we are slowly raising the bar on 
>>> our docs, to be in accordance with Oracle's guidelines.
>>>
>>> Hiding the caption (style="display:none") is an interim measure we 
>>> have been using during the HTML 5 updates, especially in cases where 
>>> the person doing the markup changes did not know enough to create an 
>>> appropriate caption that should be displayed. In time, we should 
>>> locate and update all table captions (in our standard docs bundle) 
>>> that are not being displayed such that the text is both appropriate 
>>> and visible. If you guys want to do that as part of this update, go 
>>> ahead. FWIW, that is what we did for the java.xml module in the jaxp 
>>> repo ... pretty much all tables there now have a reasonable, visible 
>>> caption.
>>>
>>> -- Jon
>>>
>>>
>>>
>>> On 05/17/2017 11:19 AM, Phil Race wrote:
>>>> I am not sure we are using the summary in a way that makes it 
>>>> worthwhile.
>>>> As you noted in the other mail
>>>> "The summary attribute was used to give a more descriptive value
>>>> of the contents of the table.   A caption is more like a title"
>>>>
>>>> The values I see are more like a title and as you say that is not 
>>>> the idea. See the example here
>>>>
>>>> https://www.w3.org/TR/WCAG20-TECHS/H73.html
>>>>
>>>> Caption sounds like a title so it might actually be more 
>>>> appropriate than summary
>>>> for the text we have except that its not clear why we'd want it to 
>>>> be visible when we were fine without.
>>>>
>>>> But being there and invisible may be pointless unless screen 
>>>> readers look for it even if invisible.
>>>>
>>>> But if its not doing any harm I guess we can leave it as proposed
>>>>
>>>> I still need to look at the rest of the changes.
>>>>
>>>> -phil.
>>>>
>>>> On 05/12/2017 05:11 PM, Jonathan Gibbons wrote:
>>>>> Sergey,
>>>>>
>>>>> FWIW, the invisible caption should be regarded as a temporary 
>>>>> solution, until content authors can review/update the text of the 
>>>>> caption and make it visible.
>>>>>
>>>>> The general guideline in this conversion work has been to avoid 
>>>>> changing the visible text of the specification, and captions fall 
>>>>> into a grey area of whether the text is significant/normative or 
>>>>> not.  Hence the temporary step to make them not displayed for now.
>>>>>
>>>>> -- Jon
>>>>>
>>>>> On 05/12/2017 05:00 PM, Sergey Bylokhov wrote:
>>>>>> The "summary" is unsupported by the HTML5 and we replace it by 
>>>>>> invisible caption.
>>>>>> These new styles are located in the stylesheet.css in the root of 
>>>>>> the JavaDoc api folder, so I assume these styles should be used 
>>>>>> by others as well.
>>>>>> They were added by this fix:
>>>>>> https://bugs.openjdk.java.net/browse/JDK-8179479
>>>>>>
>>>>>> ----- philip.race at oracle.com wrote:
>>>>>>
>>>>>>> Does this in any way match the rest of the docs ? Or is everyone 
>>>>>>> left
>>>>>>> to
>>>>>>> style things how they want.
>>>>>>> I thought (?) maybe there is to be some javadoc tool support for 
>>>>>>> CSS
>>>>>>> styles.
>>>>>>>
>>>>>>> Also why are all the table summaries removed ?
>>>>>>>
>>>>>>> -phil.
>>>>>>>
>>>>>>> On 5/12/17, 4:52 PM, Sergey Bylokhov wrote:
>>>>>>>> This is because I use the same style for most of the tables
>>>>>>> 'class="striped"', which apply the same/unified style for 
>>>>>>> all(most) of
>>>>>>> our tables.
>>>>>>>> Also this is because I removed 'inlined' styles, like here:
>>>>>>>>
>>>>>>> http://cr.openjdk.java.net/~serb/8180326/api_old.01/java/awt/font/TextAttribute.html 
>>>>>>>
>>>>>>>> ----- philip.race at oracle.com wrote:
>>>>>>>>
>>>>>>>>> Adding 2d-dev because a number of the files are 2D.
>>>>>>>>>
>>>>>>>>> What is the general reason for changing the appearance of the
>>>>>>> tables?
>>>>>>>>> -phil.
>>>>>>>>>
>>>>>>>>> On 5/12/17, 4:25 PM, Sergey Bylokhov wrote:
>>>>>>>>>> Hello,
>>>>>>>>>> Please review the fix for jdk9-dev.
>>>>>>>>>>
>>>>>>>>>> This fix is a part of the effort to make all javadoc in jdk9 be
>>>>>>>>> compatible to HTML5.
>>>>>>>>>> It covers all errors which are reported by the javadoc tool
>>>>>>> during
>>>>>>>>> the build of jdk for java.desktop module.
>>>>>>>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8180326
>>>>>>>>>> Webrev can be found at:
>>>>>>>>> http://cr.openjdk.java.net/~serb/8180326/webrev.01
>>>>>>>>>> Note that an appearance of some tables were changed after the
>>>>>>> fix:
>>>>>>>>>> Before:
>>>>>>> http://cr.openjdk.java.net/~serb/8180326/api_old.01/java/awt/font/TextAttribute.html 
>>>>>>>
>>>>>>>>>> After:
>>>>>>> http://cr.openjdk.java.net/~serb/8180326/api.01/java/awt/font/TextAttribute.html 
>>>>>>>
>>>>>>>>>> Before:
>>>>>>> http://cr.openjdk.java.net/~serb/8180326/api_old.01/javax/sound/sampled/AudioSystem.html 
>>>>>>>
>>>>>>>>>> After :
>>>>>>> http://cr.openjdk.java.net/~serb/8180326/api.01/javax/sound/sampled/AudioSystem.html 
>>>>>>>
>>>>>>>>>> Before:
>>>>>>> http://cr.openjdk.java.net/~serb/8180326/api_old.01/javax/sound/sampled/AudioPermission.html 
>>>>>>>
>>>>>>>>>> After:
>>>>>>> http://cr.openjdk.java.net/~serb/8180326/api.01/javax/sound/sampled/AudioPermission.html 
>>>>>>>
>>>>>
>>>>
>>>
>>
>