- From: Lachlan Hunt via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 24 Oct 2008 10:03:18 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/html-author In directory hutz:/tmp/cvs-serv16680 Modified Files: Overview.html Overview.src.html Log Message: Updated attribute syntax descriptions Index: Overview.html =================================================================== RCS file: /sources/public/html5/html-author/Overview.html,v retrieving revision 1.13 retrieving revision 1.14 diff -u -d -r1.13 -r1.14 --- Overview.html 19 Jul 2008 18:21:34 -0000 1.13 +++ Overview.html 24 Oct 2008 10:03:16 -0000 1.14 @@ -39,13 +39,14 @@ <h1 id=the-web>The Web Developer’s Guide to HTML 5</h1> - <h2 class="no-num no-toc" id=w3c-editors>W3C Editor’s Draft 19 July 2008</h2> + <h2 class="no-num no-toc" id=w3c-editors>W3C Editor’s Draft 24 October + 2008</h2> <dl> <dt>This version: <dd><a - href="http://www.w3.org/TR/2008/ED-html5-author-20080719">http://www.w3.org/TR/2008/ED-html5-author-20080719</a> + href="http://www.w3.org/TR/2008/ED-html5-author-20081024">http://www.w3.org/TR/2008/ED-html5-author-20081024</a> <dt>Latest version: @@ -123,21 +124,24 @@ <ul class=toc> <li><a href="#introduction"><span class=secno>1. </span>Introduction</a> <ul class=toc> - <li><a href="#conventions"><span class=secno>1.1 </span>Conventions</a> + <li><a href="#understanding"><span class=secno>1.1 </span>Understanding + Semantics</a> + + <li><a href="#conventions"><span class=secno>1.2 </span>Conventions</a> <ul class=toc> - <li><a href="#notes"><span class=secno>1.1.1 </span>Notes, Tips and + <li><a href="#notes"><span class=secno>1.2.1 </span>Notes, Tips and Warnings</a> - <li><a href="#example"><span class=secno>1.1.2 </span>Example + <li><a href="#example"><span class=secno>1.2.2 </span>Example Markup</a> <ul class=toc> - <li><a href="#attributes"><span class=secno>1.1.2.1. + <li><a href="#attributes"><span class=secno>1.2.2.1. </span>Attributes</a> - <li><a href="#void-elements"><span class=secno>1.1.2.2. </span>Void + <li><a href="#void-elements"><span class=secno>1.2.2.2. </span>Void Elements</a> - <li><a href="#namespaces"><span class=secno>1.1.2.3. + <li><a href="#namespaces"><span class=secno>1.2.2.3. </span>Namespaces</a> </ul> </ul> @@ -169,11 +173,11 @@ <li><a href="#unquoted-attr"><span class=secno>3.3.2 </span>Unquoted Attribute Values</a> - <li><a href="#single-quote-attr"><span class=secno>3.3.3 - </span>Single-Quoted Attribute Values</a> - - <li><a href="#double-quote-attr"><span class=secno>3.3.4 + <li><a href="#double-quote-attr"><span class=secno>3.3.3 </span>Double-Quoted Attribute Values</a> + + <li><a href="#single-quote-attr"><span class=secno>3.3.4 + </span>Single-Quoted Attribute Values</a> </ul> </ul> @@ -185,7 +189,8 @@ <li><a href="#metadata"><span class=secno>4.1.1 </span>Metadata Content</a> - <li><a href="#prose"><span class=secno>4.1.2 </span>Prose content</a> + <li><a href="#flow-content"><span class=secno>4.1.2 </span>Flow + content</a> <li><a href="#sectioning"><span class=secno>4.1.3 </span>Sectioning content</a> @@ -259,12 +264,52 @@ familiarise themselves with <a href="http://www.w3.org/TR/html5-diff/">the differences from HTML 4</a> [HTML4DIFF] - <h3 id=conventions><span class=secno>1.1 </span>Conventions</h3> + <h3 id=understanding><span class=secno>1.1 </span>Understanding Semantics</h3> + + <p>In general, the purpose of writing and publishing a document is to + convey information to the readers. This could be any kind of information, + such as telling a story, reporting news and current affairs or describing + available products and services. Whatever the information is, it needs to + be conveyed to the reader in a way that can be easily understood. + + <p>A typical document, such as an book, news article, blog entry or letter + is often grouped into different sections containing a variety of headings, + paragraphs, lists, tables, quotes and various other typographical + structures. All of these structures are important for more easily + conveying information to the reader and thus authors need a way to clearly + identify each of these structures in a way that can then be easily + presented to the user. This is the purpose of markup. + + <p>Markup is a machine readable language that describes aspects of a + document such as its structure, semantics and/or style. Some markup + languages are designed solely for the purpose of describing the + presentation of the document, such as RTF (Rich Text Format). Others, such + as HTML, are more generic and rather than focussing on describing the + presentation, they are designed to focus on describing the meaning or + purpose of the content and leave the presentation for another layer to + deal with. + + <p>HTML provides a wide variety of semantic elements that can be used to + mark up various common typographical structures. There are heading + elements for marking up different levels of headings, a paragraph (p) + element for paragraph, various list elements for marking up different + types of lists, and a table elements for marking up tables. + + <p>It's important to distinguish between the structure and semantics of + content, which should be described using HTML, and its presentation. In + one document, a heading may be presented visually in a large bold typeface + with wide margins above and below to separate it from the surrounding + content and make it stand out. In another document, a heading may be + presented in a light coloured, italic, fancy script typeface. But + regardless of the presentation, it's still a heading and the markup can + still uses the same basic elements for identifying common structures. + + <h3 id=conventions><span class=secno>1.2 </span>Conventions</h3> <p>To ease readability and improve understanding, this document uses a number of conventions. - <h4 id=notes><span class=secno>1.1.1 </span>Notes, Tips and Warnings</h4> + <h4 id=notes><span class=secno>1.2.1 </span>Notes, Tips and Warnings</h4> <p>Notes are used throughout this document to provide additional information. Tips are used to provide useful hints and suggestions. @@ -273,7 +318,7 @@ <p class=issue>[Need to provide examples of these] - <h4 id=example><span class=secno>1.1.2 </span>Example Markup</h4> + <h4 id=example><span class=secno>1.2.2 </span>Example Markup</h4> <p>Example markup is provided for both HTML and XHTML. In some cases, the markup is the same and thus only one example is needed, but in others @@ -323,7 +368,7 @@ </pre> </div> - <h5 id=attributes><span class=secno>1.1.2.1. </span>Attributes</h5> + <h5 id=attributes><span class=secno>1.2.2.1. </span>Attributes</h5> <p>Unless explicitly stated otherwise for a specific purpose, all attribute values in examples are quoted using double quotes. In HTML examples, @@ -346,7 +391,7 @@ </pre> </div> - <h5 id=void-elements><span class=secno>1.1.2.2. </span>Void Elements</h5> + <h5 id=void-elements><span class=secno>1.2.2.2. </span>Void Elements</h5> <p>In XHTML examples, due to the XML Well-Formedness requirements, void elements are always marked up using the trailing slash. @@ -370,7 +415,7 @@ </pre> </div> - <h5 id=namespaces><span class=secno>1.1.2.3. </span>Namespaces</h5> + <h5 id=namespaces><span class=secno>1.2.2.3. </span>Namespaces</h5> <p>Some XHTML examples make use of XML namespaces. In such cases, the following prefixes are assumed to be defined even if there is no @@ -620,8 +665,9 @@ <div class=example> <p>Example:</p> - <p>This example illustrates how to mark up a div element with an attribute - named <code>class</code> using a value of <code>"example"</code>.</p> + <p>This example illustrates how to mark up a <code>div</code> element with + an attribute named <code>class</code> using a value of + <code>"example"</code>.</p> <pre><code><div class="example">...</div></code></pre> </div> @@ -635,19 +681,40 @@ <pre><code><section id="example">...</section <strong>id="example"</strong>></code></pre> </div> + <p>In XHTML, attribute names are case sensitive and most are defined to be + lowercase. In HTML, attribute names are case insensitive, and so they + could be written in all uppercase or mixed case, depending on your own + preferences. It is conventional, however, to use the same case as would be + used in XHTML, which is generally all lowercase. + + <div class="html example"> + <p>HTML Example:</p> + + <pre><code><div CLASS="example"></code></pre> + </div> + + <p>In general, the values of attributes can contain any text or character + references, although depending on the syntax used, some additional + restrictions apply, which are outlined below. + <p>There are four slightly different syntaxes that may be used for - attributes in HTML: Empty attribute syntax, Unquoted attribute value - syntax, Single-quoted attribute value syntax and Double-quoted attribute - value syntax. All four syntaxes may be used in the HTML syntax, depending - on what is needed for each specific attribute. However, in the XHTML - syntax, attribute values must always be quoted using either single or - double quotes. + attributes in HTML: empty, unquoted, single-quoted and double-quoted. All + four syntaxes may be used in the HTML syntax, depending on what is needed + for each specific attribute. However, in the XHTML syntax, attribute + values must always be quoted using either single or double quotes. <h4 id=empty-attr><span class=secno>3.3.1 </span>Empty Attributes</h4> <p>An empty attribute is one where the value has been omitted. This is a syntactic shorthand for specifying the attribute with an empty value, and - is commonly used for boolean attributes. + is commonly used for boolean attributes. This syntax may be used in the + HTML syntax, but not in the XHTML syntax. + + <p class=note>Note: In previous editions of HTML, which were formally based + on SGML, it was technically an attribute's name that could be omitted + where the value was a unique enumerated value specified in the DTD. + However, due to legacy constraints, this has been changed in HTML5 to + reflect the way implementations really work. <div class="html example"> <p>HTML Example:</p> @@ -660,9 +727,9 @@ <pre><code><input disabled="">...</div></code></pre> </div> - <p class=note>Note: While, in the previous example, it is semantically - equivalent to specifying the attribute with the value - <code>"disabled"</code>, it is not exactly the same. + <p class=note>Note: The previous example is semantically equivalent to + specifying the attribute with the value <code>"disabled"</code>, but it is + not exactly the same. <div class="html example"> <p>Example:</p> @@ -679,36 +746,57 @@ Values</h4> <p>In HTML, but not in XHTML, the quotes surrounding the value may also be - omitted in most cases. This does not apply to XHTML. The value may contain - any characters except for spaces, single or double quotes (<code>'</code> - or <code>"</code>), an equals sign (<code>=</code>) or a greater-than - symbol (<code>></code>). If you need an attribute to contain those - characters, they either need to be escaped using character references, or - you need to use either the <span title=single-quote-attr>single-</span> or - <span title=double-quote-attr>double-quoted attribute values</span>. + omitted in most cases. The value may contain any characters except for + spaces, single or double quotes (<code>'</code> or <code>"</code>), an + equals sign (<code>=</code>) or a greater-than symbol (<code>></code>). + If you need an attribute to contain those characters, they either need to + be escaped using character references, or you need to use either the <span + title=single-quote-attr>single-</span> or <span + title=double-quote-attr>double-quoted attribute values</span>. - <h4 id=single-quote-attr><span class=secno>3.3.3 </span>Single-Quoted + <p>Some additional characters cannot be used in unquoted attribute values, + including space characters, single (<code>'</code>) or double + (<code>"</code>) quotation marks, equals signs (<code>=</code>) or greater + than signs (<code>></code>). + + <div class="html example"> + <p>HTML Example:</p> + + <pre><code><div class=example></code></pre> + </div> + + <h4 id=double-quote-attr><span class=secno>3.3.3 </span>Double-Quoted Attribute Values</h4> + <p>In both HTML and XHTML, attribute values may be surrounded with double + quotes. + + <p>By quoting attributes, the value may contain the additional characters + that can't be used in unquoted attribute values, but for obvious reasons, + these attributes cannot contain additional double quotation marks within + the value. + <div class=example> <p>Example:</p> - <pre><code><div class='example'>...</div></code></pre> + <pre><code><div class="example class names">...</div></code></pre> </div> - <h4 id=double-quote-attr><span class=secno>3.3.4 </span>Double-Quoted + <h4 id=single-quote-attr><span class=secno>3.3.4 </span>Single-Quoted Attribute Values</h4> - <p>In XHTML, attribute names are case sensitive and most are defined to be - lowercase. In HTML, attribute names are case insensitive, and so they - could be written in all uppercase or mixed case, depending on your own - preferences. It is conventional, however, to use the same case as would be - used in XHTML, which is generally all lowercase. + <p>In both HTML and XHTML, attribute values may be surrounded with double + quotes. - <div class="html example"> - <p>HTML Example:</p> + <p>By quoting attributes, the value may contain the additional characters + that can't be used in unquoted attribute values, but for obvious reasons, + these attributes cannot contain additional single quotation marks within + the value. - <pre><code><div CLASS="example"></code></pre> + <div class=example> + <p>Example:</p> + + <pre><code><div class='example class names'>...</div></code></pre> </div> <h2 id=element><span class=secno>4. </span>Element Structure and Semantics</h2> @@ -755,7 +843,28 @@ metadata elements include: <code>title</code>, <code>meta</code>, <code>link</code>, <code>script</code> and <code>style</code> - <h4 id=prose><span class=secno>4.1.2 </span>Prose content</h4> + <h4 id=flow-content><span class=secno>4.1.2 </span>Flow content</h4> + + <p>Most elements that are used in the body of documents and applications + are categorised as flow content. Most of the elements used to mark up the + main content in the body of a page are considered to be flow content. In + general, this includes elements that are presented visually as either + block level or inline level. + + <p>Some common flow content includes elements like div, p, ul, and + + <p>As a general rule, elements whose content model allows any flow content + should have either at least one descendant text node that is not + inter-element whitespace, or at least one descendant element node that is + embedded content. For the purposes of this requirement, del elements and + their descendants must not be counted as contributing to the ancestors of + the del element. + + <p>This requirement is not a hard requirement, however, as there are many + cases where an element can be empty legitimately, for example when it is + used as a placeholder which will later be filled in by a script, or when + the element is part of a template and would on most pages be filled in but + on some pages is not relevant. <h4 id=sectioning><span class=secno>4.1.3 </span>Sectioning content</h4> @@ -995,7 +1104,7 @@ <p><a href="#sectioning0" title="sectioning elements">Sectioning</a> <span title="block-level elements">block-level element</span>. - <dl class=element> + <dl class=summary> <dt>Contexts in which this element may be used: <dd>Where <span>block-level elements</span> are expected. Index: Overview.src.html =================================================================== RCS file: /sources/public/html5/html-author/Overview.src.html,v retrieving revision 1.13 retrieving revision 1.14 diff -u -d -r1.13 -r1.14 --- Overview.src.html 19 Jul 2008 18:21:34 -0000 1.13 +++ Overview.src.html 24 Oct 2008 10:03:16 -0000 1.14 @@ -113,6 +113,46 @@ <p>Authors who are familiar with previous versions of HTML are advised to familiarise themselves with <a href="http://www.w3.org/TR/html5-diff/">the differences from HTML 4</a> [HTML4DIFF]</p> + <h3>Understanding Semantics</h3> + + <p>In general, the purpose of writing and publishing a document is to convey + information to the readers. This could be any kind of information, such + as telling a story, reporting news and current affairs or describing + available products and services. Whatever the information is, it needs + to be conveyed to the reader in a way that can be easily understood.</p> + + <p>A typical document, such as an book, news article, blog entry or letter + is often grouped into different sections containing a variety of + headings, paragraphs, lists, tables, quotes and various other + typographical structures. All of these structures are important for more + easily conveying information to the reader and thus authors need a way to + clearly identify each of these structures in a way that can then be + easily presented to the user. This is the purpose of markup.</p> + + <p>Markup is a machine readable language that describes aspects of a + document such as its structure, semantics and/or style. Some markup + languages are designed solely for the purpose of describing the + presentation of the document, such as RTF (Rich Text Format). Others, + such as HTML, are more generic and rather than focussing on describing + the presentation, they are designed to focus on describing the meaning or + purpose of the content and leave the presentation for another layer to + deal with.</p> + + <p>HTML provides a wide variety of semantic elements that can be used to + mark up various common typographical structures. There are heading + elements for marking up different levels of headings, a paragraph (p) + element for paragraph, various list elements for marking up different + types of lists, and a table elements for marking up tables.</p> + + <p>It's important to distinguish between the structure and semantics of + content, which should be described using HTML, and its presentation. In + one document, a heading may be presented visually in a large bold + typeface with wide margins above and below to separate it from the + surrounding content and make it stand out. In another document, a + heading may be presented in a light coloured, italic, fancy script + typeface. But regardless of the presentation, it's still a heading and + the markup can still uses the same basic elements for identifying common + structures.</p> <h3>Conventions</h3> <p>To ease readability and improve understanding, this document uses a @@ -440,8 +480,8 @@ <div class="example"> <p>Example:</p> - <p>This example illustrates how to mark up a div element with an - attribute named <code>class</code> using a value of + <p>This example illustrates how to mark up a <code>div</code> element + with an attribute named <code>class</code> using a value of <code>"example"</code>.</p> <pre><code><div class="example">...</div></code></pre> </div> @@ -454,19 +494,39 @@ <pre><code><section id="example">...</section <strong>id="example"</strong>></code></pre> </div> + <p>In XHTML, attribute names are case sensitive and most are defined to be + lowercase. In HTML, attribute names are case insensitive, and so they + could be written in all uppercase or mixed case, depending on your own + preferences. It is conventional, however, to use the same case as would + be used in XHTML, which is generally all lowercase.</p> + + <div class="html example"> + <p>HTML Example:</p> + <pre><code><div CLASS="example"></code></pre> + </div> + + <p>In general, the values of attributes can contain any text or + character references, although depending on the syntax used, some + additional restrictions apply, which are outlined below.</p> + <p>There are four slightly different syntaxes that may be used for - attributes in HTML: Empty attribute syntax, Unquoted attribute value - syntax, Single-quoted attribute value syntax and Double-quoted attribute - value syntax. All four syntaxes may be used in the HTML syntax, depending - on what is needed for each specific attribute. However, in the XHTML - syntax, attribute values must always be quoted using either single or - double quotes.</p> + attributes in HTML: empty, unquoted, single-quoted and double-quoted. All + four syntaxes may be used in the HTML syntax, depending on what is needed + for each specific attribute. However, in the XHTML syntax, attribute + values must always be quoted using either single or double quotes.</p> <h4 id="empty-attr">Empty Attributes</h4> <p>An empty attribute is one where the value has been omitted. This is a syntactic shorthand for specifying the attribute with an empty value, - and is commonly used for boolean attributes.</p> + and is commonly used for boolean attributes. This syntax may be used in + the HTML syntax, but not in the XHTML syntax.</p> + + <p class="note">Note: In previous editions of HTML, which were formally + based on SGML, it was technically an attribute's name that could be + omitted where the value was a unique enumerated value specified in the + DTD. However, due to legacy constraints, this has been changed in HTML5 + to reflect the way implementations really work.</p> <div class="html example"> <p>HTML Example:</p> @@ -477,9 +537,9 @@ <pre><code><input disabled="">...</div></code></pre> </div> - <p class="note">Note: While, in the previous example, it is semantically - equivalent to specifying the attribute with the value <code>"disabled"</code>, - it is not exactly the same.</p> + <p class="note">Note: The previous example is semantically equivalent to + specifying the attribute with the value <code>"disabled"</code>, but it + is not exactly the same.</p> <div class="html example"> <p>Example:</p> @@ -493,36 +553,56 @@ <h4 id="unquoted-attr">Unquoted Attribute Values</h4> <p>In HTML, but not in XHTML, the quotes surrounding the value may also be - omitted in most cases. This does not apply to XHTML. The value may - contain any characters except for spaces, single or double quotes - (<code>'</code> or <code>"</code>), an equals sign (<code>=</code>) or a - greater-than symbol (<code>></code>). If you need an attribute to - contain those characters, they either need to be escaped using - character references, or you need to use either the - <span title="single-quote-attr">single-</span> or - <span title="double-quote-attr">double-quoted attribute values</span>.</p> + omitted in most cases. The value may contain any characters except for + spaces, single or double quotes (<code>'</code> or <code>"</code>), an + equals sign (<code>=</code>) or a greater-than symbol + (<code>></code>). If you need an attribute to contain those + characters, they either need to be escaped using character references, or + you need to use either the <span title="single-quote-attr">single-</span> + or <span title="double-quote-attr">double-quoted attribute values</span>.</p> - <h4 id="single-quote-attr">Single-Quoted Attribute Values</h4> + <p>Some additional characters cannot be used in unquoted attribute values, + including space characters, single (<code>'</code>) or double + (<code>"</code>) quotation marks, equals signs (<code>=</code>) or + greater than signs (<code>></code>).</p> + + <div class="html example"> + <p>HTML Example:</p> + <pre><code><div class=example></code></pre> + </div> + + <h4 id="double-quote-attr">Double-Quoted Attribute Values</h4> + + <p>In both HTML and XHTML, attribute values may be surrounded with double + quotes.</p> + + <p>By quoting attributes, the value may contain the additional characters + that can't be used in unquoted attribute values, but for obvious reasons, + these attributes cannot contain additional double quotation marks within + the value.</p> <div class="example"> <p>Example:</p> - <pre><code><div class='example'>...</div></code></pre> + <pre><code><div class="example class names">...</div></code></pre> </div> - <h4 id="double-quote-attr">Double-Quoted Attribute Values</h4> + <h4 id="single-quote-attr">Single-Quoted Attribute Values</h4> - <p>In XHTML, attribute names are case sensitive and most are defined to be - lowercase. In HTML, attribute names are case insensitive, and so they - could be written in all uppercase or mixed case, depending on your own - preferences. It is conventional, however, to use the same case as would - be used in XHTML, which is generally all lowercase.</p> + <p>In both HTML and XHTML, attribute values may be surrounded with double + quotes.</p> - <div class="html example"> - <p>HTML Example:</p> - <pre><code><div CLASS="example"></code></pre> + <p>By quoting attributes, the value may contain the additional characters + that can't be used in unquoted attribute values, but for obvious reasons, + these attributes cannot contain additional single quotation marks within + the value.</p> + + <div class="example"> + <p>Example:</p> + <pre><code><div class='example class names'>...</div></code></pre> </div> + <h2>Element Structure and Semantics</h2> <h3>Categories</h3> @@ -558,7 +638,28 @@ <code>meta</code>, <code>link</code>, <code>script</code> and <code>style</code></p> - <h4>Prose content</h4> + <h4>Flow content</h4> + + <p>Most elements that are used in the body of documents and applications are + categorised as flow content. Most of the elements used to mark up the + main content in the body of a page are considered to be flow content. + In general, this includes elements that are presented visually as either + block level or inline level.</p> + + <p>Some common flow content includes elements like div, p, ul, and + + <p>As a general rule, elements whose content model allows any flow content + should have either at least one descendant text node that is not + inter-element whitespace, or at least one descendant element node that is + embedded content. For the purposes of this requirement, del elements and + their descendants must not be counted as contributing to the ancestors of + the del element.</p> + + <p>This requirement is not a hard requirement, however, as there are many + cases where an element can be empty legitimately, for example when it is + used as a placeholder which will later be filled in by a script, or when + the element is part of a template and would on most pages be filled in + but on some pages is not relevant.</p> <h4>Sectioning content</h4> @@ -753,7 +854,7 @@ <h4>The <dfn><code>section</code></dfn> element</h4> <p><span title="sectioning elements">Sectioning</span> <span title="block-level elements">block-level element</span>.</p> - <dl class="element"> + <dl class="summary"> <dt>Contexts in which this element may be used:</dt> <dd>Where <span>block-level elements</span> are expected.</dd> <dt>Content model:</dt>
Received on Friday, 24 October 2008 10:03:28 UTC