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

html5/html-design-principles Overview.html,1.23,1.24 Overview.src.html,1.23,1.24

From: Maciej Stachowiak via cvs-syncmail <cvsmail@w3.org>
Date: Tue, 26 May 2009 07:36:26 +0000
To: public-html-commits@w3.org
Message-Id: <E1M8rD0-000422-Ct@lionel-hutz.w3.org>
Update of /sources/public/html5/html-design-principles
In directory hutz:/tmp/cvs-serv15227

Modified Files:
	Overview.html Overview.src.html 
Log Message:
Made sure that examples are clearly marked as such. Cleaned up some examples. Added disclaimer
that examples are not final decisions about HTML, necessarily.


Index: Overview.html
===================================================================
RCS file: /sources/public/html5/html-design-principles/Overview.html,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -d -r1.23 -r1.24
--- Overview.html	24 Nov 2007 00:40:26 -0000	1.23
+++ Overview.html	26 May 2009 07:36:24 -0000	1.24
@@ -6,6 +6,7 @@
 
   <style type="text/css">
       .example { padding-left: 1em; border-left: 3px solid green }
+      .example:before { content: "Example: "; font-weight: bold; }
       .note { font-style: italic; }
       dfn { font-style:normal; font-weight:bold }
       code { color:orangered }
@@ -21,8 +22,7 @@
 
    <h1 id=html-design-principles>HTML Design Principles</h1>
 
-   <h2 class="no-num no-toc" id=w3c-doctype>W3C Working Draft 26 November
-    2007</h2>
+   <h2 class="no-num no-toc" id=w3c-doctype>W3C Working Draft 26 May 2009</h2>
 
    <dl>
     <dt>This Version:</dt>
@@ -31,7 +31,7 @@
         log</a>)</dd>-->
 
     <dd><a
-     href="http://www.w3.org/TR/2007/WD-html-design-principles-20071126/">http://www.w3.org/TR/2007/WD-html-design-principles-20071126/</a>
+     href="http://www.w3.org/TR/2009/WD-html-design-principles-20090526/">http://www.w3.org/TR/2009/WD-html-design-principles-20090526/</a>
 
     <dt>Latest Version:</dt>
     <!--<dd><a href="http://www.w3.org/html/wg/html5/principles/">http://www.w3.org/html/wg/html5/principles/</a></li>-->
@@ -136,78 +136,74 @@
   <!--begin-toc-->
 
   <ul class=toc>
-   <li><a href="#introduction"><span class=secno>1. </span>Introduction</a>
+   <li><a href="#introduction"><span class=secno>1 </span>Introduction</a>
     <ul class=toc>
-     <li><a href="#conformance"><span class=secno>1.1. </span>Conformance for
+     <li><a href="#conformance"><span class=secno>1.1 </span>Conformance for
       Documents and Implementations</a>
+
+     <li><a href="#examples"><span class=secno>1.2 </span>Examples in this
+      Document</a>
     </ul>
 
-   <li><a href="#compatibility"><span class=secno>2. </span>Compatibility</a>
-    
+   <li><a href="#compatibility"><span class=secno>2 </span>Compatibility</a>
     <ul class=toc>
-     <li><a href="#support-existing-content"><span class=secno>2.1.
+     <li><a href="#support-existing-content"><span class=secno>2.1
       </span>Support Existing Content</a>
-      <ul class=toc>
-       <li><a href="#examples"><span class=secno>2.1.1. </span>Examples</a>
-      </ul>
 
-     <li><a href="#degrade-gracefully"><span class=secno>2.2. </span>Degrade
+     <li><a href="#degrade-gracefully"><span class=secno>2.2 </span>Degrade
       Gracefully</a>
-      <ul class=toc>
-       <li><a href="#examples0"><span class=secno>2.2.1. </span>Examples</a>
-      </ul>
 
-     <li><a href="#do-not-reinvent-the-wheel"><span class=secno>2.3.
-      </span>Do not Reinvent the Wheel</a>
+     <li><a href="#do-not-reinvent-the-wheel"><span class=secno>2.3 </span>Do
+      not Reinvent the Wheel</a>
 
