RFR: JDK-8186466: Fix accessibility and other minor issues in java.base

[Jonathan Gibbons]

On 8/18/17 6:35 PM, Martin Buchholz wrote:
> Thanks as usual for the modern html lessons.  Looks good.
>
> Things I wonder about:
> - I expected to find scope= attributes in BlockingDeque.java tables. 
> TIL about colgroup and rowgroup.  (or does headers=... make that 
> redundant?)
> - I see "font-style: italic" but that seems rather low-level and I 
> expected something higher level.
> - I was surprised by
>
> 178 * <th id="peek" style="font-weight:normal; text-align:left">{@link 
> #peek() peek()}</th>179 * <td headers="Examine BDeque peek">{@link 
> #peekFirst() peekFirst()}</td>
>
> because these two cells are "parallel" and so I expected them to have 
> similar definitions.  I can see they are "related" and the headers= 
> makes that clear, but it still feels slightly wrong to make one of 
> them a <th> and the other a <td>.

Hi Martin,

We're dealing with the intersection of rules and standards here. I 
personally agree with your queasiness about the distinction between 
th/td for "similar" cells but ...

The general intent is that every data cell (td) in a table has to 
identify the header cells (th) that provide details about the row and 
column in which that data cell appears. This implies that every column 
has header cells that describe the column and that every row has header 
cells that define the row. There's also an implication of uniqueness. 
The header cells for each row/column in the table must be unique.

There are two alternative ways to associate data cells with header cells.

1. The "easiest" way, for most tables, is to put scope={row,col} etc on 
the header cells.
2. The more flexible way, for complex tables, is to put id= on header 
cells and headers="list-of-ids" on data cells.

In HTML 4, the rules were more lax about the distinction between header 
cells and data cells. In HTML 5, the rules are more strict. In HTML, you 
can only put scope=row|col on a header (th) cell, and the headers 
attribute on a data cell (td) can only refer to ids on header cells 
(th). This is the reason that so many tables throughout these changes 
have had data cells converted to header cells, which in turn leads to 
using styles to get/retain the desired visual presentation.

Now for BlockingDequeue, as here:
http://cr.openjdk.java.net/~jjg/8186466/api.00/java/util/concurrent/BlockingDeque.html
It's really two tables in one: an upper table, for "First Element 
(Head)" and a lower table, for "Last Element (Tail)". It's not a 
candidate for using the scope attribute because of the split nature of 
the table. With reference to a similarly structured table elsewhere in 
the API, I was advised by an expert in Oracle's Accessibility Office 
that some screen readers would read all the column headers for a cell, 
and not just those that might visually seem to be applicable. So, with 
the simple solution ruled out, there were 3 possibilities for this table.

1. Split it into two tables. That might work OK for this table, because 
of the similar content, but the general problem of using distinct tables 
is that to have the tables use the same widths, you generally have to 
fix the widths, as compared to letting the tables be sized 
automatically. If you don't specify widths, the tables will generally 
end up with different geometries leading to unaligned columns and/or a 
ragged right edge.

2. Move the subheaders (the First Element and Last Element cells) to a 
new column on the left, with appropriate rowspan attributes, and remove 
the second row of the italic headings. Then, the table becomes simple 
enough to use scope=row|col, at the cost of making the table wider. That 
would probably work in this case, but it would conflict with the pattern 
of Insert/Remove/Examine cells in the first column, as in other tables 
in related classes.

3. Use the headers attribute instead of the scope attribute. Although it 
leads to more complex markup, it has the advantage of preserving the 
authors' original layout.

As for your comment about using style="font-weight:italic"... You say it 
seems low level and you expected something higher level. In this case, 
the higher level you are looking for is that the enclosing HTML tag was 
changed from <td> to <th>. But "unfortunately", the default style for a 
<th> is bold text, and so I changed it to italic using a style 
attribute, to preserve the original presentation. It would be wrong to 
use <i> (See https://www.w3.org/International/questions/qa-b-and-i-tags 
) and somewhat wrong to use <em> because that would indicate that these 
headings are to be emphasized more than other headings. If the entire 
page was a standalone HTML document, this would be a classic use of a 
table-specific style, setting an id on the table node, and then 
providing out-of-line style info in either a <style> node in the <head>, 
or in an associated stylesheet. With such a mechanism, we could "move" 
all style declarations out of the flow of semantic content ... which is 
the way that HTML5 is intended to be used. But this is javadoc, and we 
don't (yet) have any such ability, although you can be sure that it has 
triggered discussions about how we can improve the use of styles in 
javadoc comments.

As an aside, I note that there are some places in the W3C website that 
hint at the possibility of being able to use <style> anywhere, and not 
just in <head>. Were that true, that would be wonderful and would 
simplify the use of styles in javadoc comments. My best guess is that 
this was considered in early versions of HTML5, and is even supported by 
some browsers, but our general rule is to follow the rules in the 
official W3C specification of HTML, and not any examples in wiki pages 
or tutorials.

Back on BlockingDequeue, if you would prefer me to change the code to 
use one of the other options (1,2,3) listed above, I will do so.

-- Jon