Skip to content

Commit

Permalink
[e] (0) Clarify <time>'s use cases and provide examples. (bug 6536)
Browse files Browse the repository at this point in the history 
git-svn-id: http://svn.whatwg.org/webapps@2878 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Mar 19, 2009
1 parent 7f75923 commit cfaf547
Show file tree
Hide file tree
Showing 2 changed files with 133 additions and 13 deletions.
74 changes: 67 additions & 7 deletions index
View file
Expand Up @@ -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-&mdash;-date:-01-jan-1901>Draft Recommendation &mdash; 18 March 2009</h2>
<h2 class="no-num no-toc" id=draft-recommendation-&mdash;-date:-01-jan-1901>Draft Recommendation &mdash; 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>
Expand Down Expand Up @@ -14377,6 +14377,33 @@ this specification: the &lt;abbr&gt;WHATWG&lt;/abbr&gt; and the
</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>
Expand All @@ -14387,6 +14414,45 @@ this specification: the &lt;abbr&gt;WHATWG&lt;/abbr&gt; and the
<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>&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
Expand Down Expand Up @@ -14511,12 +14577,6 @@ this specification: the &lt;abbr&gt;WHATWG&lt;/abbr&gt; and the

</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>
Expand Down
72 changes: 66 additions & 6 deletions source
View file
Expand Up @@ -15400,6 +15400,33 @@ this specification: the &lt;abbr>WHATWG&lt;/abbr> and the
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>
Expand All @@ -15410,6 +15437,45 @@ this specification: the &lt;abbr>WHATWG&lt;/abbr> and the
<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>&lt;div class="vevent">
&lt;a class="url" href="http://www.web2con.com/">http://www.web2con.com/&lt;/a>
&lt;span class="summary">Web 2.0 Conference&lt;/span>:
&lt;time class="dtstart" datetime="2007-10-05">October 5&lt;/time> -
&lt;time class="dtend" datetime="2007-10-20">19&lt;/time>,
at the &lt;span class="location">Argent Hotel, San Francisco, CA&lt;/span>
&lt;/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>&lt;p>I usually have a snack &lt;time>16:00&lt;/time>.&lt;/p>
&lt;p>I've liked model trains since at least 1983.&lt;/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
Expand Down Expand Up @@ -15559,12 +15625,6 @@ this specification: the &lt;abbr>WHATWG&lt;/abbr> and the

</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>
Expand Down

0 comments on commit cfaf547

Please sign in to comment.