From: André Malo <nd@apache.org>
Date: Fri, 15 Oct 2004 21:51:46 +0000 (+0000)
Subject: formatting
X-Git-Tag: 2.1.1~139
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2e86ec84d39e76f54eda176330b894eb81231eb6;p=apache

formatting


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

diff --git a/docs/manual/mod/mod_filter.xml b/docs/manual/mod/mod_filter.xml
index 73a7b3e28b..d73cf9ce08 100644
--- a/docs/manual/mod/mod_filter.xml
+++ b/docs/manual/mod/mod_filter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 
 <!--
  Copyright 2004 The Apache Software Foundation
@@ -26,171 +26,188 @@
 <status>Extension</status>
 <sourcefile>mod_filter.c</sourcefile>
 <identifier>filter_module</identifier>
-<compatibility>Apache 2.0 and higher</compatibility>
+<compatibility>Version 2.1 and higher</compatibility>
 
 <summary>
-<p>This module enables smart, context-sensitive configuration of
-output content filters.  For example, apache can be configured to
-process different content-types through different filters, even
-when the content-type is not known in advance (e.g. in a proxy).
-</p>
-<p>mod_filter works by introducing indirection into the filter
-chain.  Instead of inserting filters in the chain, we insert
-a filter harness which in turn dispatches conditionally
-to a filter provider.  Any content filter may be used as a provider
-to mod_filter; no change to existing filter modules is required
-(although it may be possible to simplify them).
-</p>
+    <p>This module enables smart, context-sensitive configuration of
+    output content filters.  For example, apache can be configured to
+    process different content-types through different filters, even
+    when the content-type is not known in advance (e.g. in a proxy).</p>
+
+    <p>mod_filter works by introducing indirection into the filter
+    chain.  Instead of inserting filters in the chain, we insert
+    a filter harness which in turn dispatches conditionally
+    to a filter provider.  Any content filter may be used as a provider
+    to mod_filter; no change to existing filter modules is required
+    (although it may be possible to simplify them).</p>
 </summary>
 
 <section id="smart"><title>Smart Filtering</title>
-<p>In the traditional filtering model, filters are inserted unconditionally
-using <directive module="mod_mime">AddOutputFilter</directive> and family.
-Each filter then needs to determine whether to run, and there is little
-flexibility available for server admins to allow the chain to be
-configured dynamically.</p>
-<p>mod_filter by contrast gives server administrators a great deal of
-flexibility in configuring the filter chain.  In fact, filters can be
-inserted based on any Request Header, Response Header or Environment
-Variable.  This generalises the limited flexibility offered by
-<directive module="core">AddOutputFilterByType</directive>, and fixes
-it to work correctly with dynamic content, regardless of the
-content generator.  The ability to dispatch based on Environment
-Variables offers the full flexibility of configuration with
-<module>mod_rewrite</module> to anyone who needs it.</p>
+    <p>In the traditional filtering model, filters are inserted unconditionally
+    using <directive module="mod_mime">AddOutputFilter</directive> and family.
+    Each filter then needs to determine whether to run, and there is little
+    flexibility available for server admins to allow the chain to be
+    configured dynamically.</p>
 
+    <p>mod_filter by contrast gives server administrators a great deal of
+    flexibility in configuring the filter chain.  In fact, filters can be
+    inserted based on any Request Header, Response Header or Environment
+    Variable.  This generalises the limited flexibility offered by
+    <directive module="core">AddOutputFilterByType</directive>, and fixes
+    it to work correctly with dynamic content, regardless of the
+    content generator.  The ability to dispatch based on Environment
+    Variables offers the full flexibility of configuration with
+    <module>mod_rewrite</module> to anyone who needs it.</p>
 </section>
+
 <section id="terms"><title>Filter Declarations, Providers and Chains</title>