-     <li><a href="#pave-the-cowpaths"><span class=secno>2.4. </span>Pave the
+     <li><a href="#pave-the-cowpaths"><span class=secno>2.4 </span>Pave the
       Cowpaths</a>
 
-     <li><a href="#evolution-not-revolution"><span class=secno>2.5.
+     <li><a href="#evolution-not-revolution"><span class=secno>2.5
       </span>Evolution Not Revolution</a>
     </ul>
 
-   <li><a href="#utility"><span class=secno>3. </span>Utility</a>
+   <li><a href="#utility"><span class=secno>3 </span>Utility</a>
     <ul class=toc>
-     <li><a href="#solve-real-problems"><span class=secno>3.1. </span>Solve
+     <li><a href="#solve-real-problems"><span class=secno>3.1 </span>Solve
       Real Problems</a>
 
-     <li><a href="#priority-of-constituencies"><span class=secno>3.2.
+     <li><a href="#priority-of-constituencies"><span class=secno>3.2
       </span>Priority of Constituencies</a>
 
-     <li><a href="#secure-by-design"><span class=secno>3.3. </span>Secure By
+     <li><a href="#secure-by-design"><span class=secno>3.3 </span>Secure By
       Design</a>
 
-     <li><a href="#separation-of-concerns"><span class=secno>3.4.
+     <li><a href="#separation-of-concerns"><span class=secno>3.4
       </span>Separation of Concerns</a>
 
-     <li><a href="#dom-consistency"><span class=secno>3.5. </span>DOM
+     <li><a href="#dom-consistency"><span class=secno>3.5 </span>DOM
       Consistency</a>
     </ul>
 
-   <li><a href="#interoperability"><span class=secno>4.
+   <li><a href="#interoperability"><span class=secno>4
     </span>Interoperability</a>
     <ul class=toc>
-     <li><a href="#well-defined-behavior"><span class=secno>4.1.
+     <li><a href="#well-defined-behavior"><span class=secno>4.1
       </span>Well-defined Behavior</a>
 
-     <li><a href="#avoid-needless-complexity"><span class=secno>4.2.
+     <li><a href="#avoid-needless-complexity"><span class=secno>4.2
       </span>Avoid Needless Complexity</a>
 
-     <li><a href="#handle-errors"><span class=secno>4.3. </span>Handle
+     <li><a href="#handle-errors"><span class=secno>4.3 </span>Handle
       Errors</a>
     </ul>
 
-   <li><a href="#universal-access"><span class=secno>5. </span>Universal
+   <li><a href="#universal-access"><span class=secno>5 </span>Universal
     Access</a>
     <ul class=toc>
-     <li><a href="#media-independence"><span class=secno>5.1. </span>Media
+     <li><a href="#media-independence"><span class=secno>5.1 </span>Media
       Independence</a>
 
-     <li><a href="#support-world-languages"><span class=secno>5.2.
+     <li><a href="#support-world-languages"><span class=secno>5.2
       </span>Support World Languages</a>
 
-     <li><a href="#accessibility"><span class=secno>5.3.
+     <li><a href="#accessibility"><span class=secno>5.3
       </span>Accessibility</a>
     </ul>
 
@@ -215,7 +211,7 @@
   </ul>
   <!--end-toc-->
 
-  <h2 id=introduction><span class=secno>1. </span>Introduction</h2>
+  <h2 id=introduction><span class=secno>1 </span>Introduction</h2>
 
   <p>In the HTML Working Group, we have representatives from many different
    communities, including the WHATWG and other W3C Working Groups. The
@@ -230,7 +226,7 @@
    findings in Architecture of the World Wide Web, but specific to the
    deliverables of this group.
 
-  <h3 id=conformance><span class=secno>1.1. </span>Conformance for Documents
+  <h3 id=conformance><span class=secno>1.1 </span>Conformance for Documents
    and Implementations</h3>
 
   <p>Many language specifications define a set of conformance requirements
