[html5] r2878 - [e] (0) Clarify <time>'s use cases and provide examples. (bug 6536)

whatwg at whatwg.org whatwg at whatwg.org
Wed Mar 18 18:10:37 PDT 2009


Author: ianh
Date: 2009-03-18 18:10:36 -0700 (Wed, 18 Mar 2009)
New Revision: 2878

Modified:
   index
   source
Log:
[e] (0) Clarify <time>'s use cases and provide examples. (bug 6536)

Modified: index
===================================================================
--- index	2009-03-18 19:31:53 UTC (rev 2877)
+++ index	2009-03-19 01:10:36 UTC (rev 2878)
@@ -39,7 +39,7 @@
   <div class=head>
    <p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG src=/images/logo></a></p>
    <h1>HTML 5</h1>
-   <h2 class="no-num no-toc" id=draft-recommendation-—-date:-01-jan-1901>Draft Recommendation — 18 March 2009</h2>
+   <h2 class="no-num no-toc" id=draft-recommendation-—-date:-01-jan-1901>Draft Recommendation — 19 March 2009</h2>
    <p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
    <p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
    <dl><dt>Multiple-page version:</dt>
@@ -14377,6 +14377,33 @@
   </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=#refsGREGORIAN>[GREGORIAN]</a></p>
 
+  <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>
@@ -14387,6 +14414,45 @@
   <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>.</p>
 
+  <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><div class="vevent">
+ <a class="url" href="http://www.web2con.com/">http://www.web2con.com/</a>
+  <span class="summary">Web 2.0 Conference</span>:
+  <time class="dtstart" datetime="2007-10-05">October 5</time> -
+  <time class="dtend" datetime="2007-10-20">19</time>,
+  at the <span class="location">Argent Hotel, San Francisco, CA</span>
+ </div></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><p>I usually have a snack <time>16:00</time>.</p>
+<p>I've liked model trains since at least 1983.</p></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
@@ -14511,14 +14577,8 @@
 
   </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".</p>
 
 
-
   <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>

Modified: source
===================================================================
--- source	2009-03-18 19:31:53 UTC (rev 2877)
+++ source	2009-03-19 01:10:36 UTC (rev 2878)
@@ -15400,6 +15400,33 @@
   date and/or a time in the proleptic Gregorian calendar. <a
   href="#refsGREGORIAN">[GREGORIAN]</a></p>
 
+  <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>time</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>time</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 title="attr-time-datetime"><code>datetime</code></dfn>
   attribute, if present, must contain a <span>valid date or time
   string</span> that identifies the date or time being specified.</p>
@@ -15410,6 +15437,45 @@
   <code>textContent</code> is a <span>valid date or time string in
   content</span>.</p>
 
+  <div class="example">
+
+   <p>The <code>time</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>time</code> element:</p>
+
+   <pre><div class="vevent">
+ <a class="url" href="http://www.web2con.com/">http://www.web2con.com/</a>
+  <span class="summary">Web 2.0 Conference</span>:
+  <time class="dtstart" datetime="2007-10-05">October 5</time> -
+  <time class="dtend" datetime="2007-10-20">19</time>,
+  at the <span class="location">Argent Hotel, San Francisco, CA</span>
+ </div></pre>
+
+  </div>
+
+  <div class="example">
+
+   <p>The <code>time</code> element is not necessary for encoding
+   dates or times. In the following snippet, the time is encoded using
+   <code>time</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><p>I usually have a snack <time>16:00</time>.</p>
+<p>I've liked model trains since at least 1983.</p></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.</p></blockquote>
+
+   <p>Or it could be rendered as follows:</p>
+
+   <blockquote><p>I usually have a snack at 16h00.</p></blockquote>
+
+  </div>
+
   <div class="impl">
 
   <p>The <dfn title="dom-time-datetime"><code>dateTime</code></dfn> DOM
@@ -15559,14 +15625,8 @@
 
   </div>
 
-  <p class="note">The <code>time</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>
 
 
-
   <h4>The <dfn><code>progress</code></dfn> element</h4>
 
   <dl class="element">




More information about the Commit-Watchers mailing list