rewrite guide: merge proxy.xml content into avoid.xml, replace proxy.xml with deprecation stub (BZ 58892, step 5)

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

Author: rbowen

docs/manual/rewrite/avoid.xml

@@ -189,6 +189,25 @@ other <code>RewriteRule</code>s in effect in the same scope, as a
 <code>ProxyPass</code>, and so may preempt what you're trying to
 accomplish.</p>
 
+<p>One case where <directive module="mod_rewrite">RewriteRule</directive>
+is genuinely useful for proxying is when you want to proxy requests only
+for content that doesn't exist locally — for example, during a migration
+from one server to another:</p>
+
+<highlight language="config">
+RewriteCond "%{REQUEST_FILENAME}"       !-f
+RewriteCond "%{REQUEST_FILENAME}"       !-d
+RewriteRule "^/(.*)"                    "http://old.example.com/$1" [P]
+ProxyPassReverse "/" "http://old.example.com/"
+</highlight>
+
+<p>In this example, requests for resources that haven't been migrated
+yet are transparently proxied to the old server. As content is migrated,
+the local files take precedence. Remember to always include a
+<directive module="mod_proxy">ProxyPassReverse</directive> directive to
+ensure that any redirects issued by the backend are correctly passed on
+to the client.</p>
+
 </section>
 
 <section id="setenv"><title>Environment Variable Testing</title>

docs/manual/rewrite/proxy.xml

@@ -27,78 +27,13 @@
 
 <summary>
 
-<p>This document supplements the <module>mod_rewrite</module>
-<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
-how to use the RewriteRule's [P] flag to proxy content to another server.
-A number of recipes are provided that describe common scenarios.</p>
+<note type="warning">This document has been deprecated. Its content has
+been merged into the
+<a href="avoid.html#proxy">When not to use mod_rewrite</a> document,
+since simple proxying is better accomplished using
+<directive module="mod_proxy">ProxyPass</directive>. This page will be
+removed in a future version of this documentation.</note>
 
 </summary>
-<seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
-<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
-<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
-<seealso><a href="access.html">Controlling access</a></seealso>
-<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
-<!--<seealso><a href="proxy.html">Proxying</a></seealso>-->
-<seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
-<seealso><a href="advanced.html">Advanced techniques</a></seealso>
-<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
-
-<section id="dynamic-proxy">
-
-  <title>Proxying Content with mod_rewrite</title>
-
-  <dl>
-    <dt>Description:</dt>
-
-    <dd>
-    <p>
-    <module>mod_rewrite</module> provides the [P] flag, which allows URLs to be passed,
-    via <module>mod_proxy</module>, to another server. Two examples are given here. In
-    one example, a URL is passed directly to another server, and served
-    as though it were a local URL. In the other example, we proxy
-    missing content to a back-end server.</p>
-    </dd>
-
-    <dt>Solution:</dt>
-
-    <dd>
-      <p>To simply map a URL to another server, we use the [P] flag, as
-      follows:</p>
-
-<highlight language="config">
-RewriteEngine  on
-RewriteBase    "/products/"
-RewriteRule    "^widget/(.*)$"  "http://product.example.com/widget/$1"  [P]
-ProxyPassReverse "/products/widget/" "http://product.example.com/widget/"
-</highlight>
-
-   <p>In the second example, we proxy the request only if we can't find
-   the resource locally. This can be very useful when you're migrating
-   from one server to another, and you're not sure if all the content
-   has been migrated yet.</p>
-
-<highlight language="config">
-RewriteCond "%{REQUEST_FILENAME}"       !-f
-RewriteCond "%{REQUEST_FILENAME}"       !-d
-RewriteRule "^/(.*)"                    "http://old.example.com/$1" [P]
-ProxyPassReverse "/" "http://old.example.com/"
-</highlight>
-    </dd>
-
-    <dt>Discussion:</dt>
-
-    <dd><p>In each case, we add a <directive
-    module="mod_proxy">ProxyPassReverse</directive> directive to ensure
-    that any redirects issued by the backend are correctly passed on to
-    the client.</p>
-
-    <p>Consider using either <directive
-    module="mod_proxy">ProxyPass</directive> or <directive
-    module="mod_proxy">ProxyPassMatch</directive> whenever possible in
-    preference to <module>mod_rewrite</module>.</p>
-    </dd>
-  </dl>
-
-</section>
 
 </manualpage>