Ignore:
Timestamp:
13/09/13 11:47:00 (7 years ago)
Author:
fielding@…
Message:

Reduce the burden of processing warn-date to recipients that do something with Warning fields; use warn-code section titles to demonstrate syntax examples (and differentiate from status codes); clarify tortured wording around Age; demonstrate 4am mastery of xslt; addresses #486

Location:
draft-ietf-httpbis/latest
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/extract-warn-code-defs.xslt

    r1897 r2384  
    1616      <ttcol>Short Description</ttcol>
    1717      <ttcol>Reference</ttcol>
    18       <xsl:apply-templates select="//section[iref[contains(@item,' (warn code)') and @primary='true']]">
    19         <xsl:sort select="iref[contains(@item,' (warn code)') and @primary='true']/@item"/>
     18      <xsl:apply-templates select="//section[iref[contains(@item,' (warn-code)') and @primary='true']]">
     19        <xsl:sort select="iref[contains(@item,' (warn-code)') and @primary='true']/@item"/>
    2020      </xsl:apply-templates>
    2121    </texttable>
     
    7676
    7777<xsl:template match="section">
    78   <xsl:variable name="t" select="iref[contains(@item,'(warn code)')]/@item"/>
    79   <xsl:variable name="text" select="substring-before($t,' (warn code)')"/>
     78  <xsl:variable name="c" select="iref[contains(@item,'(warn-code)')]/@item"/>
     79  <xsl:variable name="code" select="substring-before($c,' (warn-code)')"/>
     80  <xsl:variable name="t" select="iref[contains(@item,'(warn-text)')]/@item"/>
     81  <xsl:variable name="text" select="substring-before($t,' (warn-text)')"/>
    8082  <xsl:variable name="redirects-to-other-part" xmlns:p2="urn:ietf:id:draft-ietf-httpbis-p2-semantics#" select="rdf:Description/p2:redirects-to"/>
    8183
    8284  <xsl:if test="not($redirects-to-other-part)">
    8385    <xsl:text>&#10;</xsl:text>
    84     <c><xsl:value-of select="substring-before($text,' ')"/></c>
    85     <c><xsl:value-of select="substring($text,2+string-length(substring-before($text,' ')))"/></c>
     86    <c><xsl:value-of select="$code"/></c>
     87    <c><xsl:value-of select="$text"/></c>
    8688    <c><xref target="{@anchor}"/></c>
    8789  </xsl:if>
  • draft-ietf-httpbis/latest/p6-cache.html

    r2383 r2384  
    638638               <li><a href="#rfc.section.5.4">5.4</a>&nbsp;&nbsp;&nbsp;<a href="#header.pragma">Pragma</a></li>
    639639               <li><a href="#rfc.section.5.5">5.5</a>&nbsp;&nbsp;&nbsp;<a href="#header.warning">Warning</a><ul>
    640                      <li><a href="#rfc.section.5.5.1">5.5.1</a>&nbsp;&nbsp;&nbsp;<a href="#warn.110">110 Response is Stale</a></li>
    641                      <li><a href="#rfc.section.5.5.2">5.5.2</a>&nbsp;&nbsp;&nbsp;<a href="#warn.111">111 Revalidation Failed</a></li>
    642                      <li><a href="#rfc.section.5.5.3">5.5.3</a>&nbsp;&nbsp;&nbsp;<a href="#warn.112">112 Disconnected Operation</a></li>
    643                      <li><a href="#rfc.section.5.5.4">5.5.4</a>&nbsp;&nbsp;&nbsp;<a href="#warn.113">113 Heuristic Expiration</a></li>
    644                      <li><a href="#rfc.section.5.5.5">5.5.5</a>&nbsp;&nbsp;&nbsp;<a href="#warn.199">199 Miscellaneous Warning</a></li>
    645                      <li><a href="#rfc.section.5.5.6">5.5.6</a>&nbsp;&nbsp;&nbsp;<a href="#warn.214">214 Transformation Applied</a></li>
    646                      <li><a href="#rfc.section.5.5.7">5.5.7</a>&nbsp;&nbsp;&nbsp;<a href="#warn.299">299 Miscellaneous Persistent Warning</a></li>
    647                      <li><a href="#rfc.section.5.5.8">5.5.8</a>&nbsp;&nbsp;&nbsp;<a href="#warn.code.extensions">Warn Code Extensions</a></li>
     640                     <li><a href="#rfc.section.5.5.1">5.5.1</a>&nbsp;&nbsp;&nbsp;<a href="#warn.110">Warning: 110 means "Response is Stale"</a></li>
     641                     <li><a href="#rfc.section.5.5.2">5.5.2</a>&nbsp;&nbsp;&nbsp;<a href="#warn.111">Warning: 111 means "Revalidation Failed"</a></li>
     642                     <li><a href="#rfc.section.5.5.3">5.5.3</a>&nbsp;&nbsp;&nbsp;<a href="#warn.112">Warning: 112 means "Disconnected Operation"</a></li>
     643                     <li><a href="#rfc.section.5.5.4">5.5.4</a>&nbsp;&nbsp;&nbsp;<a href="#warn.113">Warning: 113 means "Heuristic Expiration"</a></li>
     644                     <li><a href="#rfc.section.5.5.5">5.5.5</a>&nbsp;&nbsp;&nbsp;<a href="#warn.199">Warning: 199 means "Miscellaneous Warning"</a></li>
     645                     <li><a href="#rfc.section.5.5.6">5.5.6</a>&nbsp;&nbsp;&nbsp;<a href="#warn.214">Warning: 214 means "Transformation Applied"</a></li>
     646                     <li><a href="#rfc.section.5.5.7">5.5.7</a>&nbsp;&nbsp;&nbsp;<a href="#warn.299">Warning: 299 means "Miscellaneous Persistent Warning"</a></li>
    648647                  </ul>
    649648               </li>
     
    955954         time. A typical setting of this fraction might be 10%.
    956955      </p>
    957       <p id="rfc.section.4.2.2.p.4">When a heuristic is used to calculate freshness lifetime, a cache <em class="bcp14">SHOULD</em> attach a <a href="#header.warning" class="smpl">Warning</a> header field with a 113 warn-code to the response if its current_age is more than 24 hours and such a warning is not already
     956      <p id="rfc.section.4.2.2.p.4">When a heuristic is used to calculate freshness lifetime, a cache <em class="bcp14">SHOULD</em> generate a <a href="#header.warning" class="smpl">Warning</a> header field with a 113 warn-code in the response if its current_age is more than 24 hours and such a warning is not already
    958957         present.
    959958      </p>
     
    10311030         or doing so is explicitly allowed (e.g., by the max-stale request directive; see <a href="#cache-request-directive" title="Request Cache-Control Directives">Section&nbsp;5.2.1</a>).
    10321031      </p>
    1033       <p id="rfc.section.4.2.4.p.4">A cache <em class="bcp14">SHOULD</em> append a <a href="#header.warning" class="smpl">Warning</a> header field with the 110 warn-code (see <a href="#header.warning" id="rfc.xref.header.warning.2" title="Warning">Section&nbsp;5.5</a>) to stale responses. Likewise, a cache <em class="bcp14">SHOULD</em> add the 112 warn-code to stale responses if the cache is disconnected.
    1034       </p>
    1035       <div id="rfc.iref.f.3"></div>
    1036       <p id="rfc.section.4.2.4.p.5">Note that if a cache receives a <dfn>first-hand</dfn> response (one where the freshness model is not in use; i.e., its age is 0, whether it is an entire response, or a <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> response) that it would normally forward to the requesting client, and the received response is no longer fresh, the cache <em class="bcp14">MAY</em> forward it to the requesting client without adding a new <a href="#header.warning" class="smpl">Warning</a> (but without removing any existing Warning header fields). A cache ought not attempt to validate a response simply because
    1037          that response became stale in transit.
     1032      <p id="rfc.section.4.2.4.p.4">A cache <em class="bcp14">SHOULD</em> generate a <a href="#header.warning" class="smpl">Warning</a> header field with the 110 warn-code (see <a href="#header.warning" id="rfc.xref.header.warning.2" title="Warning">Section&nbsp;5.5</a>) in stale responses. Likewise, a cache <em class="bcp14">SHOULD</em> generate a 112 warn-code in stale responses if the cache is disconnected.
     1033      </p>
     1034      <p id="rfc.section.4.2.4.p.5">A cache <em class="bcp14">SHOULD NOT</em> generate a new <a href="#header.warning" class="smpl">Warning</a> header field when forwarding a response that does not have an <a href="#header.age" class="smpl">Age</a> header field, even if the response is already stale. A cache need not validate a response that merely became stale in transit.
    10381035      </p>
    10391036      <h2 id="rfc.section.4.3"><a href="#rfc.section.4.3">4.3</a>&nbsp;<a id="validation.model" href="#validation.model">Validation</a></h2>
     
    11771174      </p>
    11781175      <div id="rfc.figure.u.6"></div><pre class="inline"><span id="rfc.iref.g.2"></span>  <a href="#header.age" class="smpl">Age</a> = <a href="#delta-seconds" class="smpl">delta-seconds</a>
    1179 </pre><p id="rfc.section.5.1.p.3">Age field-values are non-negative integers, representing time in seconds (see <a href="#delta-seconds" title="Delta Seconds">Section&nbsp;1.2.1</a>).
    1180       </p>
    1181       <p id="rfc.section.5.1.p.4">The presence of an Age header field in a response implies that a response is not first-hand. However, the converse is not
    1182          true, since HTTP/1.0 caches might not implement the Age header field.
     1176</pre><p id="rfc.section.5.1.p.3">The Age field-value is a non-negative integer, representing time in seconds (see <a href="#delta-seconds" title="Delta Seconds">Section&nbsp;1.2.1</a>).
     1177      </p>
     1178      <p id="rfc.section.5.1.p.4">The presence of an Age header field implies that the response was not generated or validated by the origin server for this
     1179         request. However, lack of an Age header field does not imply the origin was contacted, since the response might have been
     1180         received from an HTTP/1.0 cache that does not implement Age.
    11831181      </p>
    11841182      <div id="rfc.iref.c.5"></div>
     
    14531451      <h2 id="rfc.section.5.5"><a href="#rfc.section.5.5">5.5</a>&nbsp;<a id="header.warning" href="#header.warning">Warning</a></h2>
    14541452      <p id="rfc.section.5.5.p.1">The "Warning" header field is used to carry additional information about the status or transformation of a message that might
    1455          not be reflected in the message. This information is typically used to warn about possible incorrectness introduced by caching
    1456          operations or transformations applied to the payload of the message.
     1453         not be reflected in the status code. This information is typically used to warn about possible incorrectness introduced by
     1454         caching operations or transformations applied to the payload of the message.
    14571455      </p>
    14581456      <p id="rfc.section.5.5.p.2">Warnings can be used for other purposes, both cache-related and otherwise. The use of a warning, rather than an error status
     
    14731471  <a href="#header.warning" class="smpl">warn-text</a>  = <a href="#imported.abnf" class="smpl">quoted-string</a>
    14741472  <a href="#header.warning" class="smpl">warn-date</a>  = <a href="#imported.abnf" class="smpl">DQUOTE</a> <a href="#imported.abnf" class="smpl">HTTP-date</a> <a href="#imported.abnf" class="smpl">DQUOTE</a>
    1475 </pre><p id="rfc.section.5.5.p.5">Multiple warnings can be attached to a response (either by the origin server or by a cache), including multiple warnings with
    1476          the same code number, only differing in warn-text.
    1477       </p>
    1478       <p id="rfc.section.5.5.p.6">When this occurs, the user agent <em class="bcp14">SHOULD</em> inform the user of as many of them as possible, in the order that they appear in the response.
    1479       </p>
    1480       <p id="rfc.section.5.5.p.7">Systems that generate multiple Warning header fields are encouraged to order them with this user agent behavior in mind. New
    1481          Warning header fields are added after any existing Warning header fields.
    1482       </p>
    1483       <p id="rfc.section.5.5.p.8">Warnings are assigned three digit warn-codes. The first digit indicates whether the Warning is required to be deleted from
     1473</pre><p id="rfc.section.5.5.p.5">Multiple warnings can be generated in a response (either by the origin server or by a cache), including multiple warnings
     1474         with the same warn-code number that only differ in warn-text.
     1475      </p>
     1476      <p id="rfc.section.5.5.p.6">A user agent that receives one or more Warning header fields <em class="bcp14">SHOULD</em> inform the user of as many of them as possible, in the order that they appear in the response. Senders that generate multiple
     1477         Warning header fields are encouraged to order them with this user agent behavior in mind. A sender that generates new Warning
     1478         header fields <em class="bcp14">MUST</em> append them after any existing Warning header fields.
     1479      </p>
     1480      <p id="rfc.section.5.5.p.7">Warnings are assigned three digit warn-codes. The first digit indicates whether the Warning is required to be deleted from
    14841481         a stored response after validation:
    14851482      </p>
    14861483      <ul>
    1487          <li>1xx Warnings describe the freshness or validation status of the response, and so <em class="bcp14">MUST</em> be deleted by a cache after validation. They can only be generated by a cache when validating a cached entry, and <em class="bcp14">MUST NOT</em> be generated in any other situation.
    1488          </li>
    1489          <li>2xx Warnings describe some aspect of the representation that is not rectified by a validation (for example, a lossy compression
     1484         <li>1xx warn-codes describe the freshness or validation status of the response, and so <em class="bcp14">MUST</em> be deleted by a cache after validation. They can only be generated by a cache when validating a cached entry, and <em class="bcp14">MUST NOT</em> be generated in any other situation.
     1485         </li>
     1486         <li>2xx warn-codes describe some aspect of the representation that is not rectified by a validation (for example, a lossy compression
    14901487            of the representation) and <em class="bcp14">MUST NOT</em> be deleted by a cache after validation, unless a full response is sent, in which case they <em class="bcp14">MUST</em> be.
    14911488         </li>
    14921489      </ul>
    1493       <p id="rfc.section.5.5.p.9">If an implementation sends a message with one or more Warning header fields to a receiver whose version is HTTP/1.0 or lower,
    1494          then the sender <em class="bcp14">MUST</em> include in each warning-value a warn-date that matches the <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field in the message.
    1495       </p>
    1496       <p id="rfc.section.5.5.p.10">If a system receives a message with a warning-value that includes a warn-date, and that warn-date is different from the <a href="p2-semantics.html#header.date" class="smpl">Date</a> value in the response, then that warning-value <em class="bcp14">MUST</em> be deleted from the message before storing, forwarding, or using it (preventing the consequences of naive caching of Warning
    1497          header fields). If all of the warning-values are deleted for this reason, the Warning header field <em class="bcp14">MUST</em> be deleted as well.
    1498       </p>
    1499       <p id="rfc.section.5.5.p.11">The following warn-codes are defined by this specification, each with a recommended warn-text in English, and a description
    1500          of its meaning.
     1490      <p id="rfc.section.5.5.p.8">If a sender generates one or more Warning header fields in a message to be sent to a recipient known to implement only HTTP/1.0,
     1491         the sender <em class="bcp14">MUST</em> include in each generated warning-value a warn-date that matches the <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field in the message.
     1492      </p>
     1493      <p id="rfc.section.5.5.p.9">If a recipient that uses, evaluates, or displays Warning header fields receives a warn-date that is different from the <a href="p2-semantics.html#header.date" class="smpl">Date</a> value in the same message, the recipient <em class="bcp14">MUST</em> exclude the warning-value containing that warn-date before storing, forwarding, or using the message. This allows recipients
     1494         to exclude warning-values that were improperly retained after a cache validation. If all of the warning-values are excluded,
     1495         the recipient <em class="bcp14">MUST</em> exclude the Warning header field as well.
     1496      </p>
     1497      <p id="rfc.section.5.5.p.10">The following warn-codes are defined by this specification, each with a recommended warn-text in English, and a description
     1498         of its meaning. The procedure for defining additional warn codes is described in <a href="#warn.code.registry.procedure" title="Procedure">Section&nbsp;7.2.1</a>.
     1499      </p>
     1500      <div id="rfc.iref.49"></div>
     1501      <div id="rfc.iref.r.1"></div>
     1502      <h3 id="rfc.section.5.5.1"><a href="#rfc.section.5.5.1">5.5.1</a>&nbsp;<a id="warn.110" href="#warn.110">Warning: 110 means "Response is Stale"</a></h3>
     1503      <p id="rfc.section.5.5.1.p.1">A cache <em class="bcp14">SHOULD</em> generate this whenever the sent response is stale.
    15011504      </p>
    15021505      <div id="rfc.iref.50"></div>
    1503       <h3 id="rfc.section.5.5.1"><a href="#rfc.section.5.5.1">5.5.1</a>&nbsp;<a id="warn.110" href="#warn.110">110 Response is Stale</a></h3>
    1504       <p id="rfc.section.5.5.1.p.1">A cache <em class="bcp14">SHOULD</em> generate this whenever the sent response is stale.
    1505       </p>
    1506       <div id="rfc.iref.50"></div>
    1507       <h3 id="rfc.section.5.5.2"><a href="#rfc.section.5.5.2">5.5.2</a>&nbsp;<a id="warn.111" href="#warn.111">111 Revalidation Failed</a></h3>
     1506      <div id="rfc.iref.r.2"></div>
     1507      <h3 id="rfc.section.5.5.2"><a href="#rfc.section.5.5.2">5.5.2</a>&nbsp;<a id="warn.111" href="#warn.111">Warning: 111 means "Revalidation Failed"</a></h3>
    15081508      <p id="rfc.section.5.5.2.p.1">A cache <em class="bcp14">SHOULD</em> generate this when sending a stale response because an attempt to validate the response failed, due to an inability to reach
    15091509         the server.
    15101510      </p>
    1511       <div id="rfc.iref.50"></div>
    1512       <h3 id="rfc.section.5.5.3"><a href="#rfc.section.5.5.3">5.5.3</a>&nbsp;<a id="warn.112" href="#warn.112">112 Disconnected Operation</a></h3>
     1511      <div id="rfc.iref.51"></div>
     1512      <div id="rfc.iref.d.1"></div>
     1513      <h3 id="rfc.section.5.5.3"><a href="#rfc.section.5.5.3">5.5.3</a>&nbsp;<a id="warn.112" href="#warn.112">Warning: 112 means "Disconnected Operation"</a></h3>
    15131514      <p id="rfc.section.5.5.3.p.1">A cache <em class="bcp14">SHOULD</em> generate this if it is intentionally disconnected from the rest of the network for a period of time.
    15141515      </p>
    1515       <div id="rfc.iref.50"></div>
    1516       <h3 id="rfc.section.5.5.4"><a href="#rfc.section.5.5.4">5.5.4</a>&nbsp;<a id="warn.113" href="#warn.113">113 Heuristic Expiration</a></h3>
     1516      <div id="rfc.iref.52"></div>
     1517      <div id="rfc.iref.h.2"></div>
     1518      <h3 id="rfc.section.5.5.4"><a href="#rfc.section.5.5.4">5.5.4</a>&nbsp;<a id="warn.113" href="#warn.113">Warning: 113 means "Heuristic Expiration"</a></h3>
    15171519      <p id="rfc.section.5.5.4.p.1">A cache <em class="bcp14">SHOULD</em> generate this if it heuristically chose a freshness lifetime greater than 24 hours and the response's age is greater than
    15181520         24 hours.
    15191521      </p>
    1520       <div id="rfc.iref.50"></div>
    1521       <h3 id="rfc.section.5.5.5"><a href="#rfc.section.5.5.5">5.5.5</a>&nbsp;<a id="warn.199" href="#warn.199">199 Miscellaneous Warning</a></h3>
     1522      <div id="rfc.iref.53"></div>
     1523      <div id="rfc.iref.m.6"></div>
     1524      <h3 id="rfc.section.5.5.5"><a href="#rfc.section.5.5.5">5.5.5</a>&nbsp;<a id="warn.199" href="#warn.199">Warning: 199 means "Miscellaneous Warning"</a></h3>
    15221525      <p id="rfc.section.5.5.5.p.1">The warning text can include arbitrary information to be presented to a human user, or logged. A system receiving this warning <em class="bcp14">MUST NOT</em> take any automated action, besides presenting the warning to the user.
    15231526      </p>
    1524       <div id="rfc.iref.50"></div>
    1525       <h3 id="rfc.section.5.5.6"><a href="#rfc.section.5.5.6">5.5.6</a>&nbsp;<a id="warn.214" href="#warn.214">214 Transformation Applied</a></h3>
     1527      <div id="rfc.iref.54"></div>
     1528      <div id="rfc.iref.t.1"></div>
     1529      <h3 id="rfc.section.5.5.6"><a href="#rfc.section.5.5.6">5.5.6</a>&nbsp;<a id="warn.214" href="#warn.214">Warning: 214 means "Transformation Applied"</a></h3>
    15261530      <p id="rfc.section.5.5.6.p.1"><em class="bcp14">MUST</em> be added by a proxy if it applies any transformation to the representation, such as changing the content-coding, media-type,
    15271531         or modifying the representation data, unless this Warning code already appears in the response.
    15281532      </p>
    1529       <div id="rfc.iref.50"></div>
    1530       <h3 id="rfc.section.5.5.7"><a href="#rfc.section.5.5.7">5.5.7</a>&nbsp;<a id="warn.299" href="#warn.299">299 Miscellaneous Persistent Warning</a></h3>
     1533      <div id="rfc.iref.55"></div>
     1534      <div id="rfc.iref.m.7"></div>
     1535      <h3 id="rfc.section.5.5.7"><a href="#rfc.section.5.5.7">5.5.7</a>&nbsp;<a id="warn.299" href="#warn.299">Warning: 299 means "Miscellaneous Persistent Warning"</a></h3>
    15311536      <p id="rfc.section.5.5.7.p.1">The warning text can include arbitrary information to be presented to a human user, or logged. A system receiving this warning <em class="bcp14">MUST NOT</em> take any automated action.
    1532       </p>
    1533       <h3 id="rfc.section.5.5.8"><a href="#rfc.section.5.5.8">5.5.8</a>&nbsp;<a id="warn.code.extensions" href="#warn.code.extensions">Warn Code Extensions</a></h3>
    1534       <p id="rfc.section.5.5.8.p.1">Extension warn codes can be defined; see <a href="#warn.code.registry.procedure" title="Procedure">Section&nbsp;7.2.1</a> for details.
    15351537      </p>
    15361538      <h1 id="rfc.section.6"><a href="#rfc.section.6">6.</a>&nbsp;<a id="history.lists" href="#history.lists">History Lists</a></h1>
     
    16821684                  <td class="left">110</td>
    16831685                  <td class="left">Response is Stale</td>
    1684                   <td class="left"><a href="#warn.110" id="rfc.xref.warn.110.1" title="110 Response is Stale">Section&nbsp;5.5.1</a>
     1686                  <td class="left"><a href="#warn.110" id="rfc.xref.warn.110.1" title="Warning: 110 means &#34;Response is Stale&#34;">Section&nbsp;5.5.1</a>
    16851687                  </td>
    16861688               </tr>
     
    16881690                  <td class="left">111</td>
    16891691                  <td class="left">Revalidation Failed</td>
    1690                   <td class="left"><a href="#warn.111" id="rfc.xref.warn.111.1" title="111 Revalidation Failed">Section&nbsp;5.5.2</a>
     1692                  <td class="left"><a href="#warn.111" id="rfc.xref.warn.111.1" title="Warning: 111 means &#34;Revalidation Failed&#34;">Section&nbsp;5.5.2</a>
    16911693                  </td>
    16921694               </tr>
     
    16941696                  <td class="left">112</td>
    16951697                  <td class="left">Disconnected Operation</td>
    1696                   <td class="left"><a href="#warn.112" id="rfc.xref.warn.112.1" title="112 Disconnected Operation">Section&nbsp;5.5.3</a>
     1698                  <td class="left"><a href="#warn.112" id="rfc.xref.warn.112.1" title="Warning: 112 means &#34;Disconnected Operation&#34;">Section&nbsp;5.5.3</a>
    16971699                  </td>
    16981700               </tr>
     
    17001702                  <td class="left">113</td>
    17011703                  <td class="left">Heuristic Expiration</td>
    1702                   <td class="left"><a href="#warn.113" id="rfc.xref.warn.113.1" title="113 Heuristic Expiration">Section&nbsp;5.5.4</a>
     1704                  <td class="left"><a href="#warn.113" id="rfc.xref.warn.113.1" title="Warning: 113 means &#34;Heuristic Expiration&#34;">Section&nbsp;5.5.4</a>
    17031705                  </td>
    17041706               </tr>
     
    17061708                  <td class="left">199</td>
    17071709                  <td class="left">Miscellaneous Warning</td>
    1708                   <td class="left"><a href="#warn.199" id="rfc.xref.warn.199.1" title="199 Miscellaneous Warning">Section&nbsp;5.5.5</a>
     1710                  <td class="left"><a href="#warn.199" id="rfc.xref.warn.199.1" title="Warning: 199 means &#34;Miscellaneous Warning&#34;">Section&nbsp;5.5.5</a>
    17091711                  </td>
    17101712               </tr>
     
    17121714                  <td class="left">214</td>
    17131715                  <td class="left">Transformation Applied</td>
    1714                   <td class="left"><a href="#warn.214" id="rfc.xref.warn.214.1" title="214 Transformation Applied">Section&nbsp;5.5.6</a>
     1716                  <td class="left"><a href="#warn.214" id="rfc.xref.warn.214.1" title="Warning: 214 means &#34;Transformation Applied&#34;">Section&nbsp;5.5.6</a>
    17151717                  </td>
    17161718               </tr>
     
    17181720                  <td class="left">299</td>
    17191721                  <td class="left">Miscellaneous Persistent Warning</td>
    1720                   <td class="left"><a href="#warn.299" id="rfc.xref.warn.299.1" title="299 Miscellaneous Persistent Warning">Section&nbsp;5.5.7</a>
     1722                  <td class="left"><a href="#warn.299" id="rfc.xref.warn.299.1" title="Warning: 299 means &#34;Miscellaneous Persistent Warning&#34;">Section&nbsp;5.5.7</a>
    17211723                  </td>
    17221724               </tr>
     
    19931995<a href="#header.warning" class="smpl">warn-date</a> = DQUOTE HTTP-date DQUOTE
    19941996<a href="#header.warning" class="smpl">warn-text</a> = quoted-string
    1995 <a href="#header.warning" class="smpl">warning-value</a> = warn-code SP warn-agent SP warn-text SP warn-date
     1997<a href="#header.warning" class="smpl">warning-value</a> = warn-code SP warn-agent SP warn-text [ SP warn-date ]
    19961998</pre><h1 id="rfc.section.D"><a href="#rfc.section.D">D.</a>&nbsp;<a id="change.log" href="#change.log">Change Log (to be removed by RFC Editor before publication)</a></h1>
    19971999      <p id="rfc.section.D.p.1">Changes up to the first Working Group Last Call draft are summarized in &lt;<a href="http://trac.tools.ietf.org/html/draft-ietf-httpbis-p6-cache-19#appendix-C">http://trac.tools.ietf.org/html/draft-ietf-httpbis-p6-cache-19#appendix-C</a>&gt;.
     
    20582060      <p id="rfc.section.D.5.p.1">None yet.</p>
    20592061      <h1 id="rfc.index"><a href="#rfc.index">Index</a></h1>
    2060       <p class="noprint"><a href="#rfc.index.1">1</a> <a href="#rfc.index.2">2</a> <a href="#rfc.index.A">A</a> <a href="#rfc.index.B">B</a> <a href="#rfc.index.C">C</a> <a href="#rfc.index.E">E</a> <a href="#rfc.index.F">F</a> <a href="#rfc.index.G">G</a> <a href="#rfc.index.H">H</a> <a href="#rfc.index.M">M</a> <a href="#rfc.index.N">N</a> <a href="#rfc.index.O">O</a> <a href="#rfc.index.P">P</a> <a href="#rfc.index.R">R</a> <a href="#rfc.index.S">S</a> <a href="#rfc.index.V">V</a> <a href="#rfc.index.W">W</a>
     2062      <p class="noprint"><a href="#rfc.index.1">1</a> <a href="#rfc.index.2">2</a> <a href="#rfc.index.A">A</a> <a href="#rfc.index.B">B</a> <a href="#rfc.index.C">C</a> <a href="#rfc.index.D">D</a> <a href="#rfc.index.E">E</a> <a href="#rfc.index.F">F</a> <a href="#rfc.index.G">G</a> <a href="#rfc.index.H">H</a> <a href="#rfc.index.M">M</a> <a href="#rfc.index.N">N</a> <a href="#rfc.index.O">O</a> <a href="#rfc.index.P">P</a> <a href="#rfc.index.R">R</a> <a href="#rfc.index.S">S</a> <a href="#rfc.index.T">T</a> <a href="#rfc.index.V">V</a> <a href="#rfc.index.W">W</a>
    20612063      </p>
    20622064      <div class="print2col">
    20632065         <ul class="ind">
    20642066            <li><a id="rfc.index.1" href="#rfc.index.1"><b>1</b></a><ul>
    2065                   <li>110 Response is Stale (warn code)&nbsp;&nbsp;<a href="#rfc.iref.50"><b>5.5.1</b></a>, <a href="#rfc.xref.warn.110.1">7.2.2</a></li>
    2066                   <li>111 Revalidation Failed (warn code)&nbsp;&nbsp;<a href="#rfc.iref.50"><b>5.5.2</b></a>, <a href="#rfc.xref.warn.111.1">7.2.2</a></li>
    2067                   <li>112 Disconnected Operation (warn code)&nbsp;&nbsp;<a href="#rfc.iref.50"><b>5.5.3</b></a>, <a href="#rfc.xref.warn.112.1">7.2.2</a></li>
    2068                   <li>113 Heuristic Expiration (warn code)&nbsp;&nbsp;<a href="#rfc.iref.50"><b>5.5.4</b></a>, <a href="#rfc.xref.warn.113.1">7.2.2</a></li>
    2069                   <li>199 Miscellaneous Warning (warn code)&nbsp;&nbsp;<a href="#rfc.iref.50"><b>5.5.5</b></a>, <a href="#rfc.xref.warn.199.1">7.2.2</a></li>
     2067                  <li>110 (warn-code)&nbsp;&nbsp;<a href="#rfc.iref.49"><b>5.5.1</b></a>, <a href="#rfc.xref.warn.110.1">7.2.2</a></li>
     2068                  <li>111 (warn-code)&nbsp;&nbsp;<a href="#rfc.iref.50"><b>5.5.2</b></a>, <a href="#rfc.xref.warn.111.1">7.2.2</a></li>
     2069                  <li>112 (warn-code)&nbsp;&nbsp;<a href="#rfc.iref.51"><b>5.5.3</b></a>, <a href="#rfc.xref.warn.112.1">7.2.2</a></li>
     2070                  <li>113 (warn-code)&nbsp;&nbsp;<a href="#rfc.iref.52"><b>5.5.4</b></a>, <a href="#rfc.xref.warn.113.1">7.2.2</a></li>
     2071                  <li>199 (warn-code)&nbsp;&nbsp;<a href="#rfc.iref.53"><b>5.5.5</b></a>, <a href="#rfc.xref.warn.199.1">7.2.2</a></li>
    20702072               </ul>
    20712073            </li>
    20722074            <li><a id="rfc.index.2" href="#rfc.index.2"><b>2</b></a><ul>
    2073                   <li>214 Transformation Applied (warn code)&nbsp;&nbsp;<a href="#rfc.iref.50"><b>5.5.6</b></a>, <a href="#rfc.xref.warn.214.1">7.2.2</a></li>
    2074                   <li>299 Miscellaneous Persistent Warning (warn code)&nbsp;&nbsp;<a href="#rfc.iref.50"><b>5.5.7</b></a>, <a href="#rfc.xref.warn.299.1">7.2.2</a></li>
     2075                  <li>214 (warn-code)&nbsp;&nbsp;<a href="#rfc.iref.54"><b>5.5.6</b></a>, <a href="#rfc.xref.warn.214.1">7.2.2</a></li>
     2076                  <li>299 (warn-code)&nbsp;&nbsp;<a href="#rfc.iref.55"><b>5.5.7</b></a>, <a href="#rfc.xref.warn.299.1">7.2.2</a></li>
    20752077               </ul>
    20762078            </li>
     
    20912093               </ul>
    20922094            </li>
     2095            <li><a id="rfc.index.D" href="#rfc.index.D"><b>D</b></a><ul>
     2096                  <li>Disconnected Operation (warn-text)&nbsp;&nbsp;<a href="#rfc.iref.d.1"><b>5.5.3</b></a>, <a href="#rfc.xref.warn.112.1">7.2.2</a></li>
     2097               </ul>
     2098            </li>
    20932099            <li><a id="rfc.index.E" href="#rfc.index.E"><b>E</b></a><ul>
    20942100                  <li>Expires header field&nbsp;&nbsp;<a href="#rfc.xref.header.expires.1">3</a>, <a href="#rfc.xref.header.expires.2">4.2</a>, <a href="#rfc.xref.header.expires.3">4.2.1</a>, <a href="#rfc.iref.e.2"><b>5.3</b></a>, <a href="#rfc.xref.header.expires.4">7.3</a>, <a href="#rfc.xref.header.expires.5">A</a></li>
     
    20972103            </li>
    20982104            <li><a id="rfc.index.F" href="#rfc.index.F"><b>F</b></a><ul>
    2099                   <li>first-hand&nbsp;&nbsp;<a href="#rfc.iref.f.3">4.2.4</a></li>
    21002105                  <li>fresh&nbsp;&nbsp;<a href="#rfc.iref.f.1">4.2</a></li>
    21012106                  <li>freshness lifetime&nbsp;&nbsp;<a href="#rfc.iref.f.2">4.2</a></li>
     
    21242129            </li>
    21252130            <li><a id="rfc.index.H" href="#rfc.index.H"><b>H</b></a><ul>
     2131                  <li>Heuristic Expiration (warn-text)&nbsp;&nbsp;<a href="#rfc.iref.h.2"><b>5.5.4</b></a>, <a href="#rfc.xref.warn.113.1">7.2.2</a></li>
    21262132                  <li>heuristic expiration time&nbsp;&nbsp;<a href="#rfc.iref.h.1">4.2</a></li>
    21272133               </ul>
     
    21312137                  <li>max-stale (cache directive)&nbsp;&nbsp;<a href="#rfc.iref.m.2"><b>5.2.1.2</b></a></li>
    21322138                  <li>min-fresh (cache directive)&nbsp;&nbsp;<a href="#rfc.iref.m.3"><b>5.2.1.3</b></a></li>
     2139                  <li>Miscellaneous Persistent Warning (warn-text)&nbsp;&nbsp;<a href="#rfc.iref.m.7"><b>5.5.7</b></a>, <a href="#rfc.xref.warn.299.1">7.2.2</a></li>
     2140                  <li>Miscellaneous Warning (warn-text)&nbsp;&nbsp;<a href="#rfc.iref.m.6"><b>5.5.5</b></a>, <a href="#rfc.xref.warn.199.1">7.2.2</a></li>
    21332141                  <li>must-revalidate (cache directive)&nbsp;&nbsp;<a href="#rfc.iref.m.4"><b>5.2.2.1</b></a></li>
    21342142               </ul>
     
    21952203            </li>
    21962204            <li><a id="rfc.index.R" href="#rfc.index.R"><b>R</b></a><ul>
     2205                  <li>Response is Stale (warn-text)&nbsp;&nbsp;<a href="#rfc.iref.r.1"><b>5.5.1</b></a>, <a href="#rfc.xref.warn.110.1">7.2.2</a></li>
     2206                  <li>Revalidation Failed (warn-text)&nbsp;&nbsp;<a href="#rfc.iref.r.2"><b>5.5.2</b></a>, <a href="#rfc.xref.warn.111.1">7.2.2</a></li>
    21972207                  <li><em>RFC1305</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC1305.1">4.2.3</a>, <a href="#RFC1305"><b>10.2</b></a></li>
    21982208                  <li><em>RFC2119</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC2119.1">1.1</a>, <a href="#RFC2119"><b>10.1</b></a></li>
     
    22242234               </ul>
    22252235            </li>
     2236            <li><a id="rfc.index.T" href="#rfc.index.T"><b>T</b></a><ul>
     2237                  <li>Transformation Applied (warn-text)&nbsp;&nbsp;<a href="#rfc.iref.t.1"><b>5.5.6</b></a>, <a href="#rfc.xref.warn.214.1">7.2.2</a></li>
     2238               </ul>
     2239            </li>
    22262240            <li><a id="rfc.index.V" href="#rfc.index.V"><b>V</b></a><ul>
    22272241                  <li>validator&nbsp;&nbsp;<a href="#rfc.iref.v.1">4.3.1</a></li>
  • draft-ietf-httpbis/latest/p6-cache.xml

    r2383 r2384  
    2020  <!ENTITY conformance                 "<xref target='Part1' x:rel='#conformance' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    2121  <!ENTITY notation                    "<xref target='Part1' x:rel='#notation' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    22   <!ENTITY abnf-extension             "<xref target='Part1' x:rel='#abnf.extension' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     22  <!ENTITY abnf-extension              "<xref target='Part1' x:rel='#abnf.extension' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    2323  <!ENTITY acks                        "<xref target='Part1' x:rel='#acks' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    2424  <!ENTITY whitespace                  "<xref target='Part1' x:rel='#whitespace' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     
    674674<t>
    675675   When a heuristic is used to calculate freshness lifetime, a cache &SHOULD;
    676    attach a <x:ref>Warning</x:ref> header field with a 113 warn-code to the
     676   generate a <x:ref>Warning</x:ref> header field with a 113 warn-code in the
    677677   response if its current_age is more than 24 hours and such a warning is not
    678678   already present.
     
    815815</t>
    816816<t>
    817    A cache &SHOULD; append a <x:ref>Warning</x:ref> header field with the 110
    818    warn-code (see <xref target="header.warning"/>) to stale responses.
    819    Likewise, a cache &SHOULD; add the 112 warn-code to stale responses if the
    820    cache is disconnected.
    821 </t>
    822 <iref item="first-hand" />
    823 <t>
    824    Note that if a cache receives a <x:dfn>first-hand</x:dfn> response (one
    825    where the freshness model is not in use; i.e., its age is 0, whether it is
    826    an entire response, or a <x:ref>304 (Not Modified)</x:ref> response) that
    827    it would normally forward to the requesting client, and the received
    828    response is no longer fresh, the cache &MAY; forward it to the requesting
    829    client without adding a new <x:ref>Warning</x:ref> (but without removing
    830    any existing Warning header fields). A cache ought not attempt to validate
    831    a response simply because that response became stale in transit.
     817   A cache &SHOULD; generate a <x:ref>Warning</x:ref> header field with the
     818   110 warn-code (see <xref target="header.warning"/>) in stale responses.
     819   Likewise, a cache &SHOULD; generate a 112 warn-code in stale responses
     820   if the cache is disconnected.
     821</t>
     822<t>
     823   A cache &SHOULD-NOT; generate a new <x:ref>Warning</x:ref> header field
     824   when forwarding a response that does not have an <x:ref>Age</x:ref> header
     825   field, even if the response is already stale.  A cache need not validate
     826   a response that merely became stale in transit.
    832827</t>
    833828</section>
     
    11641159</artwork></figure>
    11651160<t>
    1166   Age field-values are non-negative integers, representing time in seconds
    1167   (see <xref target="delta-seconds"/>).
    1168 </t>
    1169 <t>
    1170    The presence of an Age header field in a response implies that a response
    1171    is not first-hand. However, the converse is not true, since HTTP/1.0 caches
    1172    might not implement the Age header field.
     1161   The Age field-value is a non-negative integer, representing time in seconds
     1162   (see <xref target="delta-seconds"/>).
     1163</t>
     1164<t>
     1165   The presence of an Age header field implies that the response was not
     1166   generated or validated by the origin server for this request. However,
     1167   lack of an Age header field does not imply the origin was contacted, since
     1168   the response might have been received from an HTTP/1.0 cache that does not
     1169   implement Age.
    11731170</t>
    11741171</section>
     
    17361733   The "Warning" header field is used to carry additional information
    17371734   about the status or transformation of a message that might not be reflected
    1738    in the message. This information is typically used to warn about possible
     1735   in the status code. This information is typically used to warn about possible
    17391736   incorrectness introduced by caching operations or transformations applied
    17401737   to the payload of the message.
     
    17641761</artwork></figure>
    17651762<t>
    1766    Multiple warnings can be attached to a response (either by the origin
    1767    server or by a cache), including multiple warnings with the same code
    1768    number, only differing in warn-text.
    1769 </t>
    1770 <t>
    1771    When this occurs, the user agent &SHOULD; inform the user of as many of
    1772    them as possible, in the order that they appear in the response.
    1773 </t>
    1774 <t>
    1775    Systems that generate multiple Warning header fields are encouraged to
    1776    order them with this user agent behavior in mind. New Warning header fields
    1777    are added after any existing Warning header fields.
     1763   Multiple warnings can be generated in a response (either by the origin
     1764   server or by a cache), including multiple warnings with the same warn-code
     1765   number that only differ in warn-text.
     1766</t>
     1767<t>
     1768   A user agent that receives one or more Warning header fields &SHOULD;
     1769   inform the user of as many of them as possible, in the order that they
     1770   appear in the response. Senders that generate multiple Warning header
     1771   fields are encouraged to order them with this user agent behavior in mind.
     1772   A sender that generates new Warning header fields &MUST; append them after
     1773   any existing Warning header fields.
    17781774</t>
    17791775<t>
     
    17821778   validation:
    17831779   <list style="symbols">
    1784       <t>1xx Warnings describe the freshness or validation status of the
     1780      <t>1xx warn-codes describe the freshness or validation status of the
    17851781      response, and so &MUST; be deleted by a cache after validation. They can
    17861782      only be generated by a cache when validating a cached entry, and
    17871783      &MUST-NOT; be generated in any other situation.</t>
    1788       <t>2xx Warnings describe some aspect of the representation that is not
     1784      <t>2xx warn-codes describe some aspect of the representation that is not
    17891785      rectified by a validation (for example, a lossy compression of the
    17901786      representation) and &MUST-NOT; be deleted by a cache after validation,
     
    17931789</t>
    17941790<t>
    1795    If an implementation sends a message with one or more Warning header fields
    1796    to a receiver whose version is HTTP/1.0 or lower, then the sender &MUST;
    1797    include in each warning-value a warn-date that matches the
     1791   If a sender generates one or more Warning header fields in a message to be
     1792   sent to a recipient known to implement only HTTP/1.0, the sender &MUST;
     1793   include in each generated warning-value a warn-date that matches the
    17981794   <x:ref>Date</x:ref> header field in the message.
    17991795</t>
    18001796<t>
    1801    If a system receives a message with a warning-value that includes a
    1802    warn-date, and that warn-date is different from the <x:ref>Date</x:ref>
    1803    value in the response, then that warning-value &MUST; be deleted from the
    1804    message before storing, forwarding, or using it (preventing the
    1805    consequences of naive caching of Warning header fields). If all of the
    1806    warning-values are deleted for this reason, the Warning header field &MUST;
    1807    be deleted as well.
     1797   If a recipient that uses, evaluates, or displays Warning header fields
     1798   receives a warn-date that is different from the <x:ref>Date</x:ref> value
     1799   in the same message, the recipient &MUST; exclude the warning-value
     1800   containing that warn-date before storing, forwarding, or using the message.
     1801   This allows recipients to exclude warning-values that were improperly
     1802   retained after a cache validation.
     1803   If all of the warning-values are excluded, the recipient &MUST; exclude
     1804   the Warning header field as well.
    18081805</t>
    18091806<t>
    18101807   The following warn-codes are defined by this specification, each with a
    18111808   recommended warn-text in English, and a description of its meaning.
    1812 </t>
    1813 
    1814 <section title="110 Response is Stale" anchor="warn.110">
    1815   <iref primary="true" item="110 Response is Stale (warn code)" x:for-anchor=""/>
     1809   The procedure for defining additional warn codes is described in
     1810   <xref target="warn.code.registry.procedure"/>.
     1811</t>
     1812
     1813<section title='Warning: 110 means "Response is Stale"' anchor="warn.110">
     1814  <iref primary="true" item="110 (warn-code)" x:for-anchor=""/>
     1815  <iref primary="true" item="Response is Stale (warn-text)" x:for-anchor=""/>
    18161816<t>
    18171817   A cache &SHOULD; generate this whenever the sent response is stale.
     
    18191819</section>
    18201820
    1821 <section title="111 Revalidation Failed" anchor="warn.111">
    1822   <iref primary="true" item="111 Revalidation Failed (warn code)" x:for-anchor=""/>
     1821<section title='Warning: 111 means "Revalidation Failed"' anchor="warn.111">
     1822  <iref primary="true" item="111 (warn-code)" x:for-anchor=""/>
     1823  <iref primary="true" item="Revalidation Failed (warn-text)" x:for-anchor=""/>
    18231824<t>
    18241825   A cache &SHOULD; generate this when sending a stale response because an
     
    18281829</section>
    18291830
    1830 <section title="112 Disconnected Operation" anchor="warn.112">
    1831   <iref primary="true" item="112 Disconnected Operation (warn code)" x:for-anchor=""/>
     1831<section title='Warning: 112 means "Disconnected Operation"' anchor="warn.112">
     1832  <iref primary="true" item="112 (warn-code)" x:for-anchor=""/>
     1833  <iref primary="true" item="Disconnected Operation (warn-text)" x:for-anchor=""/>
    18321834<t>
    18331835   A cache &SHOULD; generate this if it is intentionally disconnected from
     
    18361838</section>
    18371839
    1838 <section title="113 Heuristic Expiration" anchor="warn.113">
    1839   <iref primary="true" item="113 Heuristic Expiration (warn code)" x:for-anchor=""/>
     1840<section title='Warning: 113 means "Heuristic Expiration"' anchor="warn.113">
     1841  <iref primary="true" item="113 (warn-code)" x:for-anchor=""/>
     1842  <iref primary="true" item="Heuristic Expiration (warn-text)" x:for-anchor=""/>
    18401843<t>
    18411844   A cache &SHOULD; generate this if it heuristically chose a freshness
     
    18451848</section>
    18461849
    1847 <section title="199 Miscellaneous Warning" anchor="warn.199">
    1848   <iref primary="true" item="199 Miscellaneous Warning (warn code)" x:for-anchor=""/>
     1850<section title='Warning: 199 means "Miscellaneous Warning"' anchor="warn.199">
     1851  <iref primary="true" item="199 (warn-code)" x:for-anchor=""/>
     1852  <iref primary="true" item="Miscellaneous Warning (warn-text)" x:for-anchor=""/>
    18491853<t>
    18501854   The warning text can include arbitrary information to be presented to
     
    18541858</section>
    18551859
    1856 <section title="214 Transformation Applied" anchor="warn.214">
    1857   <iref primary="true" item="214 Transformation Applied (warn code)" x:for-anchor=""/>
     1860<section title='Warning: 214 means "Transformation Applied"' anchor="warn.214">
     1861  <iref primary="true" item="214 (warn-code)" x:for-anchor=""/>
     1862  <iref primary="true" item="Transformation Applied (warn-text)" x:for-anchor=""/>
    18581863<t>
    18591864   &MUST; be added by a proxy if it applies any transformation to the
     
    18641869</section>
    18651870
    1866 <section title="299 Miscellaneous Persistent Warning" anchor="warn.299">
    1867   <iref primary="true" item="299 Miscellaneous Persistent Warning (warn code)" x:for-anchor=""/>
     1871<section title='Warning: 299 means "Miscellaneous Persistent Warning"' anchor="warn.299">
     1872  <iref primary="true" item="299 (warn-code)" x:for-anchor=""/>
     1873  <iref primary="true" item="Miscellaneous Persistent Warning (warn-text)" x:for-anchor=""/>
    18681874<t>
    18691875   The warning text can include arbitrary information to be presented to
    18701876   a human user, or logged. A system receiving this warning &MUST-NOT; take
    18711877   any automated action.
    1872 </t>
    1873 </section>
    1874 
    1875 <section title="Warn Code Extensions" anchor="warn.code.extensions">
    1876 <t>
    1877    Extension warn codes can be defined; see <xref target="warn.code.registry.procedure"/>
    1878    for details.
    18791878</t>
    18801879</section>
     
    26602659<x:ref>warn-date</x:ref> = DQUOTE HTTP-date DQUOTE
    26612660<x:ref>warn-text</x:ref> = quoted-string
    2662 <x:ref>warning-value</x:ref> = warn-code SP warn-agent SP warn-text SP warn-date
     2661<x:ref>warning-value</x:ref> = warn-code SP warn-agent SP warn-text [ SP warn-date ]
    26632662</artwork>
    26642663</figure>
Note: See TracChangeset for help on using the changeset viewer.