From b24a96a731110dc4780928e6b44c8ba4081c2aa0 Mon Sep 17 00:00:00 2001
From: Rich Bowen <rbowen@apache.org>
Date: Sun, 5 Aug 2007 12:24:31 +0000
Subject: [PATCH] Trying to fill in some of the flags here, complete with
 detailed explanations and examples.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@562855 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/rewrite/flags.html.en | 48 +++++++++++++++++++++++++----
 docs/manual/rewrite/flags.xml     | 50 +++++++++++++++++++++++++++----
 2 files changed, 88 insertions(+), 10 deletions(-)

diff --git a/docs/manual/rewrite/flags.html.en b/docs/manual/rewrite/flags.html.en
index 6e05e7267a..366987357c 100644
--- a/docs/manual/rewrite/flags.html.en
+++ b/docs/manual/rewrite/flags.html.en
@@ -126,25 +126,63 @@ downloaded from your server.</p>
 RewriteRule \.exe - [F]
 </code></p></div>
 
-<p>This rule uses the "-" syntax for the rewrite target, which means
+<p>This example uses the "-" syntax for the rewrite target, which means
 that the requested URI is not modified.</p>
 
 
 
 <h3><a name="flag_g" id="flag_g">G|gone</a></h3>
-<p>Gone flag</p>
+<p>The [G] flag forces Apache to return a 410 Gone status with the
+response. This indicates that a resource used to be available, but is no
+longer available.</p>
 
 
 <h3><a name="flag_h" id="flag_h">H|handler</a></h3>
-<p>Handler flag</p>
+<p>Forces the resulting request to be handled with the specified
+handler. For example, one might use this to force all files without a
+file extension to be parsed by the php handler:</p>
+
+<div class="example"><p><code>
+RewriteRule !\. - [H=application/x-httpd-php .php]
+</code></p></div>
+
+<p>
+The regular expression above - <code>!\.</code> - will match any request
+that does not contain the literal <code>.</code> character.
+</p>
 
 
 <h3><a name="flag_l" id="flag_l">L|last</a></h3>
-<p>Last flag</p>
+<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
+<code>.htaccess</code> files or in 
+<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
+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
+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.</p>
 
 
 <h3><a name="flag_n" id="flag_n">N|next</a></h3>
-<p>Next round flag</p>
+<p>
+The [N] flag causes the ruleset to start over again from the top. Use
+with extreme caution, as it may result in loop.
+</p>
+
 
 
 <h3><a name="flag_nc" id="flag_nc">NC|nocase</a></h3>
diff --git a/docs/manual/rewrite/flags.xml b/docs/manual/rewrite/flags.xml
index afca0ec817..c9887a8103 100644
--- a/docs/manual/rewrite/flags.xml
+++ b/docs/manual/rewrite/flags.xml
@@ -134,25 +134,65 @@ downloaded from your server.</p>
 RewriteRule \.exe - [F]
 </example>
 
-<p>This rule uses the "-" syntax for the rewrite target, which means
+<p>This example uses the "-" syntax for the rewrite target, which means
 that the requested URI is not modified.</p>
 
 </section>
 
 <section id="flag_g"><title>G|gone</title>
-<p>Gone flag</p>
+<p>The [G] flag forces Apache to return a 410 Gone status with the
+response. This indicates that a resource used to be available, but is no
+longer available.</p>
 </section>
 
 <section id="flag_h"><title>H|handler</title>
-<p>Handler flag</p>
+<p>Forces the resulting request to be handled with the specified
+handler. For example, one might use this to force all files without a
+file extension to be parsed by the php handler:</p>
+
+<example>
+RewriteRule !\. - [H=application/x-httpd-php .php]
+</example>
+
+<p>
+The regular expression above - <code>!\.</code> - will match any request
+that does not contain the literal <code>.</code> character.
+</p>
 </section>
 
 <section id="flag_l"><title>L|last</title>
-<p>Last flag</p>
+<p>The [L] flag causes <module>mod_rewrite</module> 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 <directive
+module="mod_rewrite">RewriteRule</directive> in either
+<code>.htaccess</code> files or in 
+<directive type="section" module="core">Directory</directive> 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 
+<directive type="section" module="core">Directory</directive> 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 <directive
+module="mod_rewrite">RewriteRule</directive> 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.</p>
 </section>
 
 <section id="flag_n"><title>N|next</title>
-<p>Next round flag</p>
+<p>
+The [N] flag causes the ruleset to start over again from the top. Use
+with extreme caution, as it may result in loop.
+</p>
+
 </section>
 
 <section id="flag_nc"><title>NC|nocase</title>
-- 
2.40.0