hixie: Try to clarify fallback entries. It's not entirely clear that I did an acceptable job here, but it's a start. (whatwg r3952)

hixie: Try to clarify fallback entries. It's not entirely clear that I
did an acceptable job here, but it's a start. (whatwg r3952)

http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.3113&r2=1.3114&f=h
http://html5.org/tools/web-apps-tracker?from=3951&to=3952

===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.3113
retrieving revision 1.3114
diff -u -d -r1.3113 -r1.3114
--- Overview.html 22 Sep 2009 00:32:16 -0000 1.3113
+++ Overview.html 22 Sep 2009 01:08:36 -0000 1.3114
@@ -46719,16 +46719,16 @@
 
      <dt><dfn id="concept-appcache-explicit" title="concept-appcache-explicit">Explicit entries</dfn>
 
-     <dd>Resources that were listed in the cache's <a href="#concept-appcache-manifest" title="concept-appcache-manifest">manifest</a>. Explicit
-     entries can also be marked as <dfn id="concept-appcache-foreign" title="concept-appcache-foreign">foreign</dfn>, which means that they
-     have a <code title="attr-html-manifest"><a href="#attr-html-manifest">manifest</a></code>
+     <dd>Resources that were listed in the cache's <a href="#concept-appcache-manifest" title="concept-appcache-manifest">manifest</a> in an <a href="#concept-appcache-manifest-explicit" title="concept-appcache-manifest-explicit">explicit
+     section</a>. Explicit entries can also be marked as <dfn id="concept-appcache-foreign" title="concept-appcache-foreign">foreign</dfn>, which means that
+     they have a <code title="attr-html-manifest"><a href="#attr-html-manifest">manifest</a></code>
      attribute but that it doesn't point at this cache's <a href="#concept-appcache-manifest" title="concept-appcache-manifest">manifest</a>.
 
 
      <dt><dfn id="concept-appcache-fallback" title="concept-appcache-fallback">Fallback entries</dfn>
 
-     <dd>Resources that were listed in the cache's <a href="#concept-appcache-manifest" title="concept-appcache-manifest">manifest</a> as fallback
-     entries.
+     <dd>Resources that were listed in the cache's <a href="#concept-appcache-manifest" title="concept-appcache-manifest">manifest</a> in a <a href="#concept-appcache-manifest-fallback" title="concept-appcache-manifest-fallback">fallback
+     section</a>.
 
 
     </dl><p class="note">A URL in the list can be flagged with multiple
@@ -46843,7 +46843,29 @@
 
 # here is another set of files to cache, this time just the CSS file.
 CACHE:
-style/default.css</pre><h5 id="writing-cache-manifests"><span class="secno">6.9.3.2 </span>Writing cache manifests</h5><p>Manifests must be served using the
+style/default.css</pre><p>It could equally well be written as follows:<pre>CACHE MANIFEST
+NETWORK:
+comm.cgi
+CACHE:
+style/default.css
+images/sound-icon.png
+images/background.png</pre><hr><p>The following manifest defines a catch-all error page that is
+  displayed for any page on the site while the user is offline. It
+  also specifies that the <a href="#concept-appcache-onlinewhitelist-wildcard" title="concept-appcache-onlinewhitelist-wildcard">online whitelist
+  wildcard flag</a> is <i title="">open</i>, meaning that accesses
+  to resources on other sites will not be blocked. (Resources on the
+  same site are already not blocked because of the catch-all fallback
+  namespace.)<p>So long as all pages on the site reference this manifest, they
+  will get cached locally as they are fetched, so that subsequent hits
+  to the same page will load the page immediately from the
+  cache. Until the manifest is changed, those pages will not be
+  fetched from the server again. When the manifest changes, then all
+  the files will be redownloaded.<p>Subresources, such as style sheets, images, etc, would only be
+  cached using the regular HTTP caching semantics, however.<pre>CACHE MANIFEST
+FALLBACK:
+/ /offline.html
+NETWORK:
+*</pre><h5 id="writing-cache-manifests"><span class="secno">6.9.3.2 </span>Writing cache manifests</h5><p>Manifests must be served using the
   <code><a href="#text-cache-manifest">text/cache-manifest</a></code> <a href="#mime-type">MIME type</a>. All
   resources served using the <code><a href="#text-cache-manifest">text/cache-manifest</a></code>
   <a href="#mime-type">MIME type</a> must follow the syntax of application cache
