Make it clear what is meant by per-directory rewrites

and specify the rewrites in <Location> is unsupported.
(The same is probably true for <Files>, but I'd have to
think about that a little more.)

PR: 39843

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

diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml
index 61d05e2829f5644f78929c8fc33e6c8ac68fe596..672630e9e2ce7a5c000024dc4d8d91f26aed8137 100644 (file)
--- a/docs/manual/mod/mod_rewrite.xml
+++ b/docs/manual/mod/mod_rewrite.xml
@@ -1423,34 +1423,42 @@ cannot use <code>$N</code> in the substitution string!
         </li>
       </ul>
 
-<note><title>Note: Enabling rewrites in per-directory context</title>
- To enable the rewrite engine
-          for per-directory configuration files you need to set
-          ``<code>RewriteEngine On</code>'' in these files
-          <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.
-</note>
-
-<note><title>Note: Pattern matching in per-directory context</title> 
-       Never forget that <em>Pattern</em> is
-applied to a complete URL in per-server configuration
-files. <strong>However, in per-directory configuration files, the
+<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.</strong> 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.
-
-            <p>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!</p>
+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> sections, this
+should never be necessary and is unsupported.</p>
+
 </note>
 
 <note><title>Note: Substitution of Absolute URLs</title>