Hi Nick, can you take a pass through and make sure I haven't taken any steps backward?
On Sat, Apr 21, 2018 at 11:42 AM, <[email protected]> wrote: > Author: covener > Date: Sat Apr 21 15:42:03 2018 > New Revision: 1829713 > > URL: http://svn.apache.org/viewvc?rev=1829713&view=rev > Log: > 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 > > > Modified: > httpd/httpd/trunk/docs/manual/mod/mod_filter.xml > > Modified: httpd/httpd/trunk/docs/manual/mod/mod_filter.xml > URL: > http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_filter.xml?rev=1829713&r1=1829712&r2=1829713&view=diff > ============================================================================== > --- httpd/httpd/trunk/docs/manual/mod/mod_filter.xml (original) > +++ httpd/httpd/trunk/docs/manual/mod/mod_filter.xml Sat Apr 21 15:42:03 2018 > @@ -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</modul > <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</modul > <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</modul > <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.</ > <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.</ > 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.</ > <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.</ > 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.</ > <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> > > > -- Eric Covener [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
