From baecf9e13f7d3cc481ce9084c80f8dcde17fa777 Mon Sep 17 00:00:00 2001
From: Rich Bowen <rbowen@apache.org>
Date: Tue, 3 Nov 2009 00:16:57 +0000
Subject: [PATCH] Moves another rule out of rewrite_guide, and updates it for
 modern versions of mod_rewrite

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@832217 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/rewrite/index.html.en         |  2 +
 docs/manual/rewrite/index.xml             |  2 +
 docs/manual/rewrite/index.xml.tr          |  2 +-
 docs/manual/rewrite/remapping.html.en     | 95 ++++++++++++++++++++++-
 docs/manual/rewrite/remapping.xml         | 93 +++++++++++++++++++++-
 docs/manual/rewrite/rewrite_guide.html.en | 88 ---------------------
 docs/manual/rewrite/rewrite_guide.xml     | 86 --------------------
 7 files changed, 191 insertions(+), 177 deletions(-)

diff --git a/docs/manual/rewrite/index.html.en b/docs/manual/rewrite/index.html.en
index 6b5225b6aa..8b33dd78aa 100644
--- a/docs/manual/rewrite/index.html.en
+++ b/docs/manual/rewrite/index.html.en
@@ -58,6 +58,8 @@ documentation</a></li>
 <li><a href="intro.html">Introduction to regular expressions and
 mod_rewrite</a></li>
 <li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li>
+<li><a href="remapping.html">Using mod_rewrite for redirection and
+remapping of URLs</a></li>
 <li><a href="access.html">Using mod_rewrite to control access</a></li>
 <li><a href="flags.html">Flags</a></li>
 <li><a href="tech.html">Technical details</a></li>
diff --git a/docs/manual/rewrite/index.xml b/docs/manual/rewrite/index.xml
index aea2f1dbcc..e1ee141401 100644
--- a/docs/manual/rewrite/index.xml
+++ b/docs/manual/rewrite/index.xml
@@ -64,6 +64,8 @@ documentation</a></li>
 <li><a href="intro.html">Introduction to regular expressions and
 mod_rewrite</a></li>
 <li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li>
+<li><a href="remapping.html">Using mod_rewrite for redirection and
+remapping of URLs</a></li>
 <li><a href="access.html">Using mod_rewrite to control access</a></li>
 <li><a href="flags.html">Flags</a></li>
 <li><a href="tech.html">Technical details</a></li>
diff --git a/docs/manual/rewrite/index.xml.tr b/docs/manual/rewrite/index.xml.tr
index 58cfb528cb..833585c889 100644
--- a/docs/manual/rewrite/index.xml.tr
+++ b/docs/manual/rewrite/index.xml.tr
@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 636374:832069 (outdated) -->
+<!-- English Revision: 636374:832183 (outdated) -->
 <!-- =====================================================
  Translated by: Nilgün Belma Bugüner <nilgun belgeler.org>
    Reviewed by: Orhan Berent <berent belgeler.org>
diff --git a/docs/manual/rewrite/remapping.html.en b/docs/manual/rewrite/remapping.html.en
index 4da1dd33b3..57e93f6f9f 100644
--- a/docs/manual/rewrite/remapping.html.en
+++ b/docs/manual/rewrite/remapping.html.en
@@ -37,7 +37,9 @@ configuration.</div>
 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#old-to-new">From Old to New (internal)</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#old-to-new-extern">Rewriting From Old to New (external)</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#static-to-dynamic">From Static to Dynamic</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#backward-compatibility">Backward Compatibility for file extension change</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#canonicalhost">Canonical Hostnames</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#multipledirs">Search for pages in more than one directory</a></li>
 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li></ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
