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

Sergey Bylokhov sergey.bylokhov at oracle.com
Thu May 18 21:48:39 UTC 2017


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


----- jonathan.gibbons at oracle.com 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
> >>>>>>
> >>>>>> ----- 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
> 
> >>>>>>>
> >>>>>
> >>>>
> >>>
> >>
> >


More information about the 2d-dev mailing list