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.gibb...@oracle.com <mailto:jonathan.gibb...@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.ander...@oracle.com <mailto:lance.ander...@oracle.com>
