xforms for mod_filter

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

1 files changed, 48 insertions, 41 deletions

diff --git a/docs/manual/mod/mod_filter.html.en b/docs/manual/mod/mod_filter.html.en
index 155d97a1fc..7c06932f13 100644
--- a/docs/manual/mod/mod_filter.html.en
+++ b/docs/manual/mod/mod_filter.html.en
@@ -70,7 +70,7 @@
 <li><a href="#comments_section">Comments</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="smart" id="smart">Smart Filtering</a></h2>
+<h2><a name="smart" id="smart">Smart Filtering</a><a title="Permanent link" href="#smart" class="permalink">&para;</a></h2>
     <p>In the traditional filtering model, filters are inserted unconditionally
     using <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> and family.
     Each filter then needs to determine whether to run, and there is little
@@ -84,7 +84,7 @@
     flexibility offered by <code class="directive">AddOutputFilterByType</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="terms" id="terms">Filter Declarations, Providers and Chains</a></h2>
+<h2><a name="terms" id="terms">Filter Declarations, Providers and Chains</a><a title="Permanent link" href="#terms" class="permalink">&para;</a></h2>
     <p class="figure">
     <img src="../images/mod_filter_old.gif" width="160" height="310" alt="[This image displays the traditional filter model]" /><br />
     <dfn>Figure 1:</dfn> The traditional filter model</p>
@@ -114,22 +114,20 @@
     is equivalent to inserting the provider filter directly into the chain.</p>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
-<h2><a name="config" id="config">Configuring the Chain</a></h2>
+<h2><a name="config" id="config">Configuring the Chain</a><a title="Permanent link" href="#config" class="permalink">&para;</a></h2>
     <p>There are three stages to configuring a filter chain with
     <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>. For details of the directives, see below.</p>
 
     <dl>
     <dt>Declare Filters</dt>
     <dd>The <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code> directive
-    declares a filter, assigning it a name and filter type.  Required
-    only if the filter is not the default type AP_FTYPE_RESOURCE.</dd>
-
+        declares a new smart filter, assigning it a name and optional filter 
+        type.</dd>
     <dt>Register Providers</dt>
     <dd>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code>
     directive registers a provider with a filter. The filter may have
     been declared with <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code>; if not, FilterProvider will implicitly
-    declare it with the default type AP_FTYPE_RESOURCE. The provider
-    must have been
+    declare it.  The provider must have been
     registered with <code>ap_register_output_filter</code> by some module.
     The final argument to <code class="directive"><a href="#filterprovider">FilterProvider</a></code> is an expression: the provider will be
     selected to run for a request if and only if the expression evaluates
@@ -148,7 +146,7 @@
 </dl>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
-<h2><a name="errordocs" id="errordocs">Filtering and Response Status</a></h2>
+<h2><a name="errordocs" id="errordocs">Filtering and Response Status</a><a title="Permanent link" href="#errordocs" class="permalink">&para;</a></h2>
     <p>mod_filter normally only runs filters on responses with
     HTTP status 200 (OK).  If you want to filter documents with
     other response statuses, you can set the <var>filter-errordocs</var>
@@ -157,7 +155,7 @@
     expression conditions with <code class="directive">FilterProvider</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="upgrade" id="upgrade">Upgrading from Apache HTTP Server 2.2 Configuration</a></h2>
+<h2><a name="upgrade" id="upgrade">Upgrading from Apache HTTP Server 2.2 Configuration</a><a title="Permanent link" href="#upgrade" class="permalink">&para;</a></h2>
     <p>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code>
     directive has changed from httpd 2.2: the <var>match</var> and
     <var>dispatch</var> arguments are replaced with a single but
@@ -174,10 +172,12 @@
     replaced by regular expression matches.</p>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
-<h2><a name="examples" id="examples">Examples</a></h2>
+<h2><a name="examples" id="examples">Examples</a><a title="Permanent link" href="#examples" class="permalink">&para;</a></h2>
     <dl>
     <dt>Server side Includes (SSI)</dt>
-    <dd>A simple case of replacing <code class="directive">AddOutputFilterByType</code>
+    <dd>A simple case replacing <code class="directive">AddOutputFilterByType</code>.
+        This example creates a new smart filter named "SSI" that conditionally leverates
+        the "INCLUDES" filter from <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> as a provider.
     <pre class="prettyprint lang-config">FilterDeclare SSI
 FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
 FilterChain SSI</pre>
@@ -193,17 +193,24 @@ FilterChain SSI</pre>
     </dd>
 
     <dt>Emulating mod_gzip with mod_deflate</dt>