-<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>
-
-<p>In the traditional model, output filters are a simple chain
-from the content generator (handler) to the client.  This works well
-provided the filter chain can be correctly configured, but presents
-problems when the filters need to be configured dynamically based on
-the outcome of the handler.</p>
-<p class="figure">
-<img src="../images/mod_filter_new.gif" width="423" height="331"
-alt="[This image shows the mod_filter model]"/><br />
-<dfn>Figure 2:</dfn> The <module>mod_filter</module> model</p>
-<p>mod_filter works by introducing indirection into the filter
-chain.  Instead of inserting filters in the chain, we insert
-a filter harness which in turn dispatches conditionally
-to a filter provider.  Any content filter may be used as a provider
-to mod_filter; no change to existing filter modules is required
-(although it may be possible to simplify them).  There can be
-multiple providers for one filter, but no more than one provider will
-run for any single request.
-</p>
-<p>A filter chain comprises any number of instances of the filter
-harness, each of which may have any number of providers.  A special
-case is that of a single provider with unconditional dispatch: this
-is equivalent to inserting the provider filter directly into the chain.
-</p>
+    <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>
+
+    <p>In the traditional model, output filters are a simple chain
+    from the content generator (handler) to the client.  This works well
+    provided the filter chain can be correctly configured, but presents
+    problems when the filters need to be configured dynamically based on
+    the outcome of the handler.</p>
+
+    <p class="figure">
+    <img src="../images/mod_filter_new.gif" width="423" height="331"
+    alt="[This image shows the mod_filter model]"/><br />
+    <dfn>Figure 2:</dfn> The <module>mod_filter</module> model</p>
+
+    <p>mod_filter works by introducing indirection into the filter
+    chain.  Instead of inserting filters in the chain, we insert
+    a filter harness which in turn dispatches conditionally
+    to a filter provider.  Any content filter may be used as a provider
+    to mod_filter; no change to existing filter modules is required
+    (although it may be possible to simplify them).  There can be
+    multiple providers for one filter, but no more than one provider will
+    run for any single request.</p>
+
+    <p>A filter chain comprises any number of instances of the filter
+    harness, each of which may have any number of providers.  A special
+    case is that of a single provider with unconditional dispatch: this
+    is equivalent to inserting the provider filter directly into the chain.</p>
 </section>
+
 <section id="config"><title>Configuring the Chain</title>
-<p>There are three stages to configuring a filter chain with mod_filter.
-For details of the directives, see below.</p>
-<dl>
-<dt>Declare Filters</dt>
-<dd>The <directive>FilterDeclare</directive> directive declares a filter,
-assigning it a name and a dispatch criterion.</dd>
-<dt>Register Providers</dt>
-<dd>The <directive>FilterProvider</directive> directive registers a provider with a filter.
-The filter must have been registered with <directive>FilterDeclare</directive>.
-The provider must have been registered with
-<code>ap_register_output_filter</code> by some module.  The final argument
-to <directive>FilterProvider</directive> is a match string, that will be checked against
-the filter's dispatch criterion to determine whether to run this provider.</dd>
-<dt>Configure the Chain</dt>
-<dd>The above directives build components of a smart filter chain,
-but do not configure it to run.  The <directive>FilterChain</directive> directive
-builds a filter chain from smart filters declared, offering the
-flexibility to insert filters at the beginning or end of the chain,
-remove a filter, or clear the chain.</dd>
+    <p>There are three stages to configuring a filter chain with mod_filter.
+    For details of the directives, see below.</p>
+
+    <dl>
+    <dt>Declare Filters</dt>
+    <dd>The <directive>FilterDeclare</directive> directive declares a filter,
+    assigning it a name and a dispatch criterion.</dd>
+
+    <dt>Register Providers</dt>
+    <dd>The <directive>FilterProvider</directive> directive registers a
+    provider with a filter. The filter must have been registered with
+    <directive>FilterDeclare</directive>. The provider must have been
+    registered with <code>ap_register_output_filter</code> by some module.
+    The final argument to <directive>FilterProvider</directive> is a match
+    string, that will be checked against the filter's dispatch criterion
+    to determine whether to run this provider.</dd>
+
+    <dt>Configure the Chain</dt>
+    <dd>The above directives build components of a smart filter chain,
+    but do not configure it to run.  The <directive>FilterChain</directive>
+    directive builds a filter chain from smart filters declared, offering the
+    flexibility to insert filters at the beginning or end of the chain,
+    remove a filter, or clear the chain.</dd>
 </dl>
 </section>
