Skip to content

Commit

Permalink
[at] (0) Make the 'Determining which heading and section applies to a…
Browse files Browse the repository at this point in the history 
… particular node' subsection redundant; fix up some cross-reference issues that were caused by the recent outline algorithm rewrite.

git-svn-id: http://svn.whatwg.org/webapps@1258 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Feb 27, 2008
1 parent 9c911bd commit 2ee6eee
Show file tree
Hide file tree
Showing 2 changed files with 96 additions and 499 deletions.
324 changes: 50 additions & 274 deletions index
View file
Original file line number Diff line number Diff line change
Expand Up @@ -462,12 +462,8 @@
<li><a href="#outlines"><span class=secno>3.8.10.1. </span>Creating
an outline</a>

<li><a href="#associatedSection"><span class=secno>3.8.10.2.
</span>Determining which heading and section applies to a
particular node</a>

<li><a href="#distinguishing"><span class=secno>3.8.10.3.
</span>Distinguishing site-wide headers from page headers</a>
<li><a href="#distinguishing"><span class=secno>3.8.10.2.
</span>Distinguishing site-wide headings from page headings</a>
</ul>
</ul>

Expand Down Expand Up @@ -2032,8 +2028,8 @@
conformance should act in accordance to the semantics of the documents
that they process.</p>

<p class=example>A tool that generates <span title="sections and
headings">document outlines</span> but increases the nesting level for
<p class=example>A tool that generates <a href="#outline"
title=outline>document outlines</a> but increases the nesting level for
each paragraph and does not increase the nesting level for each section
would not be conforming.</p>

Expand Down Expand Up @@ -8871,16 +8867,19 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>

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

<p>This section defines an algorithm for creating an outline for a
<span>sectioning content 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.</span>
<p>This section defines an algorithm for creating an <dfn
id=outline>outline</dfn> for a <span>sectioning content 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.</span>

<p>The outline for a <span>sectioning content 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 zero or one
heading associated with it.</span>
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.</span>

<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
Expand Down Expand Up @@ -9019,9 +9018,10 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
<p>Do nothing.
</dl>

<p>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>
<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>

<li>
<p>If the <var title="">current outlinee</var> is null, then there was no
Expand All @@ -9033,6 +9033,10 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
<p>Associate any nodes that were not associated a section in the steps
above with <var title="">current outlinee</var> as their section.

<li>
<p>Associate all nodes with the heading of the section which which they
are associated, if any.

<li>
<p>If <var title="">current outlinee</var> is <a href="#the-body0">the
<code>body</code> element</a>, then the outline created for that element
Expand Down Expand Up @@ -9086,269 +9090,41 @@ isn't his only passion. He also enjoys other pleasures.&lt;/p>
}</pre>
</div>

<h5 id=associatedSection><span class=secno>3.8.10.2. </span>Determining
which heading and section applies to a particular node</h5>

<p class=big-issue>This section will be rewritten at some point. The
algorithm likely won't change, but its description will be dramatically
simplified.

<p>Given a particular node, user agents must use the following algorithm,
<em>in the given order</em>, to determine which heading and section the
node is most closely associated with. The processing of this algorithm
must stop as soon as the associated section and heading are established
(even if they are established to be nothing).

<ol>
<li>If the node has an ancestor that is a <code><a
href="#header">header</a></code> element, then the associated heading is
the most distant such ancestor. The associated section is that <code><a
href="#header">header</a></code>'s associated section (i.e. repeat this
algorithm for that <code><a href="#header">header</a></code>).

<li>If the node has an ancestor that is an <code><a
href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> element, then
the associated heading is the most distant such ancestor. The associated
section is that heading's section (i.e. repeat this algorithm for that
heading element).

