RFR (JDK11/doc-only) 8199176: Accessibility issues in java.base docs
Roger.Riggs at Oracle.com
Fri Mar 23 17:49:14 UTC 2018
(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.)
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>:*
> In the later page, it actually started with <h1> :
> <h1><a id="jvm_mods"></a>Summary of relevant Java Virtual Machine
> *Currently using <h3>:*
> 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.
>> 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
More information about the core-libs-dev