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

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Philip Race
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Philip Race
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
>>>>
>>>> ----- [hidden email] 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 
>>>>>
>>>>>> ----- [hidden email] 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 
>>>>>
>>>
>>
>

Loading...