From cbf164a6c55c6200a5618a485ab68be63a23fb62 Mon Sep 17 00:00:00 2001
From: Rich Bowen <rbowen@apache.org>
Date: Mon, 15 Jun 2026 19:14:34 +0000
Subject: [PATCH] Sync trunk mod_rewrite doc with enhancements to 2.4

At some point, I made an update to the 2.4 doc and didn't make it in
trunk. This improves the "what gets matched" and "per-directory" bits of
the RewriteRule doc.


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

diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml
index a06cdf7ffa..e0cb272f07 100644
--- a/docs/manual/mod/mod_rewrite.xml
+++ b/docs/manual/mod/mod_rewrite.xml
@@ -1168,24 +1168,104 @@ RewriteRule  "^/$"                 "/homepage.std.html"     [L]
 
 <note><title><a id="what_is_matched" name="what_is_matched">What is matched?</a></title>
 
-<p>
-The <em>Pattern</em> is matched against the %-decoded URL-path
-(in server context) or the directory-relative path (in
-<glossary ref="perdirectory">per-directory context</glossary>).
-See <a href="../rewrite/intro.html#rewriterule">RewriteRule
-Basics</a> for details on what the pattern is matched against
-in each context.
-</p>
+<ul>
+      <li><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").
+      This is the (%-decoded) <a href="directive-dict.html#Syntax">URL-path</a>.</p></li>
+
+      <li><p>In <glossary ref="perdirectory">per-directory context</glossary>
+      (<directive module="core">Directory</directive> and .htaccess),
+      the <em>Pattern</em> is matched against only a partial path, for example a request
+      of "/app1/index.html" may result in comparison against "app1/index.html" 
+      or "index.html" depending on the directory-path for which the
+      <directive>RewriteRule</directive> applies.</p>
+
+      <p>The directory-path to which the rule applies is stripped from the currently mapped
+      filesystem path before comparison (up to and including a trailing slash). 
+      The net result of this <glossary ref="perdirectory">per-directory</glossary> prefix stripping is that rules in
+      this context only match against the portion of the currently mapped filesystem path 
+      "below" the directory-path to which the rule applies.</p>
+
+      <p>Directives such as <directive module="core"
+      >DocumentRoot</directive> and <directive module="mod_alias">Alias</directive>, or even the 
+      result of previous <directive>RewriteRule</directive> substitutions, determine
+      the currently mapped filesystem path.  
+      </p>
+      </li>
+
+      <li><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></li>
+</ul>
 </note>
 
 <note><title><glossary ref="perdirectory">Per-directory</glossary> Rewrites</title>
-<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>
+<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>
 </note>
 
       <p>For information on <glossary ref="regex">regular
-- 
2.47.3