Skip to content

Commit

Permalink
[e] (0) Add some examples of outlines.
Browse files Browse the repository at this point in the history 
Fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=20068
Affected topics: HTML

git-svn-id: http://svn.whatwg.org/webapps@7709 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Feb 8, 2013
1 parent cbfe8fe commit db6d58a
Show file tree
Hide file tree
Showing 3 changed files with 924 additions and 2 deletions.
289 changes: 288 additions & 1 deletion complete.html
View file
Expand Up @@ -481,7 +481,8 @@ <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 8 February 2013</
<li><a href=#the-address-element><span class=secno>4.4.10 </span>The <code>address</code> element</a></li>
<li><a href=#headings-and-sections><span class=secno>4.4.11 </span>Headings and sections</a>
<ol>
<li><a href=#outlines><span class=secno>4.4.11.1 </span>Creating an outline</a></ol></li>
<li><a href=#outlines><span class=secno>4.4.11.1 </span>Creating an outline</a></li>
<li><a href=#sample-outlines><span class=secno>4.4.11.2 </span>Sample outlines</a></ol></li>
<li><a href=#usage-summary-0><span class=secno>4.4.12 </span>Usage summary</a>
<ol>
<li><a href=#article-or-section?><span class=secno>4.4.12.1 </span>Article or section?</a></ol></ol></li>
Expand Down Expand Up @@ -17539,6 +17540,292 @@ <h5 id=outlines><span class=secno>4.4.11.1 </span>Creating an outline</h5>
</div>


<h5 id=sample-outlines><span class=secno>4.4.11.2 </span>Sample outlines</h5>

<p><i>This section is non-normative.</i></p>

<div class=example>

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

<pre>&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>

<p>This book would form the following outline:</p>

<ol class=brief><li> The Tax Book
<ol class=brief><li> Earning money
<ol class=brief><li> Getting a job
</ol><li> Spending money
<ol class=brief><li> Cheap things
<li> Expensive things
</ol><li> Investing money
<li> Losing money
<ol class=brief><li> Poor judgement
</ol></ol></ol><p>Notice that the <code><a href=#the-title-element>title</a></code> element does not participate in the outline.</p>

</div>

<div class=example>

<p>Here is a similar document, but this time using <code><a href=#the-section-element>section</a></code> elements to get the same
effect:</p>

<pre>&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>

<p>This book would form the same outline:</p>

<ol class=brief><li> The Tax Book
<ol class=brief><li> Earning money
<ol class=brief><li> Getting a job
</ol><li> Spending money
<ol class=brief><li> Cheap things
<li> Expensive things
</ol><li> Investing money
<li> Losing money
<ol class=brief><li> Poor judgement
</ol></ol></ol></div>

<div class=example>

<p>A document can contain multiple top-level headings:</p>

<pre>&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;Carambola&lt;/h1&gt;
&lt;p&gt;Star.&lt;/p&gt;</pre>

<p>This would form the following simple outline consisting of three top-level sections:</p>

<ol class=brief><li> Apples
<li> Bananas
<li> Carambola
</ol><p>Effectively, the <code><a href=#the-body-element>body</a></code> element is split into three.</p>

</div>

<div class=example>

<p>Mixing both the <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>&ndash;<code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h6</a></code> model and the
<code><a href=#the-section-element>section</a></code>/<code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code> model can lead to some unintuitive results.</p>

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

<pre>&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;Carambola&lt;/h1&gt;
&lt;p&gt;Star.&lt;/p&gt;
&lt;/section&gt;</pre>

<p>The resulting outline would be:</p>

<ol class=brief><li> <i>(untitled page)</i>
<ol class=brief><li> Apples
<li> Bananas
<li> Carambola
</ol></ol><p>This result is described as <i>unintuitive</i> because it results in three subsections even
though there's only one <code><a href=#the-section-element>section</a></code> element. Effectively, the <code><a href=#the-section-element>section</a></code> is
split into three, just like the implied <code><a href=#the-body-element>body</a></code> element in the previous example.</p>

<p>(In this example, "<i>(untitled page)</i>" is the implied heading for the <code><a href=#the-body-element>body</a></code>
element, since it has no explicit heading.)</p>

</div>

<div class=example>

<p>Headings never rise above other sections. Thus, in the following example, the first
<code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code> does not actually describe the page header; it describes the header for the
second half of the page:</p>

<pre>&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>

<p>The resulting outline would be:</p>

<ol class=brief><li> <i>(untitled page)</i>
<ol class=brief><li> A plea from our caretakers
</ol><li> Feathers
</ol></div>

<div class=example>

<p>Thus, when an <code><a href=#the-article-element>article</a></code> element starts with a <code><a href=#the-nav-element>nav</a></code> block and only later
has its heading, the result is that the <code><a href=#the-nav-element>nav</a></code> block is not part of the same section as
the rest of the <code><a href=#the-article-element>article</a></code> in the outline. For instance, take this document:</p>

