From 159875a751b4de99468e1d1c63cab3baaa4788d8 Mon Sep 17 00:00:00 2001
From: Eric Covener <covener@apache.org>
Date: Mon, 2 Apr 2012 12:37:32 +0000
Subject: [PATCH] PR51969: one more try at explaining RewriteBase, simplify the
 example and show how missing rewritebase altogether would go wrong.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1308320 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/mod_rewrite.xml | 59 ++++++++++++++++-----------------
 1 file changed, 29 insertions(+), 30 deletions(-)

diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml
index 6dc853f500..9101e54222 100644
--- a/docs/manual/mod/mod_rewrite.xml
+++ b/docs/manual/mod/mod_rewrite.xml
@@ -293,42 +293,41 @@ Apache HTTP Server 2.0.41 and later</compatibility>
 <override>FileInfo</override>
 
 <usage>
-      <p>The <directive>RewriteBase</directive> directive explicitly
-      sets the base URL-path (not filesystem directory path!)  for per-directory rewrites
-      that result in the substitution of a relative path.
-      When you use a <directive module="mod_rewrite">RewriteRule</directive>
-      in a <code>.htaccess</code> file, <module>mod_rewrite</module> strips off
-      the local directory prefix before processing, then rewrites the rest of
-      the URL. When the rewrite is completed, <module>mod_rewrite</module>
-      automatically adds the local directory prefix (or the
-      <directive>RewriteBase</directive> when set) back on to the substitution
-      before handing it back to the core of the server as if it were the original
-      URL.</p>
-
-      <p>This directive is <em>required</em> for per-directory rewrites whose context
-      is a directory made available via the <directive module="mod_alias">Alias</directive>
-      directive, when the substitution uses a relative path.</p>
-
-      <p>If your URL path does not exist verbatim on the filesystem,
-      or isn't directly under your <directive module="core">DocumentRoot</directive>,
-      you must use <directive>RewriteBase</directive> in every
-      <code>.htaccess</code> file where you want to use <directive
-      module="mod_rewrite">RewriteRule</directive> directives.</p>
-
-      <p>The example below demonstrates how to map
-      http://example.com/myapp/index.html to
-      /home/www/example/newsite.html, in a <code>.htaccess</code> file. This
-      assumes that the content available at
-      http://example.com/ is on disk at /home/www/example/</p>
+      <p>The <directive>RewriteBase</directive> directive specifies the
+      URL prefix to be used for per-directory (htaccess) 
+      <directive>RewriteRule</directive> directives that substitute a relative
+      path.</p>
+      <p> This directive is <em>required</em> when you use a relative path
+      in a substitution in per-directory (htaccess) context unless either
+      of the following conditions are true:
+      <ul>
+          <li> The original request, and the substitution, are underneath the 
+               <directive module="core">DocumentRoot</directive>
+               (as opposed to reachable by other means, such as 
+               <directive module="mod_alias">Alias</directive>).</li>
+          <li> The <em>filesystem</em> path to the directory containing the
+               <directive>RewriteRule</directive>, suffixed by the relative 
+               substitution is also valid as a URL path on the server 
+               (this is rare).</li>
+      </ul>
+      </p>
+
+<p> In the example below, <directive>RewriteBase</directive> is necessary
+    to avoid rewriting to http://example.com/opt/myapp-1.2.3/welcome.html
+    since the resource was not relative to the document root.  This 
+    misconfiguration would normally cause the server to look for an "opt"
+    directory under the document root.</p>
 <example>
 <pre>
+DocumentRoot /var/www/example.com
+Alias /myapp /opt/myapp-1.2.3
+&lt;Directory /opt/myapp-1.2.3&gt;
 RewriteEngine On
-# The URL-path used to get to this context, not the filesystem path
 RewriteBase /myapp/
-RewriteRule ^index\.html$  newsite.html
+RewriteRule ^index\.html$  welcome.html 
+&lt;/Directory&gt;
 </pre>
 </example>
-
 </usage>
 
 </directivesynopsis>
-- 
2.40.0