Flush out the rewrite docs a little. In particular:

- rename flags to rewrite_flags for consistency
- note that flags is not comprehensive
- link up flags to the index page
- change the seealso links on the index page to be other useful
  links rather than a repeat of the links elsewhere on the page
- add some meat to the intro doc -- some sections still need more content



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

8 files changed, 333 insertions, 130 deletions

diff --git a/docs/manual/rewrite/index.html.en b/docs/manual/rewrite/index.html.en
index 2eeb49c64a..3eb633a6cc 100644
--- a/docs/manual/rewrite/index.html.en
+++ b/docs/manual/rewrite/index.html.en
@@ -70,9 +70,8 @@
       entire module in just one day.</p>
 
 </div>
-<div id="quickview"><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">mod_rewrite reference
-documentation</a></li><li><a href="rewrite_intro.html">Introduction</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li><li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
-advanced useful examples</a></li></ul></div>
+<div id="quickview"><h3>See also</h3><ul class="seealso"><li><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></li><li><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
+wiki</a></li><li><a href="../glossary.html">Glossary</a></li></ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="documentation" id="documentation">Documentation</a></h2>
@@ -80,11 +79,11 @@ advanced useful examples</a></li></ul></div>
 <li><a href="../mod/mod_rewrite.html">mod_rewrite reference
 documentation</a></li>
 <li><a href="rewrite_intro.html">Introduction</a></li>
+<li><a href="rewrite_flags.html">Flags</a></li>
 <li><a href="rewrite_tech.html">Technical details</a></li>
 <li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li>
 <li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - more
 useful examples</a></li>
-<li><a href="../glossary.html">Glossary</a></li>
 </ul>
 </div></div>
 <div class="bottomlang">
diff --git a/docs/manual/rewrite/index.xml b/docs/manual/rewrite/index.xml
index 3eef041276..d91cd8196e 100644
--- a/docs/manual/rewrite/index.xml
+++ b/docs/manual/rewrite/index.xml
@@ -76,24 +76,21 @@
 
 </summary>
 
-<seealso><a href="../mod/mod_rewrite.html">mod_rewrite reference
-documentation</a></seealso>
-<seealso><a href="rewrite_intro.html">Introduction</a></seealso>
-<seealso><a href="rewrite_tech.html">Technical details</a></seealso>
-<seealso><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></seealso>
-<seealso><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
-advanced useful examples</a></seealso>
+<seealso><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></seealso>
+<seealso><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
+wiki</a></seealso>
+<seealso><a href="../glossary.html">Glossary</a></seealso>
 
 <section id="documentation"><title>Documentation</title>
 <ul>
 <li><a href="../mod/mod_rewrite.html">mod_rewrite reference
 documentation</a></li>
 <li><a href="rewrite_intro.html">Introduction</a></li>
+<li><a href="rewrite_flags.html">Flags</a></li>
 <li><a href="rewrite_tech.html">Technical details</a></li>
 <li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li>
 <li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - more
 useful examples</a></li>
-<li><a href="../glossary.html">Glossary</a></li>
 </ul>
 </section>
 
diff --git a/docs/manual/rewrite/flags.html b/docs/manual/rewrite/rewrite_flags.html
index 5ea39bca4f..605b284a46 100644
--- a/docs/manual/rewrite/flags.html
+++ b/docs/manual/rewrite/rewrite_flags.html
@@ -1,3 +1,3 @@
-URI: flags.html.en
+URI: rewrite_flags.html.en
 Content-Language: en
 Content-type: text/html; charset=ISO-8859-1
diff --git a/docs/manual/rewrite/flags.html.en b/docs/manual/rewrite/rewrite_flags.html.en
index a8073eec0e..8d73f0730c 100644
--- a/docs/manual/rewrite/flags.html.en
+++ b/docs/manual/rewrite/rewrite_flags.html.en
@@ -6,33 +6,35 @@
         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
       -->
 <title>Apache mod_rewrite Flags - Apache HTTP Server</title>
-<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
-<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
-<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
-<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="/images/favicon.ico" rel="shortcut icon" /></head>
 <body id="manual-page"><div id="page-header">
-<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
+<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
 <p class="apache">Apache HTTP Server Version 2.3</p>
