try to make the mod_filter docs a little more approachable

 - more consistently refer to the filters declared via the harness as
   "smart filters"
 - reinforce that the providers are traditional filters.
 - drop some info about the optional type parameter
 - elaborate on examples

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

diff --git a/docs/manual/mod/mod_filter.xml b/docs/manual/mod/mod_filter.xml
index 5d3733319b4e4f15086af03dc96d8a0111e458f6..5f43b42c10b197c12e762737247e1c1bfd83287a 100644 (file)
--- a/docs/manual/mod/mod_filter.xml
+++ b/docs/manual/mod/mod_filter.xml
@@ -95,16 +95,14 @@
     <dl>
     <dt>Declare Filters</dt>
     <dd>The <directive module="mod_filter">FilterDeclare</directive> 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 <directive module="mod_filter">FilterProvider</directive>
     directive registers a provider with a filter. The filter may have
     been declared with <directive module="mod_filter"
     >FilterDeclare</directive>; 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 <directive module="mod_filter"
     >FilterProvider</directive> is an expression: the provider will be
@@ -152,7 +150,9 @@
 <section id="examples"><title>Examples</title>
     <dl>
     <dt>Server side Includes (SSI)</dt>
-    <dd>A simple case of replacing <directive>AddOutputFilterByType</directive>
+    <dd>A simple case replacing <directive>AddOutputFilterByType</directive>.
+        This example creates a new smart filter named "SSI" that conditionally leverates
+        the "INCLUDES" filter from <module>mod_include</module> as a provider.
     <highlight language="config">
 FilterDeclare SSI
 FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
@@ -170,18 +170,25 @@ FilterChain SSI
     </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 <module>mod_deflate</module>'s
+        INFLATE filter only if "gzip" is NOT in the Accept-Encoding header.  
+        The gzip smart filter runs with type CONTENT_SET.
     <highlight language="config">
 FilterDeclare gzip CONTENT_SET
-FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
+FilterProvider gzip INFLATE "%{req:Accept-Encoding} !~ /gzip/"
 FilterChain gzip
     </highlight>
     </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.
     <highlight language="config">
 FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
 FilterProvider unpack gif_unpack  "%{CONTENT_TYPE} = 'image/gif'"
@@ -297,7 +304,7 @@ being moved to <module>mod_filter</module> in version 2.3.7</compatibility>
 <directivesynopsis>
 <name>FilterDeclare</name>
 <description>Declare a smart filter</description>
-<syntax>FilterDeclare <var>filter-name</var> <var>[type]</var></syntax>
+<syntax>FilterDeclare <var>smart-filter-name</var> <var>[type]</var></syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context><context>.htaccess</context></contextlist>
 <override>Options</override>
@@ -305,7 +312,7 @@ being moved to <module>mod_filter</module> in version 2.3.7</compatibility>
 <usage>
     <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 <directive module="mod_filter">FilterProvider</directive>,
     <directive module="mod_filter">FilterChain</directive> and
     <directive module="mod_filter">FilterProtocol</directive> directives.</p>
@@ -321,7 +328,7 @@ being moved to <module>mod_filter</module> in version 2.3.7</compatibility>
 <directivesynopsis>
 <name>FilterProvider</name>
 <description>Register a content filter</description>
-<syntax>FilterProvider <var>filter-name</var> <var>provider-name</var>
+<syntax>FilterProvider <var>smart-filter-name</var> <var>provider-name</var>
  <var>expression</var></syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context><context>.htaccess</context></contextlist>
@@ -350,7 +357,7 @@ for a complete reference and examples.</seealso>
 <directivesynopsis>
 <name>FilterChain</name>
 <description>Configure the filter chain</description>
-<syntax>FilterChain [+=-@!]<var>filter-name</var> <var>...</var></syntax>
+<syntax>FilterChain [+=-@!]<var>smart-filter-name</var> <var>...</var></syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context><context>.htaccess</context></contextlist>
 <override>Options</override>
@@ -362,23 +369,23 @@ for a complete reference and examples.</seealso>
     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>
 </usage>
 </directivesynopsis>
@@ -386,7 +393,7 @@ for a complete reference and examples.</seealso>
 <directivesynopsis>
 <name>FilterProtocol</name>
 <description>Deal with correct HTTP protocol handling</description>
-<syntax>FilterProtocol <var>filter-name</var> [<var>provider-name</var>]
+<syntax>FilterProtocol <var>smart-filter-name</var> [<var>provider-name</var>]
     <var>proto-flags</var></syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context><context>.htaccess</context></contextlist>
@@ -399,9 +406,9 @@ for a complete reference and examples.</seealso>
     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
@@ -443,7 +450,7 @@ for a complete reference and examples.</seealso>
 <name>FilterTrace</name>
 <description>Get debug/diagnostic information from
     <module>mod_filter</module></description>
-<syntax>FilterTrace <var>filter-name</var> <var>level</var></syntax>
+<syntax>FilterTrace <var>smart-filter-name</var> <var>level</var></syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context></contextlist>