mod_proxy.xml: docs improvements

Tried to clarify the doubts raised in PR 61225
(related also to 60458) and also split a single note
into multiple ones to improve the reader's attention span
(reading through a long block of text may cause loss
of attention to important details, as it happened to me :)

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1828069 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index 9790165cb53f5afbeb60b063465d0a02816779bc..6ccf78c1d039cb543a0da927c9f0b7837baab1cb 100644 (file)
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -980,6 +980,19 @@ ProxyPass "/mirror/foo"   "http://backend.example.com"
     <code>backend.example.com</code> <em>except</em> requests made to
     <code>/mirror/foo/i</code>.</p>
 
+    <p>Mixing ProxyPass settings in different contexts does not work:</p>
+    <highlight language="config">
+ProxyPass "/mirror/foo/i" "!"
+&lt;Location "/mirror/foo/"&gt;
+    ProxyPass "http://backend.example.com/"
+&lt;/Location&gt;
+    </highlight>
+    <p>In this case, a request to <code>/mirror/foo/i</code> will get proxied,
+       because the <directive>ProxyPass</directive> directive in the Location block will be evaluated
+       first. The fact that <directive>ProxyPass</directive> supports both server and directory contexts
+       does not mean that their scope and position in the configuration file will
+       guarantee any ordering or override.</p>
+
     <note type="warning"><title>Ordering ProxyPass Directives</title>
       <p>The configured <directive module="mod_proxy">ProxyPass</directive>
       and <directive module="mod_proxy">ProxyPassMatch</directive>
@@ -988,12 +1001,15 @@ ProxyPass "/mirror/foo"   "http://backend.example.com"
       <directive module="mod_proxy">ProxyPass</directive> rules starting with the
       longest URLs first. Otherwise, later rules for longer URLS will be hidden
       by any earlier rule which uses a leading substring of the URL. Note that
-      there is some relation with worker sharing. In contrast, only one
-      <directive module="mod_proxy">ProxyPass</directive> directive can be placed
-      in a <directive module="core">Location</directive> block, and the most
-      specific location will take precedence.</p>
-
-      <p>For the same reasons, exclusions must come <em>before</em> the
+      there is some relation with worker sharing.</p>
+    </note>
+    <note type="warning"><title>Ordering ProxyPass Directives in Locations</title>
+      <p>Only one <directive module="mod_proxy">ProxyPass</directive> directive
+      can be placed in a <directive module="core">Location</directive> block,
+      and the most specific location will take precedence.</p>
+    </note>
+    <note type="warning"><title>Exclusions and the no-proxy environment variable</title>
+      <p>Exclusions must come <em>before</em> the
       general <directive>ProxyPass</directive> directives. In 2.4.26 and later, the "no-proxy"
       environment variable is an alternative to exclusions, and is the only
       way to configure an exclusion of a <directive>ProxyPass</directive>