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

[Joe Wang]

They look ok. They actually go better with the package name when they 
are just 1 level down instead of 2, that is, <h2> rather than <h3> for 
the titles when the package name is <h1>. If we don't want the strong 
emphasis on the titles, we could lower the package name generated by 
javadoc to <h2> instead of <h1>. Then we could keep the <h3>s.

Most of the package-info pages have already used <h2> for titles, which 
is why we're fixing only a handful of them here. Consider:

*Currently using <h2>:*
https://docs.oracle.com/javase/10/docs/api//java/io/package-summary.html
https://docs.oracle.com/javase/10/docs/api//java/lang/invoke/package-summary.html

In the later page, it actually started with <h1> :
  <h1><a id="jvm_mods"></a>Summary of relevant Java Virtual Machine 
changes</h1>

*Currently using <h3>:*
https://docs.oracle.com/javase/10/docs/api//javax/xml/transform/package-summary.html

-Joe


On 3/21/2018 2:39 PM, Jonathan Gibbons wrote:
>
>
> 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
>