add an early note about the Pattern in a rewriterule behaving

counterintuitively in per-directory context. (lots of mysterious no-op
rulesets due to ^/ in htaccess)

Tweak QSA text.

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

diff --git a/docs/manual/mod/mod_rewrite.html.en b/docs/manual/mod/mod_rewrite.html.en
index 971ae24393ee14b2b56d4a95dbc7ff302d0c2037..c5ca76b8124b8df26b536499139cc36fcc80b6fb 100644 (file)
--- a/docs/manual/mod/mod_rewrite.html.en
+++ b/docs/manual/mod/mod_rewrite.html.en
@@ -947,11 +947,23 @@ later</td></tr>
 
 <div class="note"><h3>What is matched?</h3>
       <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. If you wish
-      to match against the hostname, port, or query string, use a
+      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 to the current rules (see the 
+      <code class="directive"><a href="#rewritebase">RewriteBase</a></code>).  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>If you wish to match against the hostname, port, or query string, use a
       <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
       <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
-      <code>%{QUERY_STRING}</code> variables respectively.</p>
+      <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>
+
 </div>
 
       <p>For some hints on <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
@@ -1325,10 +1337,11 @@ cannot use <code>$N</code> in the substitution string!
         <dt>'<code>qsappend|QSA</code>'
         (query string
         append)</dt><dd>
-        This flag forces the rewrite engine to append a query
-        string part of the substitution string to the existing string,
+        This flag forces the rewrite engine to append the query
+        string part of the substitution string to the existing query string,
         instead of replacing it. Use this when you want to add more
-        data to the query string via a rewrite rule.</dd>
+        data to the query string via a rewrite rule. This rule has no net effect
+        unless your substitution explicitly provides a new query string.</dd>
 
         <dt>'<code>redirect|R</code>
           [=<em>code</em>]' (force <a id="redirect" name="redirect">redirect</a>)</dt><dd>

diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml
index f4bd3b7ebe29bf57e70e1d4e51dce89cbb14f5b0..ce368f676181b9126ee0876db655a0b8e34661e4 100644 (file)
--- a/docs/manual/mod/mod_rewrite.xml
+++ b/docs/manual/mod/mod_rewrite.xml
@@ -959,11 +959,23 @@ RewriteRule  ^/$                 /homepage.std.html  [L]
 
 <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. If you wish
-      to match against the hostname, port, or query string, use a
+      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 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>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.</p>
+      <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>
+
 </note>
 
       <p>For some hints on <glossary ref="regex">regular
@@ -1342,10 +1354,11 @@ cannot use <code>$N</code> in the substitution string!
         <dt>'<code>qsappend|QSA</code>'
         (query string
         append)</dt><dd>
-        This flag forces the rewrite engine to append a query
-        string part of the substitution string to the existing string,
+        This flag forces the rewrite engine to append the query
+        string part of the substitution string to the existing query string,
         instead of replacing it. Use this when you want to add more
-        data to the query string via a rewrite rule.</dd>
+        data to the query string via a rewrite rule. This rule has no net effect
+        unless your substitution explicitly provides a new query string.</dd>
 
         <dt>'<code>redirect|R</code>
           [=<em>code</em>]' (force <a id="redirect"