Re: element.createOutline vs <outline> or <toc> [was: adding a note to 4.3.10.1 Creating an outline]

On Fri, Feb 28, 2014 at 9:58 PM, Robin Berjon <robin@w3.org> wrote:
> On 28/02/2014 02:38 , Silvia Pfeiffer wrote:
>>
>> On Fri, Feb 28, 2014 at 12:00 PM, Michael[tm] Smith <mike@w3.org> wrote:
>>>
>>> It's not clear to me exactly what the generated content of such an
>>> element
>>> would end up being. An <ol>? Or a <ul>? Or what? How would Web authors be
>>> able to style it? (Would the contents be a shadow DOM or.. what?)
>>
>>
>> It's no different to other composite elements with a shadow DOM. All
>> the <ol>, <ul> etc would be inside the control. It would be stylable
>> like other shadow dom objects (once we've figured that out).
>
>
> "Once we've figured that out" might be one of the most important parts of
> that paragraph :)
>
> Seriously, such an element would be quite complex. For instance, if a given
> section does not have an anchor, how would the link point to it?

You wouldn't. Obviously, the author didn't intent the ToC to be linked up.

> Do you get
> something that when clicked scrolls to the section but without navigating to
> the anchor?

It would navigate to the anchor like any other link that's being activated.

> Or do you generate an anchor and navigate to it? If the latter,
> what happens when you share the link?

Why would the sharing of this link be different to sharing any other
links with anchor references?

> We then need to have a predictable
> anchor-generating algorithm.
>
> That's not impossible, both ReSpec and Anolis have that. But it would have
> to rely on live content. So what happens if, say, the section heading is
> editable and you edit it. Does the generated anchor change? Does the URL
> change if that's where you happened to be?

Looking at a related example: Video controls menus change based on the
DOM content of the page, e.g. if a <track> element is added, the video
controls menu would add a menu entry. I think something similar would
happen here, too: any information used in the ToC that changes in the
DOM would also change in the ToC.

> Presumably, the titles in the generated ToC would come from the section
> titles. However, while it's fine to have:
>
>     <h2 id='x'>Using the <a href='#dfn-dahut'>Dahut</a> algorithm</h2>
>
> you can't well convert that to:
>
>     <li><a href='#x'>Using the <a href='#dfn-dahut'>Dahut</a>
> algorithm</a></li>
>
> So, you could take the textContent.

Yup.

> But that falls on its face for cases
> like:
>
>     <h2>The <code>video</code> element</h2>

That depends on whether you want the formatting to remain.

> At this point, you now need a content transformation step as part of your
> ToC generation. It's not just links, other things like IDs or <dfn> need to
> be replaced.

Right, you would probably only allow "formatting" elements to remain
in the innerHTML of the ToC items and list those: em, strong, small,
sub, sup, i, b, u, ruby and friends, bdi and bdo. That's probably it.

> What if the content is using CSS counters so that for instance the sections
> with class "appendix" get a counter reset (before the first one) and a
> switch to an alphabetic counter style. Do you carry over the generated
> counter content into the ToC?

Yes.

> If not, how do you have the ToC contain enough
> contextual information from the tree to be able to reproduce the same
> effect?
>
> Then you have performance. Imagine a document the size of single-page.html
> where some content can be dynamic (e.g. toggling the author view). You need
> to keep the ToC in sync, live. That's likely to have an impact.

Yes and the author would be very much aware of that.

> And wouldn't this introduce a Flash of UnToCed Content?

What do you mena?

> While the document
> is being parsed, do you update the <toc> every time a new section is found,
> or do you generate it only at the end when the full DOM has loaded? In both
> cases I think you'll get pretty unnatural effects.

Right. I think it would make sense to do it just before firing
onloaded and update after that.

I wasn't saying that it was going to be easy - in fact: I said to move
it to HTML5.1 because I think it will take a while to sort through all
the issues. Also, of course, we'd need implementer interest.


>>> And what precedents do we have for an element like <outline> or <toc>?
>>> (that is, one that would inject some text content into one part of a
>>> document by constructing it from some other parts of the  document)
>>
>>
>> Wikipedia (in fact: mediawiki more generally) is a cow path IMO. See
>> e.g. http://en.wikipedia.org/wiki/2014_Winter_Olympics .
>> The "Contents" section is not a section created by the Web page
>> developer, but auto-created (in this case: by the CMS).
>> __TOC__ is the markup used in mediawiki.
>
>
> But it's not *live* and it's not *automatic* in the browser. Some code
> generated it out of band and using its own conventions.

Right, but that's how we find use cases for new things for the spec:
Things that get done often enough in Websites to warrant them being
done by the UA for efficiency and standardisation. We had thousands of
different ways of doing date entry forms before, too - now we've
finally accepted the need and are standardising the input.


> That's a common use case. Tools like ReSpec and Anolis do it all the time.
> But having something live and fully generic is another issue altogether. I
> actually think that the best implementation of your idea might be a revival
> of the notion of DOM Views, placed inside something akin to a seamless
> iframe. But I don't think we're likely to head there.

I wasn't aware of DOM views - that's indeed an interesting
relationship to the current discussion. I see the use case for DOM
views having been satisfied by DOM inspectors nowadays. The result of
the outline algorithm can be regarded as a subset of the DOM, but with
manipulations. Mike's suggestion to expose that to JS devs only in the
first instance is definitely an easier first step. I do, however, like
the idea of eventually taking it further.


>> I think, though, that we have plenty of examples of sites using this
>> feature. And seeing that we already have the content for it from the
>> outline algorithm, it should be fairly logical how to build it
>> (including hyperlinks to page offsets to the outline elements if they
>> have an id tag).
>
>
> I agree that it's useful and there is a lot of usage, I just disagree that
> using an element is the right way to go about it. We should start with a
> method and after a few years of that if we do notice some specific usage
> patterns that justify an element, then we can pave that cow path.

Sure, you get no disagreement from me here! I was just exploring where
this can take us, going forward to something that has a visual
representation since that will bring out the issues even further (as
your email has confirmed :-).

Cheers,
Silvia.

Received on Sunday, 2 March 2014 05:34:20 UTC