@@ -148,6 +150,54 @@ RewriteRule    ^foo\.<strong>html</strong>$  foo.<strong>cgi</strong>  [H=<stron
     </dd>
   </dl>
 
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="backward-compatibility" id="backward-compatibility">Backward Compatibility for file extension change</a></h2>
+
+  
+
+  <dl>
+    <dt>Description:</dt>
+
+    <dd>
+      <p>How can we make URLs backward compatible (still
+      existing virtually) after migrating <code>document.YYYY</code>
+      to <code>document.XXXX</code>, e.g. after translating a
+      bunch of <code>.html</code> files to <code>.php</code>?</p>
+    </dd>
+
+    <dt>Solution:</dt>
+
+    <dd>
+      <p>We rewrite the name to its basename and test for
+      existence of the new extension. If it exists, we take
+      that name, else we rewrite the URL to its original state.</p>
+
+<div class="example"><pre>
+#   backward compatibility ruleset for
+#   rewriting document.html to document.php
+#   when and only when document.php exists
+RewriteEngine on
+
+RewriteCond $1.php -f
+RewriteCond $1.html !-f
+RewriteRule ^(.*).html$ $1.php 
+</pre></div>
+    </dd>
+
+    <dt>Discussion</dt>
+    <dd>
+    <p>This example uses an often-overlooked feature of mod_rewrite,
+    by taking advantage of the order of execution of the ruleset. In
+    particular, mod_rewrite evaluates the left-hand-side of the
+    RewriteRule before it evaluates the RewriteCond directives.
+    Consequently, $1 is already defined by the time the RewriteRule
+    directives are evaluated. This allows us to test for the existence
+    of the the original (<code>document.html</code>) and target
+    (<code>document.php</code>) files using the same base filename.</p>
+    </dd>
+  </dl>
+
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="canonicalhost" id="canonicalhost">Canonical Hostnames</a></h2>
@@ -198,7 +248,50 @@ RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
         </dd>
       </dl>
 
-    </div></div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="multipledirs" id="multipledirs">Search for pages in more than one directory</a></h2>
+
+  
+
+  <dl>
+    <dt>Description:</dt>
+
+    <dd>
+      <p>A particular resource might exist in one of several places, and
+      we want to look in those places for the resource when it is
+      requested. Perhaps we've recently rearranged our directory
+      structure, dividing content into several locations.</p>
+    </dd>
+
+    <dt>Solution:</dt>
+
+    <dd>
+      <p>The following ruleset searches in two directories to find the
+      resource, and, if not finding it in either place, will attempt to
+      just serve it out of the location requested.</p>
+
+<div class="example"><pre>
+RewriteEngine on
+
+#   first try to find it in dir1/...
+#   ...and if found stop and be happy:
+RewriteCond         %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI}  -f
+RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1  [L]
+
+#   second try to find it in dir2/...
+#   ...and if found stop and be happy:
+RewriteCond         %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI}  -f
+RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1  [L]
+
+#   else go on for other Alias or ScriptAlias directives,
+#   etc.
+RewriteRule   ^(.+)  -  [PT]
+</pre></div>
+    </dd>
+  </dl>
+
+</div></div>
 <div class="bottomlang">
 <p><span>Available Languages: </span><a href="../en/rewrite/remapping.html" title="English">&nbsp;en&nbsp;</a></p>
 </div><div id="footer">
diff --git a/docs/manual/rewrite/remapping.xml b/docs/manual/rewrite/remapping.xml
index 2fd868049a..2db100f566 100644
--- a/docs/manual/rewrite/remapping.xml
+++ b/docs/manual/rewrite/remapping.xml
@@ -152,6 +152,54 @@ RewriteRule    ^foo\.<strong>html</strong>$  foo.<strong>cgi</strong>  [H=<stron
 
 </section>
 
+<section id="backward-compatibility">
+
+  <title>Backward Compatibility for file extension change</title>
+
+  <dl>
+    <dt>Description:</dt>
+
+    <dd>
+      <p>How can we make URLs backward compatible (still
+      existing virtually) after migrating <code>document.YYYY</code>
+      to <code>document.XXXX</code>, e.g. after translating a
+      bunch of <code>.html</code> files to <code>.php</code>?</p>
+    </dd>
+
+    <dt>Solution:</dt>
+
+    <dd>
+      <p>We rewrite the name to its basename and test for
+      existence of the new extension. If it exists, we take
+      that name, else we rewrite the URL to its original state.</p>
+
+<example><pre>
+#   backward compatibility ruleset for
+#   rewriting document.html to document.php
+#   when and only when document.php exists
+RewriteEngine on
+
+RewriteCond $1.php -f
+RewriteCond $1.html !-f
+RewriteRule ^(.*).html$ $1.php 
+</pre></example>
+    </dd>
+
+    <dt>Discussion</dt>
+    <dd>
+    <p>This example uses an often-overlooked feature of mod_rewrite,
+    by taking advantage of the order of execution of the ruleset. In
+    particular, mod_rewrite evaluates the left-hand-side of the
+    RewriteRule before it evaluates the RewriteCond directives.
+    Consequently, $1 is already defined by the time the RewriteRule
+    directives are evaluated. This allows us to test for the existence
+    of the the original (<code>document.html</code>) and target
+    (<code>document.php</code>) files using the same base filename.</p>
+    </dd>
+  </dl>
+
+</section>
+
 <section id="canonicalhost"><title>Canonical Hostnames</title>
 
       <dl>
@@ -201,6 +249,49 @@ RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
         </dd>
       </dl>
 
-    </section>
+</section>
+
+<section id="multipledirs">
+
+  <title>Search for pages in more than one directory</title>
+
+  <dl>
+    <dt>Description:</dt>
+
+    <dd>
+      <p>A particular resource might exist in one of several places, and
+      we want to look in those places for the resource when it is
+      requested. Perhaps we've recently rearranged our directory
+      structure, dividing content into several locations.</p>
+    </dd>
+
+    <dt>Solution:</dt>
+
+    <dd>
+      <p>The following ruleset searches in two directories to find the
+      resource, and, if not finding it in either place, will attempt to
+      just serve it out of the location requested.</p>
+
+<example><pre>
+RewriteEngine on
+
+#   first try to find it in dir1/...
+#   ...and if found stop and be happy:
+RewriteCond         %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI}  -f
+RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1  [L]
+
+#   second try to find it in dir2/...
+#   ...and if found stop and be happy:
+RewriteCond         %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI}  -f
+RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1  [L]
+
+#   else go on for other Alias or ScriptAlias directives,
+#   etc.
+RewriteRule   ^(.+)  -  [PT]
+</pre></example>
+    </dd>
+  </dl>
+
+</section>
 
 </manualpage> 
