[e] (0) Design notes.

git-svn-id: http://svn.whatwg.org/webapps@3017 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Apr 29, 2009 · c40f28c · c40f28c
1 parent 23cafda
commit c40f28c
Show file tree

Hide file tree

Showing 2 changed files with 150 additions and 36 deletions.
diff --git a/index b/index
@@ -208,16 +208,20 @@
    <li><a href=#audience><span class=secno>1.2 </span>Audience</a></li>
    <li><a href=#scope><span class=secno>1.3 </span>Scope</a></li>
    <li><a href=#history-0><span class=secno>1.4 </span>History</a></li>
-   <li><a href=#relationships-to-other-specifications><span class=secno>1.5 </span>Relationships to other specifications</a>
+   <li><a href=#design-notes><span class=secno>1.5 </span>Design notes</a>
     <ol>
-     <li><a href=#relationship-to-html-4.01-and-dom2-html><span class=secno>1.5.1 </span>Relationship to HTML 4.01 and DOM2 HTML</a></li>
-     <li><a href=#relationship-to-xhtml-1.x><span class=secno>1.5.2 </span>Relationship to XHTML 1.x</a></li>
-     <li><a href=#relationship-to-xhtml2-and-xforms><span class=secno>1.5.3 </span>Relationship to XHTML2 and XForms</a></ol></li>
-   <li><a href=#html-vs-xhtml><span class=secno>1.6 </span>HTML vs XHTML</a></li>
-   <li><a href=#structure-of-this-specification><span class=secno>1.7 </span>Structure of this specification</a>
+     <li><a href=#serializability-of-script-execution><span class=secno>1.5.1 </span>Serializability of script execution</a></li>
+     <li><a href=#compliance-with-other-specifications><span class=secno>1.5.2 </span>Compliance with other specifications</a></ol></li>
+   <li><a href=#relationships-to-other-specifications><span class=secno>1.6 </span>Relationships to other specifications</a>
     <ol>
-     <li><a href=#how-to-read-this-specification><span class=secno>1.7.1 </span>How to read this specification</a></li>
-     <li><a href=#typographic-conventions><span class=secno>1.7.2 </span>Typographic conventions</a></ol></ol></li>
+     <li><a href=#relationship-to-html-4.01-and-dom2-html><span class=secno>1.6.1 </span>Relationship to HTML 4.01 and DOM2 HTML</a></li>
+     <li><a href=#relationship-to-xhtml-1.x><span class=secno>1.6.2 </span>Relationship to XHTML 1.x</a></li>
+     <li><a href=#relationship-to-xhtml2-and-xforms><span class=secno>1.6.3 </span>Relationship to XHTML2 and XForms</a></ol></li>
+   <li><a href=#html-vs-xhtml><span class=secno>1.7 </span>HTML vs XHTML</a></li>
+   <li><a href=#structure-of-this-specification><span class=secno>1.8 </span>Structure of this specification</a>
+    <ol>
+     <li><a href=#how-to-read-this-specification><span class=secno>1.8.1 </span>How to read this specification</a></li>
+     <li><a href=#typographic-conventions><span class=secno>1.8.2 </span>Typographic conventions</a></ol></ol></li>
  <li><a href=#infrastructure><span class=secno>2 </span>Common infrastructure</a>
   <ol>
    <li><a href=#terminology><span class=secno>2.1 </span>Terminology</a>
@@ -1156,9 +1160,61 @@
 
 
 
