[e] (0) Try to make the paragraphs section more understandable.

git-svn-id: http://svn.whatwg.org/webapps@3200 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Jun 5, 2009 · 781cc7b · 781cc7b
1 parent 8991eef
commit 781cc7b
Show file tree

Hide file tree

Showing 2 changed files with 107 additions and 77 deletions.
diff --git a/index b/index
@@ -304,7 +304,7 @@
      <li><a href=#dom-feature-strings><span class=secno>2.9.7 </span>DOM feature strings</a></li>
      <li><a href=#exceptions><span class=secno>2.9.8 </span>Exceptions</a></li>
      <li><a href=#garbage-collection><span class=secno>2.9.9 </span>Garbage collection</a></ol></ol></li>
- <li><a href=#dom><span class=secno>3 </span>Semantics and structure of HTML documents</a>
+ <li><a href=#dom><span class=secno>3 </span>Semantics, structure, and APIs of HTML documents</a>
   <ol>
    <li><a href=#semantics-intro><span class=secno>3.1 </span>Introduction</a></li>
    <li><a href=#documents><span class=secno>3.2 </span>Documents</a>
@@ -7138,7 +7138,7 @@ interface <dfn id=domstringmap-0>DOMStringMap</dfn> {};</pre>
 
 
 
-  <h2 id=dom><span class=secno>3 </span>Semantics and structure of HTML documents</h2>
+  <h2 id=dom><span class=secno>3 </span>Semantics, structure, and APIs of HTML documents</h2>
 
   <h3 id=semantics-intro><span class=secno>3.1 </span>Introduction</h3>
 
@@ -9172,22 +9172,66 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0
 
   <h3 id=paragraphs><span class=secno>3.5 </span>Paragraphs</h3>
 
-  <p>A <dfn id=paragraph>paragraph</dfn> is typically a block of text with one or more
-  sentences that discuss a particular topic, as in typography, but can
-  also be used for more general thematic grouping. For instance, an
-  address is also a paragraph, as is a part of a form, a byline, or a
-  stanza in a poem.</p>
+  <p class=note>The term <a href=#paragraph>paragraph</a> as defined in this
+  section is distinct from (though related to) the <code><a href=#the-p-element>p</a></code>
+  element defined later. The <a href=#paragraph>paragraph</a> concept defined
+  here is used to describe how to interpret documents.</p>
+
+  <p>A <dfn id=paragraph>paragraph</dfn> is typically a run of <a href=#phrasing-content-0>phrasing
+  content</a> that forms a block of text with one or more sentences
+  that discuss a particular topic, as in typography, but can also be
+  used for more general thematic grouping. For instance, an address is
+  also a paragraph, as is a part of a form, a byline, or a stanza in a
+  poem.</p>
+
+  <div class=example>
+
+   <p>In the following example, there are two paragraphs in a
+   section. There is also a heading, which contains phrasing content
+   that is not a paragraph. Note how the comments and
+   <a href=#inter-element-whitespace>inter-element whitespace</a> do not form paragraphs.</p>
+
+   <pre>&lt;section&gt;
+  &lt;h1&gt;Example of paragraphs&lt;/h1&gt;
+  This is the &lt;em&gt;first&lt;/em&gt; paragraph in this example.
+  &lt;p&gt;This is the second.&lt;/p&gt;
+  &lt;!-- This is not a paragraph. --&gt;
+&lt;/section&gt;</pre>
+
+  </div>
 
   <p>Paragraphs in <a href=#flow-content-0>flow content</a> are defined relative to
   what the document looks like without the <code><a href=#the-a-element>a</a></code>,
   <code><a href=#the-ins-element>ins</a></code>, <code><a href=#the-del-element>del</a></code>, and <code><a href=#the-map-element>map</a></code> elements
   complicating matters, since those elements, with their hybrid
-  content models, can straddle paragraph boundaries.</p>
+  content models, can straddle paragraph boundaries, as shown in the
+  first two examples below.</p>
 
   <p class=note>Generally, having elements straddle paragraph
   boundaries is best avoided. Maintaining such markup can be
   difficult.</p>
 