-<img alt="" src="../images/feather.gif" /></div>
-<div class="up"><a href="./index.html"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
+<img alt="" src="/images/feather.gif" /></div>
+<div class="up"><a href="./index.html"><img title="&lt;-" alt="&lt;-" src="/images/left.gif" /></a></div>
 <div id="path">
-<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Flags</h1>
+<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="/">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Flags</h1>
 <div class="toplang">
-<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English">&nbsp;en&nbsp;</a></p>
+<p><span>Available Languages: </span></p>
 </div>
 
 <p>This document discusses the flags which are available to the
-<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive,
-providing more detailed explanations and examples of each.</p>
+<code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive,
+providing detailed explanations and examples. This is not necessarily
+a comprehensive list of all flags available, so be sure to also
+consult the reference documentation.</p>
 </div>
-<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#flags">The flags</a></li>
+<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
+<li><img alt="" src="/images/down.gif" /> <a href="#flags">The flags</a></li>
 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li><li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
 advanced useful examples</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="introduction" id="introduction">Introduction</a></h2>
-<p><code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s can have
+<p><code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s can have
 their behavior modified by one or more flags. Flags are included in
 square brackets at the end of the rule, and multiple flags are separated
 by commas.</p>
@@ -44,7 +46,7 @@ RewriteRule pattern target [Flag1,Flag2,Flag3]
 a longer form, such as <code>cookie</code>. Some flags take one or more
 arguments. Flags are not case sensitive.</p>
 
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="flags" id="flags">The flags</a></h2>
 
@@ -56,7 +58,7 @@ long form, so that you remember what each flag is supposed to do.</p>
 of how you might use them.</p>
 
 <h3><a name="flag_c" id="flag_c">C|chain</a></h3>
-<p>The [C] or [chain] flag indicates that the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is chained to the next
+<p>The [C] or [chain] flag indicates that the <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is chained to the next
 rule. That is, if the rule matches, then it is processed as usual and
 control moves on to the next rule. However, if it does not match, then
 the next rule, and any other rules that are chained together, will be
@@ -66,7 +68,7 @@ skipped.</p>
 
 <h3><a name="flag_co" id="flag_co">CO|cookie</a></h3>
 <p>The [CO], or [cookie] flag, allows you to set a cookie when a
-particular <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
+particular <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
 matches. The argument consists of three required fields and two optional
 fields.</p>
 <p>You must declare a name and value for the cookie to be set, and the
@@ -109,14 +111,14 @@ RewriteRule \.(png|gif|jpg) - [E=image:1]<br />
 CustomLog logs/access_log combined env=!image
 </code></p></div>
 
-<p>Note that this same effect can be obtained using <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>. This technique is offered as
+<p>Note that this same effect can be obtained using <code class="directive"><a href="/mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>. This technique is offered as
 an example, not as a recommendation.</p>
 
 
 <h3><a name="flag_f" id="flag_f">F|forbidden</a></h3>
 <p>Using the [F] flag causes Apache to return a 403 Forbidden status
 code to the client. While the same behavior can be accomplished using
-the <code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code> directive, this 
+the <code class="directive"><a href="/mod/mod_access.html#deny">Deny</a></code> directive, this 
 allows more flexibility in assigning a Forbidden status.</p>
 
 <p>The following rule will forbid <code>.exe</code> files from being
@@ -161,25 +163,25 @@ that does not contain the literal <code>.</code> character.
 
 
 <h3><a name="flag_l" id="flag_l">L|last</a></h3>
-<p>The [L] flag causes <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing
+<p>The [L] flag causes <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing
 the rule set. In most contexts, this means that if the rule matches, no
 further rules will be processed.</p>
 
-<p>If you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either
+<p>If you are using <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either
 <code>.htaccess</code> files or in 
-<code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> sections,
+<code class="directive"><a href="/mod/core.html#directory">&lt;Directory&gt;</a></code> sections,
 it is important to have some understanding of how the rules are
 processed.  The simplified form of this is that once the rules have been
 processed, the rewritten request is handed back to the URL parsing
 engine to do what it may with it. It is possible that as the rewritten
 request is handled, the <code>.htaccess</code> file or 
-<code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section
+<code class="directive"><a href="/mod/core.html#directory">&lt;Directory&gt;</a></code> section
 may be encountered again, and thus the ruleset may be run again from the
 start. Most commonly this will happen if one of the rules causes a
 redirect - either internal or external - causing the request process to
 start over.</p>
 