<li>If the node is an <code><a href="#h1">h1</a></code>-<code><a
href="#h6">h6</a></code> element or a <code><a
href="#header">header</a></code> element, then the associated heading is
the element itself. The UA must then generate the <a
href="#outlines">hypothetical section tree</a> described in the previous
section, rooted at the nearest section ancestor (or the <a
href="#root-element">root element</a> if there is no such ancestor). If
the parent of the heading in that hypothetical tree is an element in the
real document tree, then that element is the associated section.
Otherwise, there is no associated section element.

<li>If the node is an element of <a href="#sectioning0">sectioning
content</a>, then the associated section is itself. The UA must then
generate the <a href="#outlines">hypothetical section tree</a> described
in the previous section, rooted at the section itself. If the section
element, in that hypothetical tree, has a child element that is an
<code><a href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code>
element or a <code><a href="#header">header</a></code> element, then that
element is the associated heading. Otherwise, there is no associated
heading element.

<li>If the node is a <code><a href="#footer">footer</a></code> or <code><a
href="#address">address</a></code> element, then the associated section
is the nearest ancestor element of <a href="#sectioning0">sectioning
content</a>, if there is one. The node's associated heading is the same
as that element of <a href="#sectioning0">sectioning content</a>'s
associated heading (i.e. repeat this algorithm for that element of <a
href="#sectioning0">sectioning content</a>). If there is no ancestor
element of <a href="#sectioning0">sectioning content</a>, the element has
no associated section nor an associated heading.

<li>Otherwise, the node is just a normal node, and the document has to be
examined more closely to determine its section and heading. Create a view
rooted at the nearest ancestor element of <a
href="#sectioning0">sectioning content</a> (or the <a
href="#root-element">root element</a> if there is none) that has just
<code><a href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code>
elements, <code><a href="#header">header</a></code> elements, the node
itself, and elements of <a href="#sectioning0">sectioning content</a>
other than <code><a href="#blockquote">blockquote</a></code> elements.
(Descendants of any of the nodes in this view can be ignored, as can any
node later in the tree than the node in question, as the algorithm below
merely walks backwards up this view.)

<li>Let <var title="">n</var> be an iterator for this view, initialised at
the node in question.

<li>Let <var title="">c</var> be the current best candidate heading,
initially null, and initially not used. It is used when top-level heading
candidates are to be searched for (see below).

<li>Repeat these steps (which effectively goes backwards through the
node's previous siblings) until an answer is found:
<ol>
<li>If <var title="">n</var> points to a node with no previous sibling,
and <var title="">c</var> is null, then return the node's parent node
as the answer. If the node has no parent node, return null as the
answer.

<li>Otherwise, if <var title="">n</var> points to a node with no
previous sibling, return <var title="">c</var> as the answer.

<li>Adjust <var title="">n</var> so that it points to the previous
sibling of the current position.

<li>If <var title="">n</var> is pointing at an <code><a
href="#h1">h1</a></code> or <code><a href="#header">header</a></code>
element, then return that element as the answer.

<li>If <var title="">n</var> is pointing at an <code><a
href="#h2">h2</a></code>-<code><a href="#h6">h6</a></code> element, and
heading candidates are not being searched for, then return that element
as the answer.

<li>Otherwise, if <var title="">n</var> is pointing at an <code><a
href="#h2">h2</a></code>-<code><a href="#h6">h6</a></code> element, and
either <var title="">c</var> is still null, or <var title="">c</var> is
a heading of lower <a href="#rank">rank</a> than this one, then set
<var title="">c</var> to be this element, and continue going backwards
through the previous siblings.

<li>If <var title="">n</var> is pointing at an element of <a
href="#sectioning0">sectioning content</a>, then from this point on
top-level heading candidates are being searched for. (Specifically, we
are looking for the nearest top-level header for the current section.)
Continue going backwards through the previous siblings.
</ol>

<li>If the answer from the previous step (the loop) is null, which can
only happen if the node has no preceeding headings and is not contained
in an element of <a href="#sectioning0">sectioning content</a>, then
there is no associated heading and no associated section.

<li>Otherwise, if the answer from the earlier loop step is an element of
<a href="#sectioning0">sectioning content</a>, then the associated
section is that element and the associated heading is that element of <a
href="#sectioning0">sectioning content</a>'s associated heading (i.e.
repeat this algorithm for that section).

