Review Request : 7198272 - RFE : Javadoc Accessibility : Generate WAI-ARIA compliant HTML

[Jonathan Gibbons]

On 11/14/2012 10:26 PM, jayashree viswanathan wrote:
> Hi Jon ,
>
> http://www.w3.org/TR/wai-aria/appendices
>
> Please read through "10.1.6. HTML 4.01 plus WAI-ARIA DTD"  . The 
> question on if we would like to move upto HTML 5, XHTML now can be a 
> separate discussion as always with each offering some advantages Vs 
> the other and javadoc as a tool can move upto one of these with 
> changes to be made for them based on need.
>
> Though I believe this need not be an impediment to move to WAI-ARIA 
> standard as mentioned in the page itself to move to this upcoming 
> standard .
>
> I agree with your point on HtmlTree nodes and can add the ARIA 
> attributes to the node, rather than constructing a string and I can 
> make the changes and pass on a fresh webrev soon .
>
> Thanks and Regards,
> Jayashree V
>
>

Jayashree,

Thanks for the reference; it makes interesting reading, and may provide 
a way forward.

I certainly like the idea of separating use of and conformance to 
WAI-ARIA from whether or not to move to HTML 5, and would welcome a 
discussion on what it would take to have javadoc generate HTML 5. Maybe 
that is initially provided as an option.   I think there needs to be two 
parts to the discussion: what would we have to do to javadoc-generated 
output (coming from the tool itself) and and would be the implications 
on existing doc comments.


Now to the ARIA DTD you mentioned. I read it and I'm somewhat confused 
by the content.  In particular, I wonder if all the text is intentional, 
or if we have come across a cut-n-paste error.   In section 10.1.6, it says:

> However, note that when this DOCTYPE is present in a document, most 
> user agents treat the document as generic XML rather than HTML. This 
> causes them to be unable to support named character entities defined 
> by the DTD (e.g., ©). Therefore, authors need to avoid use of 
> named entities outside of the predefined entities in XML 
> <http://www.w3.org/TR/xml/#sec-predefined-ent> ([XML 
> <http://www.w3.org/TR/wai-aria/references#ref_XML>], Section 4.6). 

I have a hard time believing that you could treat an HTML document as 
"generic XML", and I see the identical text in 10.1.3, for an XHTML+ARIA 
DTD, where the text makes more sense (i.e. is more believable.)

Do you have any more experience with the use of HTML+ARIA DTD, and with 
documents using it?

I'm wondering if we should make use of ARIA an option in the doclet, so 
that user's can choose whether or not to use it.   If the option is 
selected, then javadoc would change the DTD and add all the 
role="presentation" attributes that you suggest.  I note that once you 
start using HtmlTree nodes, it is much easier to conditionally add 
attributes to them that it is to change the string content that might be 
generated.

----

As a side note on HtmlTree nodes, the goal is that RawHtml nodes should 
only be used for unparsed user input (i.e. provided via options).  There 
are still some internal uses of RawHtml, most notably for links, which 
have yet to be converted to the new paradigm.  In time, I would like to 
eliminate /all/ RawHtml nodes, and parse HTML supplied in options and 
convert it to valid nodes.

-- Jon


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20121115/67ef8b9d/attachment.html