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

[mandy chung]

On 8/22/17 5:24 PM, Jonathan Gibbons wrote:
It is also the hardest to review the diff.   A specdiff would help 
for this specification.  Skimming on the javadoc and seems okay.


Specdiff has some amount of trouble, and so I don't entirely 
understand or trust what
it was trying to show me.   The hard part of this is the updates to 
the big table at the
beginning.  To verify that no obvious changes to the spec have 
accidentally been made,
I cut-n-pasted the table contents into a plain-text file, for the 
generated API page,
before and after the changes. When comparing the two text files, the 
only changes
are extra blank lines in the original version, caused by empty table 
rows, which have
been eliminated in the new version by using CSS to provide extra 
whitespace before
the internal headings. Apart from these blank lines, the textual 
content of the tables

is the same, before and after the changes.


Thanks for verifying that.

THumbs up.

Mandy

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

[Jonathan Gibbons]

On 08/22/2017 01:54 PM, mandy chung wrote:



On 8/18/17 5:03 PM, Jonathan Gibbons wrote:
Please review these fixes for various minor documentation issues in 
the java.base module.
I reviewed the following files and the other files are already covered 
by Naoto and Martin.


Here are more detailed notes on the changes:

src/java.base/share/classes/java/lang/String.java
Some greek text that previously used discrete image files for the 
characters
has been updated to use Unicode characters, specified with HTML 
entities.
All related image files in the doc-files subdirectory have now 
been removed.


src/java.base/share/classes/java/lang/doc-files/ValueBased.html
The file is trivially updated to HTML 5.

src/java.base/share/classes/java/lang/doc-files/threadPrimitiveDeprecation.html 


The file is updated to HTML 5.

src/java.base/share/classes/java/time/format/DateTimeFormatter.java
Two missing quote marks are added.
The quotes are regrettably necessary: some of the examples 
contain spaces,

and some cells have more than one example,

src/java.base/share/classes/java/util/Deque.java
The tables are made accessible.
Where reasonable, the tables are converted to the de-facto standard
"striped" style.

src/java.base/share/classes/java/util/Queue.java
A table is made accessible, and converted to the de-facto standard
"striped" style.



Change in the above files look okay.

:
src/java.base/share/classes/java/util/doc-files/coll-designfaq.html
The file is updated to HTML 5.
The name attributes, which each duplicated the id attribute on
the same enclosing  element, are removed.

src/java.base/share/classes/java/util/doc-files/coll-index.html
The file is trivially updated to HTML 5.

