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

Sergey Bylokhov
Hi, Alexander.
These closing tags are optional in html5 standard [1]. On the link to the SO there are three the example which work differently but according standards[2][3][4].

[1] https://www.w3.org/TR/html5/syntax.html#syntax-tag-omission

[2] http://jsfiddle.net/robertc/rNv93/1/
[3] http://jsfiddle.net/UqzEp/2/
[4] http://jsfiddle.net/UqzEp/3/

----- [hidden email] wrote:
>

Hi Sergey,
>

Why do we omitting closing th tag?
>

e.g.
>

+     * <caption>Metal's system color mapping</caption>
+     * <thead>
+     *  <tr>
+     *    <th>Key
+     *    <th>Value
+     * </thead>

I know that HTML parsers are usually forgiving such things. But sometimes it may make thing worse:
>

https://stackoverflow.com/questions/7125354/what-are-the-actual-problems-of-not-closing-tags-and-attributes-in-html/7135378#7135378

Thanks,
Alexander.
> On 05/06/2017 06:23, 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

          

                      

                  

                

              

            

          

>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Alexander Zvegintsev

Thanks for clarification, looks good to me.

Thanks,
Alexander.
On 07/06/2017 23:22, Sergey Bylokhov wrote:
Hi, Alexander.
These closing tags are optional in html5 standard [1]. On the link to the SO there are three the example which work differently but according standards[2][3][4].

[1] https://www.w3.org/TR/html5/syntax.html#syntax-tag-omission

[2] http://jsfiddle.net/robertc/rNv93/1/
[3] http://jsfiddle.net/UqzEp/2/
[4] http://jsfiddle.net/UqzEp/3/

----- [hidden email] wrote:
>

Hi Sergey,
>

Why do we omitting closing th tag?
>

e.g.
>

+     * <caption>Metal's system color mapping</caption>
+     * <thead>
+     *  <tr>
+     *    <th>Key
+     *    <th>Value
+     * </thead>

I know that HTML parsers are usually forgiving such things. But sometimes it may make thing worse:
>

https://stackoverflow.com/questions/7125354/what-are-the-actual-problems-of-not-closing-tags-and-attributes-in-html/7135378#7135378

Thanks,
Alexander.
> On 05/06/2017 06:23, 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...