I found a page about sections and outlines for HTML5. Not 100% sure it's official and the page says most browsers don't follow it, but I think it's a pretty cool idea so I'm trying to create code that inserts implicit sections explicitly and creates an outline.
The conceptual problem I have is similar to one of the examples where implicit and explicit sectioning are mixed (abbreviated version):
<body>
<h1>Mammals</h1>
<h2>Whales</h2>
...
<section>
<h3>Forest elephants</h3>
...
<h3>Mongolian gerbils</h3>
...
<h2>Reptiles</h2>
...
</section>
</body>
Which should give:
1. Mammals
1.1 Whales (implicitly defined by the h2 element)
1.2 Forest elephants (explicitly defined by the section element)
1.3 Mongolian gerbils (implicitly defined by the h3 element, which closes the previous section at the same time)
2. Reptiles (implicitly defined by the h2 element, which closes the previous section at the same time)
But I run into trouble with this (starting a section with a header and then using a less deep header later on). Consider this slightly modified example:
<body>
<h1>Mammals</h1>
<h2>Whales</h2>
...
<section>
<h3>Forest elephants</h3>
...
<h2>Reptiles</h2>
...
<h1>Martians</h2>
<p>Just being annoying</p>
</section>
</body>
How am I supposed to deal with that? The last <h1> should end up at the level of a <h0> in the outer scope, which doesn't exist.
(Personally I think it would make most sense to have explicit sections that start with <h3> only allow <h3>, <h4>, <h5> and <h6>, but that doesn't reproduce the example and I'd like to do it the 'official' way.)
The outline algorithm accounts for this by simply never allowing a heading element within a sectioning element to be higher than the sectioning element itself. From the spec:
When entering a heading content element
If the current section has no heading, let the element being entered be the heading for the current section.
Otherwise, if the element being entered has a rank equal to or higher than the heading of the last section of the outline of the current outline target, or if the heading of the last section of the outline of the current outline target is an implied heading, then create a new section and append it to the outline of the current outline target element, so that this new section is the new last section of that outline. Let current section be that new section. Let the element being entered be the new heading for the current section.
For instance, if you have an <h3> as the first heading in a section, then any <h2> or <h1> that follows it within the same section will be treated equally, creating implicit sections separate from the first. Only <h4> to <h6> will create implicit subsections without starting a new section.
Your first example actually produces the following outline:
1. Mammals 1.1 Whales 1.2 Forest elephants 1.3 Mongolian gerbils 1.4 Reptiles
And your second example produces the following outline:
1. Mammals 1.1 Whales 1.2 Forest elephants 1.3 Reptiles 1.4 Martians