@@ -252,14 +248,20 @@
    principles will do their best to make clear which set of requirements they
    apply to.
 
-  <h2 id=compatibility><span class=secno>2. </span>Compatibility</h2>
+  <h3 id=examples><span class=secno>1.2 </span>Examples in this Document</h3>
+
+  <p>Many of the principles are illustrated with examples of cases where they
+   have been applied. None of them should be taken as indicating a final
+   decision on any given HTML5 feature.
+
+  <h2 id=compatibility><span class=secno>2 </span>Compatibility</h2>
 
   <p>There are many ways of interpreting compatibility. Sometimes the terms
    "backwards compatibility" and "forwards compatibility" are used, but
    sometimes the meaning of those terms can be unclear. The principles in
    this section address different facets of compatibility.
 
-  <h3 id=support-existing-content><span class=secno>2.1. </span>Support
+  <h3 id=support-existing-content><span class=secno>2.1 </span>Support
    Existing Content</h3>
 
   <p class=note>This principle applies primarily to the supported language.
@@ -309,8 +311,6 @@
    that something is part of the supported language does not by itself mean
    that relying on it is condoned or encouraged.
 
-  <h4 id=examples><span class=secno>2.1.1. </span>Examples</h4>
-
   <p class=example>Many sites use broken markup, such as badly nested
    elements (<code>&lt;b>a&lt;i>b&lt;/b>c&lt;/i></code>), and both authors
    and users have expectations based on the error handling used by legacy
@@ -320,7 +320,7 @@
   <p class=example>Some sites rely on the <code>&lt;u&gt;</code> element
    giving the presentational effect of an underline.
 
-  <h3 id=degrade-gracefully><span class=secno>2.2. </span>Degrade Gracefully</h3>
+  <h3 id=degrade-gracefully><span class=secno>2.2 </span>Degrade Gracefully</h3>
 
   <p class=note>This principle applies primarily to the conforming language.
 
@@ -375,9 +375,7 @@
   </ul>
 
   <p>This list is not exhaustive; in some cases slightly more complicated
-   approaches are more effective.
-
-  <h4 id=examples0><span class=secno>2.2.1. </span>Examples</h4>
+   approaches are more effective.</p>
   <!--
     <p class="example">The default presentation of the
     proposed <code>&lt;section&gt;</code> element can be emulated
@@ -385,8 +383,8 @@
     -->
 
   <p class=example>The default presentation of the proposed
-   <code>irrelevant</code> attribute can be emulated through the CSS rule
-   <code>[irrelevant] { display: none; }</code>.
+   <code>hidden</code> attribute can be emulated through the CSS rule
+   <code>[hidden] { display: none; }</code>.
 
   <p class=example>Proposed new multimedia elements like <code>&lt;canvas>
    fallback &lt;/canvas></code> or <code>&lt;video> fallback
@@ -405,7 +403,7 @@
    "combo box" control can be a text field or a text field with an associated
    pop-up menu in existing mainstream browsers
 
-  <h3 id=do-not-reinvent-the-wheel><span class=secno>2.3. </span>Do not
+  <h3 id=do-not-reinvent-the-wheel><span class=secno>2.3 </span>Do not
    Reinvent the Wheel</h3>
 
   <p>If there is already a widely used and implemented technology covering
@@ -417,7 +415,7 @@
   <p class=example><code>contenteditable=""</code> was already used and
    implemented by user agents. No need to invent a new feature.
 
-  <h3 id=pave-the-cowpaths><span class=secno>2.4. </span>Pave the Cowpaths</h3>
+  <h3 id=pave-the-cowpaths><span class=secno>2.4 </span>Pave the Cowpaths</h3>
 
   <p>When a practice is already widespread among authors, consider adopting
    it rather than forbidding it or inventing something new.
@@ -426,7 +424,7 @@
    opposed to <code>&lt;br></code> in HTML and there is no harm done by
    allowing that to be used.
 
