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