Ticket #307: 307.diff

p6-cache.xml

@@ -1184 +1184 @@
       x:for-anchor="" />
    <x:anchor-alias value="Cache-Control"/>
    <x:anchor-alias value="cache-directive"/>
-   <x:anchor-alias value="cache-extension"/>
-   <x:anchor-alias value="cache-request-directive"/>
-   <x:anchor-alias value="cache-response-directive"/>
 <t>
    The "Cache-Control" header field is used to specify directives for
    caches along the request/response chain. Such cache directives are
@@ -1213 +1210 @@
    to all recipients along the request/response chain. It is not possible to 
    target a directive to a specific cache.
 </t>
-<t>Cache directives are identified by a token, to be compared case-insensitively, and have an optional argument.</t>
-<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Cache-Control"/><iref primary="true" item="Grammar" subitem="cache-extension"/>
+<t>
+   Cache directives are identified by a token, to be compared case-insensitively,
+   and have an optional argument, that can use both token and quoted-string
+   syntax. Recipients &MUST; accept both forms. 
+</t>
+<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Cache-Control"/><iref primary="true" item="Grammar" subitem="cache-directive"/>
   <x:ref>Cache-Control</x:ref>   = 1#<x:ref>cache-directive</x:ref>
 
-  <x:ref>cache-directive</x:ref> = <x:ref>cache-request-directive</x:ref>
-     / <x:ref>cache-response-directive</x:ref>
-
-  <x:ref>cache-extension</x:ref> = <x:ref>token</x:ref> [ "=" ( <x:ref>token</x:ref> / <x:ref>quoted-string</x:ref> ) ]
+  <x:ref>cache-directive</x:ref> = <x:ref>token</x:ref> [ "=" ( <x:ref>token</x:ref> / <x:ref>quoted-string</x:ref> ) ]
 </artwork></figure>
+<t>
+   For the cache directives defined below, no argument is defined (nor allowed)
+   otherwise stated otherwise.
+</t>
 
 <section anchor="cache-request-directive" 
    title="Request Cache-Control Directives">
-   <x:anchor-alias value="cache-request-directive" />
 
-<figure><artwork type="abnf2616"><iref item="Grammar" primary="true" 
-   subitem="cache-request-directive" />
-  <x:ref>cache-request-directive</x:ref> =
-       "no-cache"
-     / "no-store"
-     / "max-age" "=" <x:ref>delta-seconds</x:ref>
-     / "max-stale" [ "=" <x:ref>delta-seconds</x:ref> ]
-     / "min-fresh" "=" <x:ref>delta-seconds</x:ref>
-     / "no-transform"
-     / "only-if-cached"
-     / <x:ref>cache-extension</x:ref>
-</artwork></figure>
-
-<t>
-   <x:dfn>no-cache</x:dfn>
+<section title="no-cache" anchor="cache-request-directive.no-cache">
    <iref item="Cache Directives" primary="true" subitem="no-cache" />
    <iref item="no-cache" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The no-cache request directive indicates that a cache &MUST-NOT; 
-      use a stored response to satisfy the request without successful 
-      validation on the origin server.</t> 
-   </list>
+<t>
+   The no-cache request directive indicates that a cache &MUST-NOT; 
+   use a stored response to satisfy the request without successful 
+   validation on the origin server.
 </t>
-<t>
-   <x:dfn>no-store</x:dfn>
+</section>
+ 
+<section title="no-store" anchor="cache-request-directive.no-store">
    <iref item="Cache Directives" primary="true" subitem="no-store" />
    <iref item="no-store" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The no-store request directive indicates that a cache &MUST-NOT;