-  <h3 id=evolution-not-revolution><span class=secno>2.5. </span>Evolution Not
+  <h3 id=evolution-not-revolution><span class=secno>2.5 </span>Evolution Not
    Revolution</h3>
 
   <p>Revolutions sometimes change the world to the better. Most often,
@@ -441,20 +439,19 @@
   <p class=example>Switching to XML syntax requires a global change, so
    continue supporting classic HTML syntax as well.
 
-  <h2 id=utility><span class=secno>3. </span>Utility</h2>
+  <h2 id=utility><span class=secno>3 </span>Utility</h2>
 
   <p>These principles call for a design that makes sure HTML can be used
    effectively for its many intended purposes.
 
-  <h3 id=solve-real-problems><span class=secno>3.1. </span>Solve Real
-   Problems</h3>
+  <h3 id=solve-real-problems><span class=secno>3.1 </span>Solve Real Problems</h3>
 
   <p>Changes to the spec should solve actual real-world problems. Abstract
    architectures that don't address an existing need are less favored than
    pragmatic solutions to problems that web content faces today. And existing
    widespread problems should be solved, when possible.
 
-  <h3 id=priority-of-constituencies><span class=secno>3.2. </span>Priority of
+  <h3 id=priority-of-constituencies><span class=secno>3.2 </span>Priority of
    Constituencies</h3>
 
   <p>In case of conflict, consider users over authors over implementors over
@@ -466,7 +463,7 @@
    reasons alone. Of course, it is preferred to make things better for
    multiple constituencies at once.
 
-  <h3 id=secure-by-design><span class=secno>3.3. </span>Secure By Design</h3>
+  <h3 id=secure-by-design><span class=secno>3.3 </span>Secure By Design</h3>
 
   <p>Ensure that features work with the security model of the web.
    Preferrably address security considerations directly in the specification.
@@ -476,7 +473,7 @@
    Cross-document messaging is designed to allow this without violating
    security constraints.
 
-  <h3 id=separation-of-concerns><span class=secno>3.4. </span>Separation of
+  <h3 id=separation-of-concerns><span class=secno>3.4 </span>Separation of
    Concerns</h3>
 
   <p>HTML should allow separation of content and presentation. For this
@@ -490,17 +487,17 @@
    may be pragmatic (for brevity, history, simplicity) rather than completely
    accurate.
 
-  <p class=example>The <code>article</code> element defines an individual
-   article, but not the details of how it is displayed. A journal article may
-   be the only article on a page, formatted in multiple columns, while a blog
-   post may share a page with multiple other articles and be presented in a
-   box with a border.
+  <p class=example>The <code>&lt;article></code> element defines an
+   individual article, but not the details of how it is displayed. A journal
+   article may be the only article on a page, formatted in multiple columns,
+   while a blog post may share a page with multiple other articles and be
+   presented in a box with a border.
 
-  <p class=example>The <code>b</code> and <code>i</code> elements are widely
-   used &mdash; it is better to give them good default rendering for various
-   media including aural than to try to ban them.
+  <p class=example>The <code>&lt;b></code> and <code>&lt;i></code> elements
+   are widely used &mdash; it may be better to give them good default
+   rendering for various media including aural than to try to ban them.
 
-  <h3 id=dom-consistency><span class=secno>3.5. </span>DOM Consistency</h3>
+  <h3 id=dom-consistency><span class=secno>3.5 </span>DOM Consistency</h3>
 
   <p>The two serializations should be designed in such a way that the DOM
    trees produced by the respective parsers appear as consistently as
@@ -516,12 +513,12 @@
    the <code>http://www.w3.org/1999/xhtml</code> namespace in the DOM for
    compatibility with the XML syntax of HTML&nbsp;5.
 
-  <h2 id=interoperability><span class=secno>4. </span>Interoperability</h2>
+  <h2 id=interoperability><span class=secno>4 </span>Interoperability</h2>
 
   <p>These principles exist to improve the chances of HTML implementations
    being truly interoperable.
 
