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.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1584079 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/mod/mod_headers.xml b/docs/manual/mod/mod_headers.xml
index d696e640523a178d4e754b2bab01f61dedf1a4cc..0bb3b39a78d369364e0720d76507ab4d40c57d01 100644 (file)
--- a/docs/manual/mod/mod_headers.xml
+++ b/docs/manual/mod/mod_headers.xml
@@ -317,22 +317,22 @@ Header merge Cache-Control no-store env=NO_STORE
     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=NO_STORE
             <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>