-      store any part of either this request or any response to it. This
-      directive applies to both private and shared caches. "&MUST-NOT;
-      store" in this context means that the cache &MUST-NOT; intentionally
-      store the information in non-volatile storage, and &MUST; make a
-      best-effort attempt to remove the information from volatile storage as
-      promptly as possible after forwarding it.</t>
-      <t>This directive is NOT a reliable or sufficient mechanism for ensuring
-      privacy. In particular, malicious or compromised caches might not
-      recognize or obey this directive, and communications networks might be
-      vulnerable to eavesdropping.</t>
-      <t>Note that if a request containing this directive is satisfied from a
-      cache, the no-store request directive does not apply to the already
-      stored response.</t>
-   </list>
+<t>
+   The no-store request directive indicates that a cache &MUST-NOT;
+   store any part of either this request or any response to it. This
+   directive applies to both private and shared caches. "&MUST-NOT;
+   store" in this context means that the cache &MUST-NOT; intentionally
+   store the information in non-volatile storage, and &MUST; make a
+   best-effort attempt to remove the information from volatile storage as
+   promptly as possible after forwarding it.
 </t>
 <t>
-   <x:dfn>max-age</x:dfn>
+   This directive is NOT a reliable or sufficient mechanism for ensuring
+   privacy. In particular, malicious or compromised caches might not
+   recognize or obey this directive, and communications networks might be
+   vulnerable to eavesdropping.
+</t>
+<t>
+   Note that if a request containing this directive is satisfied from a
+   cache, the no-store request directive does not apply to the already
+   stored response.
+</t>
+</section>
+
+<section title="max-age" anchor="cache-request-directive.max-age">
    <iref item="Cache Directives" primary="true" subitem="max-age" />
    <iref item="max-age" primary="true" subitem="Cache Directive" />
+<t>
+   Argument syntax:
    <list>
-      <t>The max-age request directive indicates that the client is unwilling to
-      accept a response whose age is greater than the specified number of
-      seconds. Unless the max-stale request directive is also present, the
-      client is not willing to accept a stale response.</t>
+      <t>
+        <x:ref>delta-seconds</x:ref> (see <xref target="delta-seconds"/>)
+      </t>
    </list>
 </t>
 <t>
-   <x:dfn>max-stale</x:dfn>
+   The max-age request directive indicates that the client is unwilling to
+   accept a response whose age is greater than the specified number of
+   seconds. Unless the max-stale request directive is also present, the
+   client is not willing to accept a stale response.
+</t>
+</section>
+
+<section title="max-stale" anchor="cache-request-directive.max-stale">
    <iref item="Cache Directives" primary="true" subitem="max-stale" />
    <iref item="max-stale" primary="true" subitem="Cache Directive" />
+<t>
+   Argument syntax:
    <list>
-      <t>The max-stale request directive indicates that the client is willing
-      to accept a response that has exceeded its expiration time. If max-stale
-      is assigned a value, then the client is willing to accept a response
-      that has exceeded its expiration time by no more than the specified
-      number of seconds. If no value is assigned to max-stale, then the client
-      is willing to accept a stale response of any age.</t>
+      <t>
+        <x:ref>delta-seconds</x:ref> (see <xref target="delta-seconds"/>)
+      </t>
    </list>
 </t>
 <t>
-   <x:dfn>min-fresh</x:dfn>
+   The max-stale request directive indicates that the client is willing
+   to accept a response that has exceeded its expiration time. If max-stale
+   is assigned a value, then the client is willing to accept a response
+   that has exceeded its expiration time by no more than the specified
+   number of seconds. If no value is assigned to max-stale, then the client
+   is willing to accept a stale response of any age.
+</t>
+</section>
+
+<section title="min-fresh" anchor="cache-request-directive.min-fresh">
    <iref item="Cache Directives" primary="true" subitem="min-fresh" />
    <iref item="min-fresh" primary="true" subitem="Cache Directive" />
+<t>
+   Argument syntax:
    <list>
