From: Rich Bowen <rbowen@apache.org>
Date: Sat, 2 May 2026 20:24:21 +0000 (+0000)
Subject: rewrite guide: add Discussion sections to recipes where useful - alternatives, cross... 
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bd4ebbe66aa25b6d6ea95f5781d52fbbf81a6cc2;p=thirdparty%2Fapache%2Fhttpd.git

rewrite guide: add Discussion sections to recipes where useful - alternatives, cross-references, caveats (BZ 58892, step 15)

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

diff --git a/docs/manual/rewrite/remapping.xml b/docs/manual/rewrite/remapping.xml
index 3322033d41..098a2a2353 100644
--- a/docs/manual/rewrite/remapping.xml
+++ b/docs/manual/rewrite/remapping.xml
@@ -68,7 +68,7 @@ RewriteEngine  on
 RewriteRule    "^<strong>/foo</strong>\.html$"  "<strong>/bar</strong>.html" [PT]
 </highlight>
     </dd>
-  </dl>
+</dl>
 
 </section>
 
@@ -377,6 +377,15 @@ RedirectMatch "^/docs/(.*)" "http://new.example.com/docs/$1"
 Redirect "/docs/" "http://new.example.com/docs/"
 </highlight>
     </dd>
+
+    <dt>Discussion:</dt>
+
+    <dd>
+      <p>For simple redirections to another server, the
+      <directive module="mod_alias">Redirect</directive> or
+      <directive module="mod_alias">RedirectMatch</directive> directives
+      are preferred, as they are simpler and more efficient.</p>
+    </dd>
   </dl>
 
 </section>
@@ -530,6 +539,18 @@ RewriteRule "^/?(.*)"      "http://www.%{HTTP_HOST}/$1" [L,R,NE]
     <p>These rulesets will work either in your main server configuration
     file, or in a <code>.htaccess</code> file placed in the <directive
     module="core">DocumentRoot</directive> of the server.</p>
+
+    <dt>Discussion:</dt>
+
+    <dd>
+      <p>If you have access to the server configuration, a
+      <directive module="mod_alias">Redirect</directive> in a dedicated
+      <directive module="core" type="section">VirtualHost</directive>
+      is the cleanest approach. Use the
+      <directive module="core" type="section">If</directive> directive
+      as a middle ground, and <module>mod_rewrite</module> only if you
+      are limited to <code>.htaccess</code>.</p>
+    </dd>
         </dd>
       </dl>
 
@@ -574,6 +595,15 @@ RewriteRule "^(.+)" "%{DOCUMENT_ROOT}/<strong>dir2</strong>/$1"  [L]
 RewriteRule "^"     "-"                                          [PT]
 </highlight>
     </dd>
+
+    <dt>Discussion:</dt>
+
+    <dd>
+      <p>This is useful during migrations when content is being moved
+      between directories. For permanent setups, consider using
+      <directive module="mod_alias">Alias</directive> or symbolic links
+      instead.</p>
+    </dd>
   </dl>
 
 </section>
@@ -715,6 +745,15 @@ file, as well as in a &lt;Directory&gt; block.</p>
 
 </dd>
 
+<dt>Discussion:</dt>
+
+<dd>
+<p>The <directive module="mod_dir">FallbackResource</directive> directive
+is almost always the better choice for this use case. See the
+<a href="avoid.html#fallback-resource">When not to use mod_rewrite</a>
+document for a simpler one-line alternative.</p>
+</dd>
+
 </dl>
 
 </section>
@@ -777,6 +816,15 @@ RewriteRule "^/?path/([^/]+)/([^/]+)" "/path?$1=$2" [PT]
 
 </dd>
 
+<dt>Discussion:</dt>
+
+<dd>
+<p>See also the <a href="flags.html#flag_qsa">[QSA]</a> and
+<a href="flags.html#flag_qsd">[QSD]</a> flags, which control whether
+the original query string is appended to or discarded from the
+substitution.</p>
+</dd>
+
 </dl>
 </section>
 
@@ -808,6 +856,15 @@ RewriteEngine on
 RewriteRule   "^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*)"  "/home/<strong>$2</strong>/$1/public_html$3"
 </highlight>
     </dd>
+
+    <dt>Discussion:</dt>
+
+    <dd>
+      <p>This technique is primarily useful for large hosting
+      environments with thousands of users. For most sites,
+      <module>mod_userdir</module> handles tilde-based user URLs
+      without requiring <module>mod_rewrite</module>.</p>
+    </dd>
   </dl>
 
 </section>
@@ -883,6 +940,15 @@ RewriteRule   "^foo\.html$"             "foo.night.html"
       content dynamically, and customizing it based on the time of day.</note>
 
     </dd>
+
+    <dt>Discussion:</dt>
+
+    <dd>
+      <p>Serving dynamic content through your application is almost
+      always a better approach. Caching by browsers, proxies, and
+      <module>mod_cache</module> makes time-based rewriting unreliable
+      in practice.</p>
+    </dd>
   </dl>
 
 </section>
@@ -926,6 +992,16 @@ RewriteRule "^(.+)\.html$"     "/regenerate_page.cgi"   [PT,L]
     from the document directory, and they will then be regenerated the
     next time they are requested.</p>
     </dd>
+
+    <dt>Discussion:</dt>
+
+    <dd>
+      <p>Modern approaches such as <module>mod_cache</module>, CDN
+      caching layers, or application-level caching provide more robust
+      and controllable solutions for serving pre-generated static
+      content. The <code>-U</code> subrequest test used here also
+      carries a performance cost on every request.</p>
+    </dd>
   </dl>
 
 </section>
diff --git a/docs/manual/rewrite/rewritemap.xml b/docs/manual/rewrite/rewritemap.xml
index 0f2221cb3c..2821e5547c 100644
--- a/docs/manual/rewrite/rewritemap.xml
+++ b/docs/manual/rewrite/rewritemap.xml
@@ -515,6 +515,16 @@ RewriteMap    users-to-hosts      "txt:/path/to/map.users-to-hosts"
 RewriteRule   "^/u/([^/]+)/?(.*)" "http://${users-to-hosts:$1|server0}/u/$1/$2"
 </highlight>
     </dd>
+
+    <dt>Discussion:</dt>
+
+    <dd>
+      <p>For distributing requests across backend servers,
+      <module>mod_proxy_balancer</module> provides a more robust and
+      configurable approach, with support for health checking, load
+      weighting, and session stickiness. The <code>txt:</code> map
+      approach shown here is simpler but lacks these features.</p>
+    </dd>
   </dl>
 
   <p>See the <directive module="mod_rewrite">RewriteMap</directive>