- From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 05 Jun 2009 22:17:58 +0000
- To: public-html-commits@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><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 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 —
+ 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
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><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!
Received on Friday, 5 June 2009 22:18:03 UTC