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

Sergey Bylokhov
If there are no objections I'll change the target ws from dev to client, to minimize the merges between some other javadoc fixes.

----- [hidden email] wrote:

> Hello.
> Here is an updated version where most of the caption are visible.
> Bug: https://bugs.openjdk.java.net/browse/JDK-8180326
> Webrev can be found at:
> http://cr.openjdk.java.net/~serb/8180326/webrev.02/
> Specdiff:
> http://cr.openjdk.java.net/~serb/8180326/specdiff.02/overview-summary.html
>
> You can use search to check the changes in some specific class:
> Old docs:
> http://cr.openjdk.java.net/~serb/8180326/api_old.02/overview-summary.html
> New docs:
> http://cr.openjdk.java.net/~serb/8180326/api.02/overview-summary.html
>
>
> ----- [hidden email] wrote:
>
> > 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
> > >>>>>>
> > >>>>>> ----- [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
> >
> > >>>>>>>
> > >>>>>
> > >>>>
> > >>>
> > >>
> > >
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Philip Race
I don't remember anything left that I would object to .. and we'll push
client changes
to dev this week anyway so it all sounds fine.

-phil.

On 6/4/17, 5:53 PM, Sergey Bylokhov wrote:

> If there are no objections I'll change the target ws from dev to client, to minimize the merges between some other javadoc fixes.
>
> ----- [hidden email] wrote:
>
>> Hello.
>> Here is an updated version where most of the caption are visible.
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8180326
>> Webrev can be found at:
>> http://cr.openjdk.java.net/~serb/8180326/webrev.02/
>> Specdiff:
>> http://cr.openjdk.java.net/~serb/8180326/specdiff.02/overview-summary.html
>>
>> You can use search to check the changes in some specific class:
>> Old docs:
>> http://cr.openjdk.java.net/~serb/8180326/api_old.02/overview-summary.html
>> New docs:
>> http://cr.openjdk.java.net/~serb/8180326/api.02/overview-summary.html
>>
>>
>> ----- [hidden email] wrote:
>>
>>> 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
>>>>>>>>>
>>>>>>>>> ----- [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...