Skip to content

Commit

Permalink
[e] (0) examples and xrefs in the outline section
Browse files Browse the repository at this point in the history 
git-svn-id: http://svn.whatwg.org/webapps@1749 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Jun 12, 2008
1 parent 6da4ca7 commit 503116b
Show file tree
Hide file tree
Showing 2 changed files with 287 additions and 161 deletions.
236 changes: 154 additions & 82 deletions index
View file
Expand Up @@ -9315,36 +9315,90 @@ isn't his only passion. He also enjoys other pleasures.</p>

<h5 id=outlines><span class=secno>3.7.10.1. </span>Creating an outline</h5>

<p>This section defines an algorithm for creating an <dfn
id=outline>outline</dfn> for a <a href="#sectioning0">sectioning
content</a> element or a <a href="#sectioning1">sectioning root</a>
element. It is defined in terms of a walk over the nodes of a DOM tree, in
tree order, with each node being visited when it is <i>entered</i> and
when it is <i>exited</i> during the walk.

<p>The outline for a <a href="#sectioning0">sectioning content</a> element
or a <a href="#sectioning1">sectioning root</a> element consists of a list
of one or more potentially nested sections. Each section can have one
heading associated with it. The algorithm for the outline also associates
each node in the DOM tree with a particular section and potentially a
heading. (The sections in the outline aren't <code><a
href="#section">section</a></code> elements, though some may correspond to
such elements &mdash; they are merely conceptual sections.)
<p>This section defines an algorithm for creating an outline for a <a
href="#sectioning0">sectioning content</a> element or a <a
href="#sectioning1">sectioning root</a> element. It is defined in terms of
a walk over the nodes of a DOM tree, in tree order, with each node being
visited when it is <i>entered</i> and when it is <i>exited</i> during the
walk.

<p>The <dfn id=outline>outline</dfn> for a <a
href="#sectioning0">sectioning content</a> element or a <a
href="#sectioning1">sectioning root</a> element consists of a list of one
or more potentially nested <a href="#section0"
title=concept-section>sections</a>. A <dfn id=section0
title=concept-section>section</dfn> is a container that corresponds to
some nodes in the original DOM tree. Each section can have one heading
associated with it, and can contain any number of further nested sections.
The algorithm for the outline also associates each node in the DOM tree
with a particular section and potentially a heading. (The sections in the
outline aren't <code><a href="#section">section</a></code> elements,
though some may correspond to such elements &mdash; they are merely
conceptual sections.)

<div class=example>
<p>The following markup fragment:</p>

<pre>&lt;body>
&lt;h1>A&lt;/h1>
&lt;p>B&lt;/p>
&lt;h2>C&lt;/h2>
&lt;p>D&lt;/p>
&lt;h2>E&lt;/h2>
&lt;p>F&lt;/p>
&lt;/body></pre>

<p>...results in the following outline being created for the <code><a
href="#body0">body</a></code> node (and thus the entire document):</p>

<ol class=brief>
<li>
<p>Section created for <code><a href="#body0">body</a></code> node.</p>

<p>Associated with heading "A".</p>

<p>Also associated with paragraph "B".</p>

<p>Nested sections:</p>

<ol class=brief>
<li>
<p>Section implied for first <code><a href="#h2">h2</a></code>
element.</p>

<p>Associated with heading "C".</p>

<p>Also associated with paragraph "D".</p>

<p>No nested sections.</p>

<li>
<p>Section implied for second <code><a href="#h2">h2</a></code>
element.</p>

<p>Associated with heading "E".</p>

<p>Also associated with paragraph "F".</p>

<p>No nested sections.</p>
</ol>
</ol>
</div>

<p>The algorithm that must be followed during a walk of a DOM subtree
rooted at a <a href="#sectioning0">sectioning content</a> element or a <a
href="#sectioning1">sectioning root</a> element to determine that
element's outline is as follows:
element's <a href="#outline">outline</a> is as follows:

<ol>
<li>
<p>Let <var title="">current outlinee</var> be null. (It holds the
element whose outline is being created.)
element whose <a href="#outline">outline</a> is being created.)

<li>
<p>Let <var title="">current section</var> be null. (It holds a pointer
to a section, so that elements in the DOM can all be associated with a
section.)
to a <a href="#section0" title=concept-section>section</a>, so that
elements in the DOM can all be associated with a section.)

<li>
<p>Create a stack to hold elements, which is used to handle nesting.
Expand Down Expand Up @@ -9381,12 +9435,14 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
<p>Let <var title="">current outlinee</var> be the element that is
being entered.</p>

<p>Let <var title="">current section</var> be a newly created section
for the <var title="">current outlinee</var> element.</p>
<p>Let <var title="">current section</var> be a newly created <a
href="#section0" title=concept-section>section</a> for the <var
title="">current outlinee</var> element.</p>

