From: Rich Bowen <rbowen@apache.org>
Date: Tue, 14 Aug 2007 01:32:07 +0000 (+0000)
Subject: Complete the various flags. I'd like to see more examples here, and
X-Git-Tag: 2.3.0~1610
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0c83d1dd09d3252f0d979501e1ee335a74610d79;p=thirdparty%2Fapache%2Fhttpd.git

Complete the various flags. I'd like to see more examples here, and
perhaps some of the examples that are given in the main doc can be
expanded on somewhat, here, in a rather less confusing manner.


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

diff --git a/docs/manual/rewrite/flags.html.en b/docs/manual/rewrite/flags.html.en
index 3779cee9abc..73bd33ee475 100644
--- a/docs/manual/rewrite/flags.html.en
+++ b/docs/manual/rewrite/flags.html.en
@@ -223,23 +223,109 @@ being converted to its hexcode equivalent, <code>%23</code>.
 
 
 <h3><a name="flag_ns" id="flag_ns">NS|nosubreq</a></h3>
-<p>No internal subrequest flag</p>
+<p>Use of the [NS] flag prevents the rule from being used on
+subrequests. For example, a page which is included using an SSI (Server
+Side Include) is a subrequest, and you may want to avoid rewrites
+happening on those subrequests.</p>
+
+<p>
+Images, javascript files, or css files, loaded as part of an HTML page,
+are not subrequests - the browser requests them as separate HTTP
+requests.
+</p>
 
 
 <h3><a name="flag_p" id="flag_p">P|proxy</a></h3>
-<p>Proxy flag</p>
+<p>Use of the [P] flag causes the request to be handled by
+<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, and handled via a proxy request. For
+example, if you wanted all image requests to be handled by a back-end
+image server, you might do something like the following:</p>
+
+<div class="example"><p><code>
+RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
+</code></p></div>
+
+<p>Use of the [P] flag implies [L] - that is, the request is immediatly
+pushed through the proxy, and any following rules will not be
+considered.</p>
+
 
 
 <h3><a name="flag_pt" id="flag_pt">PT|passthrough</a></h3>
-<p>Passthrough flag</p>
+
+<p>
+The target (or substitution string) in a RewriteRule is assumed to be a
+file path, by default. The use of the [PT] flag causes it to be trated
+as a URI instead. That is to say, the
+use of the [PT] flag causes the result of the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be passed back through
+URL mapping, so that location-based mappings, such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>, for example, might have a chance to take
+effect.
+</p>
+
+<p>
+If, for example, you have an 
+<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>
+for /icons, and have a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> pointing there, you should
+use the [PT] flag to ensure that the 
+<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> is evaluated.
+</p>
+
+<div class="example"><p><code>
+Alias /icons /usr/local/apache/icons
+RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
+</code></p></div>
+
+<p>
+Omission of the [PT] flag in this case will cause the Alias to be
+ignored, resulting in a 'File not found' error being returned.
+</p>
+
 
 
 <h3><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h3>
-<p>Query String Append flag</p>
+<p>
+When the replacement URI contains a query string, the default behavior
+of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to discard
+the existing query string, and replace it with the newly generated one.
+Using the [QSA] flag causes the query strings to be combined.
+</p>
+
+<p>Consider the following rule:</p>
+
+<div class="example"><p><code>
+RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
+</code></p></div>
+
+<p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
+mapped to <code>/page.php?page=123&amp;one=two</code>. Without the [QSA]
+flag, that same request will be mapped to
+<code>/page.php?page=123</code> - that is, the existing query string
+will be discarded.
+</p>
 
 
 <h3><a name="flag_r" id="flag_r">R|redirect</a></h3>