<li>Otherwise, if the answer from that same earlier step is an <code><a
href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> element or a
<code><a href="#header">header</a></code> element, then the associated
heading is that element and the associated section is that heading
element's associated section (i.e. repeat this algorithm for that
heading).
</ol>

<p class=note>Not all nodes have an associated header or section. For
example, if a section is implied, as when multiple headers are found in
one element of <a href="#sectioning0">sectioning content</a>, then a node
in that section has an anonymous associated section (its section is not
represented by a real element), and the algorithm above does not associate
that node with any particular element of <a href="#sectioning0">sectioning
content</a>.

<div class=example>
<p>For the following fragment:</p>

<pre>&lt;body&gt;
&lt;h1&gt;X&lt;/h1&gt;
&lt;h2&gt;X&lt;/h2&gt;
&lt;blockquote&gt;
&lt;h3&gt;X&lt;/h3&gt;
&lt;/blockquote&gt;
&lt;p id="a"&gt;X&lt;/p&gt;
&lt;h4&gt;Text Node A&lt;/h4&gt;
&lt;section&gt;
&lt;h5&gt;X&lt;/h5&gt;
&lt;/section&gt;
&lt;p&gt;Text Node B&lt;/p&gt;
&lt;/body&gt;</pre>

<p>The associations are as follows (not all associations are shown):</p>

<table>
<thead>
<tr>
<th>Node

<th>Associated heading

<th>Associated section

<tbody>
<tr>
<td><code>&lt;body&gt;</code>

<td><code>&lt;h1&gt;</code>

<td><code>&lt;body&gt;</code>

<tr>
<td><code>&lt;h1&gt;</code>

<td><code>&lt;h1&gt;</code>

<td><code>&lt;body&gt;</code>

<tr>
<td><code>&lt;h2&gt;</code>

<td><code>&lt;h2&gt;</code>

<td>None.

<tr>
<td><code>&lt;blockquote&gt;</code>

<td><code>&lt;h2&gt;</code>

<td>None.

<tr>
<td><code>&lt;h3&gt;</code>

<td><code>&lt;h3&gt;</code>

<td><code>&lt;blockquote&gt;</code>

<tr>
<td><code>&lt;p id="a"&gt;</code>

<td><code>&lt;h2&gt;</code>

<td>None.

<tr>
<td><code>Text Node A</code>

<td><code>&lt;h4&gt;</code>

<td>None.

<tr>
<td><code>Text Node B</code>

<td><code>&lt;h1&gt;</code>

<td><code>&lt;body&gt;</code>
</table>
</div>

<h5 id=distinguishing><span class=secno>3.8.10.3. </span>Distinguishing
site-wide headers from page headers</h5>
<h5 id=distinguishing><span class=secno>3.8.10.2. </span>Distinguishing
site-wide headings from page headings</h5>

<p>Given the <a href="#outlines">hypothetical section tree</a>, but
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, if the root of the tree is <a href="#the-body0">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 header of <a
href="#the-body0">the <code>body</code> element</a> should be assumed to
be a site-wide header, and the header of the <code><a
href="#article">article</a></code> element should be assumed to be the
page's header.
<p>Given the <a href="#outline">outline</a> of a document, but 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, if
the only root of the tree is <a href="#the-body0">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-body0">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="#outlines">hypothetical section tree</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
root of the tree is <a href="#the-body0">the <code>body</code>
element</a>'s section, its heading is the site-wide heading, <a
href="#the-body0">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 header is the page heading.
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-body0">the <code>body</code> element</a>'s section, its
heading is the site-wide heading, <a href="#the-body0">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="#outlines">hypothetical
section tree</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, either <a href="#the-body0">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.
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, either <a href="#the-body0">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.

<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
Loading

0 comments on commit 2ee6eee

Please sign in to comment.