svn commit: r890440 - in /httpd/httpd/branches/2.2.x/docs/manual: glossary.xml mod/mod_alias.xml

[po...@apache.org]

Author: poirier
Date: Mon Dec 14 19:02:20 2009
New Revision: 890440

URL: http://svn.apache.org/viewvc?rev=890440&view=rev
Log:
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.

Modified:
    httpd/httpd/branches/2.2.x/docs/manual/glossary.xml
    httpd/httpd/branches/2.2.x/docs/manual/mod/mod_alias.xml

Modified: httpd/httpd/branches/2.2.x/docs/manual/glossary.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/glossary.xml?rev=890440&r1=890439&r2=890440&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/glossary.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/glossary.xml Mon Dec 14 19:02:20 2009
@@ -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>

Modified: httpd/httpd/branches/2.2.x/docs/manual/mod/mod_alias.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/mod/mod_alias.xml?rev=890440&r1=890439&r2=890440&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/mod/mod_alias.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/mod/mod_alias.xml Mon Dec 14 19:02:20 2009
@@ -180,13 +180,65 @@
       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 @@
     <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>