+
 <section id="examples"><title>Examples</title>
-<dl>
-<dt>Serverside Includes (SSI)</dt>
-<dd>
-<p>A simple case of using mod_filter in place of
-<code>AddOutputFilterByType</code></p>
-<example>
-FilterDeclare SSI Content-Type<br/>
-FilterProvider SSI INCLUDES $text/html<br/>
-FilterChain SSI<br/>
-</example>
-</dd>
-<dt>Serverside Includes (SSI)</dt>
-<dd>
-<p>The same as the above but dispatching on handler (classic
-SSI behaviour; .shtml files get processed).</p>
-<example>
-FilterDeclare SSI Handler<br/>
-FilterProvider SSI INCLUDES server-parsed<br/>
-FilterChain SSI<br/>
-</example>
-</dd>
-<dt>Emulating mod_gzip with mod_deflate</dt>
-<dd>
-<p>Insert INFLATE filter only if "gzip" is NOT in the
-Accept-Encoding header.</p>
-<example>
-FilterDeclare gzip req=Accept-Encoding<br/>
-FilterProvider gzip inflate !$gzip<br/>
-FilterChain gzip<br/>
-</example>
-</dd>
-<dt>Image Downsampling</dt>
-<dd>
-<p>Suppose we want to downsample all web images, and have filters
-for GIF, JPEG and PNG.</p>
-<example>
-FilterDeclare unpack Content-Type<br/>
-FilterProvider unpack jpeg_unpack $image/jpeg<br/>
-FilterProvider unpack gif_unpack $image/gif<br/>
-FilterProvider unpack png_unpack $image/png<br/>
-FilterDeclare downsample Content-Type<br/>
-FilterProvider downsample downsample_filter $image<br/>
-FilterProtocol downsample "change=yes"<br/>
-FilterDeclare repack Content-Type<br/>
-FilterProvider repack jpeg_pack $image/jpeg<br/>
-FilterProvider repack gif_pack $image/gif<br/>
-FilterProvider repack png_pack $image/png<br/>
-&lt;Location /image-filter&gt;<br/>
-FilterChain unpack downsample repack<br/>
-&lt;/Location&gt;
-</example>
-</dd>
-</dl>
+    <dl>
+    <dt>Server side Includes (SSI)</dt>
+    <dd>A simple case of using mod_filter in place of
+    <directive module="core">AddOutputFilterByType</directive>
+    <example>
+      FilterDeclare SSI Content-Type<br/>
+      FilterProvider SSI INCLUDES $text/html<br/>
+      FilterChain SSI
+    </example>
+    </dd>
+
+    <dt>Server side Includes (SSI)</dt>
+    <dd>The same as the above but dispatching on handler (classic
+    SSI behaviour; .shtml files get processed).
+    <example>
+      FilterDeclare SSI Handler<br/>
+      FilterProvider SSI INCLUDES server-parsed<br/>
+      FilterChain SSI
+    </example>
+    </dd>
+
+    <dt>Emulating mod_gzip with mod_deflate</dt>
+    <dd>Insert INFLATE filter only if "gzip" is NOT in the
+    Accept-Encoding header.
+    <example>
+      FilterDeclare gzip req=Accept-Encoding<br/>
+      FilterProvider gzip inflate !$gzip<br/>
+      FilterChain gzip
+    </example>
+    </dd>
+
+    <dt>Image Downsampling</dt>
+    <dd>Suppose we want to downsample all web images, and have filters
+    for GIF, JPEG and PNG.
+    <example>
+      FilterDeclare unpack Content-Type<br/>
+      FilterProvider unpack jpeg_unpack $image/jpeg<br/>
+      FilterProvider unpack gif_unpack $image/gif<br/>
+      FilterProvider unpack png_unpack $image/png<br/>
+      <br />
+      FilterDeclare downsample Content-Type<br/>
+      FilterProvider downsample downsample_filter $image<br/>
+      FilterProtocol downsample "change=yes"<br/>
+      <br />
+      FilterDeclare repack Content-Type<br/>
+      FilterProvider repack jpeg_pack $image/jpeg<br/>
+      FilterProvider repack gif_pack $image/gif<br/>
+      FilterProvider repack png_pack $image/png<br/>
+      &lt;Location /image-filter&gt;<br/>
+      <indent>
+        FilterChain unpack downsample repack<br/>
+      </indent>
+      &lt;/Location&gt;
+    </example>
+    </dd>
+    </dl>
 </section>