@@ -46887,13 +46909,13 @@
     possible section headers:
 
     <dl><dt><code>CACHE:</code>
-     <dd>Switches to the explicit section.
+     <dd>Switches to the <dfn id="concept-appcache-manifest-explicit" title="concept-appcache-manifest-explicit">explicit section</dfn>.
 
      <dt><code>FALLBACK:</code>
-     <dd>Switches to the fallback section.
+     <dd>Switches to the <dfn id="concept-appcache-manifest-fallback" title="concept-appcache-manifest-fallback">fallback section</dfn>.
 
      <dt><code>NETWORK:</code>
-     <dd>Switches to the online whitelist section.
+     <dd>Switches to the <dfn id="concept-appcache-manifest-network" title="concept-appcache-manifest-network">online whitelist section</dfn>.
 
     </dl><p>Section header lines must consist of zero or more U+0020 SPACE
     and U+0009 CHARACTER TABULATION (tab) characters, followed by one
@@ -46901,37 +46923,39 @@
     followed by zero or more U+0020 SPACE and U+0009 CHARACTER
     TABULATION (tab) characters.</p>
 
-    <p>Ironically, by default, the current section is the explicit
-    section.</p>
+    <p>Ironically, by default, the current section is the
+    <a href="#concept-appcache-manifest-explicit" title="concept-appcache-manifest-explicit">explicit section</a>.</p>
 
    <dt>Data for the current section
    <dd>
     <p>The format that data lines must take depends on the current
     section.</p>
 
-    <p>When the current section is the explicit section, data lines
-    must consist of zero or more U+0020 SPACE and U+0009 CHARACTER
-    TABULATION (tab) characters, a <a href="#valid-url">valid URL</a> identifying
-    a resource other than the manifest itself, and then zero or more
-    U+0020 SPACE and U+0009 CHARACTER TABULATION (tab) characters.</p>
+    <p>When the current section is the <a href="#concept-appcache-manifest-explicit" title="concept-appcache-manifest-explicit">explicit
+    section</a>, data lines must consist of zero or more U+0020
+    SPACE and U+0009 CHARACTER TABULATION (tab) characters, a
+    <a href="#valid-url">valid URL</a> identifying a resource other than the
+    manifest itself, and then zero or more U+0020 SPACE and U+0009
+    CHARACTER TABULATION (tab) characters.</p>
 
-    <p>When the current section is the online whitelist section, data
-    lines must consist of zero or more U+0020 SPACE and U+0009
-    CHARACTER TABULATION (tab) characters, either a single U+002A
-    ASTERISK character (*) <!--
+    <p>When the current section is the <a href="#concept-appcache-manifest-network" title="concept-appcache-manifest-network">online whitelist
+    section</a>, data lines must consist of zero or more U+0020
+    SPACE and U+0009 CHARACTER TABULATION (tab) characters, either a
+    single U+002A ASTERISK character (*) <!--
     concept-appcache-onlinewhitelist-wildcard --> or a <a href="#valid-url">valid
     URL</a> identifying a resource other than the manifest itself,
     and then zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION
     (tab) characters.</p>
 
-    <p>When the current section is the fallback section, data lines
-    must consist of zero or more U+0020 SPACE and U+0009 CHARACTER
-    TABULATION (tab) characters, a <a href="#valid-url">valid URL</a> identifying
-    a resource other than the manifest itself, one or more U+0020
-    SPACE and U+0009 CHARACTER TABULATION (tab) characters, another
+    <p>When the current section is the <a href="#concept-appcache-manifest-fallback" title="concept-appcache-manifest-fallback">fallback
+    section</a>, data lines must consist of zero or more U+0020
+    SPACE and U+0009 CHARACTER TABULATION (tab) characters, a
     <a href="#valid-url">valid URL</a> identifying a resource other than the
-    manifest itself, and then zero or more U+0020 SPACE and U+0009
-    CHARACTER TABULATION (tab) characters.</p>
+    manifest itself, one or more U+0020 SPACE and U+0009 CHARACTER
+    TABULATION (tab) characters, another <a href="#valid-url">valid URL</a>
+    identifying a resource other than the manifest itself, and then
+    zero or more U+0020 SPACE and U+0009 CHARACTER TABULATION (tab)
+    characters.</p>
 
     <p class="note">The URLs in data lines can't be empty strings,
     since those would be relative URLs to the manifest itself. Such