<p>Let there be a new outline for the new <var title="">current
outlinee</var>, initialized with just the new <var title="">current
section</var> as the only section in the outline.</p>
<p>Let there be a new <a href="#outline">outline</a> for the new <var
title="">current outlinee</var>, initialized with just the new <var
title="">current section</var> as the only <a href="#section0"
title=concept-section>section</a> in the outline.</p>

<dt>When exiting a <a href="#sectioning0">sectioning content</a>
element, if the stack is not empty
Expand All @@ -9396,12 +9452,13 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
title="">current outlinee</var> be that element.</p>

<p>Let <var title="">current section</var> be the last section in the
outline of the <var title="">current outlinee</var> element.</p>
<a href="#outline">outline</a> of the <var title="">current
outlinee</var> element.</p>

<p>Append the outline of the <a href="#sectioning0">sectioning
content</a> element being exited to the <var title="">current
section</var>. (This does not change which section is the last section
in the outline.)</p>
<p>Append the <a href="#outline">outline</a> of the <a
href="#sectioning0">sectioning content</a> element being exited to the
<var title="">current section</var>. (This does not change which
section is the last section in the <a href="#outline">outline</a>.)</p>

<dt>When exiting a <a href="#sectioning1">sectioning root</a> element,
if the stack is not empty
Expand All @@ -9416,15 +9473,17 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>

<li>
<p>Let <var title="">current section</var> be the last section in the
outline of the <var title="">current outlinee</var> element.
<a href="#outline">outline</a> of the <var title="">current
outlinee</var> element.

<li>
<p><i>Loop:</i> If <var title="">current section</var> has no child
sections, stop these steps.

<li>
<p>Let <var title="">current section</var> be the last child section
of the current <var title="">current section</var>.
<p>Let <var title="">current section</var> be the last child <a
href="#section0" title=concept-section>section</a> of the current
<var title="">current section</var>.

<li>
<p>Go back to the substep labeled <i>Loop</i>.
Expand All @@ -9437,8 +9496,10 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
<p class=note>The <var title="">current outlinee</var> is the element
being exited.</p>

<p>Let <var title="">current section</var> be the first section in the
outline of the <var title="">current outlinee</var> element.</p>
<p>Let <var title="">current section</var> be the first <a
href="#section0" title=concept-section>section</a> in the <a
href="#outline">outline</a> of the <var title="">current
outlinee</var> element.</p>

<p>Skip to the next step in the overall set of steps. (The walk is
over.)</p>
Expand All @@ -9455,13 +9516,15 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
element being entered be the heading for the <var title="">current
section</var>.</p>

<p>Otherwise, if the element being entered has a rank equal to or
greater than the heading of the <var title="">current section</var>,
then create a new section and append it to the outline of the <var
title="">current outlinee</var> element, so that this new section is
the new last section of that outline. Let <var title="">current
section</var> be that new section. Let the element being entered be
the new heading for the <var title="">current section</var>.</p>
<p>Otherwise, if the element being entered has a <a
href="#rank">rank</a> equal to or greater than the heading of the <var
title="">current section</var>, then create a new <a href="#section0"
title=concept-section>section</a> and append it to the <a
href="#outline">outline</a> of the <var title="">current
outlinee</var> element, so that this new section is the new last
section of that outline. Let <var title="">current section</var> be
that new section. Let the element being entered be the new heading for
the <var title="">current section</var>.</p>

<p>Otherwise, run these substeps:</p>

Expand All @@ -9471,18 +9534,21 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
section</var>.

<li>
<p>If the element being entered has a rank lower than the rank of the
heading of the <var title="">candidate section</var>, then create a
new section, and append it to <var title="">candidate section</var>.
(This does not change which section is the last section in the
outline.) Let <var title="">current section</var> be this new
section. Let the element being entered be the new heading for the
<var title="">current section</var>. Abort these substeps.</p>
<p>If the element being entered has a <a href="#rank">rank</a> lower
than the rank of the heading of the <var title="">candidate
section</var>, then create a new <a href="#section0"
title=concept-section>section</a>, and append it to <var
title="">candidate section</var>. (This does not change which
section is the last section in the outline.) Let <var
title="">current section</var> be this new section. Let the element
being entered be the new heading for the <var title="">current
section</var>. Abort these substeps.</p>

<li>
<p>Let <var title="">new candidate section</var> be the section that
contains <var title="">candidate section</var> in the outline of
<var title="">current outlinee</var>.
<p>Let <var title="">new candidate section</var> be the <a
href="#section0" title=concept-section>section</a> that contains
<var title="">candidate section</var> in the <a
href="#outline">outline</a> of <var title="">current outlinee</var>.

<li>
<p>Let <var title="">candidate section</var> be <var title="">new
Expand All @@ -9503,27 +9569,29 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>

<p id=associatedSection>In addition, whenever you exit a node, after
doing the steps above, if <var title="">current section</var> is not
null, associate the node with the section <var title="">current
section</var>.</p>
null, associate the node with the <a href="#section0"
title=concept-section>section</a> <var title="">current section</var>.</p>