-<p>It is therefore important, if you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives in one of these
+<p>It is therefore important, if you are using <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives in one of these
 context that you take explicit steps to avoid rules looping, and not
 count solely on the [L] flag to terminate execution of a series of
 rules, as shown below.</p>
@@ -217,7 +219,7 @@ pattern still matches, perform this substitution.</p>
 
 
 <h3><a name="flag_nc" id="flag_nc">NC|nocase</a></h3>
-<p>Use of the [NC] flag causes the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be matched in a
+<p>Use of the [NC] flag causes the <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be matched in a
 case-insensitive manner. That is, it doesn't care whether letters appear
 as upper-case or lower-case in the matched URI.</p>
 
@@ -265,7 +267,7 @@ requests.
 
 <h3><a name="flag_p" id="flag_p">P|proxy</a></h3>
 <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
+<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>
 
@@ -285,17 +287,17 @@ considered.</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
+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
+<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.
+<code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code> is evaluated.
 </p>
 
 <div class="example"><p><code>
@@ -313,7 +315,7 @@ ignored, resulting in a 'File not found' error being returned.
 <h3><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h3>
 <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
+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>
@@ -359,7 +361,7 @@ URI in request' warnings.
 <h3><a name="flag_s" id="flag_s">S|skip</a></h3>
 <p>The [S] flag is used to skip rules that you don't want to run. This
 can be thought of as a <code>goto</code> statement in your rewrite
-ruleset. In the following example, we only want to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the requested URI
+ruleset. In the following example, we only want to run the <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the requested URI
 doesn't correspond with an actual file.</p>
 
 <div class="example"><p><code>
@@ -373,8 +375,8 @@ RewriteRule (.*\.gif) images.php?$1<br />
 RewriteRule (.*\.html) docs.php?$1
 </code></p></div>
 
-<p>This technique is useful because a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> only applies to the
-<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> immediately
+<p>This technique is useful because a <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> only applies to the
+<code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> immediately
 following it. Thus, if you want to make a <code>RewriteCond</code> apply
 to several <code>RewriteRule</code>s, one possible technique is to
 negate those conditions and use a [Skip] flag.</p>
@@ -383,7 +385,7 @@ negate those conditions and use a [Skip] flag.</p>
 
 <h3><a name="flag_t" id="flag_t">T|type</a></h3>
 <p>Sets the MIME type with which the resulting response will be
-sent. This has the same effect as the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> directive.</p>
+sent. This has the same effect as the <code class="directive"><a href="/mod/mod_mime.html#addtype">AddType</a></code> directive.</p>
 
 <p>For example, you might use the following technique to serve Perl
 source code as plain text, if requested in a particular way:</p>
@@ -403,7 +405,7 @@ RewriteRule IMG - [T=image/jpg]
 </code></p></div>
 
 <p>Please note that this is a trivial example, and could be better done
-using <code class="directive"><a href="../mod/core.html#filesmatch">&lt;FilesMatch&gt;</a></code>
+using <code class="directive"><a href="/mod/core.html#filesmatch">&lt;FilesMatch&gt;</a></code>
 instead. Always consider the alternate
 solutions to a problem before resorting to rewrite, which will
 invariably be a less efficient solution than the alternatives.</p>
@@ -411,8 +413,8 @@ invariably be a less efficient solution than the alternatives.</p>
 
 </div></div>
 <div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English">&nbsp;en&nbsp;</a></p>
+<p><span>Available Languages: </span></p>
 </div><div id="footer">
 <p class="apache">Copyright 2008 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
-<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
+<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>
 </body></html>
\ No newline at end of file
diff --git a/docs/manual/rewrite/flags.xml b/docs/manual/rewrite/rewrite_flags.xml
index 6378b31570..ee67d3debb 100644
--- a/docs/manual/rewrite/flags.xml
+++ b/docs/manual/rewrite/rewrite_flags.xml
@@ -28,7 +28,9 @@
 <summary>
 <p>This document discusses the flags which are available to the
 <directive module="mod_rewrite">RewriteRule</directive> directive,
