httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From n.@apache.org
Subject cvs commit: httpd-2.0/docs/manual/mod mod_filter.xml
Date Fri, 15 Oct 2004 22:32:21 GMT
nd          2004/10/15 15:32:21

  Modified:    docs/manual/mod mod_filter.xml
  Log:
  markup
  
  Revision  Changes    Path
  1.6       +117 -118  httpd-2.0/docs/manual/mod/mod_filter.xml
  
  Index: mod_filter.xml
  ===================================================================
  RCS file: /home/cvs/httpd-2.0/docs/manual/mod/mod_filter.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -u -r1.5 -r1.6
  --- mod_filter.xml	15 Oct 2004 21:51:46 -0000	1.5
  +++ mod_filter.xml	15 Oct 2004 22:32:20 -0000	1.6
  @@ -34,12 +34,12 @@
       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
  +    <p><module>mod_filter</module> 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>
  +    to <module>mod_filter</module>; 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>
  @@ -49,11 +49,11 @@
       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
  +    <p><module>mod_filter</module> 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
  @@ -77,12 +77,12 @@
       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
  +    <p><module>mod_filter</module> 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
  +    to <module>mod_filter</module>; 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>
   
  @@ -93,36 +93,38 @@
   </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>
  +    <p>There are three stages to configuring a filter chain with
  +    <module>mod_filter</module>. 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>
  +    <dd>The <directive module="mod_filter">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
  +    <dd>The <directive module="mod_filter">FilterProvider</directive>
  +    directive registers a provider with a filter. The filter must have
  +    been registered with <directive module="mod_filter"
  +    >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>
  +    The final argument to <directive module="mod_filter"
  +    >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>
  +    but do not configure it to run.  The <directive module="mod_filter"
  +    >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>Server side Includes (SSI)</dt>
  -    <dd>A simple case of using mod_filter in place of
  +    <dd>A simple case of using <module>mod_filter</module> in place of
       <directive module="core">AddOutputFilterByType</directive>
       <example>
         FilterDeclare SSI Content-Type<br/>
  @@ -199,14 +201,16 @@
       <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
  +    <p><module>mod_filter</module> 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 module="mod_filter">FilterProtocol</directive> implements
  +    some of this functionality, but there are no API calls yet.</p>
  +
  +    <p>At the same time, <module>mod_filter</module> 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 module="mod_filter"
  +    >FilterProtocol</directive> directives), <module>mod_filter</module>
       will leave the headers untouched.</p>
   </section>
   
  @@ -214,31 +218,31 @@
   <name>FilterDeclare</name>
   <description>Declare a smart filter</description>
   <syntax>FilterDeclare <var>filter-name</var> [req|resp|env]=<var>dispatch</var>
  -<var>[type]</var>
  -</syntax>
  +    <var>[type]</var></syntax>
   <contextlist><context>server config</context><context>virtual host</context>
   <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>
  +    configuration.  The first argument is a <var>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>
   
       <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>
  +    word <code>handler</code>, which causes <module>mod_filter</module>
  +    to dispatch on the content 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>
  +    is the type of filter, and takes values of <code>ap_filter_type</code>
  +    - namely <code>RESOURCE</code> (the default), <code>CONTENT_SET</code>,
  +    <code>PROTOCOL</code>, <code>TRANSCODE</code>, <code>CONNECTION</code>
  +    or <code>NETWORK</code>.</p>
   </usage>
   </directivesynopsis>
   
  @@ -254,56 +258,46 @@
       <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
  +    as <var>dispatch</var> in the <directive module="mod_filter"
  +    >FilterDeclare</directive> directive that declared
  +    <var>filter-name</var>.</p>
  +
  +    <p><var>filter-name</var> must have been declared with
  +    <directive module="mod_filter">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>
  +    the filter's <var>dispatch</var> criterion.  The <var>match</var>
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
  +    (<code>!</code>), 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>
  +    any leading <code>!</code> as follows:</p>
   
  -    <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>
  +    <table style="zebra" border="yes">
  +    <tr><th>Character</th><th>Description</th></tr>
  +    <tr><td><em>(none)</em></td><td>exact match</td></tr>
  +    <tr><td><code>$</code></td><td>substring match</td></tr>
  +    <tr><td><code>/</code></td><td>regexp match</td></tr>
  +    <tr><td><code>=</code></td><td>integer equality</td></tr>
  +    <tr><td><code>&lt;</code></td><td>integer less-than</td></tr>
  +    <tr><td><code>&gt;</code></td><td>integer greater-than</td></tr>
  +    <tr><td><code>*</code></td><td>Unconditional match</td></tr>
  +    </table>
   </usage>
   </directivesynopsis>
   
   <directivesynopsis>
   <name>FilterChain</name>
   <description>Configure the filter chain</description>
  -<syntax>FilterChain ([+=-@!]<var>filter-name</var>)+</syntax>
  +<syntax>FilterChain [+=-@!]<var>filter-name</var> <var>...</var></syntax>
   <contextlist><context>server config</context><context>virtual host</context>
   <context>directory</context><context>.htaccess</context></contextlist>
   
  @@ -314,23 +308,23 @@
       determines what to do:</p>
   
       <dl>
  -    <dt>+filter-name</dt>
  -    <dd>Add filter-name to the end of the filter chain</dd>
  +    <dt><code>+<var>filter-name</var></code></dt>
  +    <dd>Add <var>filter-name</var> 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><code>@<var>filter-name</var></code></dt>
  +    <dd>Insert <var>filter-name</var> at the start of the filter chain</dd>
   
  -    <dt>-filter-name</dt>
  -    <dd>Remove filter-name from the filter chain</dd>
  +    <dt><code>-<var>filter-name</var></code></dt>
  +    <dd>Remove <var>filter-name</var> from the filter chain</dd>
   
  -    <dt>=filter-name</dt>
  -    <dd>Empty the filter chain and insert filter-name</dd>
  +    <dt><code>=<var>filter-name</var></code></dt>
  +    <dd>Empty the filter chain and insert <var>filter-name</var></dd>
   
  -    <dt>!</dt>
  +    <dt><code>!</code></dt>
       <dd>Empty the filter chain</dd>
   
  -    <dt>filter-name</dt>
  -    <dd>Equivalent to +filter-name</dd>
  +    <dt><code><var>filter-name</var></code></dt>
  +    <dd>Equivalent to <code>+<var>filter-name</var></code></dd>
       </dl>
   </usage>
   </directivesynopsis>
  @@ -338,42 +332,45 @@
   <directivesynopsis>
   <name>FilterProtocol</name>
   <description>Deal with correct HTTP protocol handling</description>
  -<syntax>FilterProtocol filter-name [provider-name] "proto-flags"</syntax>
  +<syntax>FilterProtocol <var>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>
   
   <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>This directs <module>mod_filter</module> 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>
  +    applies specifically to a <var>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
  +    filter runs <em>any</em> provider.</p>
   
       <p><var>proto-flags</var> is one or more of</p>
   
       <dl>
  -    <dt>change=yes</dt>
  +    <dt><code>change=yes</code></dt>
       <dd>The filter changes the content, including possibly the content
       length</dd>
   
  -    <dt>change=1:1</dt>
  +    <dt><code>change=1:1</code></dt>
       <dd>The filter changes the content, but will not change the content
       length</dd>
   
  -    <dt>byteranges=no</dt>
  +    <dt><code>byteranges=no</code></dt>
       <dd>The filter cannot work on byteranges and requires complete input</dd>
   
  -    <dt>proxy=no</dt>
  +    <dt><code>proxy=no</code></dt>
       <dd>The filter should not run in a proxy context</dd>
   
  -    <dt>proxy=transform</dt>
  +    <dt><code>proxy=transform</code></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>
  +    <dt><code>cache=no</code></dt>
       <dd>The filter renders the output uncacheable (eg by introducing randomised
       content changes)</dd>
       </dl>
  @@ -382,29 +379,31 @@
   
   <directivesynopsis>
   <name>FilterTrace</name>
  -<description>Get debug/diagnostic information from mod_filter</description>
  -<syntax>FilterTrace filter-name level</syntax>
  +<description>Get debug/diagnostic information from
  +    <module>mod_filter</module></description>
  +<syntax>FilterTrace <var>filter-name</var> <var>level</var></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.
  +    <p>This directive generates debug information from
  +    <module>mod_filter</module>.
       It is designed to help test and debug providers (filter modules), although
  -    it may also help with mod_filter itself.</p>
  +    it may also help with <module>mod_filter</module> itself.</p>
   
  -    <p>The debug output depends on the level set:</p>
  +    <p>The debug output depends on the <var>level</var> set:</p>
       <dl>
  -    <dt>0 (default)</dt>
  +    <dt><code>0</code> (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
  +    <dt><code>1</code></dt>
  +    <dd><module>mod_filter</module> 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>
  +    <dt><code>2</code> (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>
  
  
  

Mime
View raw message