Your explanation is so awesome it seems it should be preserved in a javadoc
style guide somewhere.
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.
On Sat, Aug 19, 2017 at 9:10 AM, Jonathan Gibbons <
jonathan.gibb...@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
> 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
>
