'Re: [OpenJDK 2D-Dev] <Sound Dev> <Swing Dev> [9] Review Request: 8180326 Update the tables in java.d'

[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-2d-dev
Subject:    Re: [OpenJDK 2D-Dev] <Sound Dev> <Swing Dev> [9] Review Request: 8180326 Update the tables in java.d
From:       Philip Race <philip.race () oracle ! com>
Date:       2017-06-05 1:12:28
Message-ID: 5934AFFC.8080805 () oracle ! com
[Download RAW message or body]

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. 
> ----- sergey.bylokhov@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.gibbons@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@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@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
> > 


[prev in list] [next in list] [prev in thread] [next in thread]
Configure | About | News | Add a list | Sponsored by KoreLogic