RFR: 8184021: Fix tables in jaxp doc comments to be accessible

[Jonathan Gibbons]

On 7/7/17 5:50 PM, huizhe wang wrote:
> Hi Jon,
>
> For the table in CatalogFeatures, the id attribute for Type and Value 
> are not used, may be unnecessary. Instead, scope="col" can be added, 
> is that right?
> 50 * <th id="VType">Type</th>
> 51 * <th id="VValue">Value</th>
>
> I'm new to accessibility, but it seems to me the following can use 
> scope="colgroup" instead?
By itself, that is not enough.
>
> 46 * <th scope="col" colspan="2" style="text-align:center">Value [2]</th>
>
>
> Since the 1st and 7th columns already have scope="row",  if 
> scope="col" can be added to the 8th (Action) column, the cells in the 
> 8th (Action) column then won't need the "headers" attribute, would 
> that be right?
No, the cells in the 8th column need to identify the column, and two row 
header cells.  You can only use "scope=row|col" on simple matrix-like 
tables ... as soon as you have spanning rows or columns you need to use 
header cells.

> 1st column: 74 * <th rowspan="2" scope="row" 
> style="font-weight:normal" id="PREFER">PREFER</th> ...
> 7th column: 81 * <th scope="row" id="system" 
> style="font-weight:normal">{@code system}</th>
> 8th column: 82 * <td headers="PREFER system Action">
>
> For the table in XMLStreamWriter, it looks like to me we can avoid the 
> headers for each cell by instead making the following changes:
> add rowspan="2" to
>    45  *             <th>Method</th> <!-- method -->
> add scope="colgroup" to
> 46 * <th colspan="2">{@code isRepairingNamespaces} == true</th>
> 47 * <th colspan="2">{@code isRepairingNamespaces} == false</th>
> remove:
>    50  *             <th></th> <!-- method -->
>
> add scope="col" to
> 51 * <th>namespaceURI bound</th>
> 52 * <th>namespaceURI unbound</th>
> 53 * <th>namespaceURI bound</th>
> 54 * <th>namespaceURI unbound</th>
>
> add scope="row" to the first column of the rows in the body.
>
> Would that make sense?

Again, if it's not a simple matrix-like table, you need headers to 
identify all applicable headers to the data cells.
>
> Thanks,
> Joe
>
> On 7/7/2017 2:53 PM, Jonathan Gibbons wrote:
>> Sorry, I meant to include that; will post shortly, beside the webrev.
>>
>> -- Jon
>>
>> On 07/07/2017 01:33 PM, Lance Andersen wrote:
>>> Hi Jon,
>>>
>>> The changes looked good to me.   Is the html available by chance to 
>>> do an extra sanity check?
>>>
>>> Best
>>> Lance
>>>> On Jul 7, 2017, at 2:14 PM, Jonathan Gibbons 
>>>> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> 
>>>> wrote:
>>>>
>>>> Please review the following fixes to the doc comments in the jaxp 
>>>> repo.
>>>>
>>>> The primary goal is to fix user-written tables in doc comments for 
>>>> accessibility, either by updating tables to use scope=row|col in 
>>>> header cells for simple tables, or by using the headings attribute 
>>>> in more complex tables.  The majority of the changes, to tables 
>>>> using class="striped", were done mechanically, using a custom Java 
>>>> utility. Three tables were fixed up manually.
>>>>
>>>> In addition, I removed the use of <p> tags which introduced empty 
>>>> paragraph. These tags caused warnings when checking the code with 
>>>> the "tidy" program.
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8184021
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8184021/webrev.00/ 
>>>> <http://cr.openjdk.java.net/%7Ejjg/8184021/webrev.00/>
>>>>
>>>> -----
>>>>
>>>> The following list of comments about the changes is ordered 
>>>> according to the list in the webrev.
>>>>
>>>> Catalog:
>>>>    removed empty <p>
>>>>
>>>> CatalogFeatures:
>>>>    first table updated manually (class="plain")
>>>>    removed empty <p>
>>>>    second table updated with utility
>>>>
>>>> CatalogResolver:
>>>>    removed empty <p>
>>>>
>>>> DatatypeFactory, Duration:
>>>>   table updated with utility
>>>>
>>>> XMLGregorianCalendar:
>>>>   all tables updated with utility
>>>>
>>>> datatype/package-info:
>>>>   table updated with utility
>>>>
>>>> NamespaceContext:
>>>>   all tables updated with utility
>>>>
>>>> XMLEventWriter, XMLInputFactory, XMLOutputFactory, XMLStreamReader:
>>>>   table updated with utility
>>>>
>>>> XMLStreamWriter:
>>>>    this is the one table with class="striped" that had to be updated
>>>>    manually, because of the complex headers
>>>>
>>>> SchemaFactory:
>>>>    table updated with utility, but table organization could be 
>>>> improved (by spec owner)
>>>>    for example, to split first column into a name and a URI, and/or 
>>>> use the second
>>>>    column as a row header.
>>>>
>>>> Validator, XPath, XPathExpression, xpath/package-info:
>>>>   table updated manually (class="plain")
>>>>
>>>> Attr
>>>>   table updated with utility
>>>>   table could be improved by removing redundant atributes, like 
>>>> rowspan='1' colspan='1'
>>>>
>>>> Document, Node:
>>>>   all tables updated with utility
>>>>
>>>> -- Jon
>>>
>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif><http://oracle.com/us/design/oracle-email-sig-198324.gif> 
>>>
>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance 
>>> Andersen| Principal Member of Technical Staff | +1.781.442.2037
>>> Oracle Java Engineering
>>> 1 Network Drive
>>> Burlington, MA 01803
>>> Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>
>>>
>>>
>>>
>>
>