Changeset 2387

Timestamp:

13/09/13 13:09:58 (9 years ago)

Author:

julian.reschke@…

Message:

enhance consistency in header field descriptions (see #495)

Location:

draft-ietf-httpbis/latest

Files:

• p4-conditional.html (modified) (5 diffs)
• p4-conditional.xml (modified) (5 diffs)

draft-ietf-httpbis/latest/p4-conditional.html

@@ -939 +939 @@
       <p id="rfc.section.3.1.p.1">The "If-Match" header field makes the request method conditional on the recipient cache or origin server either having at
          least one current representation of the target resource, when the field-value is "*", or having a current representation of
-         the target resource that has an entity-tag matching a member of the list of entity-tags provided in the field-value. A recipient <em class="bcp14">MUST</em> use the strong comparison function when comparing entity-tags for If-Match (<a href="#entity.tag.comparison" title="Comparison">Section&nbsp;2.3.2</a>).
+         the target resource that has an entity-tag matching a member of the list of entity-tags provided in the field-value.
+      </p>
+      <p id="rfc.section.3.1.p.2">A recipient <em class="bcp14">MUST</em> use the strong comparison function when comparing entity-tags for If-Match (<a href="#entity.tag.comparison" title="Comparison">Section&nbsp;2.3.2</a>).
       </p>
       <div id="rfc.figure.u.8"></div><pre class="inline"><span id="rfc.iref.g.7"></span>  <a href="#header.if-match" class="smpl">If-Match</a> = "*" / 1#<a href="#header.etag" class="smpl">entity-tag</a>
-</pre><p id="rfc.section.3.1.p.3">Examples:</p>
+</pre><p id="rfc.section.3.1.p.4">Examples:</p>
       <div id="rfc.figure.u.9"></div><pre class="text">  If-Match: "xyzzy"
   If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
   If-Match: *
-</pre><p id="rfc.section.3.1.p.5">If-Match is most often used with state-changing methods (e.g., POST, PUT, DELETE) to prevent accidental overwrites when multiple
+</pre><p id="rfc.section.3.1.p.6">If-Match is most often used with state-changing methods (e.g., POST, PUT, DELETE) to prevent accidental overwrites when multiple
          user agents might be acting in parallel on the same resource (i.e., to prevent the "lost update" problem). It can also be
          used with safe methods to abort a request if the <a href="p2-semantics.html#representations" class="smpl">selected representation</a> does not match one already stored (or partially stored) from a prior request.
       </p>
-      <p id="rfc.section.3.1.p.6">An origin server that receives an If-Match header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). If the field-value is "*", the condition is false if the origin server does not have a current representation for the target
+      <p id="rfc.section.3.1.p.7">An origin server that receives an If-Match header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). If the field-value is "*", the condition is false if the origin server does not have a current representation for the target
          resource. If the field-value is a list of entity-tags, the condition is false if none of the listed tags match the entity-tag
          of the selected representation.
       </p>