+
 <section id="protocol"><title>Protocol Handling</title>
-<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
-imposes a burden on filter authors to re-implement some common
-functionality in every filter:</p>
-<ul>
-<li>Many filters will change the content, invalidating existing content
-tags, checksums, hashes, and lengths.</li>
-<li>Filters that require an entire, unbroken response in input need to
-ensure they don't get byteranges from a backend.</li>
-<li>Filters that transform output in a filter need to ensure they don't
-violate a <code>Cache-Control: no-transform</code> header from the
-backend.</li>
-<li>Filters may make responses uncacheable.</li>
-</ul>
-<p>mod_filter aims to offer generic handling of these details of filter
-implementation, reducing the complexity required of content filter modules.
-This is work-in-progress; the <directive>FilterProtocol</directive>
-implements some of this functionality, but there are no API calls yet.</p>
-<p>At the same time, mod_filter should not interfere with a filter that
-wants to handle all aspects of the protocol.  By default (i.e. in the
-absence of any <directive>FilterProtocol</directive> directives), mod_filter
-will leave the headers untouched.</p>
+    <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
+    imposes a burden on filter authors to re-implement some common
+    functionality in every filter:</p>
+
+    <ul>
+    <li>Many filters will change the content, invalidating existing content
+    tags, checksums, hashes, and lengths.</li>
+
+    <li>Filters that require an entire, unbroken response in input need to
+    ensure they don't get byteranges from a backend.</li>
+
+    <li>Filters that transform output in a filter need to ensure they don't
+    violate a <code>Cache-Control: no-transform</code> header from the
+    backend.</li>
+
+    <li>Filters may make responses uncacheable.</li>
+    </ul>
+
+    <p>mod_filter aims to offer generic handling of these details of filter
+    implementation, reducing the complexity required of content filter modules.
+    This is work-in-progress; the <directive>FilterProtocol</directive>
+    implements some of this functionality, but there are no API calls yet.</p>
+
+    <p>At the same time, mod_filter should not interfere with a filter that
+    wants to handle all aspects of the protocol.  By default (i.e. in the
+    absence of any <directive>FilterProtocol</directive> directives), mod_filter
+    will leave the headers untouched.</p>
 </section>
 
 <directivesynopsis>
@@ -203,71 +220,83 @@ will leave the headers untouched.</p>
 <context>directory</context><context>.htaccess</context></contextlist>
 
 <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 <code>filter-name</code>