-      <t>The min-fresh request directive indicates that the client is willing
-      to accept a response whose freshness lifetime is no less than its
-      current age plus the specified time in seconds. That is, the client
-      wants a response that will still be fresh for at least the specified
-      number of seconds.</t>
+      <t>
+        <x:ref>delta-seconds</x:ref> (see <xref target="delta-seconds"/>)
+      </t>
    </list>
 </t>
 <t>
-   <x:dfn>no-transform</x:dfn>
+   The min-fresh request directive indicates that the client is willing
+   to accept a response whose freshness lifetime is no less than its
+   current age plus the specified time in seconds. That is, the client
+   wants a response that will still be fresh for at least the specified
+   number of seconds.
+</t>
+</section>
+
+<section title="no-transform" anchor="cache-request-directive.no-transform">
    <iref item="Cache Directives" primary="true" subitem="no-transform" />
    <iref item="no-transform" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The no-transform request directive indicates that an intermediary
-        (whether or not it implements a cache) &MUST-NOT; change the 
-        Content-Encoding, Content-Range or Content-Type request header fields, 
-        nor the request representation.</t>
-   </list>
+<t>
+   The no-transform request directive indicates that an intermediary
+   (whether or not it implements a cache) &MUST-NOT; change the 
+   Content-Encoding, Content-Range or Content-Type request header fields, 
+   nor the request representation.
 </t>
-<t>
-   <x:dfn>only-if-cached</x:dfn>
+</section>
+
+<section title="only-if-cached" anchor="cache-request-directive.only-if-cached">
    <iref item="Cache Directives" primary="true" subitem="only-if-cached" />
    <iref item="only-if-cached" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The only-if-cached request directive indicates that the client only
-      wishes to obtain a stored response. If it receives this directive, a
-      cache &SHOULD; either respond using a stored response that is consistent
-      with the other constraints of the request, or respond with a 504
-      (Gateway Timeout) status code. If a group of caches is being operated as
-      a unified system with good internal connectivity, a member cache &MAY;
-      forward such a request within that group of caches.</t>
-   </list>
+<t>
+   The only-if-cached request directive indicates that the client only
+   wishes to obtain a stored response. If it receives this directive, a
+   cache &SHOULD; either respond using a stored response that is consistent
+   with the other constraints of the request, or respond with a 504
+   (Gateway Timeout) status code. If a group of caches is being operated as
+   a unified system with good internal connectivity, a member cache &MAY;
+   forward such a request within that group of caches.
 </t>
 </section>
+</section>
 
 <section anchor="cache-response-directive" 
    title="Response Cache-Control Directives">
    <x:anchor-alias value="cache-response-directive" />
 
-<figure><artwork type="abnf2616"><iref item="Grammar" primary="true" 
+<!--<figure><artwork type="abnf2616"><iref item="Grammar" primary="true" 
    subitem="cache-response-directive" />
   <x:ref>cache-response-directive</x:ref> =
        "public"
@@ -1351 +1366 @@
      / "max-age" "=" <x:ref>delta-seconds</x:ref>
      / "s-maxage" "=" <x:ref>delta-seconds</x:ref>
      / <x:ref>cache-extension</x:ref>
-</artwork></figure>
+</artwork></figure>-->
 
-<t>
-   <x:dfn>public</x:dfn>
+<section title="public" anchor="cache-response-directive.only-if-cached">
    <iref item="Cache Directives" primary="true" subitem="public" />
    <iref item="public" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The public response directive indicates that a response whose 
-        associated request contains an 'Authentication' header &MAY; be 
-        stored (see <xref target="caching.authenticated.responses" />).</t>
-  </list>
+<t>
+   The public response directive indicates that a response whose 
+   associated request contains an 'Authentication' header &MAY; be 
+   stored (see <xref target="caching.authenticated.responses" />).
 </t>
-<t>
-   <x:dfn>private</x:dfn>
+</section>
+
+<section title="private" anchor="cache-response-directive.private">
    <iref item="Cache Directives" primary="true" subitem="private" />
    <iref item="private" primary="true" subitem="Cache Directive" />
