- From: Maciej Stachowiak via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 26 May 2009 07:36:26 +0000
- To: public-html-commits@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><b>a<i>b</b>c</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><u></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><section></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><canvas>
fallback </canvas></code> or <code><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><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><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 — 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><b></code> and <code><i></code> elements
+ are widely used — 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 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><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.
- <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><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><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><b>a<i>b</b>c</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><section></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><canvas> fallback </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><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 — it is better to give them good default rendering for various
+ <p class="example">The <code><b></code> and <code><i></code> elements are widely
+ used — 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><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.</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><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><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 UTC