-  <h3 id=well-defined-behavior><span class=secno>4.1. </span>Well-defined
+  <h3 id=well-defined-behavior><span class=secno>4.1 </span>Well-defined
    Behavior</h3>
 
   <p>Prefer to clearly define behavior that content authors could rely on, in
@@ -530,7 +527,7 @@
    implementations should still be free to make improvements in areas such as
    user interface and quality of rendering.
 
-  <h3 id=avoid-needless-complexity><span class=secno>4.2. </span>Avoid
+  <h3 id=avoid-needless-complexity><span class=secno>4.2 </span>Avoid
    Needless Complexity</h3>
 
   <p>Simple solutions are preferred to complex ones, when possible. Simpler
@@ -538,18 +535,18 @@
    interoperable, and easier for authors to understand. But this should not
    be used as an excuse to avoid satisfying the other principles.
 
-  <h3 id=handle-errors><span class=secno>4.3. </span>Handle Errors</h3>
+  <h3 id=handle-errors><span class=secno>4.3 </span>Handle Errors</h3>
 
   <p>Error handling should be defined so that interoperable implementations
    can be achieved. Prefer graceful error recovery to hard failure, so that
    users are not exposed to authoring errors.
 
-  <h2 id=universal-access><span class=secno>5. </span>Universal Access</h2>
+  <h2 id=universal-access><span class=secno>5 </span>Universal Access</h2>
 
   <p>Features should be designed for universal access. This category covers
    various principles related to that.
 
-  <h3 id=media-independence><span class=secno>5.1. </span>Media Independence</h3>
+  <h3 id=media-independence><span class=secno>5.1 </span>Media Independence</h3>
 
   <p>Features should, when possible, work across different platforms,
    devices, and media. This should not be taken to mean that a feature should
@@ -564,7 +561,7 @@
   <p class=example>A hyperlink can not be actuated in a printed document, but
    that is no reason to omit the <code>a</code> element.
 
-  <h3 id=support-world-languages><span class=secno>5.2. </span>Support World
+  <h3 id=support-world-languages><span class=secno>5.2 </span>Support World
    Languages</h3>
 
   <p>Enable publication in all world languages. But this should not be taken
@@ -581,22 +578,22 @@
 
   <p class=example>Text in element content has better language support than
    text in attribute content; in element content ruby annotations can be
-   inserted, as well as <code>dir</code> attributes and <code>bdo</code>
-   elements in case the Unicode bidirectional algorithm is insufficient to
-   correctly order adjacent runs of mixed direction text.
+   inserted, as well as <code>&lt;dir></code> attributes and
+   <code>&lt;bdo></code> elements in case the Unicode bidirectional algorithm
+   is insufficient to correctly order adjacent runs of mixed direction text.
 
-  <h3 id=accessibility><span class=secno>5.3. </span>Accessibility</h3>
+  <h3 id=accessibility><span class=secno>5.3 </span>Accessibility</h3>
 
   <p>Design features to be accessible to users with disabilities. Access by
    everyone regardless of ability is essential. This does not mean that
    features should be omitted entirely if not all users can make full use of
    them, but alternate mechanisms should be provided.
 
-  <p class=example>The image in an <code>img</code> may not be visible to
-   blind users, but that is a reason to provide alternate text, not to leave
-   out images.
+  <p class=example>The image in an <code>&lt;img></code> may not be visible
+   to blind users, but that is a reason to provide alternate text, not to
+   leave out images.
 
-  <p class=example>The <code>progress</code> element is intrinsically
+  <p class=example>The <code>&lt;progress></code> element is intrinsically
    accessible as it has unambiguous progress bar semantics which permits
    mapping to accessibility APIs that can represent progress indicators.
 

Index: Overview.src.html
===================================================================
RCS file: /sources/public/html5/html-design-principles/Overview.src.html,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -d -r1.23 -r1.24
--- Overview.src.html	24 Nov 2007 00:40:26 -0000	1.23
+++ Overview.src.html	26 May 2009 07:36:24 -0000	1.24
@@ -4,6 +4,7 @@
     <title>HTML Design Principles</title>
     <style type="text/css">
       .example { padding-left: 1em; border-left: 3px solid green }