+<t>
+   Argument syntax:
    <list>
-      <t>The private response directive indicates that the response message is
-      intended for a single user and &MUST-NOT; be stored by a shared cache. A
-      private cache &MAY; store the response.</t>
-      <t>If the private response directive specifies one or more field-names,
-      this requirement is limited to the field-values associated with the
-      listed response header fields. That is, a shared cache &MUST-NOT; store
-      the specified field-names(s), whereas it &MAY; store the remainder of the
-      response message.</t>
-      <t>The field-names given are not limited to the set of standard header
-      fields defined by this specification. Field names are case-insensitive.
+      <t>
+        #<x:ref>field-name</x:ref>
       </t>
-      <t> <x:h>Note:</x:h> This usage of the word "private" only controls
-      where the response can be stored; it cannot ensure the privacy of the
-      message content. Also, private response directives with field-names are
-      often handled by implementations as if an unqualified private directive
-      was received; i.e., the special handling for the qualified form is not
-      widely implemented.</t>
    </list>
 </t>
 <t>
-   <x:dfn>no-cache</x:dfn>
+   The private response directive indicates that the response message is
+   intended for a single user and &MUST-NOT; be stored by a shared cache. A
+   private cache &MAY; store the response.
+</t>
+<t>
+   If the private response directive specifies one or more field-names,
+   this requirement is limited to the field-values associated with the
+   listed response header fields. That is, a shared cache &MUST-NOT; store
+   the specified field-names(s), whereas it &MAY; store the remainder of the
+   response message.
+</t>
+<t>
+   The field-names given are not limited to the set of standard header
+   fields defined by this specification. Field names are case-insensitive.
+</t>
+<t>
+   <x:h>Note:</x:h> This usage of the word "private" only controls
+   where the response can be stored; it cannot ensure the privacy of the
+   message content. Also, private response directives with field-names are
+   often handled by implementations as if an unqualified private directive
+   was received; i.e., the special handling for the qualified form is not
+   widely implemented.
+</t>
+<t>
+   <x:h>Note:</x:h> For compatibility with non-robust recipients, even a
+   single-entry list of field names &SHOULD; be sent using the quoted-string
+   syntax.
+</t>
+</section>
+
+<section title="no-cache" anchor="cache-response-directive.no-cache">
    <iref item="Cache Directives" primary="true" subitem="no-cache" />
    <iref item="no-cache" primary="true" subitem="Cache Directive" />
+<t>
+   Argument syntax:
    <list>
-      <t>The no-cache response directive indicates that the response &MUST-NOT;
-      be used to satisfy a subsequent request without successful validation on
-      the origin server. This allows an origin server to prevent a cache from
-      using it to satisfy a request without contacting it, even by caches that
-      have been configured to return stale responses.</t>
-      <t>If the no-cache response directive specifies one or more field-names,
-      then a cache MAY use the response to satisfy a subsequent request,
-      subject to any other restrictions on caching. However, any header fields
-      in the response that have the field-name(s) listed &MUST-NOT; be sent
-      in the response to a subsequent request without successful revalidation
-      with the origin server. This allows an origin server to prevent the
-      re-use of certain header fields in a response, while still allowing
-      caching of the rest of the response.</t> 
-      <t>The field-names given are not limited to the set of standard header
-      fields defined by this specification. Field names are case-insensitive.
+      <t>
+        #<x:ref>field-name</x:ref>
       </t>
-      <t> <x:h>Note:</x:h> Most HTTP/1.0 caches will not recognize or obey
-      this directive. Also, no-cache response directives with field-names are
-      often handled by implementations as if an unqualified no-cache directive
-      was received; i.e., the special handling for the qualified form is not
-      widely implemented.</t>
    </list>
 </t>
 <t>
