[e] (0) Work on the intro section to make it more approachable.

git-svn-id: http://svn.whatwg.org/webapps@3440 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Jul 17, 2009 · 2ff737f · 2ff737f
1 parent 285de89
commit 2ff737f
Show file tree

Hide file tree

Showing 2 changed files with 101 additions and 32 deletions.
diff --git a/index b/index
@@ -1424,10 +1424,10 @@
 &lt;/html&gt;</pre>
 
   <p>HTML documents consist of a tree of elements and text. Each
-  element is denoted by a <a href=#syntax-start-tag title=syntax-start-tag>start
-  tag</a>, such as "<code title="">&lt;body&gt;</code>", and an <a href=#syntax-end-tag title=syntax-end-tag>end tag</a>, such as "<code title="">&lt;/body&gt;</code>". (Certain start tags and end tags can in
-  certain cases be <a href=#syntax-tag-omission title=syntax-tag-omission>omitted</a>
-  and are implied by other tags.)</p>
+  element is denoted in the source by a <a href=#syntax-start-tag title=syntax-start-tag>start tag</a>, such as "<code title="">&lt;body&gt;</code>", and an <a href=#syntax-end-tag title=syntax-end-tag>end
+  tag</a>, such as "<code title="">&lt;/body&gt;</code>". (Certain
+  start tags and end tags can in certain cases be <a href=#syntax-tag-omission title=syntax-tag-omission>omitted</a> and are implied by other
+  tags.)</p>
 
   <p>Tags have to be nested such that elements are all completely
   within each other, without overlapping:</p>
@@ -1461,31 +1461,64 @@
 &lt;input name=address maxlength='200'&gt;
 &lt;input name=address maxlength="200"&gt;</pre>
 
-  <hr><p>The tree formed by an HTML document in this way is turned into a
-  DOM tree when parsed. This DOM tree can then be manipulated from
-  scripts. Since DOM trees are the "live" representation of an HTML
-  document, this specification is mostly phrased in terms of DOM
-  trees, instead of the serialisation described above.</p>
+  <p>HTML user agents (e.g. Web browsers) then <i>parse</i> this
+  markup, turning it into a DOM (Document Object Model) tree. A DOM
+  tree is an in-memory representation of a document.</p>
 
-  <p>The markup snippet at the top of this section represents the
-  following DOM tree:</p>
+  <p>DOM trees contain several kinds of nodes, in particular a DOCTYPE
+  node, elements, text nodes, and comment nodes.</p>
 
