html5/spec Overview.html,1.3219,1.3220

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

Modified Files:
	Overview.html 
Log Message:
Make the display of the appcache UI more clearly optional, and elaborate a bit on the thinking behind the design. Also, add a note about how ApplicationCache is always present. (whatwg r4058)

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.3219
retrieving revision 1.3220
diff -u -d -r1.3219 -r1.3220
--- Overview.html	29 Sep 2009 11:46:06 -0000	1.3219
+++ Overview.html	30 Sep 2009 07:52:30 -0000	1.3220
@@ -215,7 +215,7 @@
    <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>
    <!--ZZZ:-->
    <!--<h2 class="no-num no-toc">W3C Working Draft 25 August 2009</h2>-->
-   <h2 class="no-num no-toc" id="editor-s-draft-29-september-2009">Editor's Draft 29 September 2009</h2>
+   <h2 class="no-num no-toc" id="editor-s-draft-30-september-2009">Editor's Draft 30 September 2009</h2>
    <!--:ZZZ-->
    <dl><!-- ZZZ: update the month/day (twice), (un)comment out--><!--
     <dt>This Version:</dt>
@@ -317,7 +317,7 @@
   track.
   <!--ZZZ:-->
   <!--This specification is the 25 August 2009 Working Draft.-->
-  This specification is the 29 September 2009 Editor's Draft.
+  This specification is the 30 September 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)
@@ -47529,7 +47529,23 @@
   a <a href="#concept-appcache-manifest" title="concept-appcache-manifest">manifest</a>, or for an
   <a href="#application-cache-group">application cache group</a>, potentially given a particular
   <a href="#cache-host">cache host</a>, and potentially given a new <a href="#concept-appcache-master" title="concept-appcache-master">master</a> resource, the user
-  agent must run the following steps:</p>
+  agent must run the steps below.</p>
+
+  <p>Some of these steps have requirements that only apply if the user
+  agent <dfn id="shows-caching-progress">shows caching progress</dfn>. Support for this is
+  optional. Caching progress UI could consist of a progress bar or
+  message panel in the user agent's interface, or an overlay, or
+  something else. Certain events fired during the <a href="#application-cache-update-process">application
+  cache update process</a> allow the script to override the display
+  of such an interface. The goal of this is to allow Web applications
+  to provide more seamless update mechanisms, hiding from the user the
+  mechanics of the application cache mechanism. User agents may
+  display user interfaces independent of this, but are encouraged to
+  not show prominent update progress notifications for applications
+  that cancel the relevant events.</p>
+
+  <p>The <a href="#application-cache-update-process">application cache update process</a> steps are as
+  follows:
 
   <ol><li><p>Optionally, wait until the permission to start the cache
    update process has been obtained from the user. This could include
@@ -47592,9 +47608,10 @@
      <i>downloading</i>, then <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire
      a simple event</a> called <code title="event-appcache-checking"><a href="#event-appcache-checking">checking</a></code> at the
      <code><a href="#applicationcache">ApplicationCache</a></code> singleton of that <a href="#cache-host">cache
-     host</a>. The default action of this event should be the
-     display of some sort of user interface indicating to the user
-     that the user agent is checking to see if it can download the
+     host</a>. The default action of this event must be, if the
+     user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of
+     some sort of user interface indicating to the user that the user
+     agent is checking to see if it can download the
      application.</li>
 
      <li><p>If these steps were invoked with a <a href="#cache-host">cache
@@ -47602,9 +47619,10 @@
      <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple event</a>
      called <code title="event-appcache-downloading"><a href="#event-appcache-downloading">downloading</a></code> that is
      cancelable at the <code><a href="#applicationcache">ApplicationCache</a></code> singleton of that