+  <div class=example>
+
+   <p>The following example takes the markup from the earlier example
+   and puts <code><a href=#the-ins-element>ins</a></code> and <code><a href=#the-del-element>del</a></code> elements around some
+   of the markup to show that the text was changed (though in this
+   case, the changes admittedly don't make much sense). Notice how
+   this example has exactly the same paragraphs as the previous one,
+   despite the <code><a href=#the-ins-element>ins</a></code> and <code><a href=#the-del-element>del</a></code> elements &mdash;
+   the <code><a href=#the-ins-element>ins</a></code> element straddles the heading and the first
+   paragraph, and the <code><a href=#the-del-element>del</a></code> element straddles the boundary
+   between the two paragraphs.</p>
+
+   <pre>&lt;section&gt;
+  &lt;ins&gt;&lt;h1&gt;Example of paragraphs&lt;/h1&gt;
+  This is the &lt;em&gt;first&lt;/em&gt; paragraph in&lt;/ins&gt; this example&lt;del&gt;.
+  &lt;p&gt;This is the second.&lt;/p&gt;&lt;/del&gt;
+  &lt;!-- This is not a paragraph. --&gt;
+&lt;/section&gt;</pre>
+
+  </div>
+
   <div class=impl>
 
   <p>Let <var title="">view</var> be a view of the DOM that replaces
@@ -9221,41 +9265,12 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0
   other than phrasing content to separate the paragraphs from each
   other.</p>
 
-  <div class=example>
-
-   <p>In the following example, there are two paragraphs in a
-   section. There is also a heading, which contains phrasing content
-   that is not a paragraph. Note how the comments and
-   <a href=#inter-element-whitespace>inter-element whitespace</a> do not form paragraphs.</p>
-
-   <pre>&lt;section&gt;
-  &lt;h1&gt;Example of paragraphs&lt;/h1&gt;
-  This is the &lt;em&gt;first&lt;/em&gt; paragraph in this example.
-  &lt;p&gt;This is the second.&lt;/p&gt;
-  &lt;!-- This is not a paragraph. --&gt;
-&lt;/section&gt;</pre>
-
-   <p>The following example takes that markup and puts
-   <code><a href=#the-ins-element>ins</a></code> and <code><a href=#the-del-element>del</a></code> elements around some of the
-   markup to show that the text was changed (though in this case, the
-   changes admittedly don't make much sense). Notice how this example
-   has exactly the same paragraphs as the previous one, despite the
-   <code><a href=#the-ins-element>ins</a></code> and <code><a href=#the-del-element>del</a></code> elements.</p>
-
-   <pre>&lt;section&gt;
-  &lt;ins&gt;&lt;h1&gt;Example of paragraphs&lt;/h1&gt;
-  This is the &lt;em&gt;first&lt;/em&gt; paragraph in&lt;/ins&gt; this example&lt;del&gt;.
-  &lt;p&gt;This is the second.&lt;/p&gt;&lt;/del&gt;
-  &lt;!-- This is not a paragraph. --&gt;
-&lt;/section&gt;</pre>
-
-  </div>
-
   <div class=example>
 
    <p>In the following example, the link spans half of the first
    paragraph, all of the heading separating the two paragraphs, and
-   half of the second paragraph.</p>
+   half of the second paragraph. It straddles the paragraphs and the
+   heading.</p>
 
    <pre>&lt;aside&gt;
  Welcome!

diff --git a/source b/source
@@ -7201,7 +7201,7 @@ interface <dfn>DOMStringMap</dfn> {};</pre>
 
 
 
-  <h2 id="dom">Semantics and structure of HTML documents</h2>
+  <h2 id="dom">Semantics, structure, and APIs of HTML documents</h2>
 
   <h3 id="semantics-intro">Introduction</h3>
 
@@ -9495,22 +9495,66 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0
 
   <h3>Paragraphs</h3>
 
-  <p>A <dfn>paragraph</dfn> is typically a block of text with one or more
-  sentences that discuss a particular topic, as in typography, but can
-  also be used for more general thematic grouping. For instance, an
-  address is also a paragraph, as is a part of a form, a byline, or a
-  stanza in a poem.</p>
+  <p class="note">The term <span>paragraph</span> as defined in this
+  section is distinct from (though related to) the <code>p</code>
+  element defined later. The <span>paragraph</span> concept defined
+  here is used to describe how to interpret documents.</p>
+
+  <p>A <dfn>paragraph</dfn> is typically a run of <span>phrasing
+  content</span> that forms a block of text with one or more sentences
+  that discuss a particular topic, as in typography, but can also be
+  used for more general thematic grouping. For instance, an address is
+  also a paragraph, as is a part of a form, a byline, or a stanza in a
+  poem.</p>
+
+  <div class="example">
+
+   <p>In the following example, there are two paragraphs in a
+   section. There is also a heading, which contains phrasing content
+   that is not a paragraph. Note how the comments and
+   <span>inter-element whitespace</span> do not form paragraphs.</p>
+
+   <pre>&lt;section>
+  &lt;h1>Example of paragraphs&lt;/h1>
+  This is the &lt;em>first&lt;/em> paragraph in this example.
+  &lt;p>This is the second.&lt;/p>
+  &lt;!-- This is not a paragraph. -->
+&lt;/section></pre>
+
+  </div>
 
   <p>Paragraphs in <span>flow content</span> are defined relative to
   what the document looks like without the <code>a</code>,
   <code>ins</code>, <code>del</code>, and <code>map</code> elements
   complicating matters, since those elements, with their hybrid
-  content models, can straddle paragraph boundaries.</p>
+  content models, can straddle paragraph boundaries, as shown in the
+  first two examples below.</p>
 
   <p class="note">Generally, having elements straddle paragraph
   boundaries is best avoided. Maintaining such markup can be
   difficult.</p>
 
+  <div class="example">
+
+   <p>The following example takes the markup from the earlier example
+   and puts <code>ins</code> and <code>del</code> elements around some
+   of the markup to show that the text was changed (though in this
+   case, the changes admittedly don't make much sense). Notice how
+   this example has exactly the same paragraphs as the previous one,
+   despite the <code>ins</code> and <code>del</code> elements &mdash;
+   the <code>ins</code> element straddles the heading and the first
+   paragraph, and the <code>del</code> element straddles the boundary
+   between the two paragraphs.</p>
+
+   <pre>&lt;section>
+  &lt;ins>&lt;h1>Example of paragraphs&lt;/h1>
+  This is the &lt;em>first&lt;/em> paragraph in&lt;/ins> this example&lt;del>.
+  &lt;p>This is the second.&lt;/p>&lt;/del>
+  &lt;!-- This is not a paragraph. -->
+&lt;/section></pre>
+
+  </div>
+
   <div class="impl">
 
   <p>Let <var title="">view</var> be a view of the DOM that replaces
@@ -9544,41 +9588,12 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0
   other than phrasing content to separate the paragraphs from each
   other.</p>
 
-  <div class="example">
-
-   <p>In the following example, there are two paragraphs in a
-   section. There is also a heading, which contains phrasing content
-   that is not a paragraph. Note how the comments and
-   <span>inter-element whitespace</span> do not form paragraphs.</p>
-
-   <pre>&lt;section>
-  &lt;h1>Example of paragraphs&lt;/h1>
-  This is the &lt;em>first&lt;/em> paragraph in this example.
-  &lt;p>This is the second.&lt;/p>
-  &lt;!-- This is not a paragraph. -->
-&lt;/section></pre>
-
-   <p>The following example takes that markup and puts
-   <code>ins</code> and <code>del</code> elements around some of the
-   markup to show that the text was changed (though in this case, the
-   changes admittedly don't make much sense). Notice how this example
-   has exactly the same paragraphs as the previous one, despite the
-   <code>ins</code> and <code>del</code> elements.</p>
-
-   <pre>&lt;section>
-  &lt;ins>&lt;h1>Example of paragraphs&lt;/h1>
-  This is the &lt;em>first&lt;/em> paragraph in&lt;/ins> this example&lt;del>.
-  &lt;p>This is the second.&lt;/p>&lt;/del>
-  &lt;!-- This is not a paragraph. -->
-&lt;/section></pre>
-
-  </div>
-
   <div class="example">
 
    <p>In the following example, the link spans half of the first
    paragraph, all of the heading separating the two paragraphs, and
-   half of the second paragraph.</p>
+   half of the second paragraph. It straddles the paragraphs and the
+   heading.</p>
 
    <pre>&lt;aside>
  Welcome!