Consolidate per-directory rewrite notes: remove duplication between mod_rewrite.xml...

The large "Per-directory Rewrites" note block in mod_rewrite.xml
duplicated content already covered (and better explained) in
rewrite/htaccess.xml. Replace it with a short link to the guide.

Migrate the useful tips that were unique to that block into
rewrite/htaccess.xml:
- ^/ never matches in per-directory context (path-stripping section)
- Use %{REQUEST_URI} to match the full URL-path, with example
- <Location>/<Files> are unsupported contexts (new section)
- <If> follows directory context rules (new section)

Part of: https://bz.apache.org/bugzilla/show_bug.cgi?id=70045

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

diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml
index 44f5de8acbbb2c28d99b58f588045657525ca4a0..32769edd37869e48de012d5c66559b41dfeb43ae 100644 (file)
--- a/docs/manual/mod/mod_rewrite.xml
+++ b/docs/manual/mod/mod_rewrite.xml
@@ -1132,70 +1132,13 @@ RewriteRule  "^/$"                 "/homepage.std.html"     [L]
 </note>
 
 <note><title><glossary ref="perdirectory">Per-directory</glossary> Rewrites</title>
-<ul>
-<li>The rewrite engine may be used in <a
-href="../howto/htaccess.html">.htaccess</a> files and 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>
-at least one of the <code>FollowSymLinks</code> or
-<code>SymLinksIfOwnerMatch</code>
-<directive module="core">Options</directive> must be enabled. Note
-that these options cannot be set in a distributed configuration file
-(<code>.htaccess</code>) unless
-<directive module="core">AllowOverride</directive> permits it
-in the server configuration.</li>
-
-<li>See the <directive module="mod_rewrite">RewriteBase</directive>
-directive for more information regarding what prefix will be added back to
-relative substitutions.</li>
-
-<li> If you wish to match against the full URL-path in a 
-<glossary ref="perdirectory">per-directory</glossary> context
-RewriteRule, use the <code>%{REQUEST_URI}</code> variable in
-a <directive module="mod_rewrite">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 <glossary ref="perdirectory">per-directory</glossary> 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
-(including their regular expression counterparts), this
-should never be necessary and is unsupported. A likely feature
-to break in these contexts is relative substitutions.</li>
-
-<li>The <directive module="core">If</directive> blocks
-follow the rules of the <em>directory</em> context.</li>
-
-<li>By default, mod_rewrite overrides rules when <a href="../sections.html#merging">
-merging sections</a> belonging to the same context. The <directive
-module="mod_rewrite">RewriteOptions</directive> directive can change this behavior,
-for example using the <em>Inherit</em> setting.</li>
-
-<li>The <directive module="mod_rewrite">RewriteOptions</directive> also regulates the
-behavior of sections that are stated at the same nesting level of the configuration. In the
-following example, by default only the RewriteRules stated in the second 
-<directive module="core">If</directive> block
-are considered, since the first ones are overridden. Using <directive
-module="mod_rewrite">RewriteOptions</directive> Inherit forces mod_rewrite to merge the two
-sections and consider both set of statements, rather than only the last one.</li>
-</ul>
-<example>
-<highlight language="config">
-&lt;If "true"&gt;
-  # Without RewriteOptions Inherit, this rule is overridden by the next
-  # section and no redirect will happen for URIs containing 'foo'
-  RewriteRule foo http://example.com/foo [R]
-&lt;/If&gt;
-&lt;If "true"&gt;
-  RewriteRule bar http://example.com/bar [R]
-&lt;/If&gt;
-</highlight>
-</example>
+<p>
+Using rewrite rules in <glossary ref="perdirectory">per-directory
+context</glossary> requires special attention to how patterns are
+matched and how rule inheritance works. See the
+<a href="../rewrite/htaccess.html">Per-directory Rewrites</a>
+guide for complete details.
+</p>
 </note>
 
       <p>For information on <glossary ref="regex">regular

diff --git a/docs/manual/rewrite/htaccess.xml b/docs/manual/rewrite/htaccess.xml
index 2e42ab9bc90cb67b728c891fd4b74df41b078721..02ddd8834007a3745b99699e3a71ca35e2d77ca3 100644 (file)
--- a/docs/manual/rewrite/htaccess.xml
+++ b/docs/manual/rewrite/htaccess.xml
@@ -131,6 +131,24 @@ determines what URL-path prefix is prepended. This subrequest
 mechanism is also why rules can loop — see
 <a href="#loops">below</a>.</p>
 
+
+<p>Because the directory prefix (including the trailing
+slash) is stripped before matching, patterns in
+<glossary ref="perdirectory">per-directory context</glossary>
+will <em>never</em> match a leading slash. A pattern
+beginning with <code>^/</code> will never match in this
+context.</p>
+
+<p>If you need to match against the full original
+URL-path (including the directory prefix), use
+<code>%{REQUEST_URI}</code> in a
+<directive module="mod_rewrite">RewriteCond</directive>:</p>
+
+<highlight language="config">
+RewriteCond "%{REQUEST_URI}" "^/admin/"
+RewriteRule "^.*$" "-" [F]
+</highlight>
+
 </section>
 
 <section id="rewritebase"><title>When you need RewriteBase</title>
@@ -279,6 +297,24 @@ would be prohibitively expensive to repeat each time.</p>
 
 </section>
 
+<section id="context-restrictions"><title>Which contexts support rewrite rules?</title>
+
+<p>Rewrite rules are supported in
+<glossary ref="perdirectory">per-directory context</glossary>
+(<a href="../howto/htaccess.html">.htaccess</a> files,
+<directive module="core" type="section">Directory</directive>, and
+<directive module="core" type="section">If</directive> blocks).</p>
+
+<p>Although rewrite rules are syntactically permitted in
+<directive module="core" type="section">Location</directive>
+and <directive module="core" type="section">Files</directive>
+sections (including their regex counterparts), this is
+unsupported and should never be necessary. Relative
+substitutions, in particular, are likely to break in
+these contexts.</p>
+
+</section>
+
 <section id="inheritance"><title>Rule inheritance with RewriteOptions</title>
 
 <p>By default, <module>mod_rewrite</module> rules are <strong>not