@@ -46939,19 +46963,20 @@
 
   </dl><p>Manifests may contain sections more than once. Sections may be
   empty.<p>URLs that are to be fallback pages associated with <a href="#concept-appcache-fallback-ns" title="concept-appcache-fallback-ns">fallback namespaces</a>, and
-  those namespaces themselves, must be given in fallback sections,
+  those namespaces themselves, must be given in <a href="#concept-appcache-manifest-fallback" title="concept-appcache-manifest-fallback">fallback sections</a>,
   with the namespace being the first URL of the data line, and the
   corresponding fallback page being the second URL. All the other
-  pages to be cached must be listed in explicit sections.<p><a href="#concept-appcache-fallback-ns" title="concept-appcache-fallback-ns">Fallback
+  pages to be cached must be listed in <a href="#concept-appcache-manifest-explicit" title="concept-appcache-manifest-explicit">explicit
+  sections</a>.<p><a href="#concept-appcache-fallback-ns" title="concept-appcache-fallback-ns">Fallback
   namespaces</a> and <a href="#concept-appcache-fallback" title="concept-appcache-fallback">fallback entries</a> must have
   the <a href="#same-origin">same origin</a> as the manifest itself.<p>A <a href="#concept-appcache-fallback-ns" title="concept-appcache-fallback-ns">fallback
   namespace</a> must not be listed more than once.<p>URLs that the user agent is to put into the <a href="#concept-appcache-onlinewhitelist" title="concept-appcache-onlinewhitelist">online whitelist</a>
-  must all be specified in online whitelist sections. (This is needed
-  for any URL that the page is intending to use to communicate back to
-  the server.) To specify that all URLs are automatically whitelisted
-  in this way, a U+002A ASTERISK character (*) character may be
-  specified as one of the URLs. <!--
-  concept-appcache-onlinewhitelist-wildcard --><p>Relative URLs must be given relative to the manifest's own
+  must all be specified in <a href="#concept-appcache-manifest-network" title="concept-appcache-manifest-network">online whitelist
+  sections</a>. (This is needed for any URL that the page is
+  intending to use to communicate back to the server.) To specify that
+  all URLs are automatically whitelisted in this way, a U+002A
+  ASTERISK character (*) character may be specified as one of the
+  URLs. <!-- concept-appcache-onlinewhitelist-wildcard --><p>Relative URLs must be given relative to the manifest's own
   URL. All URLs in the manifest must have the same <a href="#url-scheme" title="url-scheme">&lt;scheme&gt;</a> as the manifest itself
   (either explicitly or implicitly, through the use of relative
   URLs).<p>URLs in manifests must not have fragment identifiers (i.e. the
@@ -47198,11 +47223,13 @@
    whitelist URLs</var>, and the <var title="">online whitelist
    wildcard flag</var>.</li>
 
-  </ol><p class="note">If a resource is listed in the explicit section and
-  matches an entry in the online whitelist, or if a resource matches
-  both an entry in the fallback section and the online whitelist, the
-  resource will taken from the cache, and the online whitelist entry
-  will be ignored.</p>
+  </ol><p class="note">If a resource is listed in the <a href="#concept-appcache-manifest-explicit" title="concept-appcache-manifest-explicit">explicit section</a>
+  and matches an entry in the <a href="#concept-appcache-onlinewhitelist" title="concept-appcache-onlinewhitelist">online whitelist</a>, or
+  if a resource matches both an entry in the <a href="#concept-appcache-manifest-fallback" title="concept-appcache-manifest-fallback">fallback section</a>
+  and the <a href="#concept-appcache-onlinewhitelist" title="concept-appcache-onlinewhitelist">online
+  whitelist</a>, the resource will taken from the cache, and the
+  <a href="#concept-appcache-onlinewhitelist" title="concept-appcache-onlinewhitelist">online
+  whitelist</a> entry will be ignored.</p>
 
 
   <h4 id="updating-an-application-cache"><span class="secno">6.9.4 </span>Updating an application cache</h4>

Received on Tuesday, 22 September 2009 01:09:34 UTC