-  <ul class=domTree><li class=t10>DOCTYPE: <code><a href=#the-html-element>html</a></code><li class=t1><code><a href=#the-html-element>html</a></code><ul><li class=t1><code><a href=#the-head-element>head</a></code><ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9251;</span><li class=t1><code><a href=#the-title-element>title</a></code><ul><li class=t3><code>#text</code>: <span title="">Sample page</span></ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;</span></ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;</span><li class=t1><code><a href=#the-body-element>body</a></code><ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9251;</span><li class=t1><code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code><ul><li class=t3><code>#text</code>: <span title="">Sample page</span></ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9251;</span><li class=t1><code><a href=#the-p-element>p</a></code><ul><li class=t3><code>#text</code>: <span title="">This is a </span><li class=t1><code><a href=#the-a-element>a</a></code> <span class=t2 title=""><code class="attribute name">href</code>="<code class="attribute value">demo.html</code>"</span><ul><li class=t3><code>#text</code>: <span title="">simple</span></ul><li class=t3><code>#text</code>: <span title=""> sample.</span></ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9251;</span><li class=t8><code>#comment</code>: <span title=""> this is a comment </span><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9166;</span></ul></ul></ul><p>There are many more text nodes in the DOM tree than one would
+  <p>The markup snippet at the top of this section would be turned
+  into the following DOM tree:</p>
+
+  <ul class=domTree><li class=t10>DOCTYPE: <code><a href=#the-html-element>html</a></code><li class=t1><code><a href=#the-html-element>html</a></code><ul><li class=t1><code><a href=#the-head-element>head</a></code><ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9251;</span><li class=t1><code><a href=#the-title-element>title</a></code><ul><li class=t3><code>#text</code>: <span title="">Sample page</span></ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;</span></ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;</span><li class=t1><code><a href=#the-body-element>body</a></code><ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9251;</span><li class=t1><code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code><ul><li class=t3><code>#text</code>: <span title="">Sample page</span></ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9251;</span><li class=t1><code><a href=#the-p-element>p</a></code><ul><li class=t3><code>#text</code>: <span title="">This is a </span><li class=t1><code><a href=#the-a-element>a</a></code> <span class=t2 title=""><code class="attribute name">href</code>="<code class="attribute value">demo.html</code>"</span><ul><li class=t3><code>#text</code>: <span title="">simple</span></ul><li class=t3><code>#text</code>: <span title=""> sample.</span></ul><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9251;</span><li class=t8><code>#comment</code>: <span title=""> this is a comment </span><li class=t3><code>#text</code>: <span title="">&#9166;&#9251;&#9166;</span></ul></ul></ul><p>The <a href=#root-element>root element</a> of this tree is the
+  <code><a href=#the-html-element>html</a></code> element, which is the element always found at the
+  root of HTML documents. It contains two elements, <code><a href=#the-head-element>head</a></code>
+  and <code><a href=#the-body-element>body</a></code>, as well as a text node between them.</p>
+
+  <p>There are many more text nodes in the DOM tree than one would
   initially expect, because the source contains a number of spaces
   (presented by "&#9251;") and line breaks ("&#9166;") that all end
   up as text nodes in the DOM.</p>
 
