If there are no objections I'll change the target ws from dev to client, to minimize the merges between some other javadoc fixes.
----- sergey.bylok...@oracle.com 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 > > > ----- jonathan.gibb...@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.r...@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.r...@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 > > > > >>>>>>> > > >>>>> > > >>>> > > >>> > > >> > > >