-for use in <directive>FilterProvider</directive>,
-<directive>FilterChain</directive> and
-<directive>FilterProtocol</directive> directives.</p>
-<p>The second is a string with optional <code>req=</code>,
-<code>resp=</code> or <code>env=</code> prefix causing it
-to dispatch on (respectively) the request header, response
-header, or environment variable named.  In the absence of a
-prefix, it defaults to a response header.  A special case is the
-word "handler", which causes mod_filter to dispatch on the handler.</p>
-<p>The final (optional) argument
-is the type of filter, and takes values of <var>ap_filter_type</var>
-- namely <var>RESOURCE</var> (the default), <var>CONTENT_SET</var>,
-<var>PROTOCOL</var>, <var>TRANSCODE</var>, <var>CONNECTION</var>
-or <var>NETWORK</var>.
-</p>
+    <p>This directive declares an output filter together with a
+    header or environment variable that will determine runtime
+    configuration.  The first argument is a <code>filter-name</code>
+    for use in <directive>FilterProvider</directive>,
+    <directive>FilterChain</directive> and
+    <directive>FilterProtocol</directive> directives.</p>
 
+    <p>The second is a string with optional <code>req=</code>,
+    <code>resp=</code> or <code>env=</code> prefix causing it
+    to dispatch on (respectively) the request header, response
+    header, or environment variable named.  In the absence of a
+    prefix, it defaults to a response header.  A special case is the
+    word "handler", which causes mod_filter to dispatch on the handler.</p>
+
+    <p>The final (optional) argument
+    is the type of filter, and takes values of <var>ap_filter_type</var>
+    - namely <var>RESOURCE</var> (the default), <var>CONTENT_SET</var>,
+    <var>PROTOCOL</var>, <var>TRANSCODE</var>, <var>CONNECTION</var>
+    or <var>NETWORK</var>.</p>
 </usage>
 </directivesynopsis>
 
 <directivesynopsis>
 <name>FilterProvider</name>
 <description>Register a content filter</description>
-<syntax>FilterProvider <var>filter-name</var> <var>provider-name</var> <var>match</var></syntax>
+<syntax>FilterProvider <var>filter-name</var> <var>provider-name</var>
+    <var>match</var></syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context><context>.htaccess</context></contextlist>
 
 <usage>
-<p>This directive registers a <em>provider</em> for the smart filter.
-The provider will be called if and only if the <var>match</var> declared
-here matches the value of the header or environment variable declared
-as <var>dispatch</var> in the <directive>FilterDeclare</directive>
-directive that declared <var>filter-name</var>.</p>
-<p><var>filter-name</var> must have been declared with 
-<directive>FilterDeclare</directive>.  <var>provider-name</var> must have
-been registered by loading a module that registers the name with
-<code>ap_register_output_filter</code>.</p>
-<p>The <var>match</var> argument specifies a match that will be applied to
-the filter's <var>dispatch</var> criterion.  The match may be a string
-match (exact match or substring), a regexp, an integer (greater, lessthan
-or equals), or unconditional.  The first characters of the <var>match</var>
-argument determines this:</p>
-<p><strong>First</strong>, if the first character is an exclamation mark
-<strong>!</strong>, this reverses the rule, so the provider will be used
-if and only if the match <em>fails</em>.</p>
-<p><strong>Second</strong>, it interprets the first character excluding
-any leading ! as follows:</p>
-<dl>
-<dt>default</dt>
-<dd>exact match</dd>
-<dt>$</dt>
-<dd>substring match</dd>
-<dt>/</dt>
-<dd>regexp match</dd>
-<dt>=</dt>
-<dd>integer equality</dd>
-<dt>&lt;</dt>
-<dd>integer less-than</dd>
-<dt>&gt;</dt>
-<dd>integer greater-than</dd>
-<dt>*</dt>
-<dd>Unconditional match</dd>
-</dl>
+    <p>This directive registers a <em>provider</em> for the smart filter.
+    The provider will be called if and only if the <var>match</var> declared
+    here matches the value of the header or environment variable declared
+    as <var>dispatch</var> in the <directive>FilterDeclare</directive>
+    directive that declared <var>filter-name</var>.</p>
+
+    <p><var>filter-name</var> must have been declared with 
+    <directive>FilterDeclare</directive>.  <var>provider-name</var> must have
+    been registered by loading a module that registers the name with
+    <code>ap_register_output_filter</code>.</p>
+
+    <p>The <var>match</var> argument specifies a match that will be applied to
+    the filter's <var>dispatch</var> criterion.  The match may be a string
+    match (exact match or substring), a regexp, an integer (greater, lessthan
+    or equals), or unconditional.  The first characters of the <var>match</var>
+    argument determines this:</p>
+
+    <p><strong>First</strong>, if the first character is an exclamation mark
+    <strong>!</strong>, this reverses the rule, so the provider will be used
+    if and only if the match <em>fails</em>.</p>
+
+    <p><strong>Second</strong>, it interprets the first character excluding
+    any leading ! as follows:</p>
+
+    <dl>
+    <dt>default</dt>
+    <dd>exact match</dd>
+
+    <dt>$</dt>
+    <dd>substring match</dd>
+
+    <dt>/</dt>
+    <dd>regexp match</dd>
+
+    <dt>=</dt>
+    <dd>integer equality</dd>
+
+    <dt>&lt;</dt>
+    <dd>integer less-than</dd>
+
+    <dt>&gt;</dt>
+    <dd>integer greater-than</dd>
+
+    <dt>*</dt>
+    <dd>Unconditional match</dd>
+    </dl>
 </usage>
 </directivesynopsis>
 