-      <p id="rfc.section.3.1.p.7">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if a received If-Match condition evaluates to false; instead the origin server <em class="bcp14">MUST</em> respond with either: a) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code; or, b) one of the <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> status codes if the origin server has verified that a state change is being requested and the final state is already reflected
+      <p id="rfc.section.3.1.p.8">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if a received If-Match condition evaluates to false; instead the origin server <em class="bcp14">MUST</em> respond with either: a) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code; or, b) one of the <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> status codes if the origin server has verified that a state change is being requested and the final state is already reflected
          in the current state of the target resource (i.e., the change requested by the user agent has already succeeded, but the user
          agent might not be aware of it, perhaps because the prior response was lost or a compatible change was made by some other
@@ -963 +965 @@
       <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a>&nbsp;<a id="header.if-none-match" href="#header.if-none-match">If-None-Match</a></h2>
       <p id="rfc.section.3.2.p.1">The "If-None-Match" header field makes the request method conditional on the recipient cache or origin server either not having
-         a current representation for the target resource, when the field-value is "*", or not having a current representation that
-         has an entity-tag matching a member of the list of entity-tags provided in the field-value. A recipient <em class="bcp14">MUST</em> use the weak comparison function when comparing entity-tags for If-None-Match (<a href="#entity.tag.comparison" title="Comparison">Section&nbsp;2.3.2</a>).
+         a current representation of the target resource, when the field-value is "*", or not having a current representation of the
+         target resource that has an entity-tag matching a member of the list of entity-tags provided in the field-value.
+      </p>
+      <p id="rfc.section.3.2.p.2">A recipient <em class="bcp14">MUST</em> use the weak comparison function when comparing entity-tags for If-None-Match (<a href="#entity.tag.comparison" title="Comparison">Section&nbsp;2.3.2</a>).
       </p>
       <div id="rfc.figure.u.10"></div><pre class="inline"><span id="rfc.iref.g.8"></span>  <a href="#header.if-none-match" class="smpl">If-None-Match</a> = "*" / 1#<a href="#header.etag" class="smpl">entity-tag</a>
-</pre><p id="rfc.section.3.2.p.3">Examples:</p>
+</pre><p id="rfc.section.3.2.p.4">Examples:</p>
       <div id="rfc.figure.u.11"></div><pre class="text">  If-None-Match: "xyzzy"
   If-None-Match: W/"xyzzy"
@@ -973 +977 @@
   If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
   If-None-Match: *
-</pre><p id="rfc.section.3.2.p.5">If-None-Match is primarily used in conditional GET requests to enable efficient updates of cached information with a minimum
+</pre><p id="rfc.section.3.2.p.6">If-None-Match is primarily used in conditional GET requests to enable efficient updates of cached information with a minimum
          amount of transaction overhead. When a client desires to update one or more stored responses that have entity-tags, the client <em class="bcp14">SHOULD</em> generate an If-None-Match header field containing a list of those entity-tags when making a GET request; this allows recipient
          servers to send a <a href="#status.304" class="smpl">304 (Not Modified)</a> response to indicate when one of those stored responses matches the selected representation.
       </p>
-      <p id="rfc.section.3.2.p.6">If-None-Match can also be used with a value of "*" to prevent an unsafe request method (e.g., PUT) from inadvertently modifying
+      <p id="rfc.section.3.2.p.7">If-None-Match can also be used with a value of "*" to prevent an unsafe request method (e.g., PUT) from inadvertently modifying
          an existing representation of the target resource when the client believes that the resource does not have a current representation
          (<a href="p2-semantics.html#safe.methods" title="Safe Methods">Section 4.2.1</a> of <a href="#Part2" id="rfc.xref.Part2.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). This is a variation on the "lost update" problem that might arise if more than one client attempts to create an initial
          representation for the target resource.
       </p>
-      <p id="rfc.section.3.2.p.7">An origin server that receives an If-None-Match header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). If the field-value is "*", the condition is false if the origin server has a current representation for the target resource.
+      <p id="rfc.section.3.2.p.8">An origin server that receives an If-None-Match header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). If the field-value is "*", the condition is false if the origin server has a current representation for the target resource.
          If the field-value is a list of entity-tags, the condition is false if one of the listed tags match the entity-tag of the
          selected representation.
       </p>
-      <p id="rfc.section.3.2.p.8">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if the condition evaluates to false; instead, the origin server <em class="bcp14">MUST</em> respond with either a) the <a href="#status.304" class="smpl">304 (Not Modified)</a> status code if the request method is GET or HEAD; or, b) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code for all other request methods.
+      <p id="rfc.section.3.2.p.9">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if the condition evaluates to false; instead, the origin server <em class="bcp14">MUST</em> respond with either a) the <a href="#status.304" class="smpl">304 (Not Modified)</a> status code if the request method is GET or HEAD; or, b) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code for all other request methods.
       </p>
       <div id="rfc.iref.i.3"></div>
       <h2 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3</a>&nbsp;<a id="header.if-modified-since" href="#header.if-modified-since">If-Modified-Since</a></h2>