diff --git a/docs/manual/rewrite/rewrite_guide.html.en b/docs/manual/rewrite/rewrite_guide.html.en
index 5aff84504f..3dafd00a37 100644
--- a/docs/manual/rewrite/rewrite_guide.html.en
+++ b/docs/manual/rewrite/rewrite_guide.html.en
@@ -45,13 +45,11 @@
 <li><img alt="" src="../images/down.gif" /> <a href="#moveddocroot">Moved <code>DocumentRoot</code></a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#trailingslash">Trailing Slash Problem</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#movehomedirs">Move Homedirs to Different Webserver</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#multipledirs">Search for pages in more than one directory</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#setenvvars">Set Environment Variables According To URL Parts</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#uservhosts">Virtual Hosts Per User</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#redirecthome">Redirect Homedirs For Foreigners</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#redirectanchors">Redirecting Anchors</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#time-dependent">Time-Dependent Rewriting</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#backward-compatibility">Backward Compatibility for YYYY to XXXX migration</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#proxy-deny">Proxy Deny</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#external-rewriting">External Rewriting Engine</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#cluster">Web Cluster with Consistent URL Space</a></li>
@@ -245,47 +243,6 @@ RewriteRule   ^/~(.+)  http://<strong>newserver</strong>/~$1  [R,L]
 
     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
-<h2><a name="multipledirs" id="multipledirs">Search for pages in more than one directory</a></h2>
-
-      
-
-      <dl>
-        <dt>Description:</dt>
-
-        <dd>
-          <p>Sometimes it is necessary to let the webserver search
-          for pages in more than one directory. Here MultiViews or
-          other techniques cannot help.</p>
-        </dd>
-
-        <dt>Solution:</dt>
-
-        <dd>
-          <p>We program a explicit ruleset which searches for the
-          files in the directories.</p>
-
-<div class="example"><pre>
-RewriteEngine on
-
-#   first try to find it in dir1/...
-#   ...and if found stop and be happy:
-RewriteCond         %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI}  -f
-RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1  [L]
-
-#   second try to find it in dir2/...
-#   ...and if found stop and be happy:
-RewriteCond         %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI}  -f
-RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1  [L]
-
-#   else go on for other Alias or ScriptAlias directives,
-#   etc.
-RewriteRule   ^(.+)  -  [PT]
-</pre></div>
-        </dd>
-      </dl>
-
-    </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
 <h2><a name="setenvvars" id="setenvvars">Set Environment Variables According To URL Parts</a></h2>
 
       
@@ -455,51 +412,6 @@ RewriteRule   ^foo\.html$             foo.night.html
 
     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
