This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 20068 - Drop the "create an implied heading" steps from the outline algorithm.
Summary: Drop the "create an implied heading" steps from the outline algorithm.
Status: RESOLVED FIXED
Alias: None
Product: WHATWG
Classification: Unclassified
Component: HTML (show other bugs)
Version: unspecified
Hardware: PC All
: P2 normal
Target Milestone: Unsorted
Assignee: Ian 'Hixie' Hickson
QA Contact: contributor
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2012-11-24 12:15 UTC by Michael[tm] Smith
Modified: 2013-02-08 07:10 UTC (History)
2 users (show)

See Also:


Attachments

Description Michael[tm] Smith 2012-11-24 12:15:09 UTC
I think the "create an implied heading" steps in the outline algorithm could just be dropped.

The reason is: The only part of the algorithm that checks to see if any implied heading has been created is a part that says, "if the heading of the last section of the outline of the current outlinee is an implied heading". But that part could just as well be handled by not creating implied headings to begin with -- in which case a section that has no heading in the source will just have no heading in the outline. And so that part cited above could just be changed to read, "if the heading of the last section of the outline of the current outlinee has no heading".

Of course for the action of showing the outline (as opposed to building the outline) you want to be able to show something for the "implied heading" case. But you don't need to have an explicit "implied heading" indicator in the outline in order to do that; if a section has no heading at all in the outline, the action of showing the outline could just show "implied heading" (though as the spec suggests it's better of course to show something more specific like "Untitled section" or whatever).

Anyway, I think the "create an implied heading" steps in the current algorithm add nothing except potential confusion for implementors. In the implementation of the outline algorithm I'm working on for the validator, it's a noop. We handle the "if the heading of the last section of the outline of the current outlinee is an implied heading" by instead effectively just checking to see if that section has no heading.
Comment 1 Michael[tm] Smith 2012-11-24 12:34:14 UTC
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...".
Comment 2 Ian 'Hixie' Hickson 2013-02-06 22:29:25 UTC
<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?
Comment 3 Michael[tm] Smith 2013-02-07 09:01:35 UTC
(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]
Comment 4 Ian 'Hixie' Hickson 2013-02-08 02:51:07 UTC
(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.
Comment 5 Michael[tm] Smith 2013-02-08 05:57:02 UTC
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.
Comment 6 contributor 2013-02-08 07:06:54 UTC
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
Comment 7 Ian 'Hixie' Hickson 2013-02-08 07:10:38 UTC
I've added some examples to the spec to hopefully make this clearer.