-providing more detailed explanations and examples of each.</p>
+providing detailed explanations and examples. This is not necessarily
+a comprehensive list of all flags available, so be sure to also
+consult the reference documentation.</p>
 </summary>
 
 <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
diff --git a/docs/manual/rewrite/flags.xml.meta b/docs/manual/rewrite/rewrite_flags.xml.meta
index c01b41186c..7f4813680d 100644
--- a/docs/manual/rewrite/flags.xml.meta
+++ b/docs/manual/rewrite/rewrite_flags.xml.meta
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 
 <metafile>
-  <basename>flags</basename>
+  <basename>rewrite_flags</basename>
   <path>/rewrite/</path>
   <relpath>..</relpath>
 
diff --git a/docs/manual/rewrite/rewrite_intro.html.en b/docs/manual/rewrite/rewrite_intro.html.en
index 93c650c783..0fd0f0faa4 100644
--- a/docs/manual/rewrite/rewrite_intro.html.en
+++ b/docs/manual/rewrite/rewrite_intro.html.en
@@ -35,7 +35,6 @@ but this doc should help the beginner get their feet wet.
 <li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Rewrite conditions</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">Rewrite maps</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#htaccess">.htaccess files</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#EnvVar">Environment Variables</a></li>
 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module
 documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Practical solutions to common
 problems</a></li><li><a href="rewrite_guide_advanced.html">Practical solutions to
@@ -53,6 +52,19 @@ using them without actually understanding what they do.</p>
 <p>This document attempts to give sufficient background so that what
 follows is understood, rather than just copied blindly.
 </p>
+
+<p>Remember that many common URL-manipulation tasks don't require the
+full power and complexity of <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. For simple
+tasks, see <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and the documentation
+on <a href="../urlmapping.html">mapping URLs to the
+filesystem</a>.</p>
+
+<p>Finally, before proceding, be sure to configure
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewritelog">RewriteLog</a></code>. Although
+this log file can give an overwhelming amount of information, it is
+indispensable in debugging problems with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+configuration, since it will tell you exactly how each rule is
+processed.</p>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="regex" id="regex">Regular Expressions</a></h2>
@@ -137,10 +149,69 @@ ensures that it does not match.</td></tr>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="rewriterule" id="rewriterule">RewriteRule basics</a></h2>
-<p>
-Basic anatomy of a RewriteRule, with exhaustively annotated simple
-examples.
-</p>
+<p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> consists
+of three arguments separated by spaces. The arguments are</p>
+<ol>
+<li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li>
+<li><var>Substitution</var>: where should the matching requests be sent;</li>
+<li><var>[flags]</var>: options affecting the rewritten request.</li>
+</ol>
+
+<p>The <var>Pattern</var> is always a <a href="#regex">regular
+expression</a> matched against the URL-Path of the incoming request
+(the part after the hostname but before any question mark indicating
+the beginning of a query string).</p>
+
+<p>The <var>Substitution</var> can itself be one of three things:</p>
+
+<dl>
+<dt>A full filesystem path to a resource</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/games.* /usr/local/games/web
+</code></p></div>
+<p>This maps a request to an arbitrary location on your filesystem, much
+like the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive.</p>
+</dd>
+
+<dt>A web-path to a resource</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/foo$ /bar
+</code></p></div>
+<p>If <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> is set
+to <code>/usr/local/apache2/htdocs</code>, then this directive would
+map requests for <code>http://example.com/foo</code> to the
+path <code>/usr/local/apache2/htdocs/bar</code>.</p>
+</dd>
+
+<dt>An absolute URL</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R]
+</code></p></div>
+<p>This tells the client to make a new request for the specified URL.</p>
+</dd>
+</dl>
+
+<p>The <var>Substitution</var> can also
+contain <em>back-references</em> to parts of the incoming URL-path
+matched by the <var>Pattern</var>. Consider the following:</p>
+<div class="example"><p><code>
+RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1
+</code></p></div>
+<p>The variable <code>$1</code> will be replaced with whatever text
+was matched by the expression inside the parenthesis in
+the <var>Pattern</var>. For example, a request
+for <code>http://example.com/product/r14df/view</code> will be mapped
+to the path <code>/var/web/productdbr14df</code>.</p>
+
+<p>If there is more than one expression in parenthesis, they are
+available in order in the
+variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so
+on.</p>
+
+
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="flags" id="flags">Rewrite Flags</a></h2>
@@ -154,49 +225,80 @@ RewriteRule ^puppy.html smalldog.html [NC]
 </code></p></div>
 
 <p>For more details on the available flags, their meanings, and
-examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
+examples, see the <a href="rewrite_flags.html">Rewrite Flags</a> document.</p>
 
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="rewritecond" id="rewritecond">Rewrite conditions</a></h2>
-<p>The <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directive
-allows a condition to be applied to a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>.
-</p>
+<p>One or more <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
+directives can be used to restrict the types of requests that will be
+subject to the
+following <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. The
+first argument is a variable describing a characteristic of the
+request, the second argument is a <a href="#regex">regular
+expression</a> that must match the variable, and a third optional
+argument is a list of flags that modify how the match is evaluated.</p>
+
+<p>For example, to send all requests from a particular IP range to a
+different server, you could use:</p>
+<div class="example"><p><code>
+RewriteCond %{REMOTE_ADDR} ^10\2.<br />
+RewriteRule (.*) http://intranet.example.com$1
+</code></p></div>
+
+<p>When more than
+one <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> is
+specified, they must all match for
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be
+applied. For example, to deny requests that contain the word "hack" in
+their query string, except if they also contain a cookie containing
+the word "go", you could use:</p>
+<div class="example"><p><code>
+RewriteCond %{QUERY_STRING} hack<br />
+RewriteCond %{HTTP_COOKIE} !go<br />
+RewriteRule .* - [F]
+</code></p></div>
+<p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p>
+
+<p>Matches in the regular expressions contained in
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>s can be
+used as part of the <var>Substitution</var> in
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> using the
+variables <code>%1</code>, <code>%2</code>, etc. For example, this
+will direct the request to a different directory depending on the
+hostname used to access the site:</p>
+<div class="example"><p><code>
+RewriteCond %{HTTP_HOST} (.*)<br />
+RewriteRule ^/(.*) /sites/%1/$1
+</code></p></div>
+<p>If the request was for <code>http://example.com/foo/bar</code>,
+then <code>%1</code> would contain <code>example.com</code>
+and <code>$1</code> would contain <code>foo/bar</code>.</p>
+
+
 
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="rewritemap" id="rewritemap">Rewrite maps</a></h2>
-<p>Discussion of RewriteMap, including simple, but heavily annotated,
-examples.</p>
+<p>See <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>.</p>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="htaccess" id="htaccess">.htaccess files</a></h2>
-<p>Discussion of the differences between rewrite rules in httpd.conf and
-in .htaccess files.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>
-
-<p>This module keeps track of two additional (non-standard)
-CGI/SSI environment variables named <code>SCRIPT_URL</code>
-and <code>SCRIPT_URI</code>. These contain the
-<em>logical</em> Web-view to the current resource, while the
-standard CGI/SSI variables <code>SCRIPT_NAME</code> and
-<code>SCRIPT_FILENAME</code> contain the <em>physical</em>
-System-view. </p>
-
-<p>Notice: These variables hold the URI/URL <em>as they were
-initially requested</em>, <em>i.e.</em>, <em>before</em> any
-rewriting. This is important because the rewriting process is
-primarily used to rewrite logical URLs to physical
-pathnames.</p>
-
-<div class="example"><h3>Example</h3><pre>
-SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
-SCRIPT_FILENAME=/u/rse/.www/index.html
-SCRIPT_URL=/u/rse/
-SCRIPT_URI=http://en1.engelschall.com/u/rse/
-</pre></div>
+
+<p>Rewriting is typically configured in the main server configuration
+setting (outside any <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section) or
+inside <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>
+containers. This is the easiest way to do rewriting and is
+recommended. It is possible, however, to do rewriting
+inside <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code>
+sections or <a href="../howto/htaccess.html"><code>.htaccess</code>
+files</a> at the expense of some additional complexity. This technique
+is called per-directory rewrites.</p>
+
+<p>The main difference with per-directory rewrites is that the path
+prefix of the directory containing the <code>.htaccess</code> file is
+stripped before matching in
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. In addition, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritebase">RewriteBase</a></code> should be used to assure the request is properly mapped.</p>
 
 </div></div>
 <div class="bottomlang">
