RFR: 8215307: Pages do not have <h1>

[Jonathan Gibbons]

Martin,

Thank you for your interest in this area; sometimes it's good to know 
that other folk care about this sort of stuff as well ;-)

There are a number of different aspects to consider here.

1. Your suggestion presupposes HTML 5. As of right now, javadoc (or more 
accurately, the standard doclet) still supports HTML 4 ... but that 
being said, work is underway to remove support for HTML 4. javadoc has 
given warnings for a while, and it's finally time to remove it. 
Suggestions like yours are another reason why it is time to remove 
support for HTML 4. [Aside: I note the CSR to remove HTML 4, 
JDK-8215578, has just now been approved, so we will soon be proceeding 
with the actual removal.]

2. This issue (pages do not have <h1>) is part of the overall ongoing 
campaign to fix accessibility issues in generated javadoc, both in 
general and in the JDK API in particular. It's the latest in a series of 
updates over the past few years, including improved tables, improved use 
of regions, and so on. This means that we want to abide by WCAG 
standards as well as HTML 5 standards.

3. Your links are for a Working Draft. This seems to be an equivalent 
page in the latest version:

https://www.w3.org/TR/html5/sections.html#headings-and-sections

That page does not have the "every <section> has an <h1>" example. It 
does have the following text, which ties the heading rank to the nesting 
level: /Sections may contain headings of a //rank 
<https://www.w3.org/TR/html5/sections.html#rank>//equal to their section 
nesting level. Authors should use headings of the appropriate //rank 
<https://www.w3.org/TR/html5/sections.html#rank>//for the section’s 
nesting level./

Here's a relevant page from WCAG:

https://www.w3.org/TR/WCAG20-TECHS/G141.html

It says: /To facilitate navigation and understanding of overall document 
structure, authors should use headings that are properly nested (e.g., 
h1 followed by h2, h2 followed by h2 or h3, h3 followed by h3 or h4, etc.)./

4. This particular bug is (just) about changing the javadoc-generated 
headings. It doesn't enforce particular headings within comments, 
although it does encourage particular heading levels if doclint is 
enabled. You might reasonably surmise that as the overall work moves 
forward, we will need to fix up doclint, and the headings in JDK API doc 
comments, to achieve our goals in this area. That is "coming soon"; this 
review is just the first step, for the javadoc/doclet part of the work.

5. It has been suggested that javadoc should allow headings to start at 
h1 in each comment, and that javadoc should adjust them as necessary. 
For my part, I think that would be a bad idea, because it could lead to 
unexpected differences between the headings in the comments and entries 
in the style sheet. It's not good if the user wrote <h1> or <h2> in 
their comment, and javadoc rewrites it to <h3> or <h4>.

---

Finally, I welcome any additional input or interpretation of the 
prevailing existing standards in this area!

-- Jon


On 01/25/2019 01:41 AM, Martin Desruisseaux wrote:
>
> Hello Jonathan. Thanks for all this work. I was wondering if the use 
> of <h1>, <h2>, etc. nested inside <section> has been considered for 
> simplifying the heading ranks? If I understood [1] and [2] correctly, 
> the following are semantically identical in HTML5:
>
>     <h1>XXX</h1>
>       <section>
>        <h2>YYY</h2>
>        <section>
>          <h3>ZZZ</h3>
>
> and
>
>     <h1>XXX</h1>
>       <section>
>        <h1>YYY</h1>
>        <section>
>          <h1>ZZZ</h1>
>
> Wouldn't the use of <section> allows to reset the <h#> counting to 1 
> for that section, which would free the developer to care about what 
> was the rank of last <h#> element? If each field and method is in its 
> own <section>, wouldn't it allow developers to use <h1>, <h2>, etc. in 
> their javadoc for each field/method?
>
>     Martin
>
> [1]https://www.w3.org/TR/2011/WD-html5-author-20110809/headings-and-sections.html#headings-and-sections
> [2]https://www.w3.org/TR/2011/WD-html5-author-20110809/the-h1-h2-h3-h4-h5-and-h6-elements.html#rank
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190125/ba7a6234/attachment-0001.html>