Decyphering the mod_filter documentation for Apache Pocket Reference (and to update the Apache docs)

[Andrew Ford <A....@ford-mason.co.uk>]

Hi

I wondered if I could pick someone's brains about mod_filter.  It is one
of the last bits left for me to document in my Apache Pocket Reference
and I have been poring over the Apache documentation, the Apache Modules
book, and the code in an attempt to understand and summarize the
functionality.  Once the book is out of the way I intend to put some
work in on clarifying some of the Apache documentation.

It seems to be that there are a couple of places in the documentation
that confuse concepts. If someone could explain how developers perceive
these concepts I will try and make sense of it in the book and also
update the mod_filter documentation.

I am right up against the final deadline for the book so if anyone could
enlighten me (quickly) I would be grateful.


"Filters" v "Filter Harnesses" v "Filter Providers" v "Smart Filters"
==========================================

The word "filter" sometimes seems to be used to sometimes mean filter
harness - a concept used in the introductory sections of the mod_filter
documentation, but not in the descriptions of the directives - and
sometimes to mean filter provider (and sometimes possibly either or even
the entire chain).


"The" v "A" chain
===========

There is a section entitled "Configuring the Chain" but in a number of
places the text talks about configuring *a* chain.  From my
understanding mod_filter only deals with a single filter chain - the
output filter chain (which may be specific to a particular context).  Is
this correct?  So the FilterChain directive always manipulates the
output filter chain in a context.  I am not quite sure though what the
following will do

  <directory /a>
     FilterChain SSI
  </directory>
  <directory /a/b>
     FilterChain +GZIP
  </directory>

in the directory /a/b it is supposed to append the GZIP filter to the
filter chain - but does that mean it copies the filter chain for the
parent directory and then appends the GZIP filter?


Filter Types
========

Discussion of filter types uses the C language defines, without any
discussion of what they represent.  I have looked at the descriptions in
util_filter.h to find out what they mean but they ought to be documented
in the mod_filter documentation.


In summary it seems as if

* FilterDeclare declares a filter harness (a.k.a. a smart filter)
* FilterProvider declares a (simple) filter (a provider) with a filter
harness (smart filter)
    (the word "filter" in the description seems to be used in some
places to refer to the provider and sometimes to the harness
* FilterChain adds a filter harness to a/the filter chain (presumably
this is "the" chain for a context so it is also "a" chain, but the use
of the indefinite article almost implies that filter chains have an
independent existence)
* FilterProtocol configures the behaviour of specific or all providers
on a filter harness

Further questions:

* what are the recommended terms for "filter provider" (can
unambiguously use "provider" when talking about dynamic filters),
"filter harness" (should the term "smart filter" be used?), and "filter
chain"?
* can FilterChain be used to add "simple filters" (e.g. DEFLATE) to the
output chain?
* can filter harnesses be added as providers to other filter harnesses?


Any feedback would be very welcome.



Regards
Andrew

-- 
Andrew Ford                     
South Wing Compton House, Compton Green,
Redmarley, Gloucestershire, GL19 3JB, UK
Tel:    +44 1531 829900
Mobile: +44 7785 258278
Email:  A.Ford@ford-mason.co.uk