Return-Path: 
 <cvs-return-37791-apmail-httpd-cvs-archive=httpd.apache.org@httpd.apache.org>
Delivered-To: apmail-httpd-cvs-archive@www.apache.org
Received: (qmail 23608 invoked from network); 5 Jan 2011 22:40:09 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3)
  by minotaur.apache.org with SMTP; 5 Jan 2011 22:40:09 -0000
Received: (qmail 27275 invoked by uid 500); 5 Jan 2011 22:40:09 -0000
Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org
Received: (qmail 27226 invoked by uid 500); 5 Jan 2011 22:40:09 -0000
Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@httpd.apache.org
list-help: <mailto:cvs-help@httpd.apache.org>
list-unsubscribe: <mailto:cvs-unsubscribe@httpd.apache.org>
List-Post: <mailto:cvs@httpd.apache.org>
List-Id: <cvs.httpd.apache.org>
Delivered-To: mailing list cvs@httpd.apache.org
Received: (qmail 27219 invoked by uid 99); 5 Jan 2011 22:40:09 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Jan 2011 22:40:09 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Jan 2011 22:40:08 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id 51E2523888EC; Wed,  5 Jan 2011 22:39:48 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1055671 -
 /httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml
Date: Wed, 05 Jan 2011 22:39:48 -0000
To: cvs@httpd.apache.org
From: covener@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20110105223948.51E2523888EC@eris.apache.org>

Author: covener
Date: Wed Jan  5 22:39:47 2011
New Revision: 1055671

URL: http://svn.apache.org/viewvc?rev=1055671&view=rev
Log:
PR#44838: be more up front with how the per-dir RewriteRule comparison is
the filesystem path minus the Directory the rules were listed in.


Modified:
    httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml

Modified: httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml?rev=1055671&r1=1055670&r2=1055671&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml Wed Jan  5 22:39:47 2011
@@ -879,24 +879,59 @@ RewriteRule  ^/$                 /homepa
       RewriteRule.</p>
 
 <note><title>What is matched?</title>
-      <p>The <em>Pattern</em> will initially be matched against the part of the
-      URL after the hostname and port, and before the query string.</p>
-
-      <p>When the RewriteRule appears in per-directory (htaccess) context, the 
-      <em>Pattern</em> is matched against what remains of the URL after removing
-      the prefix that lead Apache httpd to the current rules (see the 
-      <directive module="mod_rewrite">RewriteBase</directive>).  The removed prefix
-      always ends with a slash, meaning the matching occurs against a string which
-      never has a leading slash.  A <em>Pattern</em> with <code>^/</code> never
-      matches in per-directory context.</p>
-
+      <p>In <directive module="core">VirtualHost</directive> context, 
+      The <em>Pattern</em> will initially be matched against the part of the
+      URL after the hostname and port, and before the query string (e.g. "/app1/index.html").</p>
+
+      <p>In <directive module="core">Directory</directive> and htaccess context,
+      the <em>Pattern</em> will initially be matched against the  
+      <em>filesystem</em> path, after removing the prefix that lead the server
+      to the current <directive>RewriteRule</directive> (e.g. "app1/index.html" 
+      or "index.html" depending on where the directives are defined).</p>
+       
       <p>If you wish to match against the hostname, port, or query string, use a
       <directive module="mod_rewrite">RewriteCond</directive> with the
       <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
-      <code>%{QUERY_STRING}</code> variables respectively. If you wish to 
-      match against the full URL-path in a per-directory (htaccess) RewriteRule, 
-      use the <code>%{REQUEST_URI}</code> variable.</p>
+      <code>%{QUERY_STRING}</code> variables respectively.</p>
+
+</note>
+
+<note><title>Per-directory Rewrites</title>
+<ul>
+<li>The rewrite engine may be used in <a
+href="../howto/htaccess.html">.htaccess</a> files in <directive type="section"
+module="core">Directory</directive> sections, with some additional
+complexity.</li>
+
+<li>To enable the rewrite engine in this context, you need to set
+"<code>RewriteEngine On</code>" <strong>and</strong>
+"<code>Options FollowSymLinks</code>" must be enabled. If your
+administrator has disabled override of <code>FollowSymLinks</code> for
+a user's directory, then you cannot use the rewrite engine. This
+restriction is required for security reasons.</li>
 
+<li>When using the rewrite engine in <code>.htaccess</code> files the
+per-directory prefix (which always is the same for a specific
+directory) is automatically <em>removed</em> for the RewriteRule pattern matching
+and automatically <em>added</em> after any relative (not starting with a
+slash or protocol name) substitution encounters the end of a rule set.  
+See the <directive module="mod_rewrite">RewriteBase</directive> 
+directive for more information regarding what prefix will be added back to 
+relative substutions.</li>
+
+<li> If you wish to match against the full URL-path in a per-directory 
+(htaccess) RewriteRule, use the <code>%{REQUEST_URI}</code> variable in
+a <directive>RewriteCond</directive>.</li>
+
+<li>The removed prefix always ends with a slash, meaning the matching occurs against a string which
+<em>never</em> has a leading slash.  Therefore, A <em>Pattern</em> with <code>^/</code> never
+matches in per-directory context.</li>
+
+<li>Although rewrite rules are syntactically permitted in <directive
+type="section" module="core">Location</directive> and <directive
+type="section" module="core">Files</directive> sections, this
+should never be necessary and is unsupported.</li>
+</ul>
 </note>
 
       <p>For some hints on <glossary ref="regex">regular
@@ -1171,44 +1206,6 @@ flag is used on the <directive module="m
 directive.</p>
 </note>
 
-<note><title>Per-directory Rewrites</title>
-
-<p>The rewrite engine may be used in <a
-href="../howto/htaccess.html">.htaccess</a> files.  To enable the
-rewrite engine for these files you need to set
-"<code>RewriteEngine On</code>" <strong>and</strong>
-"<code>Options FollowSymLinks</code>" must be enabled. If your
-administrator has disabled override of <code>FollowSymLinks</code> for
-a user's directory, then you cannot use the rewrite engine. This
-restriction is required for security reasons.</p>
-
-<p>When using the rewrite engine in <code>.htaccess</code> files the
-per-directory prefix (which always is the same for a specific
-directory) is automatically <em>removed</em> for the pattern matching
-and automatically <em>added</em> after the substitution has been
-done. This feature is essential for many sorts of rewriting; without
-this, you would always have to match the parent directory, which is
-not always possible.  There is one exception: If a substitution string
-starts with <code>http://</code>, then the directory prefix will
-<strong>not</strong> be added, and an external redirect (or proxy
-throughput, if using flag <strong>P</strong>) is forced.  See the
-<directive module="mod_rewrite">RewriteBase</directive> directive for
-more information.</p>
-
-<p>The rewrite engine may also be used in <directive type="section"
-module="core">Directory</directive> sections with the same
-prefix-matching rules as would be applied to <code>.htaccess</code>
-files.  It is usually simpler, however, to avoid the prefix substitution
-complication by putting the rewrite rules in the main server or
-virtual host context, rather than in a <directive type="section"
-module="core">Directory</directive> section.</p>
-
-<p>Although rewrite rules are syntactically permitted in <directive
-type="section" module="core">Location</directive> and <directive
-type="section" module="core">Files</directive> sections, this
-should never be necessary and is unsupported.</p>
-
-</note>
 
      <p>Here are all possible substitution combinations and their
       meanings:</p>