-<p>Redirect flag</p>
+<p>
+Use of the [R] flag causes a HTTP redirect to be issued to the browser.
+If a fully-qualified URL is specified (that is, including
+<code>http://servername/</code>) then a redirect will be issued to that
+location. Otherwise, the current servername will be used to generate the
+URL sent with the redirect.
+</p>
+
+<p>
+A status code may be specified, in the range 300-399, with a 302 status
+code being used by default if none is specified.
+</p>
+
+<p>
+You will almost always want to use [R] in conjunction with [L] (that is,
+use [R,L]) because on its own, the [R] flag prepends
+<code>http://thishost[:thisport]</code> to the URI, but then passes this
+on to the next rule in the ruleset, which can often result in 'Invalid
+URI in request' warnings.
+</p>
+
 
 
 <h3><a name="flag_s" id="flag_s">S|skip</a></h3>
diff --git a/docs/manual/rewrite/flags.xml b/docs/manual/rewrite/flags.xml
index c346b35f18b..437120fbf45 100644
--- a/docs/manual/rewrite/flags.xml
+++ b/docs/manual/rewrite/flags.xml
@@ -234,23 +234,112 @@ being converted to its hexcode equivalent, <code>%23</code>.
 </section>
 
 <section id="flag_ns"><title>NS|nosubreq</title>
-<p>No internal subrequest flag</p>
+<p>Use of the [NS] flag prevents the rule from being used on
+subrequests. For example, a page which is included using an SSI (Server
+Side Include) is a subrequest, and you may want to avoid rewrites
+happening on those subrequests.</p>
+
+<p>
+Images, javascript files, or css files, loaded as part of an HTML page,
+are not subrequests - the browser requests them as separate HTTP
+requests.
+</p>
 </section>
 
 <section id="flag_p"><title>P|proxy</title>
-<p>Proxy flag</p>
+<p>Use of the [P] flag causes the request to be handled by
+<module>mod_proxy</module>, and handled via a proxy request. For
+example, if you wanted all image requests to be handled by a back-end
+image server, you might do something like the following:</p>
+
+<example>
+RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
+</example>
+
+<p>Use of the [P] flag implies [L] - that is, the request is immediatly
+pushed through the proxy, and any following rules will not be
+considered.</p>
+
 </section>
 
 <section id="flag_pt"><title>PT|passthrough</title>
-<p>Passthrough flag</p>
+
+<p>
+The target (or substitution string) in a RewriteRule is assumed to be a
+file path, by default. The use of the [PT] flag causes it to be trated
+as a URI instead. That is to say, the
+use of the [PT] flag causes the result of the <directive
+module="mod_rewrite">RewriteRule</directive> to be passed back through
+URL mapping, so that location-based mappings, such as <directive
+module="mod_alias">Alias</directive>, for example, might have a chance to take
+effect.
+</p>
+
+<p>
+If, for example, you have an 
+<directive module="mod_alias">Alias</directive>
+for /icons, and have a <directive
+module="mod_rewrite">RewriteRule</directive> pointing there, you should
+use the [PT] flag to ensure that the 
+<directive module="mod_alias">Alias</directive> is evaluated.
+</p>
+
+<example>
+Alias /icons /usr/local/apache/icons
+RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
+</example>
+
+<p>
+Omission of the [PT] flag in this case will cause the Alias to be
+ignored, resulting in a 'File not found' error being returned.
+</p>
+
 </section>
 
 <section id="flag_qsa"><title>QSA|qsappend</title>
-<p>Query String Append flag</p>
+<p>
+When the replacement URI contains a query string, the default behavior
+of <directive module="mod_rewrite">RewriteRule</directive> is to discard
+the existing query string, and replace it with the newly generated one.
+Using the [QSA] flag causes the query strings to be combined.
+</p>
+
+<p>Consider the following rule:</p>
+
+<example>
+RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
+</example>
+
+<p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
+mapped to <code>/page.php?page=123&amp;one=two</code>. Without the [QSA]
+flag, that same request will be mapped to
+<code>/page.php?page=123</code> - that is, the existing query string
+will be discarded.
+</p>
 </section>
 
 <section id="flag_r"><title>R|redirect</title>
-<p>Redirect flag</p>
+<p>
+Use of the [R] flag causes a HTTP redirect to be issued to the browser.
+If a fully-qualified URL is specified (that is, including
+<code>http://servername/</code>) then a redirect will be issued to that
+location. Otherwise, the current servername will be used to generate the
+URL sent with the redirect.
+</p>
+
+<p>
+A status code may be specified, in the range 300-399, with a 302 status
+code being used by default if none is specified.
+</p>
+
+<p>
+You will almost always want to use [R] in conjunction with [L] (that is,
+use [R,L]) because on its own, the [R] flag prepends
+<code>http://thishost[:thisport]</code> to the URI, but then passes this
+on to the next rule in the ruleset, which can often result in 'Invalid
+URI in request' warnings.
+</p>
+
 </section>
 
 <section id="flag_s"><title>S|skip</title>