Also, there's an ambiguity in the spec caused by the "implied heading" concept: If you look at the "When entering a heading content element" step, the first condition it says to check there is, "If the current section has no heading, let the element being entered be the heading for the current section."


The "If the current section has no heading" part could be misinterpreted as in that a section which has an implied heading added would not meet that condition. I don't think that's the intent of the spec. Or least I sure hope it's not, because it would have the effect of causing the real heading for the section to be ignored or misplaced in the outline.

So if you keep the "create an implied heading" steps, I would suggest at least changing the wording of that step to say, ""If the current section has no heading or an implied heading...".

<section>a<section>b</section><h2>C</h2>c</section> is intended to result in this outline:

   1. (implied heading)
      contents: a
   1.1. (implied heading)
        contents: b
   2. C
      contents: c

<section>a<h2>A</h2><section>b</section>c</section> is intended to result in this outline:

   1. A
      contents: a, c (c comes after 1.1)
   1.1. (implied heading)
        contents: b

<section><h1>A</h1>a<section>b</section><h2>C</h2>c</section> is intended to result in this outline:

   1. A
      contents: a
   1.1. (implied heading)
        contents: b
   1.2. C
        contents: c

Without the implied headings, how do I get this result? The part that checks for implied headings isn't just the part you mention, it's also the part that says "If the current section has no heading", as you mention here:

> The "If the current section has no heading" part could be misinterpreted as
> in that a section which has an implied heading added would not meet that
> condition. I don't think that's the intent of the spec. Or least I sure hope
> it's not, because it would have the effect of causing the real heading for
> the section to be ignored or misplaced in the outline.

It is the intent of the spec. In fact this is the exact reason the spec has the implied headings stuff. What cases do you think this would break?

