[whatwg] WA 1.0 - document outline suggestion

[ROBO Design]

Hello!

I see the WA 1.0 specification contains a great deal of prose describing  
in minute detail how to build a conforming document outline, based on  
sections and headings [1]. Very good.

Why not also add in DOM: document.outline ?

Maybe something similar has been suggested or maybe something regarding  
this will be added, but here's my proposal.

For example:

<h1 id="a">bla</h1>
   <p id="el1">Bla</p>
   <h2 id="b">bla</h2>
     <p id="el2">Bla</p>
     <h3 id="c">bla</h3>
        <p id="el3">Bla</p>
   <h2 id="d">bla</h2>
     <p id="el4">Bla</p>
   <h2 id="e">bla</h2>
     <p id="el5">Bla</h2>
<h1 id="f">bla</h1>
   <p id="el6">Bla</p>

Would have the document.outline:

document.outline.item(0) = document.getElementById("a")
document.outline.item(1) = document.getElementById("f")
document.outline.item(2) = null
document.outline[0].item(0) = document.getElementById("b")
document.outline[0].item(1) = document.getElementById("d")
document.outline[0].item(2) = document.getElementById("e")
document.outline[0][1].item(0) = document.getElementById("c")

(Disclamer: the above code may not be accurately outlined, even if I read  
the outlining algorithm ... it's a bit too much to remember. But ... the  
purpose of the suggestion is not the accuracy of my outline :)

I don't know how to represent the above in prose, but I believe the  
example is self describing enough (based on questions I can provide  
further details).

The document.outline could also provide means to jump to those headings,  
like document.outline.go(N) (and document.outline[N].go(N), etc).

If somebody likes complicated things: if N is not a number, it could be  
interpreted as item(str) and go(str). Parsing it like this:

document.outline.item("0 2") = document.getElementById("e")
document.outline.item("0KJ-1!@0") = document.getElementById("c")
document.outline[0].item("1*//*+0") = document.getElementById("c")

Any (multiple) non-number character(s) become(s) a single space character.

str = trim(str.replace(/[^0-9]+/, ' '));

(Disclaimer: the above is not JS, it's something hybrid.)

Then split on spaces.

Last, but not least ... the document.outline could also provide a "flat  
view" of the outline. Example based on the above code:

document.outline.flat(0) = document.outline.item(0)
document.outline.flat(1) = document.outline[0].item(0)
document.outline.flat(2) = document.outline[0].item(1)
document.outline.flat(3) = document.outline[0][1].item(0)
document.outline.flat(4) = document.outline[0].item(2)
document.outline.flat(5) = document.outline.item(1)

And .flat(N) should be available for each outline[N][N]...[N]. For example:

document.outline[0].flat(0) = document.outline[0].item(0)
document.outline[0].flat(1) = document.outline[0].item(1)
document.outline[0].flat(2) = document.outline[0][1].item(0)
document.outline[0].flat(3) = document.outline[0].item(2)

Next, add to HTMLElement (or maybe not to *all* HTML elements):

element.goHeading(N)
element.getHeading(N)

... where N is the heading depth. Consider this (based on the above sample  
code):

document.getElementById("el3").getHeading(1) = document.getElementById("c")
document.getElementById("el3").getHeading(2) = document.getElementById("b")
document.getElementById("el3").getHeading(3) = document.getElementById("a")

Negative values should be treated like this:

document.getElementById("el3").getHeading(-1) =  
document.getElementById("a")
document.getElementById("el3").getHeading(-2) =  
document.getElementById("b")
document.getElementById("el3").getHeading(-3) =  
document.getElementById("c")

getHeading(0) should return a HTMLCollection of all "parent headings",  
starting with the closest:

[0] = document.getElementById("c")
[1] = document.getElementById("b")
[2] = document.getElementById("a")

goHeading(N) works like getHeading(N), except it returns true if the  
browser found and scrolled to the heading, or false if the heading depth  
is too high/low.

goHeading(0) should scroll back to the element itself.

The section and heading that applies to a node can be determined by the  
already-defined algorithm [2].

I believe that there's an interest in document outlining since the  
editor(s) of the specification dedicated part of their time in writing  
2.5.11. section [1]. This is why I believe necessary to benefit web  
authors too.

The use case of the above for authors: easy way of providing an accurate  
table of contents to users, in page. They would no longer be required to  
write advanced, prone to errors, scripts to generate the TOC based on the  
algorithms described in the WA 1.0, nor they would be required to write  
easy scripts that can be easily broken :).

As a final conclusion: my suggestion as a whole may not be desired (at  
first), but it's like drag and drop, like menus and more. Table of  
contents are something you see very often. Each TOC has its own way today.  
Defining the algorithm of document outlining is actually something very  
good which tries to bring order. Having DOM manipulation of the outline  
would encourage authors to use the more accurate way of generating a TOC  
in page. I am also aware that parts of the suggestion might be exaggerated  
(like .item(str) and .flat(N)).

Some kind of disclaimer: I haven't got the time to read the entire  
specification. Pardon me if this is already covered by the specification.

Thank you for taking the time to read and reply :).


[1] http://www.whatwg.org/specs/web-apps/current-work/#headings
[2] http://www.whatwg.org/specs/web-apps/current-work/#determining0


-- 
http://www.robodesign.ro
ROBO Design - We bring you the future