From 8cd7ce41fc82194368182efe2bcfea122c8a03ab Mon Sep 17 00:00:00 2001
From: Daniel Earl Poirier <poirier@apache.org>
Date: Mon, 14 Dec 2009 18:50:30 +0000
Subject: [PATCH] Expand on mod_alias documentation. Add a link from the
 glossary entry on regular expressions to the wikipedia page that seems to be
 a good reference for the syntax of PCRE's flavor of regular expressions.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@890436 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/glossary.xml      |  4 +-
 docs/manual/mod/mod_alias.xml | 84 ++++++++++++++++++++++++++++++++++-
 2 files changed, 86 insertions(+), 2 deletions(-)

diff --git a/docs/manual/glossary.xml b/docs/manual/glossary.xml
index c85d817483..d6d842a84f 100644
--- a/docs/manual/glossary.xml
+++ b/docs/manual/glossary.xml
@@ -382,7 +382,9 @@
       - for example, all .gif and .jpg files under any "images" directory could
       be written as "<code>/images/.*(jpg|gif)$</code>".  Apache uses Perl
       Compatible Regular Expressions provided by the <a
-      href="http://www.pcre.org/">PCRE</a> library.
+      href="http://www.pcre.org/">PCRE</a> library.  You can find more documentation
+      about PCRE's regular expression syntax at that site, or at
+      <a href="http://en.wikipedia.org/wiki/PCRE">Wikipedia</a>.
     </dd>
 
     <dt><a name="reverseproxy" id="reverseproxy">Reverse Proxy</a></dt>
diff --git a/docs/manual/mod/mod_alias.xml b/docs/manual/mod/mod_alias.xml
index e58633722c..9e4717d445 100644
--- a/docs/manual/mod/mod_alias.xml
+++ b/docs/manual/mod/mod_alias.xml
@@ -180,13 +180,65 @@ expressions</description>
       AliasMatch ^/icons(.*) /usr/local/apache/icons$1
     </example>
 
-    <p>It is also possible to construct an alias with case-insensitive
+    <p>The full range of <glossary ref="regex">regular expression</glossary>
+    power is available.  For example,
+    it is possible to construct an alias with case-insensitive
     matching of the url-path:</p>
 
     <example>
       AliasMatch (?i)^/image(.*) /ftp/pub/image$1
     </example>
 
+    <p>One subtle difference
+    between <directive module="mod_alias">Alias</directive>
+    and <directive module="mod_alias">AliasMatch</directive> is
+    that <directive module="mod_alias">Alias</directive> will
+    automatically copy any additional part of the URI, past the part
+    that matched, onto the end of the file path on the right side,
+    while <directive module="mod_alias">AliasMatch</directive> will
+    not.  This means that in almost all cases, you will want the
+    regular expression to match the entire request URI from beginning
+    to end, and to use substitution on the right side.</p>
+
+    <p>In other words, just changing 
+    <directive module="mod_alias">Alias</directive> to
+    <directive module="mod_alias">AliasMatch</directive> will not
+    have the same effect.  At a minimum, you need to
+    add <code>^</code> to the beginning of the regular expression
+    and add <code>(.*)$</code> to the end, and add <code>$1</code> to
+    the end of the replacement.</p>
+
+    <p>For example, suppose you want to replace this with AliasMatch:</p>
+
+    <example>
+      Alias /image/ /ftp/pub/image/
+    </example>
+
+    <p>This is NOT equivalent - don't do this!  This will send all
+    requests that have /image/ anywhere in them to /ftp/pub/image/:</p>
+
+    <example>
+      AliasMatch /image/ /ftp/pub/image/
+    </example>
+
+    <p>This is what you need to get the same effect:</p>
+
+    <example>
+      AliasMatch ^/image/(.*)$ /ftp/pub/image/$1
+    </example>
+
+    <p>Of course, there's no point in
+    using <directive module="mod_alias">AliasMatch</directive>
+    where <directive module="mod_alias">Alias</directive> would
+    work.  <directive module="mod_alias">AliasMatch</directive> lets
+    you do more complicated things.  For example, you could
+    serve different kinds of files from different directories:</p>
+
+    <example>
+      AliasMatch ^/image/(.*)\.jpg$ /files/jpg.images/$1.jpg<br/>
+      AliasMatch ^/image/(.*)\.gif$ /files/gif.images/$1.gif
+    </example>
+
 </usage>
 </directivesynopsis>
 
@@ -307,6 +359,17 @@ of the current URL</description>
     <example>
       RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
     </example>
+
+    <p>The considerations related to the difference between
+    <directive module="mod_alias">Alias</directive> and
+    <directive module="mod_alias">AliasMatch</directive>
+    also apply to the difference between
+    <directive module="mod_alias">Redirect</directive> and
+    <directive module="mod_alias">RedirectMatch</directive>.
+    See <directive module="mod_alias">AliasMatch</directive> for
+    details.</p>
+
+
 </usage>
 </directivesynopsis>
 
@@ -443,6 +506,25 @@ and designates the target as a CGI script</description>
     <example>
       ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
     </example>
+
+    <p>As for AliasMatch, the full range of <glossary ref="rexex">regular
+    expression</glossary> power is available.
+    For example, it is possible to construct an alias with case-insensitive
+    matching of the url-path:</p>
+
+    <example>
+      ScriptAliasMatch (?i)^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
+    </example>
+
+    <p>The considerations related to the difference between
+    <directive module="mod_alias">Alias</directive> and
+    <directive module="mod_alias">AliasMatch</directive>
+    also apply to the difference between
+    <directive module="mod_alias">ScriptAlias</directive> and
+    <directive module="mod_alias">ScriptAliasMatch</directive>.
+    See <directive module="mod_alias">AliasMatch</directive> for
+    details.</p>
+
 </usage>
 </directivesynopsis>
 
-- 
2.40.0