(In reply to comment #2)
> <section>a<section>b</section><h2>C</h2>c</section> is intended to result in
> this outline:
> 
>    1. (implied heading)
>       contents: a
>    1.1. (implied heading)
>         contents: b
>    2. C
>       contents: c

OK but are you sure you don't mean "1.2 C" there instead of "2. C"?

If the <h2>C</h2> is a child of the first section, I don't see why it would it make sense for the outline to show it as a sibling of that section. But I can see why it would make sense to have it as "1.2 C" child.

Anyway, I understand the logic of having it generate the above outline in that it preserves the structure in document order. But I don't think the spec is clearly stating the steps in such as way to produce the result you describe.

At least I know that outline you describe above is not generated by gsnedders's implementation nor any of the two other existing implementations of the outline algorithm I've tried. What they all consistently generate instead is this:

 1. C [contents: a, c]
 1.1 (implied heading) [contents: b]

In other words, that C heading is hoisted up to become the heading for the top section, instead of the top section having an implied heading.

So everybody who's implemented it so far has either misread the spec in the same way, or willfully disregarded it.

> <section>a<h2>A</h2><section>b</section>c</section> is intended to result in
> this outline:
> 
>    1. A
>       contents: a, c (c comes after 1.1)
>    1.1. (implied heading)
>         contents: b

Yeah, for that case all existing implementations conform to the spec.

But I don't see why the <h2>A</h2> contents would get hoisted up to become the heading for the top section in this case but not in the first case you cited -- <section>a<section>b</section><h2>C</h2>c</section>. I don't think the spec makes it clear that the two cases need to be handled differently.

If the spec says to do what you describe in your first case, then I think it would break the second case just above, if the output for this case is supposed to be as you've described.

> <section><h1>A</h1>a<section>b</section><h2>C</h2>c</section> is intended to
> result in this outline:
> 
>    1. A
>       contents: a
>    1.1. (implied heading)
>         contents: b
>    1.2. C
>         contents: c

And for that case also all existing implementations conform to the spec.

> Without the implied headings, how do I get this result?

For that last case just above and for the second case you cited, I get the spec-conforming expected result in my code just fine without actually generating any implied heading property in the outline object when I build the outline.

I deal with displaying some "[section element with no heading]" text for the heading-less parts when I render the outline from the outline object. That is, the outline object itself that I build just lacks having heading property for the heading-less parts; and then when doing the rendering step, if there's no heading property, I just emit "[section element with no heading]" (or whatever the corresponding element name is for that part).

The only case you've described that my implementation and the other implementations are not matching the behavior you've described is for the first case you gave here. And again for that one I don't understand why the behavior for hoisting up the heading should be different for that case than it is for the second case you described. Nor is it clear to me exactly what part of the spec requires those cases to be different.

> The part that checks
> for implied headings isn't just the part you mention, it's also the part
> that says "If the current section has no heading", as you mention here:
> 
> > The "If the current section has no heading" part could be misinterpreted as
> > in that a section which has an implied heading added would not meet that
> > condition. I don't think that's the intent of the spec. Or least I sure hope
> > it's not, because it would have the effect of causing the real heading for
> > the section to be ignored or misplaced in the outline.
> 
> It is the intent of the spec. In fact this is the exact reason the spec has
> the implied headings stuff. What cases do you think this would break?

I think it would break the second case you described:
<section>a<h2>A</h2><section>b</section>c</section>

I think it would cause the result to be something like:

 1. (implied heading) [contents: a]
 1.1 A [contents: c]
 1.1.1 (implied heading) [contents: b]

(In reply to comment #3)
> (In reply to comment #2)
> > <section>a<section>b</section><h2>C</h2>c</section> is intended to result in
> > this outline:
> > 
> >    1. (implied heading)
> >       contents: a
> >    1.1. (implied heading)
> >         contents: b
> >    2. C
> >       contents: c
> 
> OK but are you sure you don't mean "1.2 C" there instead of "2. C"?

No, I mean "2. C". That's the key point, and why implied headings are needed.

Consider pages that don't have sectioning elements. If the page just has:

   <h1>A</h1>
   <h1>B</h1>
   <h1>C</h1>

...then there's three top-level sections. So if we stick that in an <article>, we need to end up with three top-level sections, essentially three articles. Stick a section before the first heading, and it can't be in the same section as the heading's.


> If the <h2>C</h2> is a child of the first section, I don't see why it would
> it make sense for the outline to show it as a sibling of that section.

It's a sibling of the /section/ (not <section>) that was generated by the first part of the <section>.


> Anyway, I understand the logic of having it generate the above outline in
> that it preserves the structure in document order. But I don't think the
> spec is clearly stating the steps in such as way to produce the result you
> describe.
> 
> At least I know that outline you describe above is not generated by
> gsnedders's implementation nor any of the two other existing implementations
> of the outline algorithm I've tried. What they all consistently generate
> instead is this:
> 
>  1. C [contents: a, c]
>  1.1 (implied heading) [contents: b]
> 
> In other words, that C heading is hoisted up to become the heading for the
> top section, instead of the top section having an implied heading.

I don't understand how you end up with this given the spec text.


> So everybody who's implemented it so far has either misread the spec in the
> same way, or willfully disregarded it.

Both are quite possible...


> > <section>a<h2>A</h2><section>b</section>c</section> is intended to result in
> > this outline:
> > 
> >    1. A
> >       contents: a, c (c comes after 1.1)
> >    1.1. (implied heading)
> >         contents: b
> 
> Yeah, for that case all existing implementations conform to the spec.
> 
> But I don't see why the <h2>A</h2> contents would get hoisted up to become
> the heading for the top section in this case but not in the first case you
> cited -- <section>a<section>b</section><h2>C</h2>c</section>.

Well, the problem is that there's almost always something just before the first heading between the heading and the top of the section, even if that's whitespace or text that says something like "welcome to...". It would be weird for there to be implied sections in the spec just because there's white space in the source.

But equally it would be weird for there to be subsections above their section's heading.


> I don't think
> the spec makes it clear that the two cases need to be handled differently.

The implied heading that's inserted when you get to a subsection is how it happens in the spec.


> If the spec says to do what you describe in your first case, then I think it
> would break the second case just above, if the output for this case is
> supposed to be as you've described.

Why?


> > It is the intent of the spec. In fact this is the exact reason the spec has
> > the implied headings stuff. What cases do you think this would break?
> 
> I think it would break the second case you described:
> <section>a<h2>A</h2><section>b</section>c</section>
> 
> I think it would cause the result to be something like:
> 
>  1. (implied heading) [contents: a]
>  1.1 A [contents: c]
>  1.1.1 (implied heading) [contents: b]

Why? Implied headings are only added when you get to a sectioning element.

OK, I re-implemented my outliner to match the spec. I think I have it producing conforming output (and matching the expected results described in comment #2.

I pushed it to http://qa-dev.w3.org:8888/ for testing.

(In reply to comment #4)
> (In reply to comment #3)
> > (In reply to comment #2)
> > > <section>a<section>b</section><h2>C</h2>c</section> is intended to result in
> > > this outline:
> > > 
> > >    1. (implied heading)
> > >       contents: a
> > >    1.1. (implied heading)
> > >         contents: b
> > >    2. C
> > >       contents: c
> > 
> > OK but are you sure you don't mean "1.2 C" there instead of "2. C"?
> 
> No, I mean "2. C". That's the key point, and why implied headings are needed.

OK, my outliner implementation is now producing that.

> > If the <h2>C</h2> is a child of the first section, I don't see why it would
> > it make sense for the outline to show it as a sibling of that section.
> 
> It's a sibling of the /section/ (not <section>) that was generated by the
> first part of the <section>.

Ah, OK, yeah

> >  1. C [contents: a, c]
> >  1.1 (implied heading) [contents: b]
> > 
> > In other words, that C heading is hoisted up to become the heading for the
> > top section, instead of the top section having an implied heading.
> 
> I don't understand how you end up with this given the spec text.

I got it by treating the "generate an implied heading" step as a noop :)

> > > <section>a<h2>A</h2><section>b</section>c</section> is intended to result in
> > > this outline:
> > > 
> > >    1. A
> > >       contents: a, c (c comes after 1.1)
> > >    1.1. (implied heading)
> > >         contents: b
> > 
> > Yeah, for that case all existing implementations conform to the spec.
> > 
> > But I don't see why the <h2>A</h2> contents would get hoisted up to become
> > the heading for the top section in this case but not in the first case you
> > cited -- <section>a<section>b</section><h2>C</h2>c</section>.
> 
> Well, the problem is that there's almost always something just before the
> first heading between the heading and the top of the section, even if that's
> whitespace or text that says something like "welcome to...". It would be
> weird for there to be implied sections in the spec just because there's
> white space in the source.

OK, yeah

> But equally it would be weird for there to be subsections above their
> section's heading.

Yeah

> > I don't think
> > the spec makes it clear that the two cases need to be handled differently.
> 
> The implied heading that's inserted when you get to a subsection is how it
> happens in the spec.

Yep, I can see that now after I went back to re-read the spec.

> > If the spec says to do what you describe in your first case, then I think it
> > would break the second case just above, if the output for this case is
> > supposed to be as you've described.
> 
> Why?

Please forget I said that, I was wrong.

> Why? Implied headings are only added when you get to a sectioning element.

Right, I see that now.

Thanks for your patience in replying. After looking back at the spec, there's no further spec change after all that I can suggest at this point to make the algorithm more clear. So feel free to go ahead and mark this resolved.

Checked in as WHATWG revision r7709.
Check-in comment: Add some examples of outlines.
http://html5.org/tools/web-apps-tracker?from=7708&to=7709

I've added some examples to the spec to hopefully make this clearer.