<li>
<p>If the <var title="">current outlinee</var> is null, then there was no
<a href="#sectioning0">sectioning content</a> element or <a
href="#sectioning1">sectioning root</a> element in the DOM. There is no
outline. Abort these steps.
<a href="#outline">outline</a>. Abort these steps.

<li>
<p>Associate any nodes that were not associated a section in the steps
above with <var title="">current outlinee</var> as their section.
<p>Associate any nodes that were not associated a <a href="#section0"
title=concept-section>section</a> in the steps above with <var
title="">current outlinee</var> as their section.

<li>
<p>Associate all nodes with the heading of the section with which they
are associated, if any.
<p>Associate all nodes with the heading of the <a href="#section0"
title=concept-section>section</a> with which they are associated, if
any.

<li>
<p>If <var title="">current outlinee</var> is <a href="#the-body1">the
<code>body</code> element</a>, then the outline created for that element
is the outline of the entire document.
is the <a href="#outline">outline</a> of the entire document.
</ol>

<p>The tree of sections created by the algorithm above, or a proper subset
Expand All @@ -9532,14 +9600,16 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>

<p>When creating an interactive table of contents, entries should jump the
user to the relevant <a href="#sectioning0">sectioning content</a>
element, if the section was created for a real element in the original
document, or to the relevant <a href="#heading0">heading content</a>
element, if the section in the tree was generated for a heading in the
above process.

<p class=note>Selecting the first section of the document therefore always
takes the user to the top of the document, regardless of where the first
header in the <code><a href="#body0">body</a></code> is to be found.</p>
element, if the <a href="#section0" title=concept-section>section</a> was
created for a real element in the original document, or to the relevant <a
href="#heading0">heading content</a> element, if the <a href="#section0"
title=concept-section>section</a> in the tree was generated for a heading
in the above process.

<p class=note>Selecting the first <a href="#section0"
title=concept-section>section</a> of the document therefore always takes
the user to the top of the document, regardless of where the first header
in the <code><a href="#body0">body</a></code> is to be found.</p>
<!-- XXX assuming there is a body, anyway -->

<div class=note>
Expand Down Expand Up @@ -9580,24 +9650,25 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
sections created for <code><a href="#nav">nav</a></code> and <code><a
href="#aside">aside</a></code> elements, and any of their descendants, if
the only root of the tree is <a href="#the-body1">the <code>body</code>
element</a>'s section, and it has only a single subsection which is
created by an <code><a href="#article">article</a></code> element, then
the heading of <a href="#the-body1">the <code>body</code> element</a>
should be assumed to be a site-wide heading, and the heading of the
<code><a href="#article">article</a></code> element should be assumed to
be the page's heading.
element</a>'s <a href="#section0" title=concept-section>section</a>, and
it has only a single subsection which is created by an <code><a
href="#article">article</a></code> element, then the heading of <a
href="#the-body1">the <code>body</code> element</a> should be assumed to
be a site-wide heading, and the heading of the <code><a
href="#article">article</a></code> element should be assumed to be the
page's heading.

<p>If a page starts with a heading that is common to the whole site, the
document must be authored such that, in the document's <a
href="#outline">outline</a>, ignoring any sections created for <code><a
href="#nav">nav</a></code> and <code><a href="#aside">aside</a></code>
elements and any of their descendants, the tree has only one root section,
<a href="#the-body1">the <code>body</code> element</a>'s section, its
heading is the site-wide heading, <a href="#the-body1">the
<code>body</code> element</a> has just one subsection, that subsection is
created by an <code><a href="#article">article</a></code> element, and
that <code><a href="#article">article</a></code>'s heading is the page
heading.
elements and any of their descendants, the tree has only one root <a
href="#section0" title=concept-section>section</a>, <a
href="#the-body1">the <code>body</code> element</a>'s section, its heading
is the site-wide heading, <a href="#the-body1">the <code>body</code>
element</a> has just one subsection, that subsection is created by an
<code><a href="#article">article</a></code> element, and that <code><a
href="#article">article</a></code>'s heading is the page heading.

<p>If a page does not contain a site-wide heading, then the page must be
authored such that, in the document's <a href="#outline">outline</a>,
Expand All @@ -9606,8 +9677,9 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
descendants, either <a href="#the-body1">the <code>body</code> element</a>
has no subsections, or it has more than one subsection, or it has a single
subsection but that subsection is not created by an <code><a
href="#article">article</a></code> element, or there is more than one
section at the root of the outline.
href="#article">article</a></code> element, or there is more than one <a
href="#section0" title=concept-section>section</a> at the root of the
outline.

<p class=note>Conceptually, a site is thus a document with many articles
&mdash; when those articles are split into many pages, the heading of the
Expand Down

0 comments on commit 503116b

Please sign in to comment.