@@ -279,29 +308,32 @@ any leading ! as follows:</p>
 <context>directory</context><context>.htaccess</context></contextlist>
 
 <usage>
-<p>This configures an actual filter chain, from declared filters.
-<directive>FilterChain</directive> takes any number of arguments,
-each optionally preceded with a single-character control that
-determines what to do:</p>
-<dl>
-<dt>+filter-name</dt>
-<dd>Add filter-name to the end of the filter chain</dd>
-<dt>@filter-name</dt>
-<dd>Insert filter-name at the start of the filter chain</dd>
-<dt>-filter-name</dt>
-<dd>Remove filter-name from the filter chain</dd>
-<dt>=filter-name</dt>
-<dd>Empty the filter chain and insert filter-name</dd>
-<dt>!</dt>
-<dd>Empty the filter chain</dd>
-<dt>filter-name</dt>
-<dd>Equivalent to +filter-name</dd>
-</dl>
-</usage>
+    <p>This configures an actual filter chain, from declared filters.
+    <directive>FilterChain</directive> takes any number of arguments,
+    each optionally preceded with a single-character control that
+    determines what to do:</p>
 
+    <dl>
+    <dt>+filter-name</dt>
+    <dd>Add filter-name to the end of the filter chain</dd>
 
-</directivesynopsis>
+    <dt>@filter-name</dt>
+    <dd>Insert filter-name at the start of the filter chain</dd>
+
+    <dt>-filter-name</dt>
+    <dd>Remove filter-name from the filter chain</dd>
 
+    <dt>=filter-name</dt>
+    <dd>Empty the filter chain and insert filter-name</dd>
+
+    <dt>!</dt>
+    <dd>Empty the filter chain</dd>
+
+    <dt>filter-name</dt>
+    <dd>Equivalent to +filter-name</dd>
+    </dl>
+</usage>
+</directivesynopsis>
 
 <directivesynopsis>
 <name>FilterProtocol</name>
@@ -309,31 +341,42 @@ determines what to do:</p>
 <syntax>FilterProtocol filter-name [provider-name] "proto-flags"</syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context><context>.htaccess</context></contextlist>
+
 <usage>