-     <a href="#cache-host">cache host</a>. The default action of this event should
-     be the display of some sort of user interface indicating to the
-     user the application is being downloaded.</li>
+     <a href="#cache-host">cache host</a>. The default action of this event must
+     be, if the user agent <a href="#shows-caching-progress">shows caching progress</a>, the
+     display of some sort of user interface indicating to the user the
+     application is being downloaded.</li>
 
      <li><p>If the <a href="#concept-appcache-status" title="concept-appcache-status">status</a>
      of the <var title="">cache group</var> is either <i>checking</i>
@@ -47618,10 +47636,10 @@
      group</var>, <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple
      event</a> that is cancelable called <code title="event-appcache-checking"><a href="#event-appcache-checking">checking</a></code> at the
      <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
-     host</a>. The default action of these events should be the
-     display of some sort of user interface indicating to the user
-     that the user agent is checking for the availability of
-     updates.</li>
+     host</a>. The default action of these events must be, if the
+     user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of
+     some sort of user interface indicating to the user that the user
+     agent is checking for the availability of updates.</li>
 
     </ol><p>The remainder of the steps run asynchronously.</p>
 
@@ -47635,12 +47653,12 @@
    <li><p>If this is a <a href="#concept-appcache-cache" title="concept-appcache-cache">cache
    attempt</a>, then this algorithm was invoked with a <a href="#cache-host">cache
    host</a>; <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple
-   event</a> called <code title="event-appcache-checking"><a href="#event-appcache-checking">checking</a></code>
-   that is cancelable at the <code><a href="#applicationcache">ApplicationCache</a></code> singleton
-   of that <a href="#cache-host">cache host</a>. The default action of this event
-   should be the display of some sort of user interface indicating to
-   the user that the user agent is checking for the availability of
-   updates.</li>
+   event</a> called <code title="event-appcache-checking"><a href="#event-appcache-checking">checking</a></code> that is cancelable
+   at the <code><a href="#applicationcache">ApplicationCache</a></code> singleton of that <a href="#cache-host">cache
+   host</a>. The default action of this event must be, if the user
+   agent <a href="#shows-caching-progress">shows caching progress</a>, the display of some sort
+   of user interface indicating to the user that the user agent is
+   checking for the availability of updates.</li>
 
    <li>
 
@@ -47674,22 +47692,23 @@
      <li><p>For each <a href="#cache-host">cache host</a> associated with an
      <a href="#application-cache">application cache</a> in <var title="">cache
      group</var>, <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple
-     event</a> called <code title="event-appcache-obsolete"><a href="#event-appcache-obsolete">obsolete</a></code>
-     that is cancelable at the <code><a href="#applicationcache">ApplicationCache</a></code> singleton
-     of the <a href="#cache-host">cache host</a>. The default action of these
-     events should be the display of some sort of user interface
-     indicating to the user that the application is no longer
-     available for offline use.</li>
+     event</a> called <code title="event-appcache-obsolete"><a href="#event-appcache-obsolete">obsolete</a></code> that is
+     cancelable at the <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the
+     <a href="#cache-host">cache host</a>. The default action of these events must
+     be, if the user agent <a href="#shows-caching-progress">shows caching progress</a>, the
+     display of some sort of user interface indicating to the user
+     that the application is no longer available for offline
+     use.</li>
 
      <li><p>For each entry in <var title="">cache group</var>'s <a href="#concept-appcache-pending-masters" title="concept-appcache-pending-masters">list of pending master
      entries</a>, <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple
      event</a> that is cancelable called <code title="event-appcache-error"><a href="#event-appcache-error">error</a></code> (not <code title="event-appcache-obsolete"><a href="#event-appcache-obsolete">obsolete</a></code>!) at the
      <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
      host</a> the <code>Document</code> for this entry, if there
-     still is one. The default action of this event should be the
-     display of some sort of user interface indicating to the user
-     that the user agent failed to save the application for offline
-     use.</li>
+     still is one. The default action of this event must be, if the
+     user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of
+     some sort of user interface indicating to the user that the user
+     agent failed to save the application for offline use.</li>
 
      <li><p>If <var title="">cache group</var> has an
      <a href="#application-cache">application cache</a> whose <a href="#concept-appcache-completeness" title="concept-appcache-completeness">completeness flag</a> is
