From: Eric Covener <covener@apache.org>
Date: Wed, 2 Apr 2014 16:10:50 +0000 (+0000)
Subject: try to clarify that "onsuccess" is for anything but locally-generated errors,
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a99c867e4ba4bf8c6fcf23255e2d22cdc7ba0da6;p=thirdparty%2Fapache%2Fhttpd.git

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/trunk@1584078 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/mod/mod_headers.xml b/docs/manual/mod/mod_headers.xml
index 67e23b521f4..bccb773c06d 100644
--- 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>