-<p>This directs mod_filter to deal with ensuring the filter doesn't run
-when it shouldn't, and that the HTTP response headers are correctly set
-taking into account the effects of the filter.</p>
-<p>There are two forms of this directive.  With three arguments, it
-applies specifically to a filter-name and a provider for that filter.
-With two arguments it applies to a filter-name whenever the filter runs
-<em>any</em> provider.</p>
-<p>proto-flags is one or more of</p>
-<dl>
-<dt>change=yes</dt>
-<dd>The filter changes the content, including possibly the content length</dd>
-<dt>change=1:1</dt>
-<dd>The filter changes the content, but will not change the content length</dd>
-<dt>byteranges=no</dt>
-<dd>The filter cannot work on byteranges and requires complete input</dd>
-<dt>proxy=no</dt>
-<dd>The filter should not run in a proxy context</dd>
-<dt>proxy=transform</dt>
-<dd>The filter transforms the response in a manner incompatible with
-the HTTP <code>Cache-Control: no-transform</code> header.</dd>
-<dt>cache=no</dt>
-<dd>The filter renders the output uncacheable (eg by introducing randomised
-content changes)</dd>
-</dl>
+    <p>This directs mod_filter to deal with ensuring the filter doesn't run
+    when it shouldn't, and that the HTTP response headers are correctly set
+    taking into account the effects of the filter.</p>
+
+    <p>There are two forms of this directive.  With three arguments, it
+    applies specifically to a filter-name and a provider for that filter.
+    With two arguments it applies to a filter-name whenever the filter runs
+    <em>any</em> provider.</p>
+
+    <p><var>proto-flags</var> is one or more of</p>
+
+    <dl>
+    <dt>change=yes</dt>
+    <dd>The filter changes the content, including possibly the content
+    length</dd>
+
+    <dt>change=1:1</dt>
+    <dd>The filter changes the content, but will not change the content
+    length</dd>
+
+    <dt>byteranges=no</dt>
+    <dd>The filter cannot work on byteranges and requires complete input</dd>
+
+    <dt>proxy=no</dt>
+    <dd>The filter should not run in a proxy context</dd>
+
+    <dt>proxy=transform</dt>
+    <dd>The filter transforms the response in a manner incompatible with
+    the HTTP <code>Cache-Control: no-transform</code> header.</dd>
+
+    <dt>cache=no</dt>
+    <dd>The filter renders the output uncacheable (eg by introducing randomised
+    content changes)</dd>
+    </dl>
 </usage>
 </directivesynopsis>
 
@@ -343,25 +386,29 @@ content changes)</dd>
 <syntax>FilterTrace filter-name level</syntax>
 <contextlist><context>server config</context><context>virtual host</context>
 <context>directory</context><context>.htaccess</context></contextlist>
+
 <usage>
-<p>This directive generates debug information from mod_filter.
-It is designed to help test and debug providers (filter modules), although
-it may also help with mod_filter itself.</p>
-<p>The debug output depends on the level set:</p>
-<dl>
-<dt>0 (default)</dt>
-<dd>No debug information is generated.</dd>
-<dt>1</dt>
-<dd>mod_filter will record buckets and brigades passing through the filter
-to the error log, before the provider has processed them.
-This is similar to the information generated by
-<a href="http://apache.webthing.com/mod_diagnostics/">mod_diagnostics</a>.
-</dd>
-<dt>2 (not yet implemented)</dt>
-<dd>Will dump the full data passing through to a tempfile before the provider.
-<strong>For single-user debug only</strong>; this will not
-support concurrent hits.</dd>
-</dl>
+    <p>This directive generates debug information from mod_filter.
+    It is designed to help test and debug providers (filter modules), although
+    it may also help with mod_filter itself.</p>
+
+    <p>The debug output depends on the level set:</p>
+    <dl>
+    <dt>0 (default)</dt>
+    <dd>No debug information is generated.</dd>
+
+    <dt>1</dt>
+    <dd>mod_filter will record buckets and brigades passing through the filter
+    to the error log, before the provider has processed them.
+    This is similar to the information generated by
+    <a href="http://apache.webthing.com/mod_diagnostics/">mod_diagnostics</a>.
+    </dd>
+
+    <dt>2 (not yet implemented)</dt>
+    <dd>Will dump the full data passing through to a tempfile before the
+    provider. <strong>For single-user debug only</strong>; this will not
+    support concurrent hits.</dd>
+    </dl>
 </usage>
 </directivesynopsis>