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

[huizhe wang]

Jon,

Glad to know that works out. Hopefully this exercise with the jaxp repo 
can be a bit helpful to your effort and utility.  Thanks for using the 
jaxp repo for this exercise!

Best,
Joe

On 7/8/2017 9:58 AM, Jonathan Gibbons wrote:
>
> Joe,
>
> Thanks for the feedback.  I've done some experiments and it looks like 
> we can indeed simplify the more complex tables to always use 
> scope=row|col.
>
> I'll post an amended webrev next week.
>
> Thanks for the feedback and suggestion to revisit this issue.
>
> -- Jon
>
>
> 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?
>>
>> 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?
>> 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?
>>
>> 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>
>>>>
>>>>
>>>>
>>>
>>
>