RFR (JDK11/doc-only) 8199176: Accessibility issues in java.base docs

[Jonathan Gibbons]

On 3/21/18 2:28 PM, Alan Bateman wrote:
> On 21/03/2018 19:08, Joe Wang wrote:
>> :
>>
>> *Item 3*: Heading leavels should only increase by one
>>     This is due to the javadoc tool generates a header with an 
>> addition of headings, in this particular case, <h1>. The fix for this 
>> particular case is to replace the <h3>s with <h2>.
> I assume this has the effect of increasing the size of the headings. 
> Does it look okay? I assume many of these usages of h3 choose that to 
> avoid heading in very large font.
>
> -Alan

I know accessibility fixes are important, but usability is important 
too.  The uses of h3 were previously consistent across different pages.

We could remediate the problem either by figuring a design that has 
javadoc put a similar set of headers on every page (thus rendering this 
changeset unnecessary) or else changing the stylesheet so that <h2> on a 
package-summary page looks the same as <h3> on a class page (which 
sounds icky, even as I type it.)

-- Jon