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.gibb...@oracle.com <mailto: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
<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
