Skip to content
This repository has been archived by the owner on Jul 30, 2019. It is now read-only.

Commit

Permalink
removed outline code examples
Browse files Browse the repository at this point in the history 
these were confusing people.
  • Loading branch information
@stevefaulkner
stevefaulkner committed Jun 16, 2016
1 parent 149f96c commit 810198b
Showing 1 changed file with 1 addition and 254 deletions.
255 changes: 1 addition & 254 deletions sections/semantics-sections.include
View file
Expand Up @@ -1462,7 +1462,7 @@
cannot be relied upon to convey document structure to users. Authors should use heading <a>rank</a>
(<code>h1</code>-<code>h6</code>) to convey document structure.
</p>

<p><em>This section is non-normative</em></p>
<div class="impl">
This section defines an algorithm for creating an outline for a <a>sectioning content</a>
element or a <a>sectioning root</a> element. It is defined in terms of a walk over the nodes
Expand Down Expand Up @@ -1756,259 +1756,6 @@
</div>
</div>

<h5 id="sample-outlines">Sample outlines</h5>

<em>This section is non-normative.</em>

<div class="example">
The following document shows a straight-forward application of the <a>outline</a> algorithm.
First, here is the document, which is a book with very short chapters and subsections:

<pre highlight="html">
&lt;!DOCTYPE HTML&gt;
&lt;title&gt;The Tax Book (all in one page)&lt;/title&gt;
&lt;h1&gt;The Tax Book&lt;/h1&gt;
&lt;h2&gt;Earning money&lt;/h2&gt;
&lt;p&gt;Earning money is good.&lt;/p&gt;
&lt;h3&gt;Getting a job&lt;/h3&gt;
&lt;p&gt;To earn money you typically need a job.&lt;/p&gt;
&lt;h2&gt;Spending money&lt;/h2&gt;
&lt;p&gt;Spending is what money is mainly used for.&lt;/p&gt;
&lt;h3&gt;Cheap things&lt;/h3&gt;
&lt;p&gt;Buying cheap things often not cost-effective.&lt;/p&gt;
&lt;h3&gt;Expensive things&lt;/h3&gt;
&lt;p&gt;The most expensive thing is often not the most cost-effective either.&lt;/p&gt;
&lt;h2&gt;Investing money&lt;/h2&gt;
&lt;p&gt;You can lend your money to other people.&lt;/p&gt;
&lt;h2&gt;Losing money&lt;/h2&gt;
&lt;p&gt;If you spend money or invest money, sooner or later you will lose money.
&lt;h3&gt;Poor judgement&lt;/h3&gt;
&lt;p&gt;Usually if you lose money it's because you made a mistake.&lt;/p&gt;
</pre>

This book would form the following outline:

1. The Tax Book
1. Earning money
1. Getting a job
2. Spending money
1. Cheap things
2. Expensive things
3. Investing money
4. Losing money
1. Poor judgement

Notice that the <a element for="html"><code>title</code></a> element does not participate in the outline.
</div>

<div class="example">
Here is a similar document, but this time using <{section}> elements to get the same
effect:

<pre highlight="html">
&lt;!DOCTYPE HTML&gt;
&lt;title&gt;The Tax Book (all in one page)&lt;/title&gt;
&lt;h1&gt;The Tax Book&lt;/h1&gt;
&lt;section&gt;
&lt;h1&gt;Earning money&lt;/h1&gt;
&lt;p&gt;Earning money is good.&lt;/p&gt;
&lt;section&gt;
&lt;h1&gt;Getting a job&lt;/h1&gt;
&lt;p&gt;To earn money you typically need a job.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
&lt;section&gt;
&lt;h1&gt;Spending money&lt;/h1&gt;
&lt;p&gt;Spending is what money is mainly used for.&lt;/p&gt;
&lt;section&gt;
&lt;h1&gt;Cheap things&lt;/h1&gt;
&lt;p&gt;Buying cheap things often not cost-effective.&lt;/p&gt;
&lt;/section&gt;
&lt;section&gt;
&lt;h1&gt;Expensive things&lt;/h1&gt;
&lt;p&gt;The most expensive thing is often not the most cost-effective either.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
&lt;section&gt;
&lt;h1&gt;Investing money&lt;/h1&gt;
&lt;p&gt;You can lend your money to other people.&lt;/p&gt;
&lt;/section&gt;
&lt;section&gt;
&lt;h1&gt;Losing money&lt;/h1&gt;
&lt;p&gt;If you spend money or invest money, sooner or later you will lose money.
&lt;section&gt;
&lt;h1&gt;Poor judgement&lt;/h1&gt;
&lt;p&gt;Usually if you lose money it's because you made a mistake.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
</pre>

This book would form the same outline:

1. The Tax Book
1. Earning money
1. Getting a job
2. Spending money
1. Cheap things
2. Expensive things
3. Investing money
4. Losing money
1. Poor judgement
</div>

<div class="example">
A document can contain multiple top-level headings:

<pre highlight="html">
&lt;!DOCTYPE HTML&gt;
&lt;title&gt;Alphabetic Fruit&lt;/title&gt;
&lt;h1&gt;Apples&lt;/h1&gt;
&lt;p&gt;Pomaceous.&lt;/p&gt;
&lt;h1&gt;Bananas&lt;/h1&gt;
&lt;p&gt;Edible.&lt;/p&gt;
&lt;h1&gt;Oranges&lt;/h1&gt;
&lt;p&gt;Star.&lt;/p&gt;
</pre>