<pre>&lt;!DOCTYPE HTML&gt;
&lt;title&gt;We're adopting a child! &mdash; Ray's blog&lt;/title&gt;
&lt;h1&gt;Ray's blog&lt;/h1&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;h1&gt;We're adopting a child!&lt;/h1&gt;
&lt;/header&gt;
&lt;main&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;/main&gt;
&lt;/article&gt;</pre>

<p>The resulting outline would be:</p>

<ol class=brief><li> Ray's blog
<ol class=brief><li> <i>Untitled article</i>
<ol class=brief><li> <i>Untitled navigation section</i>
</ol><li> We're adopting a child!
</ol></ol><p>Also worthy of note in this example is that the <code><a href=#the-header-element>header</a></code> and <code><a href=#the-main-element>main</a></code>
elements have no effect whatsoever on the document outline.</p>

</div>

<div class=example>

<p>The <code><a href=#the-hgroup-element>hgroup</a></code> element can be used for subheadings. For example:</p>

<pre>&lt;!DOCTYPE HTML&gt;
&lt;title&gt;Chronotype: CS Student&lt;/title&gt;
&lt;hgroup&gt;
&lt;h1&gt; The morning &lt;/h1&gt;
&lt;h2&gt; 06:00 to 12:00 &lt;/h2&gt;
&lt;/hgroup&gt;
&lt;p&gt;We sleep.&lt;/p&gt;
&lt;hgroup&gt;
&lt;h1&gt; The afternoon &lt;/h1&gt;
&lt;h2&gt; 12:00 to 18:00 &lt;/h2&gt;
&lt;/hgroup&gt;
&lt;p&gt;We study.&lt;/p&gt;
&lt;hgroup&gt;
&lt;h2&gt;Additional Commentary&lt;/h2&gt;
&lt;h3&gt;Because not all this is necessarily true&lt;/h3&gt;
&lt;h6&gt;Ok it's almost certainly not true&lt;/h6&gt;
&lt;/hgroup&gt;
&lt;p&gt;Yeah we probably play, rather than study.&lt;/p&gt;
&lt;hgroup&gt;
&lt;h1&gt; The evening &lt;/h1&gt;
&lt;h2&gt; 18:00 to 00:00 &lt;/h2&gt;
&lt;/hgroup&gt;
&lt;p&gt;We play.&lt;/p&gt;
&lt;hgroup&gt;
&lt;h1&gt; The night &lt;/h1&gt;
&lt;h2&gt; 00:00 to 06:00 &lt;/h2&gt;
&lt;/hgroup&gt;
&lt;p&gt;We play some more.&lt;/p&gt;</pre>

<p>The resulting outline would be:</p>

<ol class=brief><li> The morning <small>06:00 to 12:00</small>
<li> The afternoon <small>12:00 to 18:00</small>
<ol class=brief><li> Additional Commentary <small>Because not all this is necessarily true <small>Ok it's almost certainly not true</small></small>
</ol><li> The evening <small>18:00 to 00:00</small>
<li> The night <small>00:00 to 06:00</small>
</ol><p>Exactly how this is represented by user agents, as most interface issues, is left as a matter
of implementation preference, but the key part is that the <code><a href=#the-hgroup-element>hgroup</a></code>'s descendant
<code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>&ndash;<code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h6</a></code> elements are what form the element's heading. Thus, the
following would be equally valid:</p>

<ol class=brief><li> The morning &mdash; 06:00 to 12:00
<li> The afternoon &mdash; 12:00 to 18:00
<ol class=brief><li> Additional Commentary &mdash; Because not all this is necessarily true &mdash; Ok it's almost certainly not true
</ol><li> The evening &mdash; 18:00 to 00:00
<li> The night &mdash; 00:00 to 06:00
</ol><p>But so would the following:</p>

<ol class=brief><li> The morning
<li> The afternoon
<ol class=brief><li> Additional Commentary
</ol><li> The evening
<li> The night
</ol><p>The following would also be valid, though maybe less practical in most contexts:</p>

<ol class=brief><li> <p>The morning
<p> 06:00 to 12:00
<li> <p>The afternoon
<p> 12:00 to 18:00
<ol class=brief><li> <p> Additional Commentary
<p> Because not all this is necessarily true
<p> Ok it's almost certainly not true
</ol><li> <p>The evening
<p> 18:00 to 00:00
<li> <p>The night
<p> 00:00 to 06:00
</ol></div>


<h4 id=usage-summary-0><span class=secno>4.4.12 </span>Usage summary</h4>

Expand Down

0 comments on commit db6d58a

Please sign in to comment.