diff --git a/docs/manual/rewrite/rewrite_intro.xml b/docs/manual/rewrite/rewrite_intro.xml
index 92f6f17c7e..760759303e 100644
--- a/docs/manual/rewrite/rewrite_intro.xml
+++ b/docs/manual/rewrite/rewrite_intro.xml
@@ -53,6 +53,19 @@ using them without actually understanding what they do.</p>
 <p>This document attempts to give sufficient background so that what
 follows is understood, rather than just copied blindly.
 </p>
+
+<p>Remember that many common URL-manipulation tasks don't require the
+full power and complexity of <module>mod_rewrite</module>. For simple
+tasks, see <module>mod_alias</module> and the documentation
+on <a href="../urlmapping.html">mapping URLs to the
+filesystem</a>.</p>
+
+<p>Finally, before proceding, be sure to configure
+the <directive module="mod_rewrite">RewriteLog</directive>. Although
+this log file can give an overwhelming amount of information, it is
+indispensable in debugging problems with <module>mod_rewrite</module>
+configuration, since it will tell you exactly how each rule is
+processed.</p>
 </section>
 
 <section id="regex"><title>Regular Expressions</title>
@@ -140,10 +153,69 @@ ensures that it does not match.</td></tr>
 </section>
 
 <section id="rewriterule"><title>RewriteRule basics</title>
-<p>
-Basic anatomy of a RewriteRule, with exhaustively annotated simple
-examples.
-</p>
+<p>A <directive module="mod_rewrite">RewriteRule</directive> consists
+of three arguments separated by spaces. The arguments are</p>
+<ol>
+<li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li>
+<li><var>Substitution</var>: where should the matching requests be sent;</li>
+<li><var>[flags]</var>: options affecting the rewritten request.</li>
+</ol>
+
+<p>The <var>Pattern</var> is always a <a href="#regex">regular
+expression</a> matched against the URL-Path of the incoming request
+(the part after the hostname but before any question mark indicating
+the beginning of a query string).</p>
+
+<p>The <var>Substitution</var> can itself be one of three things:</p>
+
+<dl>
+<dt>A full filesystem path to a resource</dt>
+<dd>
+<example>
+RewriteRule ^/games.* /usr/local/games/web
+</example>
+<p>This maps a request to an arbitrary location on your filesystem, much
+like the <directive module="mod_alias">Alias</directive> directive.</p>
+</dd>
+
+<dt>A web-path to a resource</dt>
+<dd>
+<example>
+RewriteRule ^/foo$ /bar
+</example>
+<p>If <directive module="core">DocumentRoot</directive> is set
+to <code>/usr/local/apache2/htdocs</code>, then this directive would
+map requests for <code>http://example.com/foo</code> to the
+path <code>/usr/local/apache2/htdocs/bar</code>.</p>
+</dd>
+
+<dt>An absolute URL</dt>
+<dd>
+<example>
+RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R]
+</example>
+<p>This tells the client to make a new request for the specified URL.</p>
+</dd>
+</dl>
+
+<p>The <var>Substitution</var> can also
+contain <em>back-references</em> to parts of the incoming URL-path
+matched by the <var>Pattern</var>. Consider the following:</p>
+<example>
+RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1
+</example>
+<p>The variable <code>$1</code> will be replaced with whatever text
+was matched by the expression inside the parenthesis in
+the <var>Pattern</var>. For example, a request
+for <code>http://example.com/product/r14df/view</code> will be mapped
+to the path <code>/var/web/productdbr14df</code>.</p>
+
+<p>If there is more than one expression in parenthesis, they are
+available in order in the
+variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so
+on.</p>
+
+
 </section>
 
 <section id="flags"><title>Rewrite Flags</title>
@@ -158,53 +230,82 @@ RewriteRule ^puppy.html smalldog.html [NC]
 </example>
 
 <p>For more details on the available flags, their meanings, and
-examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
+examples, see the <a href="rewrite_flags.html">Rewrite Flags</a> document.</p>
 
 </section>
 
 
 <section id="rewritecond"><title>Rewrite conditions</title>