This would form the following simple outline consisting of three top-level sections:

1. Apples
2. Bananas
3. Oranges

Effectively, the <{body}> element is split into three.
</div>

<div class="example">
Mixing both the <code>h1</code>–<code>h6</code> model and the
<code>section</code>/<code>h1</code> model can lead to some unintuitive results.

Consider for example the following, which is just the previous example but with the contents
of the (implied) <code>body</code> wrapped in a <code>section</code>:

<pre highlight="html">
&lt;!DOCTYPE HTML&gt;
&lt;title&gt;Alphabetic Fruit&lt;/title&gt;
&lt;section&gt;
&lt;h1&gt;Apples&lt;/h1&gt;
&lt;p&gt;Pomaceous.&lt;/p&gt;
&lt;h1&gt;Bananas&lt;/h1&gt;
&lt;p&gt;Edible.&lt;/p&gt;
&lt;h1&gt;Oranges&lt;/h1&gt;
&lt;p&gt;Star.&lt;/p&gt;
&lt;/section&gt;
</pre>

The resulting outline would be:

1. <i>(untitled page)</i>
1. Apples
2. Bananas
3. Oranges

This result is described as <i>unintuitive</i> because it results in three subsections even
though there's only one <{section}> element. Effectively, the <code>section</code> is
split into three, just like the implied <{body}> element in the previous example.

(In this example, "<i>(untitled page)</i>" is the implied heading for the <code>body</code>
element, since it has no explicit heading.)
</div>

<div class="example">
Headings never rise above other sections. Thus, in the following example, the first
<code>h1</code> does not actually describe the page header; it describes the header for the
second half of the page:

<pre highlight="html">
&lt;!DOCTYPE HTML&gt;
&lt;title&gt;Feathers on The Site of Encyclopedic Knowledge&lt;/title&gt;
&lt;section&gt;
&lt;h1&gt;A plea from our caretakers&lt;/h1&gt;
&lt;p&gt;Please, we beg of you, send help! We're stuck in the server room!&lt;/p&gt;
&lt;/section&gt;
&lt;h1&gt;Feathers&lt;/h1&gt;
&lt;p&gt;Epidermal growths.&lt;/p&gt;
</pre>

The resulting outline would be:

1. <i>(untitled page)</i>
1. A plea from our caretakers
2. Feathers
</div>

<div class="example">
Thus, when an <{article}> element starts with a <{nav}> block and only later
has its heading, the result is that the <{nav}> block is not part of the same section
as the rest of the <{article}> in the outline. For instance, take this document:

<pre highlight="html">
&lt;!DOCTYPE HTML&gt;
&lt;title&gt;We're adopting a child! — Ray's blog&lt;/title&gt;
...

&lt;h1&gt;Ray's blog&lt;/h1&gt;

&lt;main&gt;
&lt;article&gt;
&lt;header&gt;
&lt;nav&gt;
&lt;a href="?t=-1d"&gt;Yesterday&lt;/a&gt;;
&lt;a href="?t=-7d"&gt;Last week&lt;/a&gt;;
&lt;a href="?t=-1m"&gt;Last month&lt;/a&gt;
&lt;/nav&gt;
&lt;/header&gt;
&lt;h2&gt;We're adopting a child!&lt;/h2&gt;

&lt;p&gt;As of today, Janine and I have signed the papers to become
the proud parents of baby Diane! We've been looking forward to
this day for weeks.&lt;/p&gt;
&lt;/article&gt;
&lt;/main&gt;
...
</pre>

The resulting outline would be:

1. Ray's blog
1. <i>Untitled article</i>
1. <i>Untitled navigation section</i>
2. We're adopting a child!

Also worthy of note in this example is that the <{header}> and <{main}>
elements have no effect whatsoever on the document outline.
</div>

<h5 id="exposing-outlines-to-users">Exposing outlines to users</h5>

User agents are encouraged to expose page outlines to users to aid in navigation. This is
especially true for non-visual media, e.g., screen readers.

However, to mitigate the difficulties that arise from authors misusing <a>sectioning content</a>,
user agents are also encouraged to offer a mode that navigates the page using
<a>heading content</a> alone.

<div class="example">
For instance, a user agent could map the arrow keys as follows:

: <kbd>Shift</kbd>+<kbd>← Left</kbd>
:: Go to previous section, including subsectons of previous sections

: <kbd>Shift</kbd>+<kbd>→ Right</kbd>
:: Go to next section, including subsections of the current section

: <kbd>Shift</kbd>+<kbd>↑ Up</kbd>
:: Go to parent section of the current section

: <kbd>Shift</kbd>+<kbd>↓ Down</kbd>
:: Go to next section, skipping subsections of the current section

Plus in addition, the user agent could map the <kbd>j</kbd> and
<kbd>k</kbd> keys to navigating to the previous or next element of
<a>heading content</a>, regardless of the section's outline depth and ignoring sections with no
headings.
</div>

<h4 id="sections-usage-summary">Usage summary</h4>

<em>This section is non-normative.</em>
Expand Down

0 comments on commit 810198b

Please sign in to comment.