[e] (0) Introduce some documentation about wire formats vs presented …

…formats for date and time data.

Affected topics: HTML

git-svn-id: http://svn.whatwg.org/webapps@6904 340c8d12-0b0e-0410-8428-c7bf67bfef74

complete.html

@@ -240,7 +240,7 @@
 
   <header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
    <hgroup><h1 class=allcaps>HTML</h1>
-    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 18 January 2012</h2>
+    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 19 January 2012</h2>
    </hgroup><dl><dt><strong>Web developer edition:</strong></dt>
     <dd><strong><a href=http://developers.whatwg.org/>http://developers.whatwg.org/</a></strong></dd>
     <dt>Multiple-page version:</dt>
@@ -650,7 +650,8 @@ <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 18 January 2012</
        <li><a href="#writing-a-form's-user-interface"><span class=secno>4.10.1.1 </span>Writing a form's user interface</a></li>
        <li><a href=#implementing-the-server-side-processing-for-a-form><span class=secno>4.10.1.2 </span>Implementing the server-side processing for a form</a></li>
        <li><a href=#configuring-a-form-to-communicate-with-a-server><span class=secno>4.10.1.3 </span>Configuring a form to communicate with a server</a></li>
-       <li><a href=#client-side-form-validation><span class=secno>4.10.1.4 </span>Client-side form validation</a></ol></li>
+       <li><a href=#client-side-form-validation><span class=secno>4.10.1.4 </span>Client-side form validation</a></li>
+       <li><a href=#date-and-time-formats><span class=secno>4.10.1.5 </span>Date and time formats</a></ol></li>
      <li><a href=#categories><span class=secno>4.10.2 </span>Categories</a></li>
      <li><a href=#the-form-element><span class=secno>4.10.3 </span>The <code>form</code> element</a></li>
      <li><a href=#the-fieldset-element><span class=secno>4.10.4 </span>The <code>fieldset</code> element</a></li>
@@ -41551,6 +41552,52 @@ <h5 id=client-side-form-validation><span class=secno>4.10.1.4 </span>Client-side
 &lt;/form&gt;</pre>
 
 
+  <h5 id=date-and-time-formats><span class=secno>4.10.1.5 </span>Date and time formats</h5>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>In this pizze delivery example, the times are specified in the
+  format "HH:MM": two digits for the hour, in 24-hour format, and two
+  digits for the time. (Seconds could also be specified, though they
+  are not necessary in this example.)</p>
+
+  <p>In some locales, however, times are often expressed differently
+  when presented to users. For example, in the United States, it is
+  still common to use the 12-hour clock with an am/pm indicator, as in
+  "2pm". In France, it is common to separate the hours from the
+  minutes using an "h" character, as in "14h00".</p>
+
+  <p>Similar issues exist with dates, with the added complication that
+  even the order of the components is not always consistent; for
+  example, in Cyprus the first of February 2003 would typically be
+  written "1/2/03", while that same date in Japan would typically be
+  written as "2003&#24180;02&#26376;01&#26085;".</p>
+
+  <p>It therefore is important to distinguish the time and date format
+  used in HTML and in form submissions, which are always the formats
+  defined in this specification (and based on the well-established ISO
+  8601 standard for computer-readable date and time formats), from the
+  time and date formats presented to the user by the browser and
+  accepted as input from the user by the browser.</p>
+
+  <p>The format used "on the wire", i.e. in HTML markup and in form
+  submissions, is intended to be computer-readable and consistent
+  irrespective of the user's locale. Dates, for instance, are always
+  written in the format "YYYY-MM-DD", as in "2003-02-01". Users are
+  not expected to ever see this format.</p>
+
+  <p>The date or time given by the page in the wire format is then
+  translated to the user's preferred presentation (based on user
+  preferences or on the locale of the page itself), before being
+  displayed to the user. Similarly, after the user inputs a date or
+  time using their preferred format, the user agent converts it back
+  to the wire format before putting it in the DOM or submitting it.</p>
+
+  <p>This allows scripts in pages and on servers to process dates and
+  times in a consistent manner without needing to support dozens of
+  different formats, while still supporting the users' needs.</p>
+
+
 
 
   <h4 id=categories><span class=secno>4.10.2 </span>Categories</h4>

index

@@ -240,7 +240,7 @@
 
   <header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
    <hgroup><h1 class=allcaps>HTML</h1>
-    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 18 January 2012</h2>
+    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 19 January 2012</h2>
    </hgroup><dl><dt><strong>Web developer edition:</strong></dt>
     <dd><strong><a href=http://developers.whatwg.org/>http://developers.whatwg.org/</a></strong></dd>
     <dt>Multiple-page version:</dt>
@@ -650,7 +650,8 @@
        <li><a href="#writing-a-form's-user-interface"><span class=secno>4.10.1.1 </span>Writing a form's user interface</a></li>
        <li><a href=#implementing-the-server-side-processing-for-a-form><span class=secno>4.10.1.2 </span>Implementing the server-side processing for a form</a></li>
        <li><a href=#configuring-a-form-to-communicate-with-a-server><span class=secno>4.10.1.3 </span>Configuring a form to communicate with a server</a></li>