-    <dd>Insert INFLATE filter only if "gzip" is NOT in the
-    Accept-Encoding header.  This filter runs with ftype CONTENT_SET.
+    <dd>This example demonstrates the dynamic properties granted to traditional
+        filters when a smart filter is constructed around them. A new smart filter
+        named "gzip" is created that dynamically inserts <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code>'s
+        INFLATE filter only if "gzip" is NOT in the Accept-Encoding header.  
+        The gzip smart filter runs with type CONTENT_SET.
     <pre class="prettyprint lang-config">FilterDeclare gzip CONTENT_SET
-FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
+FilterProvider gzip INFLATE "%{req:Accept-Encoding} !~ /gzip/"
 FilterChain gzip</pre>
 
     </dd>
 
     <dt>Image Downsampling</dt>
-    <dd>Suppose we want to downsample all web images, and have filters
-    for GIF, JPEG and PNG.
+    <dd>This example demonstrates further abstractions that the smart filtering.
+        Suppose we want to downsample all web images, and have different 
+        filter providers for manipulating GIF, JPEG and PNG
+        The configuration defines smart filters "unpack" and "repack" via 
+        the harness that invokes the right underlying filter providers based on
+        the content type at runtime.
     <pre class="prettyprint lang-config">FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
 FilterProvider unpack gif_unpack  "%{CONTENT_TYPE} = 'image/gif'"
 FilterProvider unpack png_unpack  "%{CONTENT_TYPE} = 'image/png'"
@@ -222,7 +229,7 @@ FilterProvider repack png_pack  "%{CONTENT_TYPE} = 'image/png'"
     </dl>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
-<h2><a name="protocol" id="protocol">Protocol Handling</a></h2>
+<h2><a name="protocol" id="protocol">Protocol Handling</a><a title="Permanent link" href="#protocol" class="permalink">&para;</a></h2>
     <p>Historically, each filter is responsible for ensuring that whatever
     changes it makes are correctly represented in the HTTP response headers,
     and that it does not run when it would make an illegal change.  This
@@ -263,7 +270,7 @@ FilterProvider repack png_pack  "%{CONTENT_TYPE} = 'image/png'"
     Modules using it should test it carefully.</p>
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AddOutputFilterByType" id="AddOutputFilterByType">AddOutputFilterByType</a> <a name="addoutputfilterbytype" id="addoutputfilterbytype">Directive</a></h2>
+<div class="directive-section"><h2><a name="AddOutputFilterByType" id="AddOutputFilterByType">AddOutputFilterByType</a> <a name="addoutputfilterbytype" id="addoutputfilterbytype">Directive</a><a title="Permanent link" href="#addoutputfilterbytype" class="permalink">&para;</a></h2>
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>assigns an output filter to a particular media-type</td></tr>
 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AddOutputFilterByType <var>filter</var>[;<var>filter</var>...]
@@ -312,10 +319,10 @@ being moved to <code class="module"><a href="../mod/mod_filter.html">mod_filter<
 </ul>
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="FilterChain" id="FilterChain">FilterChain</a> <a name="filterchain" id="filterchain">Directive</a></h2>
+<div class="directive-section"><h2><a name="FilterChain" id="FilterChain">FilterChain</a> <a name="filterchain" id="filterchain">Directive</a><a title="Permanent link" href="#filterchain" class="permalink">&para;</a></h2>
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the filter chain</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterChain [+=-@!]<var>filter-name</var> <var>...</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterChain [+=-@!]<var>smart-filter-name</var> <var>...</var></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>Options</td></tr>
 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
@@ -327,31 +334,31 @@ being moved to <code class="module"><a href="../mod/mod_filter.html">mod_filter<
     determines what to do:</p>
 
     <dl>
-    <dt><code>+<var>filter-name</var></code></dt>
+    <dt><code>+<var>smart-filter-name</var></code></dt>
     <dd>Add <var>filter-name</var> to the end of the filter chain</dd>
 
-    <dt><code>@<var>filter-name</var></code></dt>
-    <dd>Insert <var>filter-name</var> at the start of the filter chain</dd>
+    <dt><code>@<var>smart-filter-name</var></code></dt>
+    <dd>Insert <var>smart-filter-name</var> at the start of the filter chain</dd>
 
-    <dt><code>-<var>filter-name</var></code></dt>
-    <dd>Remove <var>filter-name</var> from the filter chain</dd>
+    <dt><code>-<var>smart-filter-name</var></code></dt>
+    <dd>Remove <var>smart-filter-name</var> from the filter chain</dd>
 
