html5/spec Overview.html,1.2050,1.2051

Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv13466

Modified Files:
	Overview.html 
Log Message:
Clarify <time>'s use cases and provide examples. (bug 6536) (whatwg r2878)

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.2050
retrieving revision 1.2051
diff -u -d -r1.2050 -r1.2051
--- Overview.html	18 Mar 2009 19:32:29 -0000	1.2050
+++ Overview.html	19 Mar 2009 01:10:44 -0000	1.2051
@@ -144,7 +144,7 @@
    <p><a href=http://www.w3.org/><img alt=W3C height=48 src=http://www.w3.org/Icons/w3c_home width=72></a></p>
    <h1>HTML 5</h1>
    <h2 class="no-num no-toc" id=a-vocabulary-and-associated-apis-for-html-and-xhtml>A vocabulary and associated APIs for HTML and XHTML</h2>
-   <h2 class="no-num no-toc" id=w3c-working-draft-12-february-year><!--ZZZ:--> W3C Working Draft 12 February 2009<!-- fix date ZZZ --><!-- Editor's Draft 18 March 2009 --><!--:ZZZ--></h2>
+   <h2 class="no-num no-toc" id=w3c-working-draft-12-february-year><!--ZZZ:--> W3C Working Draft 12 February 2009<!-- fix date ZZZ --><!-- Editor's Draft 19 March 2009 --><!--:ZZZ--></h2>
    <dl><!-- ZZZ: update the month/day (twice), uncomment out --><dt>This Version:</dt>
     <dd><a href=http://www.w3.org/TR/2009/WD-html5-20090212/>http://www.w3.org/TR/2009/WD-html5-20090212/</a></dd>
 <!-- :ZZZ -->
@@ -234,7 +234,7 @@
   track.
   <!--ZZZ:-->
   This specification is the 12 February 2009 Working Draft.
-  <!-- This specification is the 18 March 2009 Editor's Draft. -->
+  <!-- This specification is the 19 March 2009 Editor's Draft. -->
   <!--:ZZZ-->
   </p><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- relationship to other work (required) --><p>This specification is also being produced by the <a href=http://www.whatwg.org/>WHATWG</a>. The two specifications are
   identical from the table of contents onwards.</p><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- context and rationale (required) --><p>This specification is intended to replace (be a new version of)
@@ -12561,13 +12561,69 @@
 };</pre>
    </dd>
   </dl><p>The <code><a href=#the-time-element>time</a></code> element <a href=#represents>represents</a> a precise
-  date and/or a time in the proleptic Gregorian calendar. <a href=#references>[GREGORIAN]</a><p>The <dfn id=attr-time-datetime title=attr-time-datetime><code>datetime</code></dfn>
+  date and/or a time in the proleptic Gregorian calendar. <a href=#references>[GREGORIAN]</a><p>This element is intended as a way to encode modern dates and
+  times in a machine-readable way so that user agents can offer to add
+  them to the user's calendar. For example, adding birthday reminders
+  or scheduling events.</p><!-- it's also intended for restyling to local conventions
+  (2000-12-31 vs 31-12-2000 vs 12-31-2000), but CSS doesn't support
+  that yet. --><div class=note>
+
+   <p>The <code><a href=#the-time-element>time</a></code> element is not intended for encoding times
+   for which a precise date or time cannot be established. For
+   example, it would be inappropriate for encoding times like "one
+   millisecond after the big bang", "the early part of the Jurassic
+   period", or "a winter around 250 BCE".</p>
+
+   <p>For dates before the introduction of the Gregorian calendar,
+   authors are encouraged to not use the <code><a href=#the-time-element>time</a></code> element, or
+   else to be very careful about converting dates and times from the
+   period to the Gregorian calendar. This is complicated by the way
+   the Gregorian calendar was phased in at different times in
+   different countries, ranging from part way through the 16th century
+   all the way to early in the 20th.</p>
+
+  </div><p>The <dfn id=attr-time-datetime title=attr-time-datetime><code>datetime</code></dfn>
   attribute, if present, must contain a <a href=#valid-date-or-time-string>valid date or time
   string</a> that identifies the date or time being specified.<p>If the <code title=attr-time-datetime><a href=#attr-time-datetime>datetime</a></code> attribute
   is not present, then the date or time must be specified in the
   content of the element, such that the element's
   <code><a href=#textcontent>textContent</a></code> is a <a href=#valid-date-or-time-string-in-content>valid date or time string in