@@ -47712,9 +47731,9 @@
     there is a DNS error, or the connection times out, or the user
     cancels the download, or the parser for manifests fails when
     checking the magic signature), or if the server returned a
-    redirect, or if the resource is labeled with a <a href="#mime-type">MIME type</a> other
-    than <code><a href="#text-cache-manifest">text/cache-manifest</a></code>, then run the <a href="#cache-failure-steps">cache
-    failure steps</a>.</p>
+    redirect, or if the resource is labeled with a <a href="#mime-type">MIME
+    type</a> other than <code><a href="#text-cache-manifest">text/cache-manifest</a></code>, then run
+    the <a href="#cache-failure-steps">cache failure steps</a>.</p>
 
    </li>
 
@@ -47741,10 +47760,10 @@
       <a href="#fire-a-simple-event">fire a simple event</a> that is cancelable called <code title="event-appcache-error"><a href="#event-appcache-error">error</a></code> at the
       <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
       host</a> the <code>Document</code> for this entry, if there
-      still is one. The default action of this event should be the
-      display of some sort of user interface indicating to the user
-      that the user agent failed to save the application for offline
-      use.</p>
+      still is one. The default action of this event must be, if the
+      user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of
+      some sort of user interface indicating to the user that the user
+      agent failed to save the application for offline use.</p>
 
       <p>Otherwise, associate the <code>Document</code> for this entry
       with <var title="">cache</var>; store the resource for this
@@ -47765,9 +47784,10 @@
      group</var>, <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple
      event</a> that is cancelable called <code title="event-appcache-noupdate"><a href="#event-appcache-noupdate">noupdate</a></code> at the
      <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
-     host</a>. The default action of these events should be the
-     display of some sort of user interface indicating to the user
-     that the application is up to date.</li>
+     host</a>. The default action of these events must be, if the
+     user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of
+     some sort of user interface indicating to the user that the
+     application is up to date.</li>
 
      <li><p>Empty <var title="">cache group</var>'s <a href="#concept-appcache-pending-masters" title="concept-appcache-pending-masters">list of pending master
      entries</a>.</li>
@@ -47798,9 +47818,10 @@
    <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple event</a> that
    is cancelable called <code title="event-appcache-downloading"><a href="#event-appcache-downloading">downloading</a></code> at the
    <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
-   host</a>. The default action of these events should be the
-   display of some sort of user interface indicating to the user that
-   a new version is being downloaded.</li>
+   host</a>. The default action of these events must be, if the
+   user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of some
+   sort of user interface indicating to the user that a new version is
+   being downloaded.</li>
 
    <li><p>Let <var title="">file list</var> be an empty list of
    URLs with flags.</li>
@@ -47854,8 +47875,9 @@
      set to the number of files in <var title="">file list</var>, and
      the <code title="dom-ProgressEvents-loaded">loaded</code>
      attribute must be set to the number of number of files in <var title="">file list</var> that have been downloaded so far. The
-     default action of these events should be the display of some sort
-     of user interface indicating to the user that a file is being
+     default action of these events must be, if the user agent
+     <a href="#shows-caching-progress">shows caching progress</a>, the display of some sort of
+     user interface indicating to the user that a file is being
      downloaded in preparation for updating the application.</li>
 
      <li>
@@ -47994,9 +48016,10 @@
      event</a> that is cancelable called <code title="event-appcache-error"><a href="#event-appcache-error">error</a></code> at the
      <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the
      <code>Document</code> for this entry, if there still is one. The
-     default action of this event should be the display of some sort
-     of user interface indicating to the user that the user agent
-     failed to save the application for offline use.</p>
+     default action of this event must be, if the user agent
+     <a href="#shows-caching-progress">shows caching progress</a>, the display of some sort of
+     user interface indicating to the user that the user agent failed
+     to save the application for offline use.</p>
 
      <li>
 
