From: Daniel Earl Poirier <poirier@apache.org>
Date: Mon, 14 Dec 2009 19:02:20 +0000 (+0000)
Subject: Expand mod_alias documentation.
X-Git-Tag: 2.2.15~141
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=047bd10e009f2b43c3f161e11f5ca402c8d5ae77;p=thirdparty%2Fapache%2Fhttpd.git

Expand mod_alias documentation.
Add link from glossary entry for regular expressions to the wikipedia entry,
which seems to be a good reference for PCRE's flavor of regular expression syntax.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x@890440 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/glossary.xml b/docs/manual/glossary.xml
index c85d817483d..d6d842a84f2 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 bb2c64be2fe..83938c17954 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>
 
@@ -426,6 +478,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>