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

[Jonathan Gibbons]

On 8/19/17 11:34 AM, Martin Buchholz wrote:
> Your explanation is so awesome it seems it should be preserved in a 
> javadoc style guide somewhere.
One we can sort out the "Java Style Guidelines", I would like to write 
such a guide as you suggest.
>
> There are refactorings that make logical sense ("subtables"?)  but 
> lose readability in practice.
>
> I'm happy with what you have, but as always have suggestions:
>
> - I would use centered text for "*First Element (Head)"*; that would 
> be consistent with jdk9 formatting, and consistent with the html 
> default "header text is centered".
>
> 139 * <th id="Insert" rowspan="4" style="text-align:left; 
> vertical-align:top">Insert</th>
> I might have chosen centered here as well.

I'll make those two changes for you.
>
>
> On Sat, Aug 19, 2017 at 9:10 AM, Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>
>
>
>     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
>     <http://cr.openjdk.java.net/%7Ejjg/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
>     <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
>
>