+      .example:before { content: "Example: "; font-weight: bold; }
       .note { font-style: italic; }
       dfn { font-style:normal; font-weight:bold }
       code { color:orangered }
@@ -164,6 +165,12 @@
     considerable overlap, but the principles will do their best to
     make clear which set of requirements they apply to.</p>
 
+    <h3 id="examples">Examples in this Document</h3>
+
+    <p>Many of the principles are illustrated with examples of cases
+    where they have been applied. None of them should be taken as
+    indicating a final decision on any given HTML5 feature.</p>
+
 
     <h2 id="compatibility">Compatibility</h2>
 
@@ -227,8 +234,6 @@
     part of the supported language does not by itself mean that
     relying on it is condoned or encouraged.</p>
 
-    <h4>Examples</h4>
-
     <p class="example">Many sites use broken markup, such as badly nested
     elements (<code>&lt;b>a&lt;i>b&lt;/b>c&lt;/i></code>), and both authors and
     users have expectations based on the error handling used by legacy user
@@ -293,8 +298,6 @@
     <p>This list is not exhaustive; in some cases slightly more
     complicated approaches are more effective.</p>
 
-    <h4>Examples</h4>
-
     <!--
     <p class="example">The default presentation of the
     proposed <code>&lt;section&gt;</code> element can be emulated
@@ -302,8 +305,8 @@
     -->
 
     <p class="example">The default presentation of the
-    proposed <code>irrelevant</code> attribute can be emulated
-    through the CSS rule <code>[irrelevant] { display: none; }</code>.</p>
+    proposed <code>hidden</code> attribute can be emulated
+    through the CSS rule <code>[hidden] { display: none; }</code>.</p>
 
     <p class="example">Proposed new multimedia elements
     like <code>&lt;canvas> fallback &lt;/canvas></code>
@@ -405,14 +408,14 @@
     pragmatic (for brevity, history, simplicity) rather than completely
     accurate.</p>
 
-    <p class="example">The <code>article</code> element defines an individual
+    <p class="example">The <code>&lt;article></code> element defines an individual
     article, but not the details of how it is displayed. A journal article may
     be the only article on a page, formatted in multiple columns, while a blog
     post may share a page with multiple other articles and be presented in a box
     with a border.</p>
     
-    <p class="example">The <code>b</code> and <code>i</code> elements are widely
-    used &mdash; it is better to give them good default rendering for various
+    <p class="example">The <code>&lt;b></code> and <code>&lt;i></code> elements are widely
+    used &mdash; it may be better to give them good default rendering for various
     media including aural than to try to ban them.</p>
     
     
@@ -499,7 +502,7 @@
     
     <p class="example">Text in element content has better language support than
     text in attribute content; in element content ruby annotations can be
-    inserted, as well as <code>dir</code> attributes and <code>bdo</code>
+    inserted, as well as <code>&lt;dir></code> attributes and <code>&lt;bdo></code>
     elements in case the Unicode bidirectional algorithm is insufficient to
     correctly order adjacent runs of mixed direction text.</p>
 
@@ -511,11 +514,11 @@
     features should be omitted entirely if not all users can make full use
     of them, but alternate mechanisms should be provided.</p>
 
-    <p class="example">The image in an <code>img</code> may not be visible to
+    <p class="example">The image in an <code>&lt;img></code> may not be visible to
     blind users, but that is a reason to provide alternate text, not to leave
     out images.</p>
     
-    <p class="example">The <code>progress</code> element is intrinsically
+    <p class="example">The <code>&lt;progress></code> element is intrinsically
     accessible as it has unambiguous progress bar semantics which permits
     mapping to accessibility APIs that can represent progress
     indicators.</p>
Received on Tuesday, 26 May 2009 07:36:35 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 26 May 2009 07:36:36 GMT