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