-      <p id="rfc.section.3.3.p.1">The "If-Modified-Since" header field can be used with GET or HEAD to make the method conditional by modification date: if
-         the selected representation has not been modified since the time specified in this field, then respond with a <a href="#status.304" class="smpl">304 (Not Modified)</a> status code and only send metadata that might be useful for identifying or updating a cached representation. Hence, transfer
+      <p id="rfc.section.3.3.p.1">The "If-Modified-Since" header field makes the GET or HEAD request method conditional on the selected representation's modification
+         date being more recent than the date provided in the field-value: if the selected representation has not been modified since
+         the time specified in this field, then respond with a <a href="#status.304" class="smpl">304 (Not Modified)</a> status code and only send metadata that might be useful for identifying or updating a cached representation. Hence, transfer
          of the selected representation's data is avoided if that data has not changed.
       </p>
@@ -1017 +1022 @@
       </p>
       <p id="rfc.section.3.3.p.10">When used for limiting the scope of retrieval to a recent time window, a user agent will generate an If-Modified-Since field
-         value based on either its own local clock or a <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field received from the server during a past run. Origin servers that choose an exact timestamp match based on the
+         value based on either its own local clock or a <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field received from the server in a prior response. Origin servers that choose an exact timestamp match based on the
          selected representation's <a href="#header.last-modified" class="smpl">Last-Modified</a> field will not be able to help the user agent limit its data transfers to only those changed during the specified window.
       </p>
@@ -1039 +1044 @@
          (i.e., to prevent the "lost update" problem). It can also be used with safe methods to abort a request if the <a href="p2-semantics.html#representations" class="smpl">selected representation</a> does not match one already stored (or partially stored) from a prior request.
       </p>
-      <p id="rfc.section.3.4.p.9">An origin server that receives an If-Unmodified-Since header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). The condition is false if the selected representation has been modified since the time specified in this field.
+      <p id="rfc.section.3.4.p.9">An origin server that receives an If-Unmodified-Since header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). The condition is false if the selected representation's last modification date is more recent than the date provided in
+         the field-value.
       </p>
       <p id="rfc.section.3.4.p.10">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if a received If-Unmodified-Since condition evaluates to false; instead the origin server <em class="bcp14">MUST</em> respond with either: a) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code; or, b) one of the <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> status codes if the origin server has verified that a state change is being requested and the final state is already reflected

draft-ietf-httpbis/latest/p4-conditional.xml

@@ -674 +674 @@
    entity-tag matching a member of the list of entity-tags provided in the
    field-value.
+</t>
+<t>
    A recipient &MUST; use the strong comparison function when comparing
    entity-tags for If-Match (<xref target="entity.tag.comparison"/>).
@@ -727 +729 @@
    The "If-None-Match" header field makes the request method conditional on
    the recipient cache or origin server either not having a current
-   representation for the target resource, when the field-value is "*", or
-   not having a current representation that has an entity-tag matching a
-   member of the list of entity-tags provided in the field-value.
+   representation of the target resource, when the field-value is "*", or
+   not having a current representation of the target resource that has an
+   entity-tag matching a member of the list of entity-tags provided in the
+   field-value.
+</t>
+<t>
    A recipient &MUST; use the weak comparison function when comparing
    entity-tags for If-None-Match (<xref target="entity.tag.comparison"/>).
@@ -788 +793 @@
   <x:anchor-alias value="If-Modified-Since"/>
 <t>
-   The "If-Modified-Since" header field can be used with GET or HEAD to make
-   the method conditional by modification date: if the selected representation
+   The "If-Modified-Since" header field makes the GET or HEAD request method
+   conditional on the selected representation's modification date being more
+   recent than the date provided in the field-value: if the selected representation
    has not been modified since the time specified in this field, then respond
    with a <x:ref>304 (Not Modified)</x:ref> status code and only send
@@ -850 +856 @@
    user agent will generate an If-Modified-Since field value based on either
    its own local clock or a <x:ref>Date</x:ref> header field received from the
-   server during a past run. Origin servers that choose an exact timestamp
+   server in a prior response. Origin servers that choose an exact timestamp
    match based on the selected representation's <x:ref>Last-Modified</x:ref>
    field will not be able to help the user agent limit its data transfers to
@@ -905 +911 @@
    evaluate the condition prior to performing the method
    (<xref target="evaluation"/>). The condition is false if the selected
-   representation has been modified since the time specified in this field.
+   representation's last modification date is more recent than the date
+   provided in the field-value.
 </t>
 <t>