-       <li><a href=#client-side-form-validation><span class=secno>4.10.1.4 </span>Client-side form validation</a></ol></li>
+       <li><a href=#client-side-form-validation><span class=secno>4.10.1.4 </span>Client-side form validation</a></li>
+       <li><a href=#date-and-time-formats><span class=secno>4.10.1.5 </span>Date and time formats</a></ol></li>
      <li><a href=#categories><span class=secno>4.10.2 </span>Categories</a></li>
      <li><a href=#the-form-element><span class=secno>4.10.3 </span>The <code>form</code> element</a></li>
      <li><a href=#the-fieldset-element><span class=secno>4.10.4 </span>The <code>fieldset</code> element</a></li>
@@ -41551,6 +41552,52 @@ the cell that corresponds to the values of the two dice.
 &lt;/form&gt;</pre>
 
 
+  <h5 id=date-and-time-formats><span class=secno>4.10.1.5 </span>Date and time formats</h5>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>In this pizze delivery example, the times are specified in the
+  format "HH:MM": two digits for the hour, in 24-hour format, and two
+  digits for the time. (Seconds could also be specified, though they
+  are not necessary in this example.)</p>
+
+  <p>In some locales, however, times are often expressed differently
+  when presented to users. For example, in the United States, it is
+  still common to use the 12-hour clock with an am/pm indicator, as in
+  "2pm". In France, it is common to separate the hours from the
+  minutes using an "h" character, as in "14h00".</p>
+
+  <p>Similar issues exist with dates, with the added complication that
+  even the order of the components is not always consistent; for
+  example, in Cyprus the first of February 2003 would typically be
+  written "1/2/03", while that same date in Japan would typically be
+  written as "2003&#24180;02&#26376;01&#26085;".</p>
+
+  <p>It therefore is important to distinguish the time and date format
+  used in HTML and in form submissions, which are always the formats
+  defined in this specification (and based on the well-established ISO
+  8601 standard for computer-readable date and time formats), from the
+  time and date formats presented to the user by the browser and
+  accepted as input from the user by the browser.</p>
+
+  <p>The format used "on the wire", i.e. in HTML markup and in form
+  submissions, is intended to be computer-readable and consistent
+  irrespective of the user's locale. Dates, for instance, are always
+  written in the format "YYYY-MM-DD", as in "2003-02-01". Users are
+  not expected to ever see this format.</p>
+
+  <p>The date or time given by the page in the wire format is then
+  translated to the user's preferred presentation (based on user
+  preferences or on the locale of the page itself), before being
+  displayed to the user. Similarly, after the user inputs a date or
+  time using their preferred format, the user agent converts it back
+  to the wire format before putting it in the DOM or submitting it.</p>
+
+  <p>This allows scripts in pages and on servers to process dates and
+  times in a consistent manner without needing to support dozens of
+  different formats, while still supporting the users' needs.</p>
+
+
 
 
   <h4 id=categories><span class=secno>4.10.2 </span>Categories</h4>

source

@@ -48506,6 +48506,52 @@ the cell that corresponds to the values of the two dice.
 &lt;/form></pre>
 
 
+  <h5>Date and time formats</h5>
+
+  <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+  <p>In this pizze delivery example, the times are specified in the
+  format "HH:MM": two digits for the hour, in 24-hour format, and two
+  digits for the time. (Seconds could also be specified, though they
+  are not necessary in this example.)</p>
+
+  <p>In some locales, however, times are often expressed differently
+  when presented to users. For example, in the United States, it is
+  still common to use the 12-hour clock with an am/pm indicator, as in
+  "2pm". In France, it is common to separate the hours from the
+  minutes using an "h" character, as in "14h00".</p>
+
+  <p>Similar issues exist with dates, with the added complication that
+  even the order of the components is not always consistent; for
+  example, in Cyprus the first of February 2003 would typically be
+  written "1/2/03", while that same date in Japan would typically be
+  written as "2003&#x5E74;02&#x6708;01&#x65E5;".</p>
+
+  <p>It therefore is important to distinguish the time and date format
+  used in HTML and in form submissions, which are always the formats
+  defined in this specification (and based on the well-established ISO
+  8601 standard for computer-readable date and time formats), from the
+  time and date formats presented to the user by the browser and
+  accepted as input from the user by the browser.</p>
+
+  <p>The format used "on the wire", i.e. in HTML markup and in form
+  submissions, is intended to be computer-readable and consistent
+  irrespective of the user's locale. Dates, for instance, are always
+  written in the format "YYYY-MM-DD", as in "2003-02-01". Users are
+  not expected to ever see this format.</p>
+
+  <p>The date or time given by the page in the wire format is then
+  translated to the user's preferred presentation (based on user
+  preferences or on the locale of the page itself), before being
+  displayed to the user. Similarly, after the user inputs a date or
+  time using their preferred format, the user agent converts it back
+  to the wire format before putting it in the DOM or submitting it.</p>
+
+  <p>This allows scripts in pages and on servers to process dates and
+  times in a consistent manner without needing to support dozens of
+  different formats, while still supporting the users' needs.</p>
+
+
 
 
   <h4>Categories</h4>