-<h2><a name="backward-compatibility" id="backward-compatibility">Backward Compatibility for YYYY to XXXX migration</a></h2>
-
-      
-
-      <dl>
-        <dt>Description:</dt>
-
-        <dd>
-          <p>How can we make URLs backward compatible (still
-          existing virtually) after migrating <code>document.YYYY</code>
-          to <code>document.XXXX</code>, e.g. after translating a
-          bunch of <code>.html</code> files to <code>.phtml</code>?</p>
-        </dd>
-
-        <dt>Solution:</dt>
-
-        <dd>
-          <p>We just rewrite the name to its basename and test for
-          existence of the new extension. If it exists, we take
-          that name, else we rewrite the URL to its original state.</p>
-
-
-<div class="example"><pre>
-#   backward compatibility ruleset for
-#   rewriting document.html to document.phtml
-#   when and only when document.phtml exists
-#   but no longer document.html
-RewriteEngine on
-RewriteBase   /~quux/
-#   parse out basename, but remember the fact
-RewriteRule   ^(.*)\.html$              $1      [C,E=WasHTML:yes]
-#   rewrite to document.phtml if exists
-#   Note: This is a per-directory example, so %{REQUEST_FILENAME} is the full 
-#         filesystem path as already mapped by the server.
-RewriteCond   %{REQUEST_FILENAME}.phtml -f
-RewriteRule   ^(.*)$ $1.phtml                   [S=1]
-#   else reverse the previous basename cutout
-RewriteCond   %{ENV:WasHTML}            ^yes$
-RewriteRule   ^(.*)$ $1.html
-</pre></div>
-        </dd>
-      </dl>
-
-    </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
 <h2><a name="proxy-deny" id="proxy-deny">Proxy Deny</a></h2>
 
       
diff --git a/docs/manual/rewrite/rewrite_guide.xml b/docs/manual/rewrite/rewrite_guide.xml
index 10e664803b..06f77925d5 100644
--- a/docs/manual/rewrite/rewrite_guide.xml
+++ b/docs/manual/rewrite/rewrite_guide.xml
@@ -223,47 +223,6 @@ RewriteRule   ^/~(.+)  http://<strong>newserver</strong>/~$1  [R,L]
 
     </section>
 
-    <section id="multipledirs">
-
-      <title>Search for pages in more than one directory</title>
-
-      <dl>
-        <dt>Description:</dt>
-
-        <dd>
-          <p>Sometimes it is necessary to let the webserver search
-          for pages in more than one directory. Here MultiViews or
-          other techniques cannot help.</p>
-        </dd>
-
-        <dt>Solution:</dt>
-
-        <dd>
-          <p>We program a explicit ruleset which searches for the
-          files in the directories.</p>
-
-<example><pre>
-RewriteEngine on
-
-#   first try to find it in dir1/...
-#   ...and if found stop and be happy:
-RewriteCond         %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI}  -f
-RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1  [L]
-
-#   second try to find it in dir2/...
-#   ...and if found stop and be happy:
-RewriteCond         %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI}  -f
-RewriteRule  ^(.+)  %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1  [L]
-
-#   else go on for other Alias or ScriptAlias directives,
-#   etc.
-RewriteRule   ^(.+)  -  [PT]
-</pre></example>
-        </dd>
-      </dl>
-
-    </section>
-
     <section id="setenvvars">
 
       <title>Set Environment Variables According To URL Parts</title>
@@ -434,51 +393,6 @@ RewriteRule   ^foo\.html$             foo.night.html
 
     </section>
 
-    <section id="backward-compatibility">
-
-      <title>Backward Compatibility for YYYY to XXXX migration</title>
-
-      <dl>
-        <dt>Description:</dt>
-
-        <dd>
-          <p>How can we make URLs backward compatible (still
-          existing virtually) after migrating <code>document.YYYY</code>
-          to <code>document.XXXX</code>, e.g. after translating a
-          bunch of <code>.html</code> files to <code>.phtml</code>?</p>
-        </dd>
-
-        <dt>Solution:</dt>
-
-        <dd>
-          <p>We just rewrite the name to its basename and test for
-          existence of the new extension. If it exists, we take
-          that name, else we rewrite the URL to its original state.</p>
-
-
-<example><pre>
-#   backward compatibility ruleset for
-#   rewriting document.html to document.phtml
-#   when and only when document.phtml exists
-#   but no longer document.html
-RewriteEngine on
-RewriteBase   /~quux/
-#   parse out basename, but remember the fact
-RewriteRule   ^(.*)\.html$              $1      [C,E=WasHTML:yes]
-#   rewrite to document.phtml if exists
-#   Note: This is a per-directory example, so %{REQUEST_FILENAME} is the full 
-#         filesystem path as already mapped by the server.
-RewriteCond   %{REQUEST_FILENAME}.phtml -f
-RewriteRule   ^(.*)$ $1.phtml                   [S=1]
-#   else reverse the previous basename cutout
-RewriteCond   %{ENV:WasHTML}            ^yes$
-RewriteRule   ^(.*)$ $1.html
-</pre></example>
-        </dd>
-      </dl>
-
-    </section>
-
     <section id="proxy-deny">
 
       <title>Proxy Deny</title>
-- 
2.40.0