--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
+<modulesynopsis>
+
+<name>mod_example</name>
+<description>Illustrates the Apache module API</description>
+<status>Experimental</status>
+<sourcefile>mod_example.c</sourcefile>
+<identifier>example_module</identifier>
+
+<summary>
+<note type="warning">
+ This document has not been updated
+ to take into account changes made in the 2.0 version of the
+ Apache HTTP Server. Some of the information may still be
+ relevant, but please use it with care.
+</note>
+
+ <p>The files in the <code>src/modules/example directory</code>
+ under the Apache distribution directory tree are provided as an
+ example to those that wish to write modules that use the Apache
+ API.</p>
+
+ <p>The main file is <code>mod_example.c</code>, which
+ illustrates all the different callback mechanisms and call
+ syntaxes. By no means does an add-on module need to include
+ routines for all of the callbacks - quite the contrary!</p>
+
+ <p>The example module is an actual working module. If you link
+ it into your server, enable the "example-handler" handler for a
+ location, and then browse to that location, you will see a
+ display of some of the tracing the example module did as the
+ various callbacks were made.</p>
+</summary>
+
+<section><title>Compiling the example module</title>
+
+ <p>To include the example module in your server, follow the
+ steps below:</p>
+
+ <ol>
+ <li>
+ Uncomment the "AddModule modules/example/mod_example" line
+ near the bottom of the <code>src/Configuration</code> file.
+ If there isn't one, add it; it should look like this:
+<example>
+ AddModule modules/example/mod_example.o
+</example>
+ </li>
+
+ <li>Run the <code>src/Configure</code> script
+ ("<code>cd src; ./Configure</code>"). This will
+ build the Makefile for the server itself, and update the
+ <code>src/modules/Makefile</code> for any additional modules
+ you have requested from beneath that subdirectory.</li>
+
+ <li>Make the server (run "<code>make</code>" in the
+ <code>src</code> directory).</li>
+ </ol>
+
+ <p>To add another module of your own:</p>
+
+ <ol type="A">
+ <li><code>mkdir src/modules/<em>mymodule</em></code></li>
+
+ <li><code>cp src/modules/example/*
+ src/modules/<em>mymodule</em></code></li>
+
+ <li>Modify the files in the new directory.</li>
+
+ <li>Follow steps [1] through [3] above, with appropriate
+ changes.</li>
+ </ol>
+</section>
+
+<section><title>Using the <code>mod_example</code> Module</title>
+
+ <p>To activate the example module, include a block similar to
+ the following in your <code>srm.conf</code> file:</p>
+<example>
+ <Location /example-info><br />
+ SetHandler example-handler<br />
+ </Location>
+</example>
+
+ <p>As an alternative, you can put the following into a <a
+ href="core.html#accessfilename"><code>.htaccess</code></a> file
+ and then request the file "test.example" from that location:</p>
+<example>
+ AddHandler example-handler .example
+</example>
+
+ <p>After reloading/restarting your server, you should be able
+ to browse to this location and see the brief display mentioned
+ earlier.</p>
+</section>
+
+<directivesynopsis>
+<name>Example</name>
+<description>Demonstration directive to illustrate the Apache module
+API</description>
+<syntax>Example</syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context><context>directory</context>
+<context>.htaccess</context></contextlist>
+
+<usage>
+ <p>The <directive>Example</directive> directive just sets a demonstration
+ flag which the example module's content handler displays. It
+ takes no arguments. If you browse to an URL to which the
+ example content-handler applies, you will get a display of the
+ routines within the module and how and in what order they were
+ called to service the document request. The effect of this
+ directive one can observe under the point "<code>Example
+ directive declared here: YES/NO</code>".</p>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
+<modulesynopsis>
+
+<name>mod_ext_filter</name>
+<description>Pass the response body
+ through an external program before delivery to the
+ client</description>
+<status>Experimental</status>
+<sourcefile>mod_ext_filter.c</sourcefile>
+<identifier>ext_filter_module</identifier>
+
+<summary>
+ <p>This is an <strong>experimental</strong> module and should
+ be used with care. Test your <module>mod_ext_filter</module>
+ configuration carefully to ensure that it performs the desired
+ function. You may wish to review <a href="../filter.html">
+ this information</a> for background on the Apache filtering
+ model.</p>
+
+ <p><module>mod_ext_filter</module> presents a simple and familiar
+ programming model for filters. With this module, a program
+ which reads from stdin and writes to stdout (i.e., a Unix-style
+ filter command) can be a filter for Apache. This filtering
+ mechanism is much slower than using a filter which is specially
+ written for the Apache API and runs inside of the Apache server
+ process, but it does have the following benefits:</p>
+
+ <ul>
+ <li>the programming model is much simpler</li>
+
+ <li>any programming/scripting language can be used, provided
+ that it allows the program to read from standard input and
+ write to standard output</li>
+
+ <li>existing programs can be used unmodified as Apache
+ filters</li>
+ </ul>
+
+ <p>Even when the performance characteristics are not suitable
+ for production use, <code>mod_ext_filter</code> can be used as
+ a prototype environment for filters.</p>
+</summary>
+
+<section><title>Examples</title>
+
+<section><title>Generating HTML from some other type of response</title>
+<example>
+<pre>
+ # mod_ext_filter directive to define a filter to HTML-ize text/c files
+ # using the external program /usr/bin/enscript, with the type of the
+ # result set to text/html
+ ExtFilterDefine c-to-html mode=output intype=text/c outtype=text/html \
+ cmd="/usr/bin/enscript --color -W html -Ec -o - -"
+
+ <Directory "/export/home/trawick/apacheinst/htdocs/c">
+
+ # core directive to cause the new filter to be run on output
+ SetOutputFilter c-to-html
+
+ # mod_mime directive to set the type of .c files to text/c
+ AddType text/c .c
+
+ # mod_ext_filter directive to set the debug level just high
+ # enough to see a log message per request showing the configuration
+ # in force
+ ExtFilterOptions DebugLevel=1
+
+ </Directory>
+</pre>
+</example>
+</section>
+
+<section><title>Implementing a content encoding filter</title>
+<example>
+<pre>
+ # mod_ext_filter directive to define the external filter
+ ExtFilterDefine gzip mode=output cmd=/bin/gzip
+
+ <Location /gzipped>
+
+ # core directive to cause the gzip filter to be run on output
+ SetOutputFilter gzip
+
+ # mod_header directive to add "Content-Encoding: gzip" header field
+ Header set Content-Encoding gzip
+
+ </Location>
+</pre>
+</example>
+
+ <p>Note: this gzip example is just for the purposes of illustration.
+ Please refer to <module>mod_deflate</module> for a practical
+ implementation.</p>
+</section>
+
+<section><title>Slowing down the server</title>
+<example>
+<pre>
+ # mod_ext_filter directive to define a filter which runs everything
+ # through cat; cat doesn't modify anything; it just introduces extra
+ # pathlength and consumes more resources
+ ExtFilterDefine slowdown mode=output cmd=/bin/cat preservescontentlength
+
+ <Location />
+
+ # core directive to cause the slowdown filter to be run several times on
+ # output
+ SetOutputFilter slowdown slowdown slowdown
+
+ </Location>
+</pre>
+</example>
+</section>
+
+</section> <!-- Examples -->
+
+<directivesynopsis>
+<name>ExtFilterDefine</name>
+<syntax>ExtFilterDefine <em>filtername</em> <em>parameters</em></syntax>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+ <p>The <directive>ExtFilterDefine</directive> directive defines the
+ characteristics of an external filter, including the program to
+ run and its arguments.</p>
+
+ <p><em>filtername</em> specifies the name of the filter being
+ defined. This name can then be used in SetOutputFilter
+ directives. It must be unique among all registered filters.
+ <em>At the present time, no error is reported by the
+ register-filter API, so a problem with duplicate names isn't
+ reported to the user.</em></p>
+
+ <p>Subsequent parameters can appear in any order and define the
+ external command to run and certain other characteristics. The
+ only required parameter is <em>cmd=</em>. These parameters
+ are:</p>
+
+ <dl>
+ <dt>cmd=<em>cmdline</em></dt>
+
+ <dd>The <code>cmd=</code> keyword allows you to specify the
+ external command to run. If there are arguments after the
+ program name, the command line should be surrounded in
+ quotation marks.</dd>
+
+ <dt>mode=<em>mode</em></dt>
+
+ <dd><em>mode</em> should be <em>output</em> for now (the
+ default). In the future, <em>mode=input</em> will be used to
+ specify a filter for request bodies.</dd>
+
+ <dt>intype=<em>imt</em></dt>
+
+ <dd>This parameter specifies the internet media type (i.e.,
+ MIME type) of documents which should be filtered. By default,
+ all documents are filtered. If <code>intype=</code> is
+ specified, the filter will be disabled for documents of other
+ types.</dd>
+
+ <dt>outtype=<em>imt</em></dt>
+
+ <dd>This parameter specifies the internet media type (i.e.,
+ MIME type) of filtered documents. It is useful when the
+ filter changes the internet media type as part of the
+ filtering operation. By default, the internet media type is
+ unchanged.</dd>
+
+ <dt>PreservesContentLength</dt>
+
+ <dd>The <code>PreservesContentLength</code> keyword specifies
+ that the filter preserves the content length. This is not the
+ default, as most filters change the content length. In the
+ event that the filter doesn't modify the length, this keyword
+ should be specified.</dd>
+ </dl>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ExtFilterOptions</name>
+<syntax>ExtFilterOptions
+ <em>option</em> [<em>option</em>] ...</syntax>
+<default>ExtFilterOptions DebugLevel=0 NoLogStderr</default>
+<contextlist><context>directory</context></contextlist>
+
+<usage>
+ <p>The <directive>ExtFilterOptions</directive> directive specifies
+ special processing options for <code>mod_ext_filter</code>.
+ <em>Option</em> can be one of</p>
+
+ <dl>
+ <dt>DebugLevel=<em>n</em></dt>
+
+ <dd>
+ The <code>DebugLevel</code> keyword allows you to specify
+ the level of debug messages generated by
+ <code>mod_ext_filter</code>. By default, no debug messages
+ are generated. This is equivalent to
+ <code>DebugLevel=0</code>. With higher numbers, more debug
+ messages are generated, and server performance will be
+ degraded. The actual meanings of the numeric values are
+ described with the definitions of the DBGLVL_ constants
+ near the beginning of <code>mod_ext_filter.c</code>.
+
+ <p>Note: The core directive LogLevel should be used to
+ cause debug messages to be stored in the Apache error
+ log.</p>
+ </dd>
+
+ <dt>LogStderr | NoLogStderr</dt>
+
+ <dd>The <code>LogStderr</code> keyword specifies that
+ messages written to standard error by the external filter
+ program will be saved in the Apache error log.
+ <code>NoLogStderr</code> disables this feature.</dd>
+ </dl>
+
+ <p>Example:</p>
+<example>
+ ExtFilterOptions LogStderr DebugLevel=0
+</example>
+
+ <p>Messages written to the filter's standard error will be stored
+ in the Apache error log. No debug messages will be generated by
+ <module>mod_ext_filter</module>. </p>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>
\ No newline at end of file
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
+<modulesynopsis>
+
+<name>mod_file_cache</name>
+<description>Caches a static list of files in memory</description>
+<status>Experimental</status>
+<sourcefile>mod_file_cache.c</sourcefile>
+<identifier>file_cache_module</identifier>
+
+<summary>
+
+<note type="warning">
+This module should be used with care. You can easily
+ create a broken site using mod_file_cache, so read this
+ document carefully.
+</note>
+
+ <p><em>Caching</em> frequently requested files that change very
+ infrequently is a technique for reducing server load.
+ mod_file_cache provides two techniques for caching frequently
+ requested <em>static</em> files. Through configuration
+ directives, you can direct mod_file_cache to either open then
+ mmap()a file, or to pre-open a file and save the file's open
+ <em>file handle</em>. Both techniques reduce server load when
+ processing requests for these files by doing part of the work
+ (specifically, the file I/O) for serving the file when the
+ server is started rather than during each request.</p>
+
+ <p>Notice: You cannot use this for speeding up CGI programs or
+ other files which are served by special content handlers. It
+ can only be used for regular files which are usually served by
+ the Apache core content handler.</p>
+
+ <p>This module is an extension of and borrows heavily from the
+ mod_mmap_static module in Apache 1.3.</p>
+</summary>
+
+<section><title>Using mod_file_cache</title>
+
+ <p><module>mod_file_cache</module> caches a list of statically
+ configured files via <directive
+ module="mod_file_cache">MMapFile</directive> or <directive
+ module="mod_file_cache">CacheFile</directive> directives in the
+ main server configuration.</p>
+
+ <p>Not all platforms support both directives. For example, Apache
+ on Windows does not currently support the <directive
+ module="mod_file_cache">MMapStatic</directive> directive, while
+ other platforms, like AIX, support both. You will receive an error
+ message in the server error log if you attempt to use an
+ unsupported directive. If given an unsupported directive, the
+ server will start but the file will not be cached. On platforms
+ that support both directives, you should experiment with both to
+ see which works best for you.</p>
+
+<section><title>MmapFile Directive</title>
+
+ <p>The <directive module="mod_file_cache">MmapFile</directive>
+ directive of <module>mod_file_cache</module> maps a list of
+ statically configured files into memory through the system call
+ <code>mmap()</code>. This system call is available on most modern
+ Unix derivates, but not on all. There are sometimes
+ system-specific limits on the size and number of files that can be
+ mmap()d, experimentation is probably the easiest way to find
+ out.</p>
+
+ <p>This mmap()ing is done once at server start or restart,
+ only. So whenever one of the mapped files changes on the
+ filesystem you <em>have</em> to restart the server (see the <a
+ href="../stopping.html">Stopping and Restarting</a>
+ documentation). To reiterate that point: if the files are
+ modified <em>in place</em> without restarting the server you
+ may end up serving requests that are completely bogus. You
+ should update files by unlinking the old copy and putting a new
+ copy in place. Most tools such as <code>rdist</code> and
+ <code>mv</code> do this. The reason why this modules doesn't
+ take care of changes to the files is that this check would need
+ an extra <code>stat()</code> every time which is a waste and
+ against the intent of I/O reduction.</p>
+</section>
+
+<section><title>CacheFile Directive</title>
+
+ <p>The <directive module="mod_file_cache">CacheFile</directive>
+ directive of <module>mod_file_cache</module> opens an active
+ <em>handle</em> or <em>file descriptor</em> to the file (or files)
+ listed in the configuration directive and places these open file
+ handles in the cache. When the file is requested, the server
+ retrieves the handle from the cache and passes it to the
+ sendfile() (or TransmitFile() on Windows), socket API.</p>
+
+ <p>Insert more details about sendfile API...</p>
+
+ <p>This file handle caching is done once at server start or
+ restart, only. So whenever one of the cached files changes on
+ the filesystem you <em>have</em> to restart the server (see the
+ <a href="../stopping.html">Stopping and Restarting</a>
+ documentation). To reiterate that point: if the files are
+ modified <em>in place</em> without restarting the server you
+ may end up serving requests that are completely bogus. You
+ should update files by unlinking the old copy and putting a new
+ copy in place. Most tools such as <code>rdist</code> and
+ <code>mv</code> do this.</p>
+</section>
+
+<note><title>Note</title> Don't bother asking for a for a
+ directive which recursively caches all the files in a
+ directory. Try this instead... See the
+ <directive module="core">Include</directive> directive, and consider
+ this command:
+<example>
+ find /www/htdocs -type f -print \ <br />
+ | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
+</example>
+</note>
+
+</section>
+
+<directivesynopsis>
+<name>MMapFile</name>
+<syntax>MMapFile <em>file-path</em> [<em>file-path</em>] ...</syntax>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+ <p>The <directive>MMapFile</directive> directive maps one or more files
+ (given as whitespace separated arguments) into memory at server
+ startup time. They are automatically unmapped on a server
+ shutdown. When the files have changed on the filesystem at
+ least a HUP or USR1 signal should be send to the server to
+ re-mmap them.</p>
+
+ <p>Be careful with the <em>file-path</em> arguments: They have
+ to literally match the filesystem path Apache's URL-to-filename
+ translation handlers create. We cannot compare inodes or other
+ stuff to match paths through symbolic links <em>etc.</em>
+ because that again would cost extra <code>stat()</code> system
+ calls which is not acceptable. This module may or may not work
+ with filenames rewritten by <module>mod_alias</module> or
+ <module>mod_rewrite</module>.</p>
+
+<example><title>Example</title>
+ MMapFile /usr/local/apache/htdocs/index.html
+</example>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>CacheFile</name>
+<syntax>CacheFile
+ <em>file-path</em> [<em>file-path</em>] ...</syntax>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+ <p>The <directive>CacheFile</directive> directive opens handles to
+ one or more files (given as whitespace separated arguments) and
+ places these handles into the cache at server startup
+ time. Handles to cached files are automatically closed on a server
+ shutdown. When the files have changed on the filesystem, the
+ server should be restarted to to re-cache them.</p>
+
+ <p>Be careful with the <em>file-path</em> arguments: They have
+ to literally match the filesystem path Apache's URL-to-filename
+ translation handlers create. We cannot compare inodes or other
+ stuff to match paths through symbolic links <em>etc.</em>
+ because that again would cost extra <code>stat()</code> system
+ calls which is not acceptable. This module may or may not work
+ with filenames rewritten by <module>mod_alias</module> or
+ <module>mod_rewrite</module>.</p>
+
+<example><title>Example</title>
+ CacheFile /usr/local/apache/htdocs/index.html
+</example>
+</usage>
+
+</directivesynopsis>
+</modulesynopsis>
\ No newline at end of file
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
+<modulesynopsis>
+
+<name>mod_headers</name>
+<description>Customization of HTTP request
+ and response headers</description>
+<status>Extension</status>
+<sourcefile>mod_headers.c</sourcefile>
+<identifier>headers_module</identifier>
+<compatibility>RequestHeader is available only in Apache 2.0</compatibility>
+
+<summary>
+ <p>This module provides directives to control and modify HTTP
+ request and response headers. Headers can be merged, replaced
+ or removed.</p>
+</summary>
+
+<section><title>Order of Processing</title>
+
+ <p>The directives provided by mod_header can occur almost
+ anywhere within the server configuration. They are valid in the
+ main server config and virtual host sections, inside
+ <Directory>, <Location> and <Files> sections,
+ and within .htaccess files.</p>
+
+ <p>The directives are processed in the following order:</p>
+
+ <ol>
+ <li>main server</li>
+
+ <li>virtual host</li>
+
+ <li><Directory> sections and .htaccess</li>
+
+ <li><Location></li>
+
+ <li><Files></li>
+ </ol>
+
+ <p>Order is important. These two headers have a different
+ effect if reversed:</p>
+
+<example>
+RequestHeader append MirrorID "mirror 12"<br />
+ RequestHeader unset MirrorID
+</example>
+
+ <p>This way round, the MirrorID header is not set. If reversed,
+ the MirrorID header is set to "mirror 12".</p>
+</section>
+
+<section><title>Example</title>
+
+ <ol>
+ <li>Copy all request headers that begin with "TS" to the
+ response headers:
+
+<example>
+ Header echo ^TS*
+</example></li>
+
+ <li>Add a header, MyHeader, to the response including a
+ timestamp for when the request was received and how long it
+ took to begin serving the request. This header can be used by
+ the client to intuit load on the server or in isolating
+ bottlenecks between the client and the server.
+
+<example>
+ Header add MyHeader "%D %t"
+</example>
+ results in this header being added to the response:
+<example>
+ MyHeader: D=3775428 t=991424704447256
+</example>
+ </li>
+
+ <li>Say hello to Joe
+
+<example>
+ Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."
+</example>
+ results in this header being added to the response:
+<example>
+ MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
+</example>
+ </li>
+
+ <li>Conditionally send MyHeader on the response if and only
+ if header "MyRequestHeader" is present on the request. This
+ is useful for constructing headers in response to some client
+ stimulus. Note that this example requires the services of the
+ mod_setenvif module.
+
+<example>
+ SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br />
+ Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
+</example>
+ If the header "MyRequestHeader: value" is present on the
+ HTTP request, the response will contain the following
+ header:
+<example>
+ MyHeader: D=3775428 t=991424704447256 mytext
+</example>
+ </li>
+ </ol>
+</section>
+
+<directivesynopsis>
+<name>RequestHeader</name>
+<description>Configure HTTP request headers</description>
+<syntax>RequestHeader set|append|add|unset <em>header</em>
+[<em>value</em>]</syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context>
+<context>directory</context>
+<context>.htaccess</context></contextlist>
+<override>FileInfo</override>
+
+<usage>
+ <p>This directive can replace, merge or remove HTTP request
+ headers. The header is modified just before the content handler
+ is run, allowing incoming headers to be modified. The action it
+ performs is determined by the first argument. This can be one
+ of the following values:</p>
+
+ <ul>
+ <li><strong>set</strong><br />
+ The request header is set, replacing any previous header
+ with this name</li>
+
+ <li><strong>append</strong><br />
+ The request header is appended to any existing header of the
+ same name. When a new value is merged onto an existing header
+ it is separated from the existing header with a comma. This
+ is the HTTP standard way of giving a header multiple
+ values.</li>
+
+ <li><strong>add</strong><br />
+ The request header is added to the existing set of headers,
+ even if this header already exists. This can result in two
+ (or more) headers having the same name. This can lead to
+ unforeseen consequences, and in general "append" should be
+ used instead.</li>
+
+ <li><strong>unset</strong><br />
+ The request header of this name is removed, if it exists. If
+ there are multiple headers of the same name, all will be
+ removed.</li>
+ </ul>
+
+ <p>This argument is followed by a header name, which can
+ include the final colon, but it is not required. Case is
+ ignored. For <code>add</code>, <code>append</code> and
+ <code>set</code> a value is given as the third argument. If
+ this value contains spaces, it should be surrounded by double
+ quotes. For unset, no value should be given.</p>
+
+ <p>The <directive>RequestHeader</directive> directive is processed
+ just before the request is run by its handler in the fixup phase.
+ This should allow headers generated by the browser, or by Apache
+ input filters to be overridden or modified.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>Header</name>
+<description>Configure HTTP response headers</description>
+<syntax>Header set|append|add|unset|echo <em>header</em>
+[<em>value</em>]</syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context>
+<context>directory</context>
+<context>.htaccess</context></contextlist>
+<override>FileInfo</override>
+
+<usage>
+ <p>This directive can replace, merge or remove HTTP response
+ headers. The header is modified just after the content handler
+ and output filters are run, allowing outgoing headers to be
+ modified. The action it performs is determined by the first
+ argument. This can be one of the following values:</p>
+
+ <ul>
+ <li><strong>set</strong><br />
+ The response header is set, replacing any previous header
+ with this name. The <em>value</em> may be a format
+ string.</li>
+
+ <li><strong>append</strong><br />
+ The response header is appended to any existing header of
+ the same name. When a new value is merged onto an existing
+ header it is separated from the existing header with a comma.
+ This is the HTTP standard way of giving a header multiple
+ values.</li>
+
+ <li><strong>add</strong><br />
+ The response header is added to the existing set of headers,
+ even if this header already exists. This can result in two
+ (or more) headers having the same name. This can lead to
+ unforeseen consequences, and in general "append" should be
+ used instead.</li>
+
+ <li><strong>unset</strong><br />
+ The response header of this name is removed, if it exists.
+ If there are multiple headers of the same name, all will be
+ removed.</li>
+
+ <li><strong>echo</strong><br />
+ Request headers with this name are echoed back in the
+ response headers. <em>header</em> may be a regular
+ expression.</li>
+ </ul>
+
+ <p>This argument is followed by a <em>header</em> name, which
+ can include the final colon, but it is not required. Case is
+ ignored for set, append, add and unset. The <em>header</em>
+ name for echo is case sensitive and may be a regular
+ expression.</p>
+
+ <p>For <code>add</code>, <code>append</code> and
+ <code>set</code> a <em>value</em> is specified as the third
+ argument. If <em>value</em> contains spaces, it should be
+ surrounded by doublequotes. <em>value</em> may be a character
+ string, a string containing format specifiers or a combination
+ of both. The following format specifiers are supported in
+ <em>value</em>:</p>
+<table>
+<tr><td>%t: </td> <td>The time the request was received in Universal
+Coordinated Time since the epoch (Jan. 1, 1970) measured in
+microseconds. The value is preceded by "t=".</td></tr>
+
+<tr><td>%D: </td> <td>The time from when the request was received to
+the time the headers are sent on the wire. This is a measure of the
+duration of the request. The value is preceded by "D=".</td></tr>
+
+<tr><td>%{FOOBAR}e:</td> <td>The contents of the <a href="../env.html">environment
+variable</a> FOOBAR.</td></tr>
+</table>
+
+ <p>When the <directive>Header</directive> directive is used with the
+ <code>add</code>, <code>append</code>, or <code>set</code>
+ argument, a fourth argument may be used to specify conditions
+ under which the action will be taken. If the <a
+ href="../env.html">environment variable</a> specified in the
+ <code>env=...</code> argument exists (or if the environment
+ variable does not exist and <code>env=!...</code> is specified)
+ then the action specified by the <directive>Header</directive> directive
+ will take effect. Otherwise, the directive will have no effect
+ on the request.</p>
+
+ <p>The Header directives are processed just before the response
+ is sent to the network. These means that it is possible to set
+ and/or override most headers, except for those headers added by
+ the header filter.</p>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>
+
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
+<modulesynopsis>
+
+<name>mod_imap</name>
+<description>Server-side imagemap processing</description>
+<status>Base</status>
+<sourcefile>mod_imap.c</sourcefile>
+<identifier>imap_module</identifier>
+
+<summary>
+ <p>This module processes <code>.map</code> files, thereby
+ replacing the functionality of the <code>imagemap</code> CGI
+ program. Any directory or document type configured to use the
+ handler <code>imap-file</code> (using either
+ <directive module="mod_mime">AddHandler</directive> or
+ <directive module="core">SetHandler</directive>)
+ will be processed by this module.</p>
+
+ <p>The following directive will activate files ending with
+ <code>.map</code> as imagemap files:</p>
+
+<example>AddHandler imap-file map</example>
+
+ <p>Note that the following is still supported:</p>
+
+<example>AddType application/x-httpd-imap map</example>
+
+ <p>However, we are trying to phase out "magic MIME types" so we
+ are deprecating this method.</p>
+</summary>
+
+<section><title>New Features</title>
+
+ <p>The imagemap module adds some new features that were not
+ possible with previously distributed imagemap programs.</p>
+
+ <ul>
+ <li>URL references relative to the Referer: information.</li>
+
+ <li>Default <BASE> assignment through a new map
+ directive <code>base</code>.</li>
+
+ <li>No need for <code>imagemap.conf</code> file.</li>
+
+ <li>Point references.</li>
+
+ <li>Configurable generation of imagemap menus.</li>
+ </ul>
+</section>
+
+<section><title>Imagemap File</title>
+
+ <p>The lines in the imagemap files can have one of several
+ formats:</p>
+
+<example>
+ directive value [x,y ...]<br />
+ directive value "Menu text" [x,y ...]<br />
+ directive value x,y ... "Menu text"
+</example>
+ <p>The directive is one of <code>base</code>,
+ <code>default</code>, <code>poly</code>, <code>circle</code>,
+ <code>rect</code>, or <code>point</code>. The value is an
+ absolute or relative URL, or one of the special values listed
+ below. The coordinates are <code>x,y</code> pairs separated by
+ whitespace. The quoted text is used as the text of the link if
+ a imagemap menu is generated. Lines beginning with '#' are
+ comments.</p>
+
+<section><title>Imagemap File Directives</title>
+ <p>There are six directives allowed in the imagemap file. The
+ directives can come in any order, but are processed in the
+ order they are found in the imagemap file.</p>
+
+ <dl>
+ <dt><code>base</code> Directive</dt>
+
+ <dd>Has the effect of <code><BASE HREF="value"></code>.
+ The non-absolute URLs of the map-file are taken relative to
+ this value. The <code>base</code> directive overrides
+ ImapBase as set in a .htaccess file or in the server
+ configuration files. In the absence of an ImapBase
+ configuration directive, <code>base</code> defaults to
+ <code>http://server_name/</code>.<br />
+ <code>base_uri</code> is synonymous with <code>base</code>.
+ Note that a trailing slash on the URL is significant.</dd>
+
+ <dt><code>default</code> Directive</dt>
+
+ <dd>The action taken if the coordinates given do not fit any
+ of the <code>poly</code>, <code>circle</code> or
+ <code>rect</code> directives, and there are no
+ <code>point</code> directives. Defaults to
+ <code>nocontent</code> in the absence of an ImapDefault
+ configuration setting, causing a status code of <code>204 No
+ Content</code> to be returned. The client should keep the
+ same page displayed.</dd>
+
+ <dt><code>poly</code> Directive</dt>
+
+ <dd>Takes three to one-hundred points, and is obeyed if the
+ user selected coordinates fall within the polygon defined by
+ these points.</dd>
+
+ <dt><code>circle</code></dt>
+
+ <dd>Takes the center coordinates of a circle and a point on
+ the circle. Is obeyed if the user selected point is with the
+ circle.</dd>
+
+ <dt><code>rect</code> Directive</dt>
+
+ <dd>Takes the coordinates of two opposing corners of a
+ rectangle. Obeyed if the point selected is within this
+ rectangle.</dd>
+
+ <dt><code>point</code> Directive</dt>
+
+ <dd>Takes a single point. The point directive closest to the
+ user selected point is obeyed if no other directives are
+ satisfied. Note that <code>default</code> will not be
+ followed if a <code>point</code> directive is present and
+ valid coordinates are given.</dd>
+ </dl>
+</section>
+
+<section><title>Values</title>
+
+ <p>The values for each of the directives can any of the following:</p>
+
+
+ <dl>
+ <dt>a URL</dt>
+
+ <dd>The URL can be relative or absolute URL. Relative URLs
+ can contain '..' syntax and will be resolved relative to the
+ <code>base</code> value.<br />
+ <code>base</code> itself will not resolved according to the
+ current value. A statement <code>base mailto:</code> will
+ work properly, though.</dd>
+
+ <dt><code>map</code></dt>
+
+ <dd>Equivalent to the URL of the imagemap file itself. No
+ coordinates are sent with this, so a menu will be generated
+ unless ImapMenu is set to 'none'.</dd>
+
+ <dt><code>menu</code></dt>
+
+ <dd>Synonymous with <code>map</code>.</dd>
+
+ <dt><code>referer</code></dt>
+
+ <dd>Equivalent to the URL of the referring document. Defaults
+ to <code>http://servername/</code> if no Referer: header was
+ present.</dd>
+
+ <dt><code>nocontent</code></dt>
+
+ <dd>Sends a status code of <code>204 No Content</code>,
+ telling the client to keep the same page displayed. Valid for
+ all but <code>base</code>.</dd>
+
+ <dt><code>error</code></dt>
+
+ <dd>Fails with a <code>500 Server Error</code>. Valid for all
+ but <code>base</code>, but sort of silly for anything but
+ <code>default</code>.</dd>
+ </dl>
+</section>
+
+<section><title>Coordinates</title>
+
+ <dl>
+ <dt><code>0,0 200,200</code></dt>
+
+ <dd>A coordinate consists of an <code>x</code> and a <code>y</code>
+ value separated by a comma. The coordinates are separated
+ from each other by whitespace. To accommodate the way Lynx
+ handles imagemaps, should a user select the coordinate
+ <code>0,0</code>, it is as if no coordinate had been
+ selected.</dd>
+ </dl>
+
+</section>
+
+<section><title>Quoted Text</title>
+
+ <dl>
+ <dt><code>"Menu Text"</code></dt>
+
+ <dd>After the value or after the coordinates, the line
+ optionally may contain text within double quotes. This string
+ is used as the text for the link if a menu is
+ generated:<br />
+ <code><a HREF="http://foo.com/">Menu
+ text</a></code><br />
+ If no quoted text is present, the name of the link will be
+ used as the text:<br />
+ <code><a
+ HREF="http://foo.com/">http://foo.com</a></code><br />
+ It is impossible to escape double quotes within this
+ text.</dd>
+ </dl>
+</section>
+</section>
+
+<section><title>Example Mapfile</title>
+
+<example>
+ #Comments are printed in a 'formatted' or
+ 'semiformatted' menu.<br />
+ #And can contain html tags. <hr><br />
+ base referer<br />
+ poly map "Could I have a menu, please?" 0,0 0,10 10,10
+ 10,0<br />
+ rect .. 0,0 77,27 "the directory of the referer"<br />
+ circle http://www.inetnebr.com/lincoln/feedback/ 195,0
+ 305,27<br />
+ rect another_file "in same directory as referer" 306,0
+ 419,27<br />
+ point http://www.zyzzyva.com/ 100,100<br />
+ point http://www.tripod.com/ 200,200<br />
+ rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"<br />
+</example>
+
+</section>
+
+<section><title>Referencing your mapfile</title>
+
+<example>
+ <A HREF="/maps/imagemap1.map"><br />
+ <IMG ISMAP SRC="/images/imagemap1.gif"><br />
+ </A>
+</example>
+</section>
+
+<directivesynopsis>
+<name>ImapMenu</name>
+<description>Action if no coordinates are given when calling
+an imagemap</description>
+<syntax>ImapMenu
+ none|formatted|semiformatted|unformatted</syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context>
+<context>directory</context>
+<context>.htaccess</context></contextlist>
+<override>Indexes</override>
+
+<usage>
+ <p>The <directive>ImapMenu</directive> directive determines the
+ action taken if an imagemap file is called without valid
+ coordinates.</p>
+
+ <dl>
+ <dt><code>none</code></dt>
+
+ <dd>If ImapMenu is <code>none</code>, no menu is generated,
+ and the <code>default</code> action is performed.</dd>
+
+ <dt><code>formatted</code></dt>
+
+ <dd>A <code>formatted</code> menu is the simplest menu.
+ Comments in the imagemap file are ignored. A level one header
+ is printed, then an hrule, then the links each on a separate
+ line. The menu has a consistent, plain look close to that of
+ a directory listing.</dd>
+
+ <dt><code>semiformatted</code></dt>
+
+ <dd>In the <code>semiformatted</code> menu, comments are
+ printed where they occur in the imagemap file. Blank lines
+ are turned into HTML breaks. No header or hrule is printed,
+ but otherwise the menu is the same as a
+ <code>formatted</code> menu.</dd>
+
+ <dt><code>unformatted</code></dt>
+
+ <dd>Comments are printed, blank lines are ignored. Nothing is
+ printed that does not appear in the imagemap file. All breaks
+ and headers must be included as comments in the imagemap
+ file. This gives you the most flexibility over the appearance
+ of your menus, but requires you to treat your map files as
+ HTML instead of plaintext.</dd>
+ </dl>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ImapDefault</name>
+<description>Default action when an imagemap is called with coordinates
+that are not explicitly mapped</description>
+<syntax>ImapDefault error|nocontent|map|referer|<em>URL</em></syntax>
+<default>ImapDefault nocontent</default>
+<contextlist><context>server config</context>
+<context>virtual host</context>
+<context>directory</context>
+<context>.htaccess</context></contextlist>
+<override>Indexes</override>
+
+<usage>
+ <p>The <directive>ImapDefault</directive> directive sets the default
+ <code>default</code> used in the imagemap files. Its value is
+ overridden by a <code>default</code> directive within the
+ imagemap file. If not present, the <code>default</code> action
+ is <code>nocontent</code>, which means that a <code>204 No
+ Content</code> is sent to the client. In this case, the client
+ should continue to display the original page.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ImapBase</name>
+<description>Default <code>base</code> for imagemap files</description>
+<syntax>ImapBase map|referer|<em>URL</em></syntax>
+<default>ImapBase http://servername/</default>
+<contextlist><context>server config</context>
+<context>virtual host</context>
+<context>directory</context>
+<context>.htaccess</context></contextlist>
+<override>Indexes</override>
+
+<usage>
+ <p>The <directive>ImapBase</directive> directive sets the default
+ <code>base</code> used in the imagemap files. Its value is
+ overridden by a <code>base</code> directive within the imagemap
+ file. If not present, the <code>base</code> defaults to
+ <code>http://servername/</code>.</p>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>
\ No newline at end of file
projects / apache / commitdiff