W3C home > Mailing lists > Public > public-html-commits@w3.org > June 2009

html5/spec Overview.html,1.2352,1.2353

From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
Date: Fri, 05 Jun 2009 22:17:58 +0000
To: public-html-commits@w3.org
Message-Id: <E1MChja-00020X-4g@lionel-hutz.w3.org>
Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv7703

Modified Files:
	Overview.html 
Log Message:
Try to make the paragraphs section more understandable. (whatwg r3200)

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.2352
retrieving revision 1.2353
diff -u -d -r1.2352 -r1.2353
--- Overview.html	5 Jun 2009 19:00:31 -0000	1.2352
+++ Overview.html	5 Jun 2009 22:17:53 -0000	1.2353
@@ -368,7 +368,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>
@@ -6498,7 +6498,7 @@
 
   </div>
 
-  </div><h2 id="dom"><span class="secno">3 </span>Semantics and structure of HTML documents</h2><h3 id="semantics-intro"><span class="secno">3.1 </span>Introduction</h3><p><em>This section is non-normative.</em><p class="XXX">An introduction to marking up a document.<h3 id="documents"><span class="secno">3.2 </span>Documents</h3><p>Every XML and HTML document in an HTML UA is represented by a
+  </div><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><p><em>This section is non-normative.</em><p class="XXX">An introduction to marking up a document.<h3 id="documents"><span class="secno">3.2 </span>Documents</h3><p>Every XML and HTML document in an HTML UA is represented by a
   <code>Document</code> object. <a href="#references">[DOM3CORE]</a><p><dfn id="the-document-s-address">The document's address</dfn> is an <a href="#absolute-url">absolute URL</a>
   that is set when the <code>Document</code> is created. <dfn id="the-document-s-current-address">The
   document's current address</dfn> is an <a href="#absolute-url">absolute URL</a>
@@ -8167,17 +8167,55 @@
   element, by the children in the "transparent" part of their content
   model, retaining order.<p>When a transparent element has no parent, then the part of its
   content model that is "transparent" must instead be treated as
-  accepting any <a href="#flow-content-0">flow content</a>.<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>Paragraphs in <a href="#flow-content-0">flow content</a> are defined relative to
+  accepting any <a href="#flow-content-0">flow content</a>.<h3 id="paragraphs"><span class="secno">3.5 </span>Paragraphs</h3><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>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.<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 class="note">Generally, having elements straddle paragraph
+  content models, can straddle paragraph boundaries, as shown in the
+  first two examples below.<p class="note">Generally, having elements straddle paragraph
   boundaries is best avoided. Maintaining such markup can be
-  difficult.<div class="impl">
+  difficult.<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
   all <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
@@ -8206,37 +8244,10 @@
   other than phrasing content to separate the paragraphs from each
   other.<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!
Received on Friday, 5 June 2009 22:18:03 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Friday, 5 June 2009 22:18:04 GMT