-  <h3 id=relationships-to-other-specifications><span class=secno>1.5 </span>Relationships to other specifications</h3>
+  <h3 id=design-notes><span class=secno>1.5 </span>Design notes</h3>
+
+  <p><em>This section is non-normative.</em></p>
+
+  <p>It must be admitted that many aspects of HTML appear at first
+  glance to be nonsensical and inconsistent.</p>
+
+  <p>HTML, its supporting DOM APIs, as well as many of its supporting
+  technologies, have been developed over a period of several decades
+  by a wide array of people with different priorities who, in many
+  cases, did not know of each other's existence.</p>
+
+  <p>Features have thus arisen from many sources, and have not always
+  been designed in especially consistent ways. Furthermore, because of
+  the unique characteristics of the Web, implementation bugs have
+  often become de-facto, and now de-jure, standards, as content is
+  often unintentionally written in ways that rely on them before they
+  can be fixed.</p>
+
+  <p>Despite all this, efforts have been made to adhere to certain
+  design goals. These are described in the next few subsections.</p>
+
+
+  <h4 id=serializability-of-script-execution><span class=secno>1.5.1 </span>Serializability of script execution</h4>
+
+  <p><em>This section is non-normative.</em></p>
+
+  <p>To avoid exposing Web authors to the complexities of
+  multithreading, the HTML and DOM APIs are designed such that no
+  script can ever detect the simultaneous execution of other
+  scripts. Even with <span title=Worker>workers</span>, the intent
+  is that the behavior of implementations can be thought of as
+  completely serialising the execution of all scripts in all <a href=#browsing-context title="browsing context">browsing contexts</a>.</p>
+
+  <p class=note>The <code title=dom-navigator-GetStorageUpdates><a href=#dom-navigator-getstorageupdates>navigator.getStorageUpdates()</a></code>
+  method, in this model, is equivalent to allowing other scripts to
+  run while the calling script is blocked.</p>
+
 
-  <h4 id=relationship-to-html-4.01-and-dom2-html><span class=secno>1.5.1 </span>Relationship to HTML 4.01 and DOM2 HTML</h4>
+  <h4 id=compliance-with-other-specifications><span class=secno>1.5.2 </span>Compliance with other specifications</h4>
+
+  <p><em>This section is non-normative.</em></p>
+
+  <p>HTML5 interacts with and relies on a wide variety of other
+  specifications. In certain circumstances, unfortunately, the desire
+  to be compatible with legacy content has led to HTML5 violating the
+  requirements of these other specifications. Whenever this has
+  occured, the transgressions have been noted as "<dfn id=willful-violation title="willful
+  violation">willful violations</dfn>".</p>
+
+
+
+  <h3 id=relationships-to-other-specifications><span class=secno>1.6 </span>Relationships to other specifications</h3>
+
+  <h4 id=relationship-to-html-4.01-and-dom2-html><span class=secno>1.6.1 </span>Relationship to HTML 4.01 and DOM2 HTML</h4>
 
   <p><em>This section is non-normative.</em></p>
 
@@ -1169,7 +1225,7 @@
   backwards-compatibility is retained. <a href=#refsHTML4>[HTML4]</a> <a href=#refsDOM2HTML>[DOM2HTML]</a></p>
 
 
-  <h4 id=relationship-to-xhtml-1.x><span class=secno>1.5.2 </span>Relationship to XHTML 1.x</h4>
+  <h4 id=relationship-to-xhtml-1.x><span class=secno>1.6.2 </span>Relationship to XHTML 1.x</h4>
 
   <p><em>This section is non-normative.</em></p>
 
@@ -1190,7 +1246,7 @@
   to continue using the XHTML 1.1 line of specifications.</p>
 
 
-  <h4 id=relationship-to-xhtml2-and-xforms><span class=secno>1.5.3 </span>Relationship to XHTML2 and XForms</h4>
+  <h4 id=relationship-to-xhtml2-and-xforms><span class=secno>1.6.3 </span>Relationship to XHTML2 and XForms</h4>
 
   <p><em>This section is non-normative.</em></p>
 
@@ -1217,7 +1273,7 @@
   processor.</p>
 
 
-  <h3 id=html-vs-xhtml><span class=secno>1.6 </span>HTML vs XHTML</h3>
+  <h3 id=html-vs-xhtml><span class=secno>1.7 </span>HTML vs XHTML</h3>
 
   <p><em>This section is non-normative.</em></p>
 
@@ -1256,7 +1312,7 @@
   not in "HTML5" and "XHTML5". And so forth.</p>
 
 