-<p>The <directive module="mod_rewrite">RewriteCond</directive> directive
-allows a condition to be applied to a <directive
-module="mod_rewrite">RewriteRule</directive>.
-</p>
+<p>One or more <directive module="mod_rewrite">RewriteCond</directive>
+directives can be used to restrict the types of requests that will be
+subject to the
+following <directive module="mod_rewrite">RewriteRule</directive>. The
+first argument is a variable describing a characteristic of the
+request, the second argument is a <a href="#regex">regular
+expression</a> that must match the variable, and a third optional
+argument is a list of flags that modify how the match is evaluated.</p>
+
+<p>For example, to send all requests from a particular IP range to a
+different server, you could use:</p>
+<example>
+RewriteCond %{REMOTE_ADDR} ^10\2.<br />
+RewriteRule (.*) http://intranet.example.com$1
+</example>
+
+<p>When more than
+one <directive module="mod_rewrite">RewriteCond</directive> is
+specified, they must all match for
+the <directive module="mod_rewrite">RewriteRule</directive> to be
+applied. For example, to deny requests that contain the word "hack" in
+their query string, except if they also contain a cookie containing
+the word "go", you could use:</p>
+<example>
+RewriteCond %{QUERY_STRING} hack<br />
+RewriteCond %{HTTP_COOKIE} !go<br />
+RewriteRule .* - [F]
+</example>
+<p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p>
+
+<p>Matches in the regular expressions contained in
+the <directive module="mod_rewrite">RewriteCond</directive>s can be
+used as part of the <var>Substitution</var> in
+the <directive module="mod_rewrite">RewriteRule</directive> using the
+variables <code>%1</code>, <code>%2</code>, etc. For example, this
+will direct the request to a different directory depending on the
+hostname used to access the site:</p>
+<example>
+RewriteCond %{HTTP_HOST} (.*)<br />
+RewriteRule ^/(.*) /sites/%1/$1
+</example>
+<p>If the request was for <code>http://example.com/foo/bar</code>,
+then <code>%1</code> would contain <code>example.com</code>
+and <code>$1</code> would contain <code>foo/bar</code>.</p>
+
+
 
 </section>
 
 <section id="rewritemap"><title>Rewrite maps</title>
-<p>Discussion of RewriteMap, including simple, but heavily annotated,
-examples.</p>
+<p>See <directive module="mod_rewrite">RewriteMap</directive>.</p>
 </section>
 
 <section id="htaccess"><title>.htaccess files</title>
-<p>Discussion of the differences between rewrite rules in httpd.conf and
-in .htaccess files.</p>
-</section>
 
-<section id="EnvVar"><title>Environment Variables</title>
-
-<p>This module keeps track of two additional (non-standard)
-CGI/SSI environment variables named <code>SCRIPT_URL</code>
-and <code>SCRIPT_URI</code>. These contain the
-<em>logical</em> Web-view to the current resource, while the
-standard CGI/SSI variables <code>SCRIPT_NAME</code> and
-<code>SCRIPT_FILENAME</code> contain the <em>physical</em>
-System-view. </p>
-
-<p>Notice: These variables hold the URI/URL <em>as they were
-initially requested</em>, <em>i.e.</em>, <em>before</em> any
-rewriting. This is important because the rewriting process is
-primarily used to rewrite logical URLs to physical
-pathnames.</p>
-
-<example><title>Example</title>
-<pre>
-SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
-SCRIPT_FILENAME=/u/rse/.www/index.html
-SCRIPT_URL=/u/rse/
-SCRIPT_URI=http://en1.engelschall.com/u/rse/
-</pre>
-</example>
+<p>Rewriting is typically configured in the main server configuration
+setting (outside any <directive type="section"
+module="core">Directory</directive> section) or
+inside <directive type="section" module="core">VirtualHost</directive>
+containers. This is the easiest way to do rewriting and is
+recommended. It is possible, however, to do rewriting
+inside <directive type="section" module="core">Directory</directive>
+sections or <a href="../howto/htaccess.html"><code>.htaccess</code>
+files</a> at the expense of some additional complexity. This technique
+is called per-directory rewrites.</p>
+
+<p>The main difference with per-directory rewrites is that the path
+prefix of the directory containing the <code>.htaccess</code> file is
+stripped before matching in
+the <directive module="mod_rewrite">RewriteRule</directive>. In addition, the <directive module="mod_rewrite">RewriteBase</directive> should be used to assure the request is properly mapped.</p>
 
 </section>