@@ -48062,21 +48085,23 @@
     group</var>, <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple
     event</a> that is cancelable called <code title="event-appcache-cached"><a href="#event-appcache-cached">cached</a></code> at the
     <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
-    host</a>. The default action of these events should be the
-    display of some sort of user interface indicating to the user that
-    the application has been cached and that they can now use it
+    host</a>. The default action of these events must be, if the
+    user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of
+    some sort of user interface indicating to the user that the
+    application has been cached and that they can now use it
     offline.</p>
 
     <p>Otherwise, it is an <a href="#concept-appcache-upgrade" title="concept-appcache-upgrade">upgrade attempt</a>. For each
     <a href="#cache-host">cache host</a> associated with an <a href="#application-cache">application
     cache</a> in <var title="">cache group</var>, <a href="#queue-a-task">queue a
     task</a> to <a href="#fire-a-simple-event">fire a simple event</a> that is cancelable
-    called <code title="event-appcache-updateready"><a href="#event-appcache-updateready">updateready</a></code> at the
-    <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
-    host</a>. The default action of these events should be the
-    display of some sort of user interface indicating to the user that
-    a new version is available and that they can activate it by
-    reloading the page.</p>
+    called <code title="event-appcache-updateready"><a href="#event-appcache-updateready">updateready</a></code>
+    at the <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
+    host</a>. The default action of these events must be, if the
+    user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of
+    some sort of user interface indicating to the user that a new
+    version is available and that they can activate it by reloading
+    the page.</p>
 
    </li>
 
@@ -48105,9 +48130,10 @@
      event</a> that is cancelable called <code title="event-appcache-error"><a href="#event-appcache-error">error</a></code> at the
      <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the
      <code>Document</code> for this entry, if there still is one. The
-     default action of these events should be the display of some sort
-     of user interface indicating to the user that the user agent
-     failed to save the application for offline use.</p>
+     default action of these events must be, if the user agent
+     <a href="#shows-caching-progress">shows caching progress</a>, the display of some sort of
+     user interface indicating to the user that the user agent failed
+     to save the application for offline use.</p>
 
     </ol></li>
 
@@ -48116,10 +48142,10 @@
    <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple event</a> that
    is cancelable called <code title="event-appcache-error"><a href="#event-appcache-error">error</a></code> at the
    <code><a href="#applicationcache">ApplicationCache</a></code> singleton of the <a href="#cache-host">cache
-   host</a>. The default action of these events should be the
-   display of some sort of user interface indicating to the user that
-   the user agent failed to save the application for offline
-   use.</li>
+   host</a>. The default action of these events must be, if the
+   user agent <a href="#shows-caching-progress">shows caching progress</a>, the display of some
+   sort of user interface indicating to the user that the user agent
+   failed to save the application for offline use.</li>
 
    <li><p>Empty <var title="">cache group</var>'s <a href="#concept-appcache-pending-masters" title="concept-appcache-pending-masters">list of pending master
    entries</a>.</li>
@@ -48417,7 +48443,12 @@
   return the <code><a href="#applicationcache">ApplicationCache</a></code> object associated with the
   worker. <a href="#refsWEBWORKERS">[WEBWORKERS]</a></p>
 
-  <p>The <dfn id="dom-appcache-status" title="dom-appcache-status"><code>status</code></dfn>
+  <p class="note">A <code><a href="#window">Window</a></code> or
+  <code>SharedWorkerGlobalScope</code> object has an associated
+  <code><a href="#applicationcache">ApplicationCache</a></code> object even if that <a href="#cache-host">cache
+  host</a> has no actual <a href="#application-cache">application cache</a>.</p>
+
+  <hr><p>The <dfn id="dom-appcache-status" title="dom-appcache-status"><code>status</code></dfn>
   attribute, on getting, must return the current state of the
   <a href="#application-cache">application cache</a> that the
   <code><a href="#applicationcache">ApplicationCache</a></code> object's <a href="#cache-host">cache host</a> is

Received on Wednesday, 30 September 2009 07:52:38 UTC