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

[Joe Wang]

Thanks Roger!  I'll check this changeset in for now to fix the 
accessibility issue, with a note that a future solution that correctly 
generates the appropriate and consistent headers is desirable. 
JDK-8199895 may be used for further discussion.

[1] https://bugs.openjdk.java.net/browse/JDK-8199895

Best,
Joe

On 3/23/2018 10:49 AM, Roger Riggs wrote:
> Hi Joe,
>
> Looks fine.
>
> (I would be in favor of a future solution that correctly 
> generated/fixed up the appropriate headers;
> Manual editing and corrections are an unnecessary overhead.)
>
> Thanks, Roger
>
> On 3/21/2018 6:47 PM, Joe Wang wrote:
>> 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
>>>
>>
>