-    <dt><code>=<var>filter-name</var></code></dt>
-    <dd>Empty the filter chain and insert <var>filter-name</var></dd>
+    <dt><code>=<var>smart-filter-name</var></code></dt>
+    <dd>Empty the filter chain and insert <var>smart-filter-name</var></dd>
 
     <dt><code>!</code></dt>
     <dd>Empty the filter chain</dd>
 
-    <dt><code><var>filter-name</var></code></dt>
-    <dd>Equivalent to <code>+<var>filter-name</var></code></dd>
+    <dt><code><var>smart-filter-name</var></code></dt>
+    <dd>Equivalent to <code>+<var>smart-filter-name</var></code></dd>
     </dl>
 
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="FilterDeclare" id="FilterDeclare">FilterDeclare</a> <a name="filterdeclare" id="filterdeclare">Directive</a></h2>
+<div class="directive-section"><h2><a name="FilterDeclare" id="FilterDeclare">FilterDeclare</a> <a name="filterdeclare" id="filterdeclare">Directive</a><a title="Permanent link" href="#filterdeclare" class="permalink">&para;</a></h2>
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare a smart filter</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterDeclare <var>filter-name</var> <var>[type]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterDeclare <var>smart-filter-name</var> <var>[type]</var></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>Options</td></tr>
 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
@@ -359,7 +366,7 @@ being moved to <code class="module"><a href="../mod/mod_filter.html">mod_filter<
 </table>
     <p>This directive declares an output filter together with a
     header or environment variable that will determine runtime
-    configuration.  The first argument is a <var>filter-name</var>
+    configuration.  The first argument is a <var>smart-filter-name</var>
     for use in <code class="directive"><a href="#filterprovider">FilterProvider</a></code>,
     <code class="directive"><a href="#filterchain">FilterChain</a></code> and
     <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> directives.</p>
@@ -372,10 +379,10 @@ being moved to <code class="module"><a href="../mod/mod_filter.html">mod_filter<
 
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="FilterProtocol" id="FilterProtocol">FilterProtocol</a> <a name="filterprotocol" id="filterprotocol">Directive</a></h2>
+<div class="directive-section"><h2><a name="FilterProtocol" id="FilterProtocol">FilterProtocol</a> <a name="filterprotocol" id="filterprotocol">Directive</a><a title="Permanent link" href="#filterprotocol" class="permalink">&para;</a></h2>
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deal with correct HTTP protocol handling</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProtocol <var>filter-name</var> [<var>provider-name</var>]
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProtocol <var>smart-filter-name</var> [<var>provider-name</var>]
     <var>proto-flags</var></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>Options</td></tr>
@@ -388,9 +395,9 @@ being moved to <code class="module"><a href="../mod/mod_filter.html">mod_filter<
     filter.</p>
 
     <p>There are two forms of this directive.  With three arguments, it
-    applies specifically to a <var>filter-name</var> and a
+    applies specifically to a <var>smart-filter-name</var> and a
     <var>provider-name</var> for that filter.
-    With two arguments it applies to a <var>filter-name</var> whenever the
+    With two arguments it applies to a <var>smart-filter-name</var> whenever the
     filter runs <em>any</em> provider.</p>
 
     <p>Flags specified with this directive are merged with the flags
@@ -428,10 +435,10 @@ being moved to <code class="module"><a href="../mod/mod_filter.html">mod_filter<
 
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="FilterProvider" id="FilterProvider">FilterProvider</a> <a name="filterprovider" id="filterprovider">Directive</a></h2>
+<div class="directive-section"><h2><a name="FilterProvider" id="FilterProvider">FilterProvider</a> <a name="filterprovider" id="filterprovider">Directive</a><a title="Permanent link" href="#filterprovider" class="permalink">&para;</a></h2>
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Register a content filter</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProvider <var>filter-name</var> <var>provider-name</var>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProvider <var>smart-filter-name</var> <var>provider-name</var>
  <var>expression</var></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>Options</td></tr>
@@ -460,11 +467,11 @@ for a complete reference and examples.</li>
 </ul>
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="FilterTrace" id="FilterTrace">FilterTrace</a> <a name="filtertrace" id="filtertrace">Directive</a></h2>
+<div class="directive-section"><h2><a name="FilterTrace" id="FilterTrace">FilterTrace</a> <a name="filtertrace" id="filtertrace">Directive</a><a title="Permanent link" href="#filtertrace" class="permalink">&para;</a></h2>
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Get debug/diagnostic information from
     <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterTrace <var>filter-name</var> <var>level</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterTrace <var>smart-filter-name</var> <var>level</var></code></td></tr>
 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>