svn commit: r1584079 - /httpd/httpd/branches/2.4.x/docs/manual/mod/mod_headers.xml

[co...@apache.org]

Author: covener
Date: Wed Apr  2 16:11:33 2014
New Revision: 1584079

URL: http://svn.apache.org/r1584079
Log:
Merge r1584078 from trunk:

try to clarify that "onsuccess" is for anything but locally-generated errors,
the module behavior and the doc are equally painful for users.



Modified:
    httpd/httpd/branches/2.4.x/docs/manual/mod/mod_headers.xml

Modified: httpd/httpd/branches/2.4.x/docs/manual/mod/mod_headers.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/mod/mod_headers.xml?rev=1584079&r1=1584078&r2=1584079&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/mod/mod_headers.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/mod/mod_headers.xml Wed Apr  2 16:11:33 2014
@@ -317,22 +317,22 @@ Header merge Cache-Control no-store env=
     modified.</p>
 
     <p> The optional <var>condition</var> argument determines which internal
-    table of responses headers this directive will operate against.  Other
-    components of the server may have stored their response headers in either
-    the table that corresponds to <code>onsuccess</code> or the table that
-    corresponds to <code>always</code>.  "Always" in this context refers to
-    whether headers you add will be sent during both a successful and unsucessful
-    response, but if your action is a function of an existing header, you
-    will have to read on for further complications.</p>
-
-    <p> The default value of <code>onsuccess</code> may need to be changed to
-    <code>always</code> under the circumstances similar to those listed below.
+    table of responses headers this directive will operate against. Despite the
+    name, the default value of <code>onsuccess</code> does <em>not</em> limit 
+    an <var>action</var> to responses with a 2xx status code.  Headers set under
+    this condition are still used when, for example, a request is <em>successfully</em>
+    proxied or generated by CGI, even when they have generated a failing status code.</p>
+
+    <p>When your action is a function of an existing header, you may need to specify
+    a condition of <code>always</code>, depending on which internal table the
+    original header was set in.  The table that corresponds to <code>always</code> is
+    used for locally generated error responses as well as successful responses.  
     Note also that repeating this directive with both conditions makes sense in
     some scenarios because <code>always</code> is not a superset of
     <code>onsuccess</code> with respect to existing headers:</p>
 
     <ul>
-       <li> You're adding a header to a non-success (non-2xx) response, such
+       <li> You're adding a header to a locally generated non-success (non-2xx) response, such
             as a redirect, in which case only the table corresponding to
             <code>always</code> is used in the ultimate response.</li>
        <li> You're modifying or removing a header generated by a CGI script,
@@ -343,6 +343,10 @@ Header merge Cache-Control no-store env=
             <code>onsuccess</code> condition.</li>
     </ul>
 
+    <p>It is not currently possible to limit an action to a range of HTTP 
+    status codes, if the responses are successfully handled by e.g. CGI or
+    proxy modules.</p>
+
     <p>The action it performs is determined by the first
     argument (second argument if a <var>condition</var> is specified).
     This can be one of the following values:</p>