httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sl...@apache.org
Subject svn commit: r562107 - in /httpd/httpd/branches/2.2.x/docs/manual/mod: mod_rewrite.html.en mod_rewrite.xml
Date Thu, 02 Aug 2007 13:42:08 GMT
Author: slive
Date: Thu Aug  2 06:42:07 2007
New Revision: 562107

URL: http://svn.apache.org/viewvc?view=rev&rev=562107
Log:
Merge r561840, r561902, r561906, r561918 from trunk:

Some updates to the RewriteRule docs, mostly focusing on clearly
describing what can be in the substitution string. Included is
a description of how mod_rewrite decides whether to treat the
substitution as a file-system or URL-path.

PR: 22529


R flag to mod_rewrite can set any status code

PR: 25917


Note the L doesn't necessarily mean no more rewriting.

PR: 40004


Change the flag list to a <dl> instead of <ul>. Seems much more readable to me.


Modified:
    httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.html.en
    httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.xml

Modified: httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.html.en?view=diff&rev=562107&r1=562106&r2=562107
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.html.en (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.html.en Thu Aug  2 06:42:07 2007
@@ -1042,12 +1042,11 @@
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
-      <em>Pattern</em> <em>Substitution</em></code></td></tr>
+      <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</code></td></tr>
 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The cookie-flag is available in Apache 2.0.40 and later.</td></tr>
 </table>
       <p>The <code class="directive">RewriteRule</code> directive is the real
       rewriting workhorse. The directive can occur more than once, 
@@ -1062,6 +1061,17 @@
       subsequent patterns are applied to the output of the last matched
       RewriteRule.</p>
 
+<div class="note"><h3>What is matched?</h3>
+      <p>The <em>Pattern</em> will initially be matched against the part of the
+      URL after the hostname and port, and before the query string. If you wish
+      to match against the hostname, port, or query string, use a
+      <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
+      <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
+      <code>%{QUERY_STRING}</code> variables respectively.</p>
+</div>
+
+
+
       <p>Some hints on the syntax of <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular 
       expressions</a>:</p>
 
@@ -1093,7 +1103,7 @@
 </pre></div>
 
       <p>For more information about regular expressions, have a look at the
-      perl regular expression manpage ("<a href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
+      perl regular expression manpage ("<a href="http://www.perldoc.com/perlre.html">perldoc
       perlre</a>"). If you are interested in more detailed
       information about regular expressions and their variants
       (POSIX regex etc.) the following book is dedicated to this topic:</p>
@@ -1121,10 +1131,54 @@
 cannot use <code>$N</code> in the substitution string!
 </div>
 
-      <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
-      rewrite rule is the string which is substituted for (or
-      replaces) the original URL which <em>Pattern</em>
-      matched. In addition to plain text, it can include</p>
+      <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
+      rewrite rule is the string that replaces the original URL-path that
+      was matched by <em>Pattern</em>.  The <em>Substitution</em> may
+      be a:</p>
+
+      <dl>
+
+        <dt>file-system path</dt>
+
+        <dd>Designates the location on the file-system of the resource
+        to be delivered to the client.</dd>
+
+        <dt>URL-path</dt> 
+
+        <dd>A <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
+        resource to be served. Note that <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+        tries to guess whether you have specified a file-system path
+        or a URL-path by checking to see if the first segement of the
+        path exists at the root of the file-system. For example, if
+        you specify a <em>Substitution</em> string of
+        <code>/www/file.html</code>, then this will be treated as a
+        URL-path <em>unless</em> a directory named <code>www</code>
+        exists at the root or your file-system, in which case it will
+        be treated as a file-system path. If you wish other
+        URL-mapping directives (such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>) to be applied to the
+        resulting URL-path, use the <code>[PT]</code> flag as
+        described below.</dd>
+
+        <dt>Absolute URL</dt>
+
+        <dd>If an absolute URL is specified,
+        <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> checks to see whether the
+        hostname matches the current host. If it does, the scheme and
+        hostname are stripped out and the resulting path is treated as
+        a URL-path. Otherwise, an external redirect is performed for
+        the given URL. To force an external redirect back to the
+        current host, see the <code>[R]</code> flag below.</dd>
+
+        <dt><code>-</code> (dash)</dt>
+
+        <dd>A dash indicates that no substitution should be performed
+        (the existing path is passed through untouched). This is used
+        when a flag (see below) needs to be applied without changing
+        the path.</dd>
+
+      </dl>
+
+      <p>In addition to plain text, the <em>Substition</em> string can include</p>
 
       <ol>
         <li>back-references (<code>$N</code>) to the RewriteRule
@@ -1139,6 +1193,7 @@
         <li><a href="#mapfunc">mapping-function</a> calls
         (<code>${mapname:key|default}</code>)</li>
       </ol>
+
       <p>Back-references are identifiers of the form 
 	      <code>$</code><strong>N</strong>
       (<strong>N</strong>=0..9), which will be replaced
@@ -1158,24 +1213,27 @@
       or it is explicitly terminated by a
       <code><strong>L</strong></code> flag.</p>
 
-      <p>There is a special substitution string named
-      '<code>-</code>' which means: <strong>NO
-      substitution</strong>! This is useful in providing
-      rewriting rules which <strong>only</strong> match
-      URLs but do not substitute anything for them. It is commonly used 
-      in conjunction with the <strong>C</strong> (chain) flag, in order 
-      to apply more than one pattern before substitution occurs.</p>
+     <div class="note"><h3>Modifying the Query String</h3>
+      <p>By default, the query string is passed through unchanged. You
+      can, however, create URLs in the substitution string containing
+      a query string part. Simply use a question mark inside the
+      substitution string to indicate that the following text should
+      be re-injected into the query string. When you want to erase an
+      existing query string, end the substitution string with just a
+      question mark. To combine new and old query strings, use the
+      <code>[QSA]</code> flag.</p> 
+     </div>
 
 
-      <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">flags</a> for <em>Substitution</em> by 
+      <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by 
       appending <strong><code>[</code><em>flags</em><code>]</code></strong>
       as the third argument to the <code>RewriteRule</code>
-      directive. <em>Flags</em> is a comma-separated list of any of the
-      following flags: </p>
+      directive. <em>Flags</em> is a comma-separated list, surround by square 
+      brackets, of any of the following flags: </p>
 
-      <ul>
-        <li>'<strong><code>chain|C</code></strong>'
-        (<strong>c</strong>hained with next rule)<br />
+      <dl>
+        <dt>'<code>chain|C</code>'
+        (chained with next rule)</dt><dd>
          This flag chains the current rule with the next rule
         (which itself can be chained with the following rule,
         and so on). This has the following effect: if a rule
@@ -1185,21 +1243,21 @@
         rules are skipped. For instance, it can be used to remove the
         ``<code>.www</code>'' part, inside a per-directory rule set,
         when you let an external redirect happen (where the
-        ``<code>.www</code>'' part should not occur!).</li>
+        ``<code>.www</code>'' part should not occur!).</dd>
 
-        <li>
-		'<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
-        (set <strong>co</strong>okie)<br />
+        <dt>
+		'<code>cookie|CO=</code><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
+        (set cookie)</dt><dd>
         This sets a cookie in the client's browser.  The cookie's name
         is specified by <em>NAME</em> and the value is
         <em>VAL</em>. The <em>domain</em> field is the domain of the
         cookie, such as '.apache.org', the optional <em>lifetime</em>
 	is the lifetime of the cookie in minutes, and the optional 
-	<em>path</em> is the path of the cookie</li>
+	<em>path</em> is the path of the cookie</dd>
 
-        <li>
-        '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
-        (set <strong>e</strong>nvironment variable)<br />
+        <dt>
+        '<code>env|E=</code><em>VAR</em>:<em>VAL</em>'
+        (set environment variable)</dt><dd>
         This forces an environment variable named <em>VAR</em> to
         be set to the value <em>VAL</em>, where <em>VAL</em> can
         contain regexp backreferences (<code>$N</code> and
@@ -1210,67 +1268,69 @@
         var="VAR"--&gt;</code>) or CGI (<code>$ENV{'VAR'}</code>). 
 	You can also dereference the variable in a later RewriteCond pattern, using
         <code>%{ENV:VAR}</code>. Use this to strip 
-        information from URLs, while maintaining a record of that information.</li>
+        information from URLs, while maintaining a record of that information.</dd>
 
-        <li>'<strong><code>forbidden|F</code></strong>' (force URL
-        to be <strong>f</strong>orbidden)<br />
+        <dt>'<code>forbidden|F</code>' (force URL
+        to be forbidden)</dt><dd>
         This forces the current URL to be forbidden - it immediately 
 	sends back a HTTP response of 403 (FORBIDDEN). 
 	Use this flag in conjunction with
         appropriate RewriteConds to conditionally block some
-        URLs.</li>
+        URLs.</dd>
 
-        <li>'<strong><code>gone|G</code></strong>' (force URL to be
-        <strong>g</strong>one)<br />
+        <dt>'<code>gone|G</code>' (force URL to be
+        gone)</dt><dd>
         This forces the current URL to be gone - it
         immediately sends back a HTTP response of 410 (GONE). Use
-        this flag to mark pages which no longer exist as gone.</li>
+        this flag to mark pages which no longer exist as gone.</dd>
 
-        <li>
-        '<strong><code>handler|H</code></strong>=<em>Content-handler</em>'
-        (force Content <strong>h</strong>andler)<br />
+        <dt>
+        '<code>handler|H</code>=<em>Content-handler</em>'
+        (force Content handler)</dt><dd>
          Force the Content-handler of the target file to be
         <em>Content-handler</em>. For instance, this can be used to
         simulate the <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> directive
 	<code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, 
 	which internally forces all files
         inside the mapped directory to have a handler of
-        ``<code>cgi-script</code>''.</li>
+        ``<code>cgi-script</code>''.</dd>
 
-        <li>'<strong><code>last|L</code></strong>'
-        (<strong>l</strong>ast rule)<br />
-        Stop the rewriting process here and don't apply any more
-        rewrite rules. This corresponds to the Perl
-        <code>last</code> command or the <code>break</code> command
-        in C. Use this flag to prevent the currently
-        rewritten URL from being rewritten further by following
-        rules. For example, use it to rewrite the root-path URL
-        ('<code>/</code>') to a real one, <em>e.g.</em>,
-        '<code>/e/www/</code>'.</li>
+        <dt>'<code>last|L</code>'
+        (last rule)</dt><dd> Stop the rewriting process
+        here and don't apply any more rewrite rules. This corresponds
+        to the Perl <code>last</code> command or the
+        <code>break</code> command in C. Use this flag to prevent the
+        currently rewritten URL from being rewritten further by
+        following rules. Remember, however, that if the
+        <code class="directive">RewriteRule</code> generates an internal
+        redirect (which frequently occurs when rewriting in a
+        per-directory context), this will reinject the request and
+        will cause processing to be repeated starting from the first
+        <code class="directive">RewriteRule</code>.</dd>
 
-        <li>'<strong><code>next|N</code></strong>'
-        (<strong>n</strong>ext round)<br />
+        <dt>'<code>next|N</code>'
+        (next round)</dt><dd>
         Re-run the rewriting process (starting again with the
         first rewriting rule). This time, the URL to match is no longer
         the original URL, but rather the URL returned by the last rewriting rule.
         This corresponds to the Perl <code>next</code> command or
         the <code>continue</code> command in C. Use
         this flag to restart the rewriting process -
-        to immediately go to the top of the loop.<br />
+        to immediately go to the top of the loop.
          <strong>Be careful not to create an infinite
-        loop!</strong></li>
+        loop!</strong></dd>
 
-        <li>'<strong><code>nocase|NC</code></strong>'
-        (<strong>n</strong>o <strong>c</strong>ase)<br />
+        <dt>'<code>nocase|NC</code>'
+        (no case)</dt><dd>
         This makes the <em>Pattern</em> case-insensitive,
         ignoring difference between 'A-Z' and
         'a-z' when <em>Pattern</em> is matched against the current
-        URL.</li>
+        URL.</dd>
 
-        <li>
-          '<strong><code>noescape|NE</code></strong>'
-          (<strong>n</strong>o URI <strong>e</strong>scaping of
-          output)<br />
+        <dt>
+          '<code>noescape|NE</code>'
+          (no URI escaping of
+          output)</dt><dd>
           This flag prevents mod_rewrite from applying the usual URI
           escaping rules to the result of a rewrite. Ordinarily,
           special characters (such as '%', '$', ';', and so on)
@@ -1283,13 +1343,13 @@
 </code></p></div>
           which would turn '<code>/foo/zed</code>' into a safe
           request for '<code>/bar?arg=P1=zed</code>'. 
-        </li>
+        </dd>
 
-        <li>
-          '<strong><code>nosubreq|NS</code></strong>'
-          (<strong>n</strong>ot for internal
-          <strong>s</strong>ub-requests)<br />
-          This flag forces the rewriting engine to skip a
+        <dt>
+          '<code>nosubreq|NS</code>'
+          (not for internal
+          sub-requests)</dt><dd>
+          <p>This flag forces the rewriting engine to skip a
           rewriting rule if the current request is an internal
           sub-request. For instance, sub-requests occur internally
           in Apache when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> tries to find out
@@ -1297,17 +1357,17 @@
           (<code>index.xxx</code> files). On sub-requests it is not
           always useful, and can even cause errors, if
           the complete set of rules are applied. Use this flag to
-          exclude some rules.<br />
-          To decide whether or not to use this rule: if you
+          exclude some rules.</p>
+          <p>To decide whether or not to use this rule: if you
           prefix URLs with CGI-scripts, to force them to be
 	  processed by the CGI-script, it's likely that you 
           will run into problems (or significant overhead) on
-          sub-requests. In these cases, use this flag.
-        </li>
+          sub-requests. In these cases, use this flag.</p>
+        </dd>
 
-        <li>
-          '<strong><code>proxy|P</code></strong>' (force
-          <strong>p</strong>roxy)<br />
+        <dt>
+          '<code>proxy|P</code>' (force
+          proxy)</dt><dd>
           This flag forces the substitution part to be internally
 	  sent as a proxy request and immediately (rewrite 
 	  processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You must make
@@ -1322,12 +1382,12 @@
 
           <p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order
           to use this flag.</p>
-        </li>
+        </dd>
 
-        <li>
-          '<strong><code>passthrough|PT</code></strong>'
-          (<strong>p</strong>ass <strong>t</strong>hrough to next
-          handler)<br />
+        <dt>
+          '<code>passthrough|PT</code>'
+          (pass through to next
+          handler)</dt><dd>
            This flag forces the rewrite engine to set the
           <code>uri</code> field of the internal
           <code>request_rec</code> structure to the value of the
@@ -1362,54 +1422,58 @@
           <p>The <code>PT</code> flag implies the <code>L</code> flag:
           rewriting will be stopped in order to pass the request to
           the next phase of processing.</p>
-        </li>
+        </dd>
 
-        <li>'<strong><code>qsappend|QSA</code></strong>'
-        (<strong>q</strong>uery <strong>s</strong>tring
-        <strong>a</strong>ppend)<br />
+        <dt>'<code>qsappend|QSA</code>'
+        (query string
+        append)</dt><dd>
         This flag forces the rewrite engine to append a query
         string part of the substitution string to the existing string,
         instead of replacing it. Use this when you want to add more
-        data to the query string via a rewrite rule.</li>
+        data to the query string via a rewrite rule.</dd>
 
-         <li>'<strong><code>redirect|R</code>
-          [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />
-          Prefix <em>Substitution</em> with
+        <dt>'<code>redirect|R</code>
+          [=<em>code</em>]' (force <a id="redirect" name="redirect">redirect</a>)</dt><dd>
+        <p>Prefix <em>Substitution</em> with
           <code>http://thishost[:thisport]/</code> (which makes the
           new URL a URI) to force a external redirection. If no
           <em>code</em> is given, a HTTP response of 302 (MOVED
-          TEMPORARILY) will be returned. If you want to use other response
-          codes in the range 300-400, simply specify the appropriate number
-          or use one of the following symbolic names:
-          <code>temp</code> (default), <code>permanent</code>,
-          <code>seeother</code>. Use this for rules to
-          canonicalize the URL and return it to the client - to 
-	  translate ``<code>/~</code>'' into
-          ``<code>/u/</code>'', or to always append a slash to
-          <code>/u/</code><em>user</em>, etc.<br />
-          <strong>Note:</strong> When you use this flag, make
-          sure that the substitution field is a valid URL! Otherwise,
-          you will be redirecting to an invalid location. Remember
-          that this flag on its own will only prepend
-          <code>http://thishost[:thisport]/</code> to the URL, and rewriting
-	  will continue. Usually, you will want to stop rewriting at this point,
-	  and redirect immediately. To stop rewriting, you should add 
-	  the 'L' flag.
-        </li>
+          TEMPORARILY) will be returned. If you want to use other
+          response codes, simply specify the appropriate number or use
+          one of the following symbolic names: <code>temp</code>
+          (default), <code>permanent</code>,
+          <code>seeother</code>. Use this for rules to canonicalize
+          the URL and return it to the client - to translate
+          ``<code>/~</code>'' into ``<code>/u/</code>'', or to always
+          append a slash to <code>/u/</code><em>user</em>, etc.<br />
+          <strong>Note:</strong> When you use this flag, make sure
+          that the substitution field is a valid URL! Otherwise, you
+          will be redirecting to an invalid location. Remember that
+          this flag on its own will only prepend
+          <code>http://thishost[:thisport]/</code> to the URL, and
+          rewriting will continue. Usually, you will want to stop
+          rewriting at this point, and redirect immediately. To stop
+          rewriting, you should add the 'L' flag.</p>
+          <p>While this is typically used for redirects, any valid status
+          code can be given here. If the status code is outside the redirect
+          range (300-399), then the <em>Substitution</em> string is dropped
+          and rewriting is stopped as if the <code>L</code> flag was
+          used.</p>
+        </dd>
 
-        <li>'<strong><code>skip|S</code></strong>=<em>num</em>'
-        (<strong>s</strong>kip next rule(s))<br />
+        <dt>'<code>skip|S</code>=<em>num</em>'
+        (skip next rule(s))</dt><dd>
         This flag forces the rewriting engine to skip the next
         <em>num</em> rules in sequence, if the current rule
         matches. Use this to make pseudo if-then-else constructs:
         The last rule of the then-clause becomes
         <code>skip=N</code>, where N is the number of rules in the
         else-clause. (This is <strong>not</strong> the same as the
-        'chain|C' flag!)</li>
+        'chain|C' flag!)</dd>
 
-        <li>
-        '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
-        (force MIME <strong>t</strong>ype)<br />
+        <dt>
+        '<code>type|T</code>=<em>MIME-type</em>'
+        (force MIME type)</dt><dd>
          Force the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> of the target file to be
         <em>MIME-type</em>. This can be used to
         set up the content-type based on some conditions.
@@ -1419,8 +1483,8 @@
         <div class="example"><p><code>
             RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
         </code></p></div>
-        </li>
-      </ul>
+        </dd>
+      </dl>
 
 <div class="note"><h3>Per-directory Rewrites</h3>
  
@@ -1454,38 +1518,6 @@
 <p>Although rewrite rules are syntactically permitted in <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> sections, this
 should never be necessary and is unsupported.</p>
 
-</div>
-
-<div class="note"><h3>Note: Substitution of Absolute URLs</h3>
-          <p>
-          When you prefix a substitution field with
-	  <code>http://thishost[:thisport]</code>, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will automatically strip that
-          out. This auto-reduction on URLs with an implicit 
-          external redirect is most useful in
-          combination with a mapping-function which generates the
-	  hostname part.</p>
-
-          <p><strong>Remember:</strong> An unconditional external
-          redirect to your own server will not work with the prefix
-          <code>http://thishost</code> because of this feature. To
-          achieve such a self-redirect, you have to use the
-          <strong>R</strong>-flag.</p>
-</div>
-
-<div class="note"><h3>What is matched?</h3>
-      <p>The <em>Pattern</em> will initially be matched against the part of the
-      URL after the hostname and port, and before the query string. If you wish
-      to match against the hostname, port, or query string, use a
-      <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
-      <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
-      <code>%{QUERY_STRING}</code> variables respectively.</p>
-      <p>You can, however, create URLs in the substitution string containing a
-      query string part. Simply use a question mark inside the substitution
-      string, to indicate that the following text should be re-injected into the
-      query string. When you want to erase an existing query string,
-      end the substitution string with just a question mark. To
-      combine new and old query strings, use the
-      <code>[QSA]</code> flag.</p>
 </div>
 
      <p>Here are all possible substitution combinations and their

Modified: httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.xml?view=diff&rev=562107&r1=562106&r2=562107
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/mod/mod_rewrite.xml Thu Aug  2 06:42:07 2007
@@ -1055,11 +1055,10 @@
 <name>RewriteRule</name>
 <description>Defines rules for the rewriting engine</description>
 <syntax>RewriteRule
-      <em>Pattern</em> <em>Substitution</em></syntax>
+      <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context><context>.htaccess</context></contextlist>
 <override>FileInfo</override>
-<compatibility>The cookie-flag is available in Apache 2.0.40 and later.</compatibility>
 
 <usage>
       <p>The <directive>RewriteRule</directive> directive is the real
@@ -1075,6 +1074,17 @@
       subsequent patterns are applied to the output of the last matched
       RewriteRule.</p>
 
+<note><title>What is matched?</title>
+      <p>The <em>Pattern</em> will initially be matched against the part of the
+      URL after the hostname and port, and before the query string. 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>
+</note>
+
+
+
       <p>Some hints on the syntax of <glossary ref="regex">regular 
       expressions</glossary>:</p>
 
@@ -1107,7 +1117,7 @@
 
       <p>For more information about regular expressions, have a look at the
       perl regular expression manpage ("<a
-      href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
+      href="http://www.perldoc.com/perlre.html">perldoc
       perlre</a>"). If you are interested in more detailed
       information about regular expressions and their variants
       (POSIX regex etc.) the following book is dedicated to this topic:</p>
@@ -1135,10 +1145,56 @@
 cannot use <code>$N</code> in the substitution string!
 </note>
 
-      <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
-      rewrite rule is the string which is substituted for (or
-      replaces) the original URL which <em>Pattern</em>
-      matched. In addition to plain text, it can include</p>
+      <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
+      rewrite rule is the string that replaces the original URL-path that
+      was matched by <em>Pattern</em>.  The <em>Substitution</em> may
+      be a:</p>
+
+      <dl>
+
+        <dt>file-system path</dt>
+
+        <dd>Designates the location on the file-system of the resource
+        to be delivered to the client.</dd>
+
+        <dt>URL-path</dt> 
+
+        <dd>A <directive
+        module="core">DocumentRoot</directive>-relative path to the
+        resource to be served. Note that <module>mod_rewrite</module>
+        tries to guess whether you have specified a file-system path
+        or a URL-path by checking to see if the first segement of the
+        path exists at the root of the file-system. For example, if
+        you specify a <em>Substitution</em> string of
+        <code>/www/file.html</code>, then this will be treated as a
+        URL-path <em>unless</em> a directory named <code>www</code>
+        exists at the root or your file-system, in which case it will
+        be treated as a file-system path. If you wish other
+        URL-mapping directives (such as <directive
+        module="mod_alias">Alias</directive>) to be applied to the
+        resulting URL-path, use the <code>[PT]</code> flag as
+        described below.</dd>
+
+        <dt>Absolute URL</dt>
+
+        <dd>If an absolute URL is specified,
+        <module>mod_rewrite</module> checks to see whether the
+        hostname matches the current host. If it does, the scheme and
+        hostname are stripped out and the resulting path is treated as
+        a URL-path. Otherwise, an external redirect is performed for
+        the given URL. To force an external redirect back to the
+        current host, see the <code>[R]</code> flag below.</dd>
+
+        <dt><code>-</code> (dash)</dt>
+
+        <dd>A dash indicates that no substitution should be performed
+        (the existing path is passed through untouched). This is used
+        when a flag (see below) needs to be applied without changing
+        the path.</dd>
+
+      </dl>
+
+      <p>In addition to plain text, the <em>Substition</em> string can include</p>
 
       <ol>
         <li>back-references (<code>$N</code>) to the RewriteRule
@@ -1153,6 +1209,7 @@
         <li><a href="#mapfunc">mapping-function</a> calls
         (<code>${mapname:key|default}</code>)</li>
       </ol>
+
       <p>Back-references are identifiers of the form 
 	      <code>$</code><strong>N</strong>
       (<strong>N</strong>=0..9), which will be replaced
@@ -1172,25 +1229,28 @@
       or it is explicitly terminated by a
       <code><strong>L</strong></code> flag.</p>
 
-      <p>There is a special substitution string named
-      '<code>-</code>' which means: <strong>NO
-      substitution</strong>! This is useful in providing
-      rewriting rules which <strong>only</strong> match
-      URLs but do not substitute anything for them. It is commonly used 
-      in conjunction with the <strong>C</strong> (chain) flag, in order 
-      to apply more than one pattern before substitution occurs.</p>
+     <note><title>Modifying the Query String</title>
+      <p>By default, the query string is passed through unchanged. You
+      can, however, create URLs in the substitution string containing
+      a query string part. Simply use a question mark inside the
+      substitution string to indicate that the following text should
+      be re-injected into the query string. When you want to erase an
+      existing query string, end the substitution string with just a
+      question mark. To combine new and old query strings, use the
+      <code>[QSA]</code> flag.</p> 
+     </note>
 
 
       <p>Additionally you can set special <a name="rewriteflags"
-      id="rewriteflags">flags</a> for <em>Substitution</em> by 
+      id="rewriteflags">actions</a> to be performed by 
       appending <strong><code>[</code><em>flags</em><code>]</code></strong>
       as the third argument to the <code>RewriteRule</code>
-      directive. <em>Flags</em> is a comma-separated list of any of the
-      following flags: </p>
+      directive. <em>Flags</em> is a comma-separated list, surround by square 
+      brackets, of any of the following flags: </p>
 
-      <ul>
-        <li>'<strong><code>chain|C</code></strong>'
-        (<strong>c</strong>hained with next rule)<br />
+      <dl>
+        <dt>'<code>chain|C</code>'
+        (chained with next rule)</dt><dd>
          This flag chains the current rule with the next rule
         (which itself can be chained with the following rule,
         and so on). This has the following effect: if a rule
@@ -1200,21 +1260,21 @@
         rules are skipped. For instance, it can be used to remove the
         ``<code>.www</code>'' part, inside a per-directory rule set,
         when you let an external redirect happen (where the
-        ``<code>.www</code>'' part should not occur!).</li>
+        ``<code>.www</code>'' part should not occur!).</dd>
 
-        <li>
-		'<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
-        (set <strong>co</strong>okie)<br />
+        <dt>
+		'<code>cookie|CO=</code><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
+        (set cookie)</dt><dd>
         This sets a cookie in the client's browser.  The cookie's name
         is specified by <em>NAME</em> and the value is
         <em>VAL</em>. The <em>domain</em> field is the domain of the
         cookie, such as '.apache.org', the optional <em>lifetime</em>
 	is the lifetime of the cookie in minutes, and the optional 
-	<em>path</em> is the path of the cookie</li>
+	<em>path</em> is the path of the cookie</dd>
 
-        <li>
-        '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
-        (set <strong>e</strong>nvironment variable)<br />
+        <dt>
+        '<code>env|E=</code><em>VAR</em>:<em>VAL</em>'
+        (set environment variable)</dt><dd>
         This forces an environment variable named <em>VAR</em> to
         be set to the value <em>VAL</em>, where <em>VAL</em> can
         contain regexp backreferences (<code>$N</code> and
@@ -1225,67 +1285,69 @@
         var="VAR"--&gt;</code>) or CGI (<code>$ENV{'VAR'}</code>). 
 	You can also dereference the variable in a later RewriteCond pattern, using
         <code>%{ENV:VAR}</code>. Use this to strip 
-        information from URLs, while maintaining a record of that information.</li>
+        information from URLs, while maintaining a record of that information.</dd>
 
-        <li>'<strong><code>forbidden|F</code></strong>' (force URL
-        to be <strong>f</strong>orbidden)<br />
+        <dt>'<code>forbidden|F</code>' (force URL
+        to be forbidden)</dt><dd>
         This forces the current URL to be forbidden - it immediately 
 	sends back a HTTP response of 403 (FORBIDDEN). 
 	Use this flag in conjunction with
         appropriate RewriteConds to conditionally block some
-        URLs.</li>
+        URLs.</dd>
 
-        <li>'<strong><code>gone|G</code></strong>' (force URL to be
-        <strong>g</strong>one)<br />
+        <dt>'<code>gone|G</code>' (force URL to be
+        gone)</dt><dd>
         This forces the current URL to be gone - it
         immediately sends back a HTTP response of 410 (GONE). Use
-        this flag to mark pages which no longer exist as gone.</li>
+        this flag to mark pages which no longer exist as gone.</dd>
 
-        <li>
-        '<strong><code>handler|H</code></strong>=<em>Content-handler</em>'
-        (force Content <strong>h</strong>andler)<br />
+        <dt>
+        '<code>handler|H</code>=<em>Content-handler</em>'
+        (force Content handler)</dt><dd>
          Force the Content-handler of the target file to be
         <em>Content-handler</em>. For instance, this can be used to
         simulate the <module>mod_alias</module> directive
 	<directive module="mod_alias">ScriptAlias</directive>, 
 	which internally forces all files
         inside the mapped directory to have a handler of
-        ``<code>cgi-script</code>''.</li>
+        ``<code>cgi-script</code>''.</dd>
 
-        <li>'<strong><code>last|L</code></strong>'
-        (<strong>l</strong>ast rule)<br />
-        Stop the rewriting process here and don't apply any more
-        rewrite rules. This corresponds to the Perl
-        <code>last</code> command or the <code>break</code> command
-        in C. Use this flag to prevent the currently
-        rewritten URL from being rewritten further by following
-        rules. For example, use it to rewrite the root-path URL
-        ('<code>/</code>') to a real one, <em>e.g.</em>,
-        '<code>/e/www/</code>'.</li>
+        <dt>'<code>last|L</code>'
+        (last rule)</dt><dd> Stop the rewriting process
+        here and don't apply any more rewrite rules. This corresponds
+        to the Perl <code>last</code> command or the
+        <code>break</code> command in C. Use this flag to prevent the
+        currently rewritten URL from being rewritten further by
+        following rules. Remember, however, that if the
+        <directive>RewriteRule</directive> generates an internal
+        redirect (which frequently occurs when rewriting in a
+        per-directory context), this will reinject the request and
+        will cause processing to be repeated starting from the first
+        <directive>RewriteRule</directive>.</dd>
 
-        <li>'<strong><code>next|N</code></strong>'
-        (<strong>n</strong>ext round)<br />
+        <dt>'<code>next|N</code>'
+        (next round)</dt><dd>
         Re-run the rewriting process (starting again with the
         first rewriting rule). This time, the URL to match is no longer
         the original URL, but rather the URL returned by the last rewriting rule.
         This corresponds to the Perl <code>next</code> command or
         the <code>continue</code> command in C. Use
         this flag to restart the rewriting process -
-        to immediately go to the top of the loop.<br />
+        to immediately go to the top of the loop.
          <strong>Be careful not to create an infinite
-        loop!</strong></li>
+        loop!</strong></dd>
 
-        <li>'<strong><code>nocase|NC</code></strong>'
-        (<strong>n</strong>o <strong>c</strong>ase)<br />
+        <dt>'<code>nocase|NC</code>'
+        (no case)</dt><dd>
         This makes the <em>Pattern</em> case-insensitive,
         ignoring difference between 'A-Z' and
         'a-z' when <em>Pattern</em> is matched against the current
-        URL.</li>
+        URL.</dd>
 
-        <li>
-          '<strong><code>noescape|NE</code></strong>'
-          (<strong>n</strong>o URI <strong>e</strong>scaping of
-          output)<br />
+        <dt>
+          '<code>noescape|NE</code>'
+          (no URI escaping of
+          output)</dt><dd>
           This flag prevents mod_rewrite from applying the usual URI
           escaping rules to the result of a rewrite. Ordinarily,
           special characters (such as '%', '$', ';', and so on)
@@ -1298,13 +1360,13 @@
 </example>
           which would turn '<code>/foo/zed</code>' into a safe
           request for '<code>/bar?arg=P1=zed</code>'. 
-        </li>
+        </dd>
 
-        <li>
-          '<strong><code>nosubreq|NS</code></strong>'
-          (<strong>n</strong>ot for internal
-          <strong>s</strong>ub-requests)<br />
-          This flag forces the rewriting engine to skip a
+        <dt>
+          '<code>nosubreq|NS</code>'
+          (not for internal
+          sub-requests)</dt><dd>
+          <p>This flag forces the rewriting engine to skip a
           rewriting rule if the current request is an internal
           sub-request. For instance, sub-requests occur internally
           in Apache when <module>mod_include</module> tries to find out
@@ -1312,17 +1374,17 @@
           (<code>index.xxx</code> files). On sub-requests it is not
           always useful, and can even cause errors, if
           the complete set of rules are applied. Use this flag to
-          exclude some rules.<br />
-          To decide whether or not to use this rule: if you
+          exclude some rules.</p>
+          <p>To decide whether or not to use this rule: if you
           prefix URLs with CGI-scripts, to force them to be
 	  processed by the CGI-script, it's likely that you 
           will run into problems (or significant overhead) on
-          sub-requests. In these cases, use this flag.
-        </li>
+          sub-requests. In these cases, use this flag.</p>
+        </dd>
 
-        <li>
-          '<strong><code>proxy|P</code></strong>' (force
-          <strong>p</strong>roxy)<br />
+        <dt>
+          '<code>proxy|P</code>' (force
+          proxy)</dt><dd>
           This flag forces the substitution part to be internally
 	  sent as a proxy request and immediately (rewrite 
 	  processing stops here) put through the <a
@@ -1339,12 +1401,12 @@
 
           <p>Note: <module>mod_proxy</module> must be enabled in order
           to use this flag.</p>
-        </li>
+        </dd>
 
-        <li>
-          '<strong><code>passthrough|PT</code></strong>'
-          (<strong>p</strong>ass <strong>t</strong>hrough to next
-          handler)<br />
+        <dt>
+          '<code>passthrough|PT</code>'
+          (pass through to next
+          handler)</dt><dd>
            This flag forces the rewrite engine to set the
           <code>uri</code> field of the internal
           <code>request_rec</code> structure to the value of the
@@ -1379,55 +1441,59 @@
           <p>The <code>PT</code> flag implies the <code>L</code> flag:
           rewriting will be stopped in order to pass the request to
           the next phase of processing.</p>
-        </li>
+        </dd>
 
-        <li>'<strong><code>qsappend|QSA</code></strong>'
-        (<strong>q</strong>uery <strong>s</strong>tring
-        <strong>a</strong>ppend)<br />
+        <dt>'<code>qsappend|QSA</code>'
+        (query string
+        append)</dt><dd>
         This flag forces the rewrite engine to append a query
         string part of the substitution string to the existing string,
         instead of replacing it. Use this when you want to add more
-        data to the query string via a rewrite rule.</li>
+        data to the query string via a rewrite rule.</dd>
 
-         <li>'<strong><code>redirect|R</code>
-          [=<em>code</em>]</strong>' (force <a id="redirect"
-          name="redirect"><strong>r</strong>edirect</a>)<br />
-          Prefix <em>Substitution</em> with
+        <dt>'<code>redirect|R</code>
+          [=<em>code</em>]' (force <a id="redirect"
+          name="redirect">redirect</a>)</dt><dd>
+        <p>Prefix <em>Substitution</em> with
           <code>http://thishost[:thisport]/</code> (which makes the
           new URL a URI) to force a external redirection. If no
           <em>code</em> is given, a HTTP response of 302 (MOVED
-          TEMPORARILY) will be returned. If you want to use other response
-          codes in the range 300-400, simply specify the appropriate number
-          or use one of the following symbolic names:
-          <code>temp</code> (default), <code>permanent</code>,
-          <code>seeother</code>. Use this for rules to
-          canonicalize the URL and return it to the client - to 
-	  translate ``<code>/~</code>'' into
-          ``<code>/u/</code>'', or to always append a slash to
-          <code>/u/</code><em>user</em>, etc.<br />
-          <strong>Note:</strong> When you use this flag, make
-          sure that the substitution field is a valid URL! Otherwise,
-          you will be redirecting to an invalid location. Remember
-          that this flag on its own will only prepend
-          <code>http://thishost[:thisport]/</code> to the URL, and rewriting
-	  will continue. Usually, you will want to stop rewriting at this point,
-	  and redirect immediately. To stop rewriting, you should add 
-	  the 'L' flag.
-        </li>
+          TEMPORARILY) will be returned. If you want to use other
+          response codes, simply specify the appropriate number or use
+          one of the following symbolic names: <code>temp</code>
+          (default), <code>permanent</code>,
+          <code>seeother</code>. Use this for rules to canonicalize
+          the URL and return it to the client - to translate
+          ``<code>/~</code>'' into ``<code>/u/</code>'', or to always
+          append a slash to <code>/u/</code><em>user</em>, etc.<br />
+          <strong>Note:</strong> When you use this flag, make sure
+          that the substitution field is a valid URL! Otherwise, you
+          will be redirecting to an invalid location. Remember that
+          this flag on its own will only prepend
+          <code>http://thishost[:thisport]/</code> to the URL, and
+          rewriting will continue. Usually, you will want to stop
+          rewriting at this point, and redirect immediately. To stop
+          rewriting, you should add the 'L' flag.</p>
+          <p>While this is typically used for redirects, any valid status
+          code can be given here. If the status code is outside the redirect
+          range (300-399), then the <em>Substitution</em> string is dropped
+          and rewriting is stopped as if the <code>L</code> flag was
+          used.</p>
+        </dd>
 