-  content</a>.<div class=impl>
+  content</a>.<div class=example>
+
+   <p>The <code><a href=#the-time-element>time</a></code> element can be used to encode dates, for
+   example in Microformats. The following shows a hypothetical way of
+   encoding an event using a variant on hCalendar that uses the
+   <code><a href=#the-time-element>time</a></code> element:</p>
+
+   <pre>&lt;div class="vevent"&gt;
+ &lt;a class="url" href="http://www.web2con.com/"&gt;http://www.web2con.com/&lt;/a&gt;
+  &lt;span class="summary"&gt;Web 2.0 Conference&lt;/span&gt;:
+  &lt;time class="dtstart" datetime="2007-10-05"&gt;October 5&lt;/time&gt; -
+  &lt;time class="dtend" datetime="2007-10-20"&gt;19&lt;/time&gt;,
+  at the &lt;span class="location"&gt;Argent Hotel, San Francisco, CA&lt;/span&gt;
+ &lt;/div&gt;</pre>
+
+  </div><div class=example>
+
+   <p>The <code><a href=#the-time-element>time</a></code> element is not necessary for encoding
+   dates or times. In the following snippet, the time is encoded using
+   <code><a href=#the-time-element>time</a></code>, so that it can be restyled (e.g. using XBL2) to
+   match local conventions, while the year is not marked up at all,
+   since marking it up would not be particularly useful.</p>
+
+   <pre>&lt;p&gt;I usually have a snack &lt;time&gt;16:00&lt;/time&gt;.&lt;/p&gt;
+&lt;p&gt;I've liked model trains since at least 1983.&lt;/p&gt;</pre>
+
+   <p>Using a styling technology that supports restyling times, the
+   first paragraph from the above snipet could be rendered as follows:</p>
+
+   <blockquote><p>I usually have a snack at 4pm.</blockquote>
+
+   <p>Or it could be rendered as follows:</p>
+
+   <blockquote><p>I usually have a snack at 16h00.</blockquote>
+
+  </div><div class=impl>
 
   <p>The <dfn id=dom-time-datetime title=dom-time-datetime><code>dateTime</code></dfn> DOM
   attribute must <a href=#reflect>reflect</a> the <code title=attr-time-datetime><a href=#attr-time-datetime>datetime</a></code> content attribute.</p>
@@ -12685,11 +12741,7 @@
    value 28,800,000ms, and the <code title=dom-time-timezone><a href=#dom-time-timezone>timezone</a></code> attribute would return
    null.</p>
 
-  </div><p class=note>The <code><a href=#the-time-element>time</a></code> element is not intended for
-  encoding times for which a precise date or time cannot be
-  established. For example, it would be inappropriate for encoding
-  times like "one millisecond after the big bang", "the early part of
-  the Jurassic period", or "a winter around 250 BCE".<h4 id=the-progress-element><span class=secno>4.6.11 </span>The <dfn><code>progress</code></dfn> element</h4><dl class=element><dt>Categories</dt>
+  </div><h4 id=the-progress-element><span class=secno>4.6.11 </span>The <dfn><code>progress</code></dfn> element</h4><dl class=element><dt>Categories</dt>
    <dd><a href=#flow-content-0>Flow content</a>.</dd>
    <dd><a href=#phrasing-content-0>Phrasing content</a>.</dd>
    <dt>Contexts in which this element may be used:</dt>

Received on Thursday, 19 March 2009 01:10:57 UTC