- From: Lachlan Hunt via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 05 Mar 2009 13:00:30 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/html-author
In directory hutz:/tmp/cvs-serv29367
Modified Files:
Overview.html Overview.src.html
Log Message:
Added syntactic overview
Index: Overview.html
===================================================================
RCS file: /sources/public/html5/html-author/Overview.html,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -d -r1.37 -r1.38
--- Overview.html 5 Mar 2009 03:47:42 -0000 1.37
+++ Overview.html 5 Mar 2009 13:00:27 -0000 1.38
@@ -129,7 +129,7 @@
<li><a href=#understanding-semantics><span class=secno>2.2 </span>Understanding Semantics</a></li></ol></li>
<li><a href=#the-html-and-xhtml-syntax><span class=secno>3 </span>The HTML and XHTML Syntax</a>
<ol class=toc>
- <li><a href=#html><span class=secno>3.1 </span>HTML</a></li></ol></li>
+ <li><a href=#syntactic-overview><span class=secno>3.1 </span>Syntactic Overview</a></li></ol></li>
<li><a href=#the-html-vocabulary-and-apis><span class=secno>4 </span>The HTML Vocabulary and APIs</a>
<ol class=toc>
<li><a href=#categories><span class=secno>4.1 </span>Categories</a>
@@ -400,24 +400,109 @@
</section>
</section>
-
+<!-- The HTML and XHTML Syntax -->
<section>
<h2 id=the-html-and-xhtml-syntax><span class=secno>3 </span>The HTML and XHTML Syntax</h2>
- <p>...</p>
+
+ <p>It is useful to make a distinction between the vocabulary of an HTML
+ document—the elements and attributes, and their meanings—and the syntax
+ in which it is written.</p>
+
+ <p>HTML has a defined set of elements and attributes which can be used in
+ a document; each designed for a specific purpose with their own meaning.
+ Consider this set of elements to be analogous to the list of words in a
+ dictionary. This includes elements for headings, paragraphs, lists,
+ tables, links, form controls and many other features. This is the
+ vocabulary of HTML. Similarly, just as natural languages have grammatical
+ rules for how different words can be used, HTML has rules for where and
+ how each element and attribute can be used.</p>
+
+ <p>The basic structure of elements in an HTML document is a tree structure.
+ Most elements have at most one parent element, (except for the root
+ element), and may have any number of child elements. This structure needs
+ to be reflected in the syntax used to write the document.</p>
<section>
- <h3 id=html><span class=secno>3.1 </span>HTML</h3>
- ...
+ <h3 id=syntactic-overview><span class=secno>3.1 </span>Syntactic Overview</h3>
+
+ <p>There are two syntaxes that can be used: the traditional HTML syntax,
+ and the XHTML syntax. While these are similar, each is optimised for
+ different needs and authoring habits. The former is more lenient in
+ its design and handling requirements, and has a number of convenient
+ shorthands for authors to use. The latter is based on XML and has
+ much stricter syntactic requirements, designed to discourage the
+ proliferation of syntactic errors.</p>
+
+ <p>The HTML syntax is loosely based upon the older, though very widely
+ used syntax from HTML 4.01. Although it is inspired by its SGML
+ origins, in practice, it really only shares minor syntactic
+ similarities. This features a range of shorthand syntaxes, designed
+ to make hand coding more convenient, such as allowing the omission of
+ some optional tags and attribute values. Authors are free to choose
+ whether or not they wish to take advantage of these shorthand
+ features based upon their own personal preferences.</p>
+
+ <p>The following example illustrates a basic HTML document,
+ demonstrating a few of the shorthand syntax</p>
+
+ <div class="example html">
+ <p>HTML Example:</p>
+ <pre><!DOCTYPE html>
+<html>
+ <head>
+ <title>An HTML Document</title>
+ </head>
+ <body class=example>
+ <h1>Example</h1>
+ <p>This is an example HTML document.
+ </body>
+</html></pre>
+ </div>
+
+ <p>XHTML, however, is based on the much more strict XML syntax. While
+ this too is inspired by SGML, this syntax requires documents to be
+ well-formed, which some people prefer because of it's stricter error handling,
+ forcing authors to maintain cleaner markup.</p>
+
+ <div class="example xhtml">
+ <p>XHTML Example:</p>
+ <pre><html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>An HTML Document</title>
+ </head>
+ <body class="example">
+ <h1>Example</h1>
+ <p>This is an example HTML document.</p>
+ </body>
+</html></pre>
+ </div>
+
+ <p class=note>Note: The XHTML document does not need to include the
+ DOCTYPE because XHTML documents that are delivered correctly using an
+ XML MIME type and are processed as XML by browsers, are always rendered
+ in <em>no quirks mode</em>. However, the DOCTYPE may optionally be
+ included, and should be included if the document uses the compatible
+ subset of markup that is conforming in both HTML and XHTML, and is ever
+ expected to be used in <code>text/html</code> environments.</p>
+
+ <p>Due to the similarities of both the HTML and XHTML syntaxes, it is
+ possible to mark up documents using a common subset of the syntax
+ that is the same in both, while avoiding the syntactic sugar that is
+ unique to each. This type of document is known as a polyglot
+ document because it simultaneously conforms to both syntaxes and may
+ be handled as either. There are a number of issues involved with
+ creating such documents and authors wishing to do so should
+ familiarise themselves with the similarities and differences between
+ HTML and XHTML.</p>
</section>
</section>
-
+<!-- The HTML Vocabulary and APIs -->
<section>
<h2 id=the-html-vocabulary-and-apis><span class=secno>4 </span>The HTML Vocabulary and APIs</h2>
<p class=big-issue>Expect major changes to this section. Each of these
needs longer descriptions and the elements should be divided into
- categories.
- The IDL for the DOM Interfaces is likely to be replaced by something
+ categories. The IDL for the DOM Interfaces is likely to be replaced by something
a lot more reader-friendly in the future; consider it a placeholder
for now. Attributes will likely be accompanied by brief descriptions
within the summary box, in addition to fuller descriptions and examples
@@ -4367,6 +4452,7 @@
</section>
</section>
+<!-- Index of Elements -->
<section>
<h2 id=index-of-elements><span class=secno>5 </span>Index of Elements</h2>
<section>
Index: Overview.src.html
===================================================================
RCS file: /sources/public/html5/html-author/Overview.src.html,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -d -r1.38 -r1.39
--- Overview.src.html 5 Mar 2009 03:47:42 -0000 1.38
+++ Overview.src.html 5 Mar 2009 13:00:28 -0000 1.39
@@ -264,24 +264,109 @@
</section>
</section>
-
+<!-- The HTML and XHTML Syntax -->
<section>
<h1>The HTML and XHTML Syntax</h1>
- <p>...</p>
+
+ <p>It is useful to make a distinction between the vocabulary of an HTML
+ document—the elements and attributes, and their meanings—and the syntax
+ in which it is written.</p>
+
+ <p>HTML has a defined set of elements and attributes which can be used in
+ a document; each designed for a specific purpose with their own meaning.
+ Consider this set of elements to be analogous to the list of words in a
+ dictionary. This includes elements for headings, paragraphs, lists,
+ tables, links, form controls and many other features. This is the
+ vocabulary of HTML. Similarly, just as natural languages have grammatical
+ rules for how different words can be used, HTML has rules for where and
+ how each element and attribute can be used.</p>
+
+ <p>The basic structure of elements in an HTML document is a tree structure.
+ Most elements have at most one parent element, (except for the root
+ element), and may have any number of child elements. This structure needs
+ to be reflected in the syntax used to write the document.</p>
<section>
- <h1>HTML</h1>
- ...
+ <h1>Syntactic Overview</h1>
+
+ <p>There are two syntaxes that can be used: the traditional HTML syntax,
+ and the XHTML syntax. While these are similar, each is optimised for
+ different needs and authoring habits. The former is more lenient in
+ its design and handling requirements, and has a number of convenient
+ shorthands for authors to use. The latter is based on XML and has
+ much stricter syntactic requirements, designed to discourage the
+ proliferation of syntactic errors.</p>
+
+ <p>The HTML syntax is loosely based upon the older, though very widely
+ used syntax from HTML 4.01. Although it is inspired by its SGML
+ origins, in practice, it really only shares minor syntactic
+ similarities. This features a range of shorthand syntaxes, designed
+ to make hand coding more convenient, such as allowing the omission of
+ some optional tags and attribute values. Authors are free to choose
+ whether or not they wish to take advantage of these shorthand
+ features based upon their own personal preferences.</p>
+
+ <p>The following example illustrates a basic HTML document,
+ demonstrating a few of the shorthand syntax</p>
+
+ <div class="example html">
+ <p>HTML Example:</p>
+ <pre><!DOCTYPE html>
+<html>
+ <head>
+ <title>An HTML Document</title>
+ </head>
+ <body class=example>
+ <h1>Example</h1>
+ <p>This is an example HTML document.
+ </body>
+</html></pre>
+ </div>
+
+ <p>XHTML, however, is based on the much more strict XML syntax. While
+ this too is inspired by SGML, this syntax requires documents to be
+ well-formed, which some people prefer because of it's stricter error handling,
+ forcing authors to maintain cleaner markup.</p>
+
+ <div class="example xhtml">
+ <p>XHTML Example:</p>
+ <pre><html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>An HTML Document</title>
+ </head>
+ <body class="example">
+ <h1>Example</h1>
+ <p>This is an example HTML document.</p>
+ </body>
+</html></pre>
+ </div>
+
+ <p class="note">Note: The XHTML document does not need to include the
+ DOCTYPE because XHTML documents that are delivered correctly using an
+ XML MIME type and are processed as XML by browsers, are always rendered
+ in <em>no quirks mode</em>. However, the DOCTYPE may optionally be
+ included, and should be included if the document uses the compatible
+ subset of markup that is conforming in both HTML and XHTML, and is ever
+ expected to be used in <code>text/html</code> environments.</p>
+
+ <p>Due to the similarities of both the HTML and XHTML syntaxes, it is
+ possible to mark up documents using a common subset of the syntax
+ that is the same in both, while avoiding the syntactic sugar that is
+ unique to each. This type of document is known as a polyglot
+ document because it simultaneously conforms to both syntaxes and may
+ be handled as either. There are a number of issues involved with
+ creating such documents and authors wishing to do so should
+ familiarise themselves with the similarities and differences between
+ HTML and XHTML.</p>
</section>
</section>
-
+<!-- The HTML Vocabulary and APIs -->
<section>
<h1>The HTML Vocabulary and APIs</h1>
<p class="big-issue">Expect major changes to this section. Each of these
needs longer descriptions and the elements should be divided into
- categories.
- The IDL for the DOM Interfaces is likely to be replaced by something
+ categories. The IDL for the DOM Interfaces is likely to be replaced by something
a lot more reader-friendly in the future; consider it a placeholder
for now. Attributes will likely be accompanied by brief descriptions
within the summary box, in addition to fuller descriptions and examples
@@ -4231,6 +4316,7 @@
</section>
</section>
+<!-- Index of Elements -->
<section>
<h1>Index of Elements</h1>
<section>
Received on Thursday, 5 March 2009 13:00:38 UTC