-  <h3 id=structure-of-this-specification><span class=secno>1.7 </span>Structure of this specification</h3>
+  <h3 id=structure-of-this-specification><span class=secno>1.8 </span>Structure of this specification</h3>
 
   <p><em>This section is non-normative.</em></p>
 
@@ -1319,7 +1375,7 @@
   specification.</p>
 
 
-  <h4 id=how-to-read-this-specification><span class=secno>1.7.1 </span>How to read this specification</h4>
+  <h4 id=how-to-read-this-specification><span class=secno>1.8.1 </span>How to read this specification</h4>
 
   <p>This specification should be read like all other specifications.
   First, it should be read cover-to-cover, multiple times. Then, it
@@ -1328,7 +1384,7 @@
   cross-references.</p>
 
 
-  <h4 id=typographic-conventions><span class=secno>1.7.2 </span>Typographic conventions</h4>
+  <h4 id=typographic-conventions><span class=secno>1.8.2 </span>Typographic conventions</h4>
 
   <p>This is a definition, requirement, or explanation.</p>
 
@@ -1369,6 +1425,7 @@
   <p class=impl>This is an implementation requirement.</p>
 
 
+
   <h2 id=infrastructure><span class=secno>2 </span>Common infrastructure</h2>
 
   <h3 id=terminology><span class=secno>2.1 </span>Terminology</h3>
@@ -1889,8 +1946,8 @@
     rather than the official term ECMAScript, since the term
     JavaScript is more widely known. Similarly, the MIME type used to
     refer to JavaScript in this specification is <code title="">text/javascript</code>, since that is the most commonly
-    used type, despite it being an officially obsoleted type according
-    to RFC 4329. <!--willful violation--> <a href=#refsRFC4329>[RFC4329]</a></p>
+    used type, <a href=#willful-violation title="willful violation">despite it being an
+    officially obsoleted type</a> according to RFC 4329. <a href=#refsRFC4329>[RFC4329]</a></p>
 
    </dd>
 
@@ -4288,8 +4345,8 @@
   manner distinct from the precise technical meaning it is given in
   RFC 3986. Readers familiar with that RFC will find it easier to read
   <em>this</em> specification if they pretend the term "URL" as used
-  herein is really called something else altogether. This is a willful
-  violation of RFC 3986. <a href=#refsRFC3986>RFC3986</a></p>
+  herein is really called something else altogether. This is a <a href=#willful-violation>willful
+  violation</a> of RFC 3986. <a href=#refsRFC3986>RFC3986</a></p>
 
   </div>
 
@@ -4418,7 +4475,7 @@
 
   </ol><!-- XXX we might want to define "server-based naming authority",
   it's not clear RFC3986 does a good job of defining that anymore
-  (earlier URI specs did) --><p class=note>These parsing rules are a willful violation of RFC
+  (earlier URI specs did) --><p class=note>These parsing rules are a <a href=#willful-violation>willful violation</a> of RFC
   3986 and RFC 3987 to handle legacy content. <a href=#refsRFC3986>RFC3986</a> <a href=#refsRFC3987>RFC3987</a></p>
 
   </div>
@@ -5116,7 +5173,7 @@
 
     </dl></li>
 
-  </ol><p class=note>The above algorithm is a willful violation of the
+  </ol><p class=note>The above algorithm is a <a href=#willful-violation>willful violation</a> of the
   HTTP specification. <a href=#refsHTTP>[HTTP]</a></p>
 
 
@@ -5713,7 +5770,7 @@
     <tr><td> x-x-big5 <td> Big5 <td>
          <a href=#refsBIG5>[BIG5]</a> <!-- XXX ? -->
    </table><p class=note>The requirement to treat certain encodings as other
-  encodings according to the table above is a willful violation of the
+  encodings according to the table above is a <a href=#willful-violation>willful violation</a> of the
   W3C Character Model specification. <a href=#refsCHARMOD>[CHARMOD]</a></p>
 
   <hr><p>User agents must not support the CESU-8, UTF-7, BOCU-1 and SCSU
