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

whatwg at whatwg.org whatwg at whatwg.org
Fri Jun 5 15:17:49 PDT 2009


Author: ianh
Date: 2009-06-05 15:17:48 -0700 (Fri, 05 Jun 2009)
New Revision: 3200

Modified:
   index
   source
Log:
[e] (0) Try to make the paragraphs section more understandable.

Modified: index
===================================================================
--- index	2009-06-05 19:00:23 UTC (rev 3199)
+++ index	2009-06-05 22:17:48 UTC (rev 3200)
@@ -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 @@
 
 
 
-  <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 @@
 
   <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><section>
+  <h1>Example of paragraphs</h1>
+  This is the <em>first</em> paragraph in this example.
+  <p>This is the second.</p>
+  <!-- This is not a paragraph. -->
+</section></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 —
+   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><section>
+  <ins><h1>Example of paragraphs</h1>
+  This is the <em>first</em> paragraph in</ins> this example<del>.
+  <p>This is the second.</p></del>
+  <!-- This is not a paragraph. -->
+</section></pre>
+
+  </div>
+
   <div class=impl>
 
   <p>Let <var title="">view</var> be a view of the DOM that replaces
@@ -9223,39 +9267,10 @@
 
   <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><section>
-  <h1>Example of paragraphs</h1>
-  This is the <em>first</em> paragraph in this example.
-  <p>This is the second.</p>
-  <!-- This is not a paragraph. -->
-</section></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><section>
-  <ins><h1>Example of paragraphs</h1>
-  This is the <em>first</em> paragraph in</ins> this example<del>.
-  <p>This is the second.</p></del>
-  <!-- This is not a paragraph. -->
-</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><aside>
  Welcome!

Modified: source
===================================================================
--- source	2009-06-05 19:00:23 UTC (rev 3199)
+++ source	2009-06-05 22:17:48 UTC (rev 3200)
@@ -7201,7 +7201,7 @@
 
 
 
-  <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 @@
 
   <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><section>
+  <h1>Example of paragraphs</h1>
+  This is the <em>first</em> paragraph in this example.
+  <p>This is the second.</p>
+  <!-- This is not a paragraph. -->
+</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 —
+   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><section>
+  <ins><h1>Example of paragraphs</h1>
+  This is the <em>first</em> paragraph in</ins> this example<del>.
+  <p>This is the second.</p></del>
+  <!-- This is not a paragraph. -->
+</section></pre>
+
+  </div>
+
   <div class="impl">
 
   <p>Let <var title="">view</var> be a view of the DOM that replaces
@@ -9546,39 +9590,10 @@
 
   <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><section>
-  <h1>Example of paragraphs</h1>
-  This is the <em>first</em> paragraph in this example.
-  <p>This is the second.</p>
-  <!-- This is not a paragraph. -->
-</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><section>
-  <ins><h1>Example of paragraphs</h1>
-  This is the <em>first</em> paragraph in</ins> this example<del>.
-  <p>This is the second.</p></del>
-  <!-- This is not a paragraph. -->
-</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><aside>
  Welcome!




More information about the Commit-Watchers mailing list