-        <li>'<strong><code>skip|S</code></strong>=<em>num</em>'
-        (<strong>s</strong>kip next rule(s))<br />
+        <dt>'<code>skip|S</code>=<em>num</em>'
+        (skip next rule(s))</dt><dd>
         This flag forces the rewriting engine to skip the next
         <em>num</em> rules in sequence, if the current rule
         matches. Use this to make pseudo if-then-else constructs:
         The last rule of the then-clause becomes
         <code>skip=N</code>, where N is the number of rules in the
         else-clause. (This is <strong>not</strong> the same as the
-        'chain|C' flag!)</li>
+        'chain|C' flag!)</dd>
 
-        <li>
-        '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
-        (force MIME <strong>t</strong>ype)<br />
+        <dt>
+        '<code>type|T</code>=<em>MIME-type</em>'
+        (force MIME type)</dt><dd>
          Force the <glossary>MIME-type</glossary> of the target file to be
         <em>MIME-type</em>. This can be used to
         set up the content-type based on some conditions.
@@ -1437,8 +1503,8 @@
         <example>
             RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
         </example>
-        </li>
-      </ul>
+        </dd>
+      </dl>
 
 <note><title>Per-directory Rewrites</title>
  
@@ -1476,39 +1542,6 @@
 type="section" module="core">Location</directive> sections, this
 should never be necessary and is unsupported.</p>
 
-</note>
-
-<note><title>Note: Substitution of Absolute URLs</title>
-          <p>
-          When you prefix a substitution field with
-	  <code>http://thishost[:thisport]</code>, <module
-	  >mod_rewrite</module> will automatically strip that
-          out. This auto-reduction on URLs with an implicit 
-          external redirect is most useful in
-          combination with a mapping-function which generates the
-	  hostname part.</p>
-
-          <p><strong>Remember:</strong> An unconditional external
-          redirect to your own server will not work with the prefix
-          <code>http://thishost</code> because of this feature. To
-          achieve such a self-redirect, you have to use the
-          <strong>R</strong>-flag.</p>
-</note>
-
-<note><title>What is matched?</title>
-      <p>The <em>Pattern</em> will initially be matched against the part of the
-      URL after the hostname and port, and before the query string. 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>
-      <p>You can, however, create URLs in the substitution string containing a
-      query string part. Simply use a question mark inside the substitution
-      string, to indicate that the following text should be re-injected into the
-      query string. When you want to erase an existing query string,
-      end the substitution string with just a question mark. To
-      combine new and old query strings, use the
-      <code>[QSA]</code> flag.</p>
 </note>
 
      <p>Here are all possible substitution combinations and their



Mime
View raw message