src/java.base/share/classes/java/util/doc-files/coll-overview.html
The file is updated to HTML 5.
A style is added for the table declared in this file.
An alternative edit, to import and use the main javadoc stylesheet
was consider, but caused too many other visual issues.
Eventually, we should change all doc-files/*.html files to use the
standard stylesheet(s).

I agree that it should convert this to use the standard stylesheet 
rather than declaring its own style.  This change is okay for now.

src/java.base/share/classes/java/util/doc-files/coll-reference.html
The file is updated to HTML 5.

src/java.base/share/classes/java/util/regex/Pattern.java
This was the hardest file to update; in particular, the main
table listing the supported pattern constructs. Several solutions
were attempted, such as splitting the table up into smaller tables,
and moving the subheadings to a new column on the left.
As the saying goes, this solution is the worst, except for all
the others. It has the singular advantage of preserving the
existing visual appearance for most users, even if the
source code is somewhat dominated by the attributes to
make the table accessible, and to retain the same visual
presentation.  This table, and some of tables in the Collections
API, highlight the shortcomings in javadoc's support for
custom styles when it is really, really needed. In principle, all
of the style attributes in the main table could be placed
much more succintly in some local stylesheet.
The other edits in this file are more obvious and straightforward.



It is also the hardest to review the diff.   A specdiff would help for 
this specification.  Skimming on the javadoc and seems okay.


Specdiff has some amount of trouble, and so I don't entirely understand 
or trust what
it was trying to show me.   The hard part of this is the updates to the 
big table at the
beginning.  To verify that no obvious changes to the spec have 
accidentally been made,
I cut-n-pasted the table contents into a plain-text file, for the 
generated API page,
before and after the changes. When comparing the two text files, the 
only changes
are extra blank lines in the original version, caused by empty table 
rows, which have
been eliminated in the new version by using CSS to provide extra 
whitespace before
the internal headings. Apart from these blank lines, the textual content 
of the tables

is the same, before and after the changes.



The existing source uses a mixture of  {@code...} and 

src/java.base/share/classes/java/util/spi/CalendarNameProvider.java
The tables are made accessible.
Again, custom stylesheets would simplify the source code.

src/java.base/share/classes/java/lang/doc-files/*.gif (deleted)
See comments above for 
src/java.base/share/classes/java/lang/String.java.
The files 
src/java.base/share/classes/java/lang/doc-files/javalang.doc.anc*.gif

appear to be orphaned relics of earlier versions of the API.
The images exist in releases at least as far back as 1.4, and look
like they might have been part of some mathematical 
representation of

a string hash function, al

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

[mandy chung]

On 8/18/17 5:03 PM, Jonathan Gibbons wrote:
Please review these fixes for various minor documentation issues in 
the java.base module.
I reviewed the following files and the other files are already covered 
by Naoto and Martin.


Here are more detailed notes on the changes:

src/java.base/share/classes/java/lang/String.java
    Some greek text that previously used discrete image files for the 
characters
    has been updated to use Unicode characters, specified with HTML 
entities.
    All related image files in the doc-files subdirectory have now 
been removed.


src/java.base/share/classes/java/lang/doc-files/ValueBased.html
    The file is trivially updated to HTML 5.

src/java.base/share/classes/java/lang/doc-files/threadPrimitiveDeprecation.html 


    The file is updated to HTML 5.

src/java.base/share/classes/java/time/format/DateTimeFormatter.java
    Two missing quote marks are added.
    The quotes are regrettably necessary: some of the examples contain 
spaces,

    and some cells have more than one example,

src/java.base/share/classes/java/util/Deque.java
    The tables are made accessible.
    Where reasonable, the tables are converted to the de-facto standard
    "striped" style.

src/java.base/share/classes/java/util/Queue.java
    A table is made accessible, and converted to the de-facto standard
    "striped" style.



Change in the above files look okay.

:
src/java.base/share/classes/java/util/doc-files/coll-designfaq.html
    The file is updated to HTML 5.
    The name attributes, which each duplicated the id attribute on
    the same enclosing  element, are removed.

src/java.base/share/classes/java/util/doc-files/coll-index.html
    The file is trivially updated to HTML 5.

src/java.base/share/classes/java/util/doc-files/coll-overview.html
    The file is updated to HTML 5.
    A style is added for the table declared in this file.
    An alternative edit, to import and use the main javadoc stylesheet
    was consider, but caused too many other visual issues.
    Eventually, we should change all doc-files/*.html files to use the
    standard stylesheet(s).

I agree that it should convert this to use the standard stylesheet 
rather than declaring its own style.  This change is okay for now.

src/java.base/share/classes/java/util/doc-files/coll-reference.html
    The file is updated to HTML 5.

src/java.base/share/classes/java/util/regex/Pattern.java
    This was the hardest file to update; in particular, the main
    table listing the supported pattern constructs. Several solutions
    were attempted, such as splitting the table up into smaller tables,
    and moving the subheadings to a new column on the left.
    As the saying goes, this solution is the worst, except for all
    the others. It has the singular advantage of preserving the
    existing visual appearance for most users, even if the
    source code is somewhat dominated by the attributes to
    make the table accessible, and to retain the same visual
    presentation.  This table, and some of tables in the Collections
    API, highlight the shortcomings in javadoc's support for
    custom styles when it is really, really needed. In principle, all
    of the style attributes in the main table could be placed
    much more succintly in some local stylesheet.
    The other edits in this file are more obvious and straightforward.



It is also the hardest to review the diff.   A specdiff would help for 
this specification.  Skimming on the javadoc and seems okay.


The existing source uses a mixture of  {@code...} and 

src/java.base/share/classes/java/util/spi/CalendarNameProvider.java
    The tables are made accessible.
    Again, custom stylesheets would simplify the source code.

src/java.base/share/classes/java/lang/doc-files/*.gif (deleted)
    See comments above for 
src/java.base/share/classes/java/lang/String.java.
    The files 
src/java.base/share/classes/java/lang/doc-files/javalang.doc.anc*.gif

    appear to be orphaned relics of earlier versions of the API.
    The images exist in releases at least as far back as 1.4, and look
    like they might have been part of some mathematical representation of
    a string hash function, although I've not been able to track down
    where the images were used.


+1
Mandy

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

[Martin Buchholz]

I'm happy.  Thanks for going the extra kilometer.

On Mon, Aug 21, 2017 at 3:31 PM, Jonathan Gibbons <
jonathan.gibb...@oracle.com> wrote:

>
>
> On 08/21/2017 09:38 AM, Jonathan Gibbons wrote:
>
>>
>>
>> On 8/20/17 4:11 PM, Martin Buchholz wrote:
>>
>>> Again, I am happy to take the current state of this change.
>>>
>>> On Sat, Aug 19, 2017 at 2:19 PM, Jonathan Gibbons <
>>> jonathan.gibb...@oracle.com > wrote:
>>>
>>> Actually, thead and tbody have no direct significance for
>>> accessibility. They provide a semantic differentiation of the
>>> content, and provide a hook for different styling, as you have
>>> seen for "striped". Also note, although you can have many ,
>>> you can only have at most one , and at most one .
>>>
>>> Looking at Summary of BlockingDeque methods again, we have what might
>>> logically be a thead in the middle of a table, and the law of "only one
>>> thead, and only at the beginning" might be yet another hint that the html
>>> gods want us to split this table. This could become a nested table with two
>>> rows, one for "first" and one for "last", each of which contains a subtable
>>> with a thead.
>>>
>>
>> I can investigate that.
>>
>
> I investigated.
>
> It won't be a table with two rows; it'll be a table with 3 rows, because
> it would need a header row with column headings :-(  Also, you wouldn't
> have the columns aligned, because of the use of two tables.  And so you
> might as well go with two separate tables, and the "First"/"Last" labels
> moving into captions.
>
> I guess I'd like to declare victory on the BlockingQueue/Deque tables.
> They meet the desired accessibility requirements, which was the primary
> goal.  Even if they don't get the full "striped" approach, they are at
> least visually similar to the original versions in the JDK 8 and JDK 9 API,
> with respect to font, centering, etc.
>
> If we want to continue to enhance the appearance of these tables, we
> should take it offline from this review, and do more experiments on smaller
> API examples that are faster to turn around.
>
> -- Jon
>
>

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

[Jonathan Gibbons]

On 08/21/2017 09:38 AM, Jonathan Gibbons wrote:



On 8/20/17 4:11 PM, Martin Buchholz wrote:

Again, I am happy to take the current state of this change.

On Sat, Aug 19, 2017 at 2:19 PM, Jonathan Gibbons 
mailto:jonathan.gibb...@oracle.com>> 
wrote:


Actually, thead and tbody have no direct significance for
accessibility. They provide a semantic differentiation of the
content, and provide a hook for different styling, as you have
seen for "striped". Also note, although you can have many ,
you can only have at most one , and at most one .

Looking at Summary of BlockingDeque methods again, we have what might 
logically be a thead in the middle of a table, and the law of "only 
one thead, and only at the beginning" might be yet another hint that 
the html gods want us to split this table. This could become a nested 
table with two rows, one for "first" and one for "last", each of 
which contains a subtable with a thead.


I can investigate that.


I investigated.

It won't be a table with two rows; it'll be a table with 3 rows, because 
it would need a header row with column headings :-(  Also, you wouldn't 
have the columns aligned, because of the use of two tables.  And so you 
might as well go with two separate tables, and the "First"/"Last" labels 
moving into captions.


I guess I'd like to declare victory on the BlockingQueue/Deque tables. 
They meet the desired accessibility requirements, which was the primary 
goal.  Even if they don't get the full "striped" approach, they are at 
least visually similar to the original versions in the JDK 8 and JDK 9 
API, with respect to font, centering, etc.


If we want to continue to enhance the appearance of these tables, we 
should take it offline from this review, and do more experiments on 
smaller API examples that are faster to turn around.


-- Jon

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

[Jonathan Gibbons]

On 8/21/17 9:46 AM, Martin Buchholz wrote:



On Mon, Aug 21, 2017 at 9:38 AM, Jonathan Gibbons 
mailto:jonathan.gibb...@oracle.com>> wrote:




On 8/20/17 4:11 PM, Martin Buchholz wrote:

Again, I am happy to take the current state of this change.

On Sat, Aug 19, 2017 at 2:19 PM, Jonathan Gibbons
mailto:jonathan.gibb...@oracle.com>> wrote:

Actually, thead and tbody have no direct significance for
accessibility. They provide a semantic differentiation of the
content, and provide a hook for different styling, as you
have seen for "striped". Also note, although you can have
many , you can only have at most one , and at
most one .

Looking at Summary of BlockingDeque methods again, we have what
might logically be a thead in the middle of a table, and the law
of "only one thead, and only at the beginning" might be yet
another hint that the html gods want us to split this table. 
This could become a nested table with two rows, one for "first"

and one for "last", each of which contains a subtable with a thead.


I can investigate that.

I would ask, why is this materially different from a new left-most
column in a single table, but I guess one response would be that
the subtables could be striped, which would give visual
consistency with similar tables.


Right - the new theads could get that fashionable #DDD background like 
the other tables.


Yes, that's better than encoding colors in the doc comments, in case we 
want to do style changes in the stylesheet.


-- Jon

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

[Martin Buchholz]

On Mon, Aug 21, 2017 at 9:38 AM, Jonathan Gibbons <
jonathan.gibb...@oracle.com> wrote:

>
>
> On 8/20/17 4:11 PM, Martin Buchholz wrote:
>
> Again, I am happy to take the current state of this change.
>
> On Sat, Aug 19, 2017 at 2:19 PM, Jonathan Gibbons <
> jonathan.gibb...@oracle.com> wrote:
>
>> Actually, thead and tbody have no direct significance for accessibility.
>> They provide a semantic differentiation of the content, and provide a hook
>> for different styling, as you have seen for "striped". Also note, although
>> you can have many , you can only have at most one , and at
>> most one .
>>
> Looking at  Summary of BlockingDeque methods again, we have what might
> logically be a thead in the middle of a table, and the law of "only one
> thead, and only at the beginning" might be yet another hint that the html
> gods want us to split this table.  This could become a nested table with
> two rows, one for "first" and one for "last", each of which contains a
> subtable with a thead.
>
>
> I can investigate that.
>
> I would ask, why is this materially different from a new left-most column
> in a single table, but I guess one response would be that the subtables
> could be striped, which would give visual consistency with similar tables.
>

Right - the new theads could get that fashionable #DDD background like the
other tables.

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

[Jonathan Gibbons]

On 8/20/17 4:11 PM, Martin Buchholz wrote:

Again, I am happy to take the current state of this change.

On Sat, Aug 19, 2017 at 2:19 PM, Jonathan Gibbons 
mailto:jonathan.gibb...@oracle.com>> wrote:


Actually, thead and tbody have no direct significance for
accessibility. They provide a semantic differentiation of the
content, and provide a hook for different styling, as you have
seen for "striped". Also note, although you can have many ,
you can only have at most one , and at most one .

Looking at Summary of BlockingDeque methods again, we have what might 
logically be a thead in the middle of a table, and the law of "only 
one thead, and only at the beginning" might be yet another hint that 
the html gods want us to split this table.  This could become a nested 
table with two rows, one for "first" and one for "last", each of which 
contains a subtable with a thead.


I can investigate that.

I would ask, why is this materially different from a new left-most 
column in a single table, but I guess one response would be that the 
subtables could be striped, which would give visual consistency with 
similar tables.


-- Jon

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

[Naoto Sato]

Thanks for the explanation, Jon. I am fine with the current one.

Naoto

On 8/18/17 5:37 PM, Jonathan Gibbons wrote:

Hi Naoto,

Thanks for checking out the changes.

On 08/18/2017 05:19 PM, Naoto Sato wrote:

Hi Jon,

Thank you for the cleanup! I looked at j.l.String, 
j.t.DateTimeFormatter, and j.u.ResourceBundle and all look good.


BTW, I just noticed that in ResourceBundle, line 1330 and so on, there 
is a new column "Index" introduced. Is this intentional?


Yes. It is intentional, although I'm open to better suggestions for the 
column header, or for other presentations.


Conceptually, the information is a list of pairs.   The text that 
precedes the info describes it as
"the sequence of locale-format combinations to be used to call 
|control.newBundle|. ".
HTML can't do a list of pairs as such, and so a table is used. But for 
accessibility, there must
be some subset of each row which together uniquely define the row, and 
so can be used
as row headers for the data cells in that row.  Typically, the first 
element is the
the unique element.  But that is not so in this case ... worse: there is 
no such column whose
cells define the row. Both columns contain duplicates.  That means the 
only combination
that uniquely defines the row is the entire row, which would mean the 
table would be

all header cells and no data cells!

I went with a solution to add a new column which identifies the position 
in the sequence.
If you don't like the extra column, the alternative would be a bulleted 
or numbered list,
with the two items of the pair separated by commas or some other 
punctuation, as in:


  *   Locale("de", "DE"),     java.class
  *   Locale("de", "DE") ,    java.properties
  *   Locale("de"),     java.class
  *   Locale("de"),     java.properties
  *   Locale(""),     java.class
  *   Locale(""),     java.properties

(In my mail client, that looks like a bulleted list; I don't know how 
well it will travel

through the mail system.)

-- Jon



Naoto

On 8/18/17 5:03 PM, Jonathan Gibbons wrote:
Please review these fixes for various minor documentation issues in 
the java.base module.
The changes are mostly in java.util and its subpackages, but there is 
some minor cleanup

in previously updated packages as well.

The primary focus is on addressing accessibility issues. In addition, 
some doc files have
been converted to HTML5. As with all recent fixes like this, there 
should be no change to

the underlying specifications.

JBS:https://bugs.openjdk.java.net/browse/JDK-8186466
Webrev:http://cr.openjdk.java.net/~jjg/8186466/webrev.00/index.html
API:http://cr.openjdk.java.net/~jjg/8186466/api.00/overview-summary.html

-- Jon, the Javadoc Janitor


Here are more detailed notes on the changes:

src/java.base/share/classes/java/lang/String.java
 Some greek text that previously used discrete image files for 
the characters
 has been updated to use Unicode characters, specified with HTML 
entities.
 All related image files in the doc-files subdirectory have now 
been removed.


src/java.base/share/classes/java/lang/doc-files/ValueBased.html
 The file is trivially updated to HTML 5.

src/java.base/share/classes/java/lang/doc-files/threadPrimitiveDeprecation.html 


 The file is updated to HTML 5.

src/java.base/share/classes/java/time/format/DateTimeFormatter.java
 Two missing quote marks are added.
 The quotes are regrettably necessary: some of the examples 
contain spaces,

 and some cells have more than one example,

src/java.base/share/classes/java/util/Deque.java
 The tables are made accessible.
 Where reasonable, the tables are converted to the de-facto standard
 "striped" style.

src/java.base/share/classes/java/util/Queue.java
 A table is made accessible, and converted to the de-facto standard
 "striped" style.

src/java.base/share/classes/java/util/ResourceBundle.java
 A preformatted list is converted to a semantic list.
 The tables are made accessible.
 Where reasonable, the tables are converted to the de-facto standard
 "striped" style.
 Line 3458 and following. Previously, the comment did not display 
correctly
 because javadoc incorrectly treated the dot in this string 
"'.'"
 as the end of the first sentence! The minimal fix would be to 
change that

 string to "{@code .}", but that would be stylistically inconsistent
 with the rest of the comment. There are too many occurrences of
 ... in the file as a whole to change them all at 
this time,
 so the compromise is just to replace the occurrences in this 
comment.

 Introducing more cleanup for existing uses of ... is a
 topic for another day.

src/java.base/share/classes/java/util/concurrent/BlockingDeque.java
 The tables are made accessible.
 In the second table, the "Insert"/"Remove"/"Examine" headings
 are moved from embedded rows to a new left-most column
 for consistency with other similar tables

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

[Martin Buchholz]

Again, I am happy to take the current state of this change.

On Sat, Aug 19, 2017 at 2:19 PM, Jonathan Gibbons <
jonathan.gibb...@oracle.com> wrote:

> Actually, thead and tbody have no direct significance for accessibility.
> They provide a semantic differentiation of the content, and provide a hook
> for different styling, as you have seen for "striped". Also note, although
> you can have many , you can only have at most one , and at
> most one .
>
Looking at  Summary of BlockingDeque methods again, we have what might
logically be a thead in the middle of a table, and the law of "only one
thead, and only at the beginning" might be yet another hint that the html
gods want us to split this table.  This could become a nested table with
two rows, one for "first" and one for "last", each of which contains a
subtable with a thead.

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

[Jonathan Gibbons]

On 8/19/17 11:55 AM, Martin Buchholz wrote:


I don't know how hard it would be to make the header rows in 
BlockingDeque presented like the ones in e.g. Deque.
Deque uses striped thead, which gets the #DDD background from the 
stylesheet.  And having s is probably itself an accessibility 
feature.
Actually, thead and tbody have no direct significance for accessibility. 
They provide a semantic differentiation of the content, and provide a 
hook for different styling, as you have seen for "striped". Also note, 
although you can have many , you can only have at most one 
, and at most one .


table.striped > thead {
background-color: #DDD;
border: 1px solid black;
}

we could brute force the same background color or try to convert these 
to striped tables (but you probably tried that).


The only way to make the first table in BlockingDeque use striped tables 
would be to split the table in two, and change the First/Last Element 
headers into table captions.  If you want the overhead of brute-forcing 
the color on each row, we can do that, but ideally, we should be trying 
to move inline styles out of the HTML (and into stylesheets), not 
increasing the use of inline styles (despite all appearances to the 
contrary in this overall changeset!)


There's a bunch of work going on in javadoc related to stylesheets. See 
the open issues list here:

https://bugs.openjdk.java.net/issues/?jql=project%20%3D%20jdk%20and%20Subcomponent%3D%22javadoc(tool)%22%20and%20labels%20in%20(stylesheet)%20and%20resolution%20is%20empty
If that link gets mangled by the mail system, the underlying query is
"project = jdk and Subcomponent="javadoc(tool)" and labels in 
(stylesheet) and resolution is empty"


I think BlockingDeque is a good reason and test case for better support 
for table styles. Maybe it's better to address the javadoc support for 
custom styles, rather than work around the lack of it.


-- Jon

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

[Jonathan Gibbons]

On 8/19/17 12:04 PM, Martin Buchholz wrote:

can one do something like  ?


Not the way the styles are currently set up.   The style was set up so 
that you just have to declare the table to be striped, and the contents 
follow suit. This avoids having to declare a class on all the nodes in 
the table.


The "proper" way to do this (i.e.in a pure HTML page) would be to have a 
page-specific or table-specific style.


One possible low-key suggestion for javadoc is to detect the presence of 
nominated files in the doc-files subdirectory for a package, and include 
a link to that stylesheet (in addition to system stylesheet(s)) in the 
docs for the types in that package.


-- Jon

Re: 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 * Insert

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 
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 * {@link #peek() peek()}179 * {@link #peekFirst() peekFirst()}

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  and the other a .


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:ital

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

[Martin Buchholz]

can one do something like  ?

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

[Martin Buchholz]

I don't know how hard it would be to make the header rows in BlockingDeque
presented like the ones in e.g. Deque.
Deque uses striped thead, which gets the #DDD background from the
stylesheet.  And having s is probably itself an accessibility
feature.

table.striped > thead {
background-color: #DDD;
border: 1px solid black;
}

we could brute force the same background color or try to convert these to
striped tables (but you probably tried that).

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

[Martin Buchholz]

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  *Insert

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  *{@link 
> #peek() peek()} 179  *{@link 
> #peekFirst() peekFirst()}
>
>
> 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 
> and the other a .
>
>
> 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  to . But "unfortunately", the default style for a  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  (See
> https://www.w3.org/Internat

Re: 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 * {@link 
#peek() peek()}179 * {@link 
#peekFirst() peekFirst()}


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  and the other a .


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  to . But "unfortunately", the default style for a 
 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  (See https://www.w3.org/International/questions/qa-b-and-i-tags 
) and somewhat wrong to use  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 

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

[Martin Buchholz]

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  *{@link #peek() peek()} 179  *{@link #peekFirst() peekFirst()}


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 
and the other a .

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

[Jonathan Gibbons]

Hi Naoto,

Thanks for checking out the changes.

On 08/18/2017 05:19 PM, Naoto Sato wrote:

Hi Jon,

Thank you for the cleanup! I looked at j.l.String, 
j.t.DateTimeFormatter, and j.u.ResourceBundle and all look good.


BTW, I just noticed that in ResourceBundle, line 1330 and so on, there 
is a new column "Index" introduced. Is this intentional?


Yes. It is intentional, although I'm open to better suggestions for the 
column header, or for other presentations.


Conceptually, the information is a list of pairs.   The text that 
precedes the info describes it as
"the sequence of locale-format combinations to be used to call 
|control.newBundle|. ".
HTML can't do a list of pairs as such, and so a table is used. But for 
accessibility, there must
be some subset of each row which together uniquely define the row, and 
so can be used
as row headers for the data cells in that row.  Typically, the first 
element is the
the unique element.  But that is not so in this case ... worse: there is 
no such column whose
cells define the row. Both columns contain duplicates.  That means the 
only combination
that uniquely defines the row is the entire row, which would mean the 
table would be

all header cells and no data cells!

I went with a solution to add a new column which identifies the position 
in the sequence.
If you don't like the extra column, the alternative would be a bulleted 
or numbered list,
with the two items of the pair separated by commas or some other 
punctuation, as in:


 *   Locale("de", "DE"), java.class
 *   Locale("de", "DE") ,java.properties
 *   Locale("de"), java.class
 *   Locale("de"), java.properties
 *   Locale(""), java.class
 *   Locale(""), java.properties

(In my mail client, that looks like a bulleted list; I don't know how 
well it will travel

through the mail system.)

-- Jon



Naoto

On 8/18/17 5:03 PM, Jonathan Gibbons wrote:
Please review these fixes for various minor documentation issues in 
the java.base module.
The changes are mostly in java.util and its subpackages, but there is 
some minor cleanup

in previously updated packages as well.

The primary focus is on addressing accessibility issues. In addition, 
some doc files have
been converted to HTML5. As with all recent fixes like this, there 
should be no change to

the underlying specifications.

JBS:https://bugs.openjdk.java.net/browse/JDK-8186466
Webrev:http://cr.openjdk.java.net/~jjg/8186466/webrev.00/index.html
API:http://cr.openjdk.java.net/~jjg/8186466/api.00/overview-summary.html

-- Jon, the Javadoc Janitor


Here are more detailed notes on the changes:

src/java.base/share/classes/java/lang/String.java
 Some greek text that previously used discrete image files for 
the characters
 has been updated to use Unicode characters, specified with HTML 
entities.
 All related image files in the doc-files subdirectory have now 
been removed.


src/java.base/share/classes/java/lang/doc-files/ValueBased.html
 The file is trivially updated to HTML 5.

src/java.base/share/classes/java/lang/doc-files/threadPrimitiveDeprecation.html 


 The file is updated to HTML 5.

src/java.base/share/classes/java/time/format/DateTimeFormatter.java
 Two missing quote marks are added.
 The quotes are regrettably necessary: some of the examples 
contain spaces,

 and some cells have more than one example,

src/java.base/share/classes/java/util/Deque.java
 The tables are made accessible.
 Where reasonable, the tables are converted to the de-facto standard
 "striped" style.

src/java.base/share/classes/java/util/Queue.java
 A table is made accessible, and converted to the de-facto standard
 "striped" style.

src/java.base/share/classes/java/util/ResourceBundle.java
 A preformatted list is converted to a semantic list.
 The tables are made accessible.
 Where reasonable, the tables are converted to the de-facto standard
 "striped" style.
 Line 3458 and following. Previously, the comment did not display 
correctly
 because javadoc incorrectly treated the dot in this string 
"'.'"
 as the end of the first sentence! The minimal fix would be to 
change that

 string to "{@code .}", but that would be stylistically inconsistent
 with the rest of the comment. There are too many occurrences of
 ... in the file as a whole to change them all at 
this time,
 so the compromise is just to replace the occurrences in this 
comment.

 Introducing more cleanup for existing uses of ... is a
 topic for another day.

src/java.base/share/classes/java/util/concurrent/BlockingDeque.java
 The tables are made accessible.
 In the second table, the "Insert"/"Remove"/"Examine" headings
 are moved from embedded rows to a new left-most column
 for consistency with other similar tables.

src/java.base/share/classes/java/util/concurrent/BlockingQueue.java
 The table is made accessible.

src/java.base/sha

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

[Naoto Sato]

Hi Jon,

Thank you for the cleanup! I looked at j.l.String, 
j.t.DateTimeFormatter, and j.u.ResourceBundle and all look good.


BTW, I just noticed that in ResourceBundle, line 1330 and so on, there 
is a new column "Index" introduced. Is this intentional?


Naoto

On 8/18/17 5:03 PM, Jonathan Gibbons wrote:
Please review these fixes for various minor documentation issues in the 
java.base module.
The changes are mostly in java.util and its subpackages, but there is 
some minor cleanup

in previously updated packages as well.

The primary focus is on addressing accessibility issues. In addition, 
some doc files have
been converted to HTML5. As with all recent fixes like this, there 
should be no change to

the underlying specifications.

JBS:https://bugs.openjdk.java.net/browse/JDK-8186466
Webrev:http://cr.openjdk.java.net/~jjg/8186466/webrev.00/index.html
API:http://cr.openjdk.java.net/~jjg/8186466/api.00/overview-summary.html

-- Jon, the Javadoc Janitor


Here are more detailed notes on the changes:

src/java.base/share/classes/java/lang/String.java
 Some greek text that previously used discrete image files for the 
characters
 has been updated to use Unicode characters, specified with HTML 
entities.
 All related image files in the doc-files subdirectory have now been 
removed.


src/java.base/share/classes/java/lang/doc-files/ValueBased.html
 The file is trivially updated to HTML 5.

src/java.base/share/classes/java/lang/doc-files/threadPrimitiveDeprecation.html 


 The file is updated to HTML 5.

src/java.base/share/classes/java/time/format/DateTimeFormatter.java
 Two missing quote marks are added.
 The quotes are regrettably necessary: some of the examples contain 
spaces,

 and some cells have more than one example,

src/java.base/share/classes/java/util/Deque.java
 The tables are made accessible.
 Where reasonable, the tables are converted to the de-facto standard
 "striped" style.

src/java.base/share/classes/java/util/Queue.java
 A table is made accessible, and converted to the de-facto standard
 "striped" style.

src/java.base/share/classes/java/util/ResourceBundle.java
 A preformatted list is converted to a semantic list.
 The tables are made accessible.
 Where reasonable, the tables are converted to the de-facto standard
 "striped" style.
 Line 3458 and following. Previously, the comment did not display 
correctly
 because javadoc incorrectly treated the dot in this string 
"'.'"
 as the end of the first sentence! The minimal fix would be to 
change that

 string to "{@code .}", but that would be stylistically inconsistent
 with the rest of the comment. There are too many occurrences of
 ... in the file as a whole to change them all at this 
time,

 so the compromise is just to replace the occurrences in this comment.
 Introducing more cleanup for existing uses of ... is a
 topic for another day.

src/java.base/share/classes/java/util/concurrent/BlockingDeque.java
 The tables are made accessible.
 In the second table, the "Insert"/"Remove"/"Examine" headings
 are moved from embedded rows to a new left-most column
 for consistency with other similar tables.

src/java.base/share/classes/java/util/concurrent/BlockingQueue.java
 The table is made accessible.

src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
 The table is made accessible.

src/java.base/share/classes/java/util/doc-files/coll-designfaq.html
 The file is updated to HTML 5.
 The name attributes, which each duplicated the id attribute on
 the same enclosing  element, are removed.

src/java.base/share/classes/java/util/doc-files/coll-index.html
 The file is trivially updated to HTML 5.

src/java.base/share/classes/java/util/doc-files/coll-overview.html
 The file is updated to HTML 5.
 A style is added for the table declared in this file.
 An alternative edit, to import and use the main javadoc stylesheet
 was consider, but caused too many other visual issues.
 Eventually, we should change all doc-files/*.html files to use the
 standard stylesheet(s).

src/java.base/share/classes/java/util/doc-files/coll-reference.html
 The file is updated to HTML 5.

src/java.base/share/classes/java/util/regex/Pattern.java
 This was the hardest file to update; in particular, the main
 table listing the supported pattern constructs. Several solutions
 were attempted, such as splitting the table up into smaller tables,
 and moving the subheadings to a new column on the left.
 As the saying goes, this solution is the worst, except for all
 the others. It has the singular advantage of preserving the
 existing visual appearance for most users, even if the
 source code is somewhat dominated by the attributes to
 make the table accessible, and to retain the same visual
 presentation.  This table, and some of tables in the Collection

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

[Jonathan Gibbons]

Please review these fixes for various minor documentation issues in the 
java.base module.
The changes are mostly in java.util and its subpackages, but there is 
some minor cleanup

in previously updated packages as well.

The primary focus is on addressing accessibility issues. In addition, 
some doc files have
been converted to HTML5. As with all recent fixes like this, there 
should be no change to

the underlying specifications.

JBS:https://bugs.openjdk.java.net/browse/JDK-8186466
Webrev:http://cr.openjdk.java.net/~jjg/8186466/webrev.00/index.html
API:http://cr.openjdk.java.net/~jjg/8186466/api.00/overview-summary.html

-- Jon, the Javadoc Janitor


Here are more detailed notes on the changes:

src/java.base/share/classes/java/lang/String.java
Some greek text that previously used discrete image files for the 
characters
has been updated to use Unicode characters, specified with HTML 
entities.
All related image files in the doc-files subdirectory have now been 
removed.


src/java.base/share/classes/java/lang/doc-files/ValueBased.html
The file is trivially updated to HTML 5.

src/java.base/share/classes/java/lang/doc-files/threadPrimitiveDeprecation.html
The file is updated to HTML 5.

src/java.base/share/classes/java/time/format/DateTimeFormatter.java
Two missing quote marks are added.
The quotes are regrettably necessary: some of the examples contain 
spaces,

and some cells have more than one example,

src/java.base/share/classes/java/util/Deque.java
The tables are made accessible.
Where reasonable, the tables are converted to the de-facto standard
"striped" style.

src/java.base/share/classes/java/util/Queue.java
A table is made accessible, and converted to the de-facto standard
"striped" style.

src/java.base/share/classes/java/util/ResourceBundle.java
A preformatted list is converted to a semantic list.
The tables are made accessible.
Where reasonable, the tables are converted to the de-facto standard
"striped" style.
Line 3458 and following. Previously, the comment did not display 
correctly
because javadoc incorrectly treated the dot in this string 
"'.'"
as the end of the first sentence! The minimal fix would be to 
change that

string to "{@code .}", but that would be stylistically inconsistent
with the rest of the comment. There are too many occurrences of
... in the file as a whole to change them all at this 
time,

so the compromise is just to replace the occurrences in this comment.
Introducing more cleanup for existing uses of ... is a
topic for another day.

src/java.base/share/classes/java/util/concurrent/BlockingDeque.java
The tables are made accessible.
In the second table, the "Insert"/"Remove"/"Examine" headings
are moved from embedded rows to a new left-most column
for consistency with other similar tables.

src/java.base/share/classes/java/util/concurrent/BlockingQueue.java
The table is made accessible.

src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
The table is made accessible.

src/java.base/share/classes/java/util/doc-files/coll-designfaq.html
The file is updated to HTML 5.
The name attributes, which each duplicated the id attribute on
the same enclosing  element, are removed.

src/java.base/share/classes/java/util/doc-files/coll-index.html
The file is trivially updated to HTML 5.

src/java.base/share/classes/java/util/doc-files/coll-overview.html
The file is updated to HTML 5.
A style is added for the table declared in this file.
An alternative edit, to import and use the main javadoc stylesheet
was consider, but caused too many other visual issues.
Eventually, we should change all doc-files/*.html files to use the
standard stylesheet(s).

src/java.base/share/classes/java/util/doc-files/coll-reference.html
The file is updated to HTML 5.

src/java.base/share/classes/java/util/regex/Pattern.java
This was the hardest file to update; in particular, the main
table listing the supported pattern constructs. Several solutions
were attempted, such as splitting the table up into smaller tables,
and moving the subheadings to a new column on the left.
As the saying goes, this solution is the worst, except for all
the others. It has the singular advantage of preserving the
existing visual appearance for most users, even if the
source code is somewhat dominated by the attributes to
make the table accessible, and to retain the same visual
presentation.  This table, and some of tables in the Collections
API, highlight the shortcomings in javadoc's support for
custom styles when it is really, really needed. In principle, all
of the style attributes in the main table could be placed
much more succintly in some local stylesheet.
The other edits in this file are more obvious and straightforward.

src/java.base/share/classes/java/util/spi/Calendar