-   <x:dfn>no-store</x:dfn>
+   The no-cache response directive indicates that the response &MUST-NOT;
+   be used to satisfy a subsequent request without successful validation on
+   the origin server. This allows an origin server to prevent a cache from
+   using it to satisfy a request without contacting it, even by caches that
+   have been configured to return stale responses.
+</t>
+<t>
+   If the no-cache response directive specifies one or more field-names,
+   then a cache &MAY; use the response to satisfy a subsequent request,
+   subject to any other restrictions on caching. However, any header fields
+   in the response that have the field-name(s) listed &MUST-NOT; be sent
+   in the response to a subsequent request without successful revalidation
+   with the origin server. This allows an origin server to prevent the
+   re-use of certain header fields in a response, while still allowing
+   caching of the rest of the response.
+</t> 
+<t>
+   The field-names given are not limited to the set of standard header
+   fields defined by this specification. Field names are case-insensitive.
+</t>
+<t>
+   <x:h>Note:</x:h> Most HTTP/1.0 caches will not recognize or obey
+   this directive. Also, no-cache response directives with field-names are
+   often handled by implementations as if an unqualified no-cache directive
+   was received; i.e., the special handling for the qualified form is not
+   widely implemented.
+</t>
+<t>
+   <x:h>Note:</x:h> For compatibility with non-robust recipients, even a
+   single-entry list of field names &SHOULD; be sent using the quoted-string
+   syntax.
+</t>
+</section>
+
+<section title="no-store" anchor="cache-response-directive.no-store">
    <iref item="Cache Directives" primary="true" subitem="no-store" />
    <iref item="no-store" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The no-store response directive indicates that a cache &MUST-NOT;
-      store any part of either the immediate request or response. This
-      directive applies to both private and shared caches. "&MUST-NOT;
-      store" in this context means that the cache &MUST-NOT; intentionally
-      store the information in non-volatile storage, and &MUST; make a
-      best-effort attempt to remove the information from volatile storage as
-      promptly as possible after forwarding it.</t>
-      <t>This directive is NOT a reliable or sufficient mechanism for ensuring
-      privacy. In particular, malicious or compromised caches might not
-      recognize or obey this directive, and communications networks might be
-      vulnerable to eavesdropping.</t>
-   </list>
+<t>
+   The no-store response directive indicates that a cache &MUST-NOT;
+   store any part of either the immediate request or response. This
+   directive applies to both private and shared caches. "&MUST-NOT;
+   store" in this context means that the cache &MUST-NOT; intentionally
+   store the information in non-volatile storage, and &MUST; make a
+   best-effort attempt to remove the information from volatile storage as
+   promptly as possible after forwarding it.
 </t>
 <t>
-   <x:dfn>must-revalidate</x:dfn>
+   This directive is NOT a reliable or sufficient mechanism for ensuring
+   privacy. In particular, malicious or compromised caches might not
+   recognize or obey this directive, and communications networks might be
+   vulnerable to eavesdropping.
+</t>
+</section>
+
+<section title="must-revalidate" anchor="cache-response-directive.must-revalidate">
    <iref item="Cache Directives" primary="true" subitem="must-revalidate" />
    <iref item="must-revalidate" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The must-revalidate response directive indicates that once it has
-      become stale, a cache &MUST-NOT; use the response to satisfy subsequent
-      requests without successful validation on the origin server.</t>
-      <t>The must-revalidate directive is necessary to support reliable
-      operation for certain protocol features. In all circumstances a
-      cache &MUST; obey the must-revalidate directive; in particular,
-      if a cache cannot reach the origin server for any reason, it &MUST;
-      generate a 504 (Gateway Timeout) response.</t>
-      <t>The must-revalidate directive ought to be used by servers if and only
-      if failure to validate a request on the representation could result in
-      incorrect operation, such as a silently unexecuted financial
-      transaction.</t>
-   </list>
+<t>
+   The must-revalidate response directive indicates that once it has
+   become stale, a cache &MUST-NOT; use the response to satisfy subsequent
+   requests without successful validation on the origin server.
 </t>
 <t>