@@ -35262,7 +35319,7 @@ interface <dfn id=htmloptionelement>HTMLOptionElement</dfn> : <a href=#htmleleme
 
     <p>If <var title="">action</var> is the empty string, let <var title="">action</var> be <a href="#the-document's-address">the document's address</a>.</p>
 
-    <p class=note>This step is a willful violation of RFC 3986. <a href=#refsRFC3986>[RFC3986]</a></p>
+    <p class=note>This step is a <a href=#willful-violation>willful violation</a> of RFC 3986. <a href=#refsRFC3986>[RFC3986]</a></p>
 
     <!-- Don't ask me why. But that's what IE does. It even treats
     action="" differently from action=" " or action="#" (the latter
@@ -41512,7 +41569,7 @@ interface <dfn id=window>Window</dfn> {
     <code><a href=#window>Window</a></code> object, then in JavaScript, the <code title="">this</code> keyword in the global scope must return the
     <code><a href=#window>Window</a></code> object's <code><a href=#windowproxy>WindowProxy</a></code> object.</p>
 
-    <p class=note>This is a willful violation of the JavaScript
+    <p class=note>This is a <a href=#willful-violation>willful violation</a> of the JavaScript
     specification current at the time of writing (ECMAScript edition
     3). <a href=#refsECMA262>[ECMA262]</a></p>
 
@@ -43540,7 +43597,8 @@ style/default.css</pre>
   characters, U+000D CARRIAGE RETURN (CR) characters, or U+000D
   CARRIAGE RETURN (CR) U+000A LINE FEED (LF) pairs.</p>
 
-  <p class=note>This is a willful double violation of RFC2046. <a href=#refsRFC2046>[RFC2046]</a></p>
+  <p class=note>This is a <a href=#willful-violation title="willful violation">willful
+  double violation</a> of RFC2046. <a href=#refsRFC2046>[RFC2046]</a></p>
 
   <p>The first line of an application cache manifest must consist of
   the string "CACHE", a single U+0020 SPACE character, the string

diff --git a/source b/source
@@ -136,6 +136,60 @@
 
 
 
+  <h3>Design notes</h3>
+
+  <p><em>This section is non-normative.</em></p>
+
+  <p>It must be admitted that many aspects of HTML appear at first
+  glance to be nonsensical and inconsistent.</p>
+
+  <p>HTML, its supporting DOM APIs, as well as many of its supporting
+  technologies, have been developed over a period of several decades
+  by a wide array of people with different priorities who, in many
+  cases, did not know of each other's existence.</p>
+
+  <p>Features have thus arisen from many sources, and have not always
+  been designed in especially consistent ways. Furthermore, because of
+  the unique characteristics of the Web, implementation bugs have
+  often become de-facto, and now de-jure, standards, as content is
+  often unintentionally written in ways that rely on them before they
+  can be fixed.</p>
+
+  <p>Despite all this, efforts have been made to adhere to certain
+  design goals. These are described in the next few subsections.</p>
+
+
+  <h4>Serializability of script execution</h4>
+
+  <p><em>This section is non-normative.</em></p>
+
+  <p>To avoid exposing Web authors to the complexities of
+  multithreading, the HTML and DOM APIs are designed such that no
+  script can ever detect the simultaneous execution of other
+  scripts. Even with <span title="Worker">workers</span>, the intent
+  is that the behavior of implementations can be thought of as
+  completely serialising the execution of all scripts in all <span
+  title="browsing context">browsing contexts</span>.</p>
+
+  <p class="note">The <code
+  title="dom-navigator-GetStorageUpdates">navigator.getStorageUpdates()</code>
+  method, in this model, is equivalent to allowing other scripts to
+  run while the calling script is blocked.</p>
+
+
+  <h4>Compliance with other specifications</h4>
+
+  <p><em>This section is non-normative.</em></p>
+
+  <p>HTML5 interacts with and relies on a wide variety of other
+  specifications. In certain circumstances, unfortunately, the desire
+  to be compatible with legacy content has led to HTML5 violating the
+  requirements of these other specifications. Whenever this has
+  occured, the transgressions have been noted as "<dfn title="willful
+  violation">willful violations</dfn>".</p>
+
+
+
   <h3>Relationships to other specifications</h3>
 
   <h4>Relationship to HTML 4.01 and DOM2 HTML</h4>
@@ -368,6 +422,7 @@
   <p class="impl">This is an implementation requirement.</p>
 
 
+
   <h2 id="infrastructure">Common infrastructure</h2>
 
   <h3>Terminology</h3>
@@ -924,8 +979,8 @@
     JavaScript is more widely known. Similarly, the MIME type used to
     refer to JavaScript in this specification is <code
     title="">text/javascript</code>, since that is the most commonly
-    used type, despite it being an officially obsoleted type according
-    to RFC 4329. <!--willful violation--> <a
+    used type, <span title="willful violation">despite it being an
+    officially obsoleted type</span> according to RFC 4329. <a
     href="#refsRFC4329">[RFC4329]</a></p>
 
    </dd>
@@ -3890,8 +3945,8 @@
   manner distinct from the precise technical meaning it is given in
   RFC 3986. Readers familiar with that RFC will find it easier to read
   <em>this</em> specification if they pretend the term "URL" as used
-  herein is really called something else altogether. This is a willful
-  violation of RFC 3986. <a href="#refsRFC3986">RFC3986</a></p>
+  herein is really called something else altogether. This is a <span>willful
+  violation</span> of RFC 3986. <a href="#refsRFC3986">RFC3986</a></p>
 
   </div>
 
@@ -4038,7 +4093,7 @@
   it's not clear RFC3986 does a good job of defining that anymore
   (earlier URI specs did) -->
 
-  <p class="note">These parsing rules are a willful violation of RFC
+  <p class="note">These parsing rules are a <span>willful violation</span> of RFC
   3986 and RFC 3987 to handle legacy content. <a
   href="#refsRFC3986">RFC3986</a> <a
   href="#refsRFC3987">RFC3987</a></p>
@@ -4845,7 +4900,7 @@
 
   </ol>
 
-  <p class="note">The above algorithm is a willful violation of the
+  <p class="note">The above algorithm is a <span>willful violation</span> of the
   HTTP specification. <a href="#refsHTTP">[HTTP]</a></p>
 
 
@@ -5603,7 +5658,7 @@
   </table>
 
   <p class="note">The requirement to treat certain encodings as other
-  encodings according to the table above is a willful violation of the
+  encodings according to the table above is a <span>willful violation</span> of the
   W3C Character Model specification. <a
   href="#refsCHARMOD">[CHARMOD]</a></p>
 
@@ -39691,7 +39746,7 @@ interface <dfn>HTMLOptionElement</dfn> : <span>HTMLElement</span> {
     <p>If <var title="">action</var> is the empty string, let <var
     title="">action</var> be <span>the document's address</span>.</p>
 
-    <p class="note">This step is a willful violation of RFC 3986. <a
+    <p class="note">This step is a <span>willful violation</span> of RFC 3986. <a
     href="#refsRFC3986">[RFC3986]</a></p>
 
     <!-- Don't ask me why. But that's what IE does. It even treats
@@ -46919,7 +46974,7 @@ interface <dfn>Window</dfn> {
     title="">this</code> keyword in the global scope must return the
     <code>Window</code> object's <code>WindowProxy</code> object.</p>
 
-    <p class="note">This is a willful violation of the JavaScript
+    <p class="note">This is a <span>willful violation</span> of the JavaScript
     specification current at the time of writing (ECMAScript edition
     3). <a href="#refsECMA262">[ECMA262]</a></p>
 
@@ -49268,7 +49323,8 @@ style/default.css</pre>
   characters, U+000D CARRIAGE RETURN (CR) characters, or U+000D
   CARRIAGE RETURN (CR) U+000A LINE FEED (LF) pairs.</p>
 
-  <p class="note">This is a willful double violation of RFC2046. <a
+  <p class="note">This is a <span title="willful violation">willful
+  double violation</span> of RFC2046. <a
   href="#refsRFC2046">[RFC2046]</a></p>
 
   <p>The first line of an application cache manifest must consist of