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

Jonathan Gibbons jonathan.gibbons at oracle.com
Tue Jul 11 00:46:13 UTC 2017


Thanks.  I see the ERROR. I'm not sure of the reasoning why your fix 
works: maybe because the data cell is empty, it doesn't need headers.  
I'll do more experiments!

Anyway, I'm happy to go with the suggested fix.

-- Jon


On 07/10/2017 05:40 PM, huizhe wang wrote:
> That looks great!  Almost all "green"!
>
> The only exception is the table in javax/xml/validation/Validator.java 
> where the empty cell resulted in a reported "ERROR". I tried changing 
> <th></th> to <td></td> and saw that the tool happily accepted it:
>
> - 138      *   <th></th>
> + 138      *   <td></td>
>
> If you decide to adopt the above, no need to re-generate the webrevs.
>
> Thanks,
> Joe
>
>
> On 7/10/2017 3:52 PM, Jonathan Gibbons wrote:
>> Here is the amended webrev for the work on fixing the tables (and 
>> other nits) in the jaxp docs.
>>
>> As we discussed, I changed the two manually edited tables, in 
>> CatalogFeatures and XMLStreamWriter, to use scope=row/col. There are 
>> now no tables in the jaxp repo using headers to identify row and 
>> column headers.
>>
>> I found two more tables that needed fixing in
>> /src/java.xml/share/classes/org/xml/sax/package-info.java.
>>
>> I've also fixed a minor doc bug JDK-8183984 in which ! in the first 
>> sentence was causing javadoc to generate invalid HTML output.
>> https://bugs.openjdk.java.net/browse/JDK-8183984
>>
>> Finally, I fixed one more excess <p>, in XMLReaderFactory.
>>
>> As a result of all this, the java.xml module gets a clean bill of 
>> documentary health, for all the checks we are currently tracking.
>>
>> -- Jon
>>
>> On 07/08/2017 09: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>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>



More information about the core-libs-dev mailing list