-  <hr><p>Each element in the DOM tree is represented by an object, and
-  thus objects have APIs so that they can be manipulated. For
+  <p>The <code><a href=#the-head-element>head</a></code> element contains a <code><a href=#the-title-element>title</a></code>
+  element, which itself contains a text node with the text "Sample
+  page". Similarly, the <code><a href=#the-body-element>body</a></code> element contains an
+  <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code> element, a <code><a href=#the-p-element>p</a></code> element, and a
+  comment.</p>
+
+  <hr><p>This DOM tree can be manipulated from scripts in the
+  page. Scripts (typically in JavaScript) are small programs that can
+  be embedded using the <code><a href=#script>script</a></code> element or using
+  <a href=#event-handler-content-attributes>event handler content attributes</a>. For example, here is
+  a form with a script that sets the value of the form's
+  <code><a href=#the-output-element>output</a></code> element to say "Hello World":</p>
+
+  <pre>&lt;<a href=#the-form-element>form</a> <a href=#attr-form-name title=attr-form-name>name</a>="main"&gt;
+ Result: &lt;<a href=#the-output-element>output</a> <a href=#attr-fe-name title=attr-fe-name>name</a>="result"&gt;&lt;/output&gt;
+ &lt;<a href=#script>script</a>&gt;
+  <a href=#htmldocument title=HTMLDocument>document</a>.<a href=#dom-document-forms title=dom-document-forms>forms</a>.main.<a href=#dom-form-elements title=dom-form-elements>elements</a>.result.<a href=#dom-output-value title=dom-output-value>value</a> = 'Hello World';
+ &lt;/script&gt;
+&lt;/form&gt;</pre>
+
+  <p>Each element in the DOM tree is represented by an object, and
+  these objects have APIs so that they can be manipulated. For
   instance, a link (e.g. the <code><a href=#the-a-element>a</a></code> element in the tree above)
   can have its "<code title=attr-hyperlink-href><a href=#attr-hyperlink-href>href</a></code>"
   attributed changed in several ways:</p>
 
   <pre>var a = <a href=#htmldocument title=HTMLDocument>document</a>.<a href=#dom-document-links title=dom-document-links>links</a>[0]; // obtain the first link in the document
 a.<a href=#dom-a-href title=dom-a-href>href</a> = 'sample.html'; // change the destination URL of the link
-a.<a href=#dom-uda-protocol title=dom-uda-protocol>protocol</a> = 'https'; // change just the scheme part of the URL</pre>
+a.<a href=#dom-uda-protocol title=dom-uda-protocol>protocol</a> = 'https'; // change just the scheme part of the URL
+a.setAttribute('href', 'http://example.com/'); // change the content attribute directly</pre>
 
-  <p>HTML documents represent a media-independent description of
+  <p>Since DOM trees are used as the way to represent HTML documents
+  when they are processed and presented by implementations (especially
+  interactive implementations like Web browsers), this specification
+  is mostly phrased in terms of DOM trees, instead of the markup
+  described above.</p>
+
+  <hr><p>HTML documents represent a media-independent description of
   interactive content. HTML documents might be rendered to a screen,
   or through a speech synthesizer, or on a braille display. To
   influence exactly how such rendering takes place, authors can use a
@@ -57953,6 +57986,7 @@ interface <dfn id=messageport>MessagePort</dfn> {
   discussed in the section below entitled "<a href=#the-xhtml-syntax>The XHTML
   syntax</a>".</p>
 
+
   <h3 id=writing><span class=secno>9.1 </span>Writing HTML documents</h3>
 
   <div class=impl>

diff --git a/source b/source
@@ -421,12 +421,13 @@
 &lt;/html></pre>
 
   <p>HTML documents consist of a tree of elements and text. Each
-  element is denoted by a <span title="syntax-start-tag">start
-  tag</span>, such as "<code title="">&lt;body></code>", and an <span
-  title="syntax-end-tag">end tag</span>, such as "<code
-  title="">&lt;/body></code>". (Certain start tags and end tags can in
-  certain cases be <span title="syntax-tag-omission">omitted</span>
-  and are implied by other tags.)</p>
+  element is denoted in the source by a <span
+  title="syntax-start-tag">start tag</span>, such as "<code
+  title="">&lt;body></code>", and an <span title="syntax-end-tag">end
+  tag</span>, such as "<code title="">&lt;/body></code>". (Certain
+  start tags and end tags can in certain cases be <span
+  title="syntax-tag-omission">omitted</span> and are implied by other
+  tags.)</p>
 
   <p>Tags have to be nested such that elements are all completely
   within each other, without overlapping:</p>
@@ -465,35 +466,68 @@
 &lt;input name=address maxlength='200'>
 &lt;input name=address maxlength="200"></pre>
 
-  <hr>
+  <p>HTML user agents (e.g. Web browsers) then <i>parse</i> this
+  markup, turning it into a DOM (Document Object Model) tree. A DOM
+  tree is an in-memory representation of a document.</p>
 
-  <p>The tree formed by an HTML document in this way is turned into a
-  DOM tree when parsed. This DOM tree can then be manipulated from
-  scripts. Since DOM trees are the "live" representation of an HTML
-  document, this specification is mostly phrased in terms of DOM
-  trees, instead of the serialisation described above.</p>
+  <p>DOM trees contain several kinds of nodes, in particular a DOCTYPE
+  node, elements, text nodes, and comment nodes.</p>
 
-  <p>The markup snippet at the top of this section represents the
-  following DOM tree:</p>
+  <p>The markup snippet at the top of this section would be turned
+  into the following DOM tree:</p>
 
   <ul class="domTree"><li class="t10">DOCTYPE: <code>html</code></li><li class="t1"><code>html</code><ul><li class="t1"><code>head</code><ul><li class="t3"><code>#text</code>: <span title="">&#x23CE;&#x2423;&#x2423;</span></li><li class="t1"><code>title</code><ul><li class="t3"><code>#text</code>: <span title="">Sample page</span></li></ul></li><li class="t3"><code>#text</code>: <span title="">&#x23CE;&#x2423;</span></li></ul></li><li class="t3"><code>#text</code>: <span title="">&#x23CE;&#x2423;</span></li><li class="t1"><code>body</code><ul><li class="t3"><code>#text</code>: <span title="">&#x23CE;&#x2423;&#x2423;</span></li><li class="t1"><code>h1</code><ul><li class="t3"><code>#text</code>: <span title="">Sample page</span></li></ul></li><li class="t3"><code>#text</code>: <span title="">&#x23CE;&#x2423;&#x2423;</span></li><li class="t1"><code>p</code><ul><li class="t3"><code>#text</code>: <span title="">This is a </span></li><li class="t1"><code>a</code> <span title="" class="t2"><code class="attribute name">href</code>="<code class="attribute value">demo.html</code>"</span><ul><li class="t3"><code>#text</code>: <span title="">simple</span></li></ul></li><li class="t3"><code>#text</code>: <span title=""> sample.</span></li></ul></li><li class="t3"><code>#text</code>: <span title="">&#x23CE;&#x2423;&#x2423;</span></li><li class="t8"><code>#comment</code>: <span title=""> this is a comment </span></li><li class="t3"><code>#text</code>: <span title="">&#x23CE;&#x2423;&#x23CE;</span></li></ul></li></ul></li></ul>
 
+  <p>The <span>root element</span> of this tree is the
+  <code>html</code> element, which is the element always found at the
+  root of HTML documents. It contains two elements, <code>head</code>
+  and <code>body</code>, as well as a text node between them.</p>
+
   <p>There are many more text nodes in the DOM tree than one would
   initially expect, because the source contains a number of spaces
   (presented by "&#x2423;") and line breaks ("&#x23CE;") that all end
   up as text nodes in the DOM.</p>
 
+  <p>The <code>head</code> element contains a <code>title</code>
+  element, which itself contains a text node with the text "Sample
+  page". Similarly, the <code>body</code> element contains an
+  <code>h1</code> element, a <code>p</code> element, and a
+  comment.</p>
+
   <hr>
 
+  <p>This DOM tree can be manipulated from scripts in the
+  page. Scripts (typically in JavaScript) are small programs that can
+  be embedded using the <code>script</code> element or using
+  <span>event handler content attributes</span>. For example, here is
+  a form with a script that sets the value of the form's
+  <code>output</code> element to say "Hello World":</p>
+
+  <pre>&lt;<span>form</span> <span title="attr-form-name">name</span>="main">
+ Result: &lt;<span>output</span> <span title="attr-fe-name">name</span>="result">&lt;/output>
+ &lt;<span>script</span>>
+  <span title="HTMLDocument">document</span>.<span title="dom-document-forms">forms</span>.main.<span title="dom-form-elements">elements</span>.result.<span title="dom-output-value">value</span> = 'Hello World';
+ &lt;/script>
+&lt;/form></pre>
+
   <p>Each element in the DOM tree is represented by an object, and
-  thus objects have APIs so that they can be manipulated. For
+  these objects have APIs so that they can be manipulated. For
   instance, a link (e.g. the <code>a</code> element in the tree above)
   can have its "<code title="attr-hyperlink-href">href</code>"
   attributed changed in several ways:</p>
 
   <pre>var a = <span title="HTMLDocument">document</span>.<span title="dom-document-links">links</span>[0]; // obtain the first link in the document
 a.<span title="dom-a-href">href</span> = 'sample.html'; // change the destination URL of the link
-a.<span title="dom-uda-protocol">protocol</span> = 'https'; // change just the scheme part of the URL</pre>
+a.<span title="dom-uda-protocol">protocol</span> = 'https'; // change just the scheme part of the URL
+a.setAttribute('href', 'http://example.com/'); // change the content attribute directly</pre>
+
+  <p>Since DOM trees are used as the way to represent HTML documents
+  when they are processed and presented by implementations (especially
+  interactive implementations like Web browsers), this specification
+  is mostly phrased in terms of DOM trees, instead of the markup
+  described above.</p>
+
+  <hr>
 
   <p>HTML documents represent a media-independent description of
   interactive content. HTML documents might be rendered to a screen,
@@ -71488,6 +71522,7 @@ interface <dfn>MessagePort</dfn> {
   discussed in the section below entitled "<span>The XHTML
   syntax</span>".</p>
 
+
   <h3 id="writing">Writing HTML documents</h3>
 
   <div class="impl">