-   <x:dfn>proxy-revalidate</x:dfn>
+   The must-revalidate directive is necessary to support reliable
+   operation for certain protocol features. In all circumstances a
+   cache &MUST; obey the must-revalidate directive; in particular,
+   if a cache cannot reach the origin server for any reason, it &MUST;
+   generate a 504 (Gateway Timeout) response.
+</t>
+<t>
+   The must-revalidate directive ought to be used by servers if and only
+   if failure to validate a request on the representation could result in
+   incorrect operation, such as a silently unexecuted financial
+   transaction.
+</t>
+</section>
+
+<section title="proxy-revalidate" anchor="cache-response-directive.proxy-revalidate">
    <iref item="Cache Directives" primary="true" subitem="proxy-revalidate" />
    <iref item="proxy-revalidate" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The proxy-revalidate response directive has the same meaning as the
-      must-revalidate response directive, except that it does not apply to
-      private caches.</t>
-   </list>
+<t>
+   The proxy-revalidate response directive has the same meaning as the
+   must-revalidate response directive, except that it does not apply to
+   private caches.
 </t>
-<t>
-   <x:dfn>max-age</x:dfn>
+</section>
+
+<section title="max-age" anchor="cache-response-directive.max-age">
    <iref item="Cache Directives" primary="true" subitem="max-age" />
    <iref item="max-age" primary="true" subitem="Cache Directive" />
+<t>
+   Argument syntax:
    <list>
-      <t>The max-age response directive indicates that the response is to be
-      considered stale after its age is greater than the specified number of
-      seconds.</t>
+      <t>
+        <x:ref>delta-seconds</x:ref> (see <xref target="delta-seconds"/>)
+      </t>
    </list>
 </t>
 <t>
-   <x:dfn>s-maxage</x:dfn>
+   The max-age response directive indicates that the response is to be
+   considered stale after its age is greater than the specified number of
+   seconds.
+</t>
+</section>      
+
+<section title="s-maxage" anchor="cache-response-directive.s-maxage">
    <iref item="Cache Directives" primary="true" subitem="s-maxage" />
    <iref item="s-maxage" primary="true" subitem="Cache Directive" />
+<t>
+   Argument syntax:
    <list>
-      <t>The s-maxage response directive indicates that, in shared caches, the
-      maximum age specified by this directive overrides the maximum age
-      specified by either the max-age directive or the Expires header field. The
-      s-maxage directive also implies the semantics of the proxy-revalidate
-      response directive.</t>
+      <t>
+        <x:ref>delta-seconds</x:ref> (see <xref target="delta-seconds"/>)
+      </t>
    </list>
 </t>
 <t>
-   <x:dfn>no-transform</x:dfn>
+   The s-maxage response directive indicates that, in shared caches, the
+   maximum age specified by this directive overrides the maximum age
+   specified by either the max-age directive or the Expires header field. The
+   s-maxage directive also implies the semantics of the proxy-revalidate
+   response directive.
+</t>
+</section>
+
+<section title="no-transform" anchor="cache-response-directive.no-transform">
    <iref item="Cache Directives" primary="true" subitem="no-transform" />
    <iref item="no-transform" primary="true" subitem="Cache Directive" />
-   <list>
-      <t>The no-transform response directive indicates that an intermediary
-      (regardless of whether it implements a cache) &MUST-NOT; change the 
-      Content-Encoding, Content-Range or Content-Type response header fields, 
-      nor the response representation.</t>
-   </list>
+<t>
+   The no-transform response directive indicates that an intermediary
+   (regardless of whether it implements a cache) &MUST-NOT; change the 
+   Content-Encoding, Content-Range or Content-Type response header fields, 
+   nor the response representation.
 </t>
+</section>
 
 </section>