www/apache
1
0
Fork 0
mirror of https://github.com/apache/httpd.git synced 2025-12-24 15:01:03 +03:00
Code Activity

Add some more xml versions.

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@93792 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Joshua Slive
2002-03-08 17:19:00 +00:00
parent 1d5936215a
commit 02c9e91824
5 changed files with 1125 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
docs/manual/mod/mod_example.xml Normal file
View File

@@ -0,0 +1,120 @@
<?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&nbsp;src;&nbsp;./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>
&lt;Location /example-info&gt;<br />
SetHandler example-handler<br />
&lt;/Location&gt;
</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>

232
docs/manual/mod/mod_ext_filter.xml Normal file
View File

@@ -0,0 +1,232 @@
<?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 - -"
&lt;Directory "/export/home/trawick/apacheinst/htdocs/c"&gt;
# 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
&lt;/Directory&gt;
</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
&lt;Location /gzipped&gt;
# 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
&lt;/Location&gt;
</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
&lt;Location /&gt;
# core directive to cause the slowdown filter to be run several times on
# output
SetOutputFilter slowdown slowdown slowdown
&lt;/Location&gt;
</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>

178
docs/manual/mod/mod_file_cache.xml Normal file
View File

@@ -0,0 +1,178 @@
<?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 &amp;/' &gt; /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>

261
docs/manual/mod/mod_headers.xml Normal file
View File

@@ -0,0 +1,261 @@
<?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
&lt;Directory&gt;, &lt;Location&gt; and &lt;Files&gt; 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>&lt;Directory&gt; sections and .htaccess</li>
<li>&lt;Location&gt;</li>
<li>&lt;Files&gt;</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>

334
docs/manual/mod/mod_imap.xml Normal file
View File

@@ -0,0 +1,334 @@
<?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 &lt;BASE&gt; 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>&lt;BASE HREF="value"&gt;</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>&lt;a HREF="http://foo.com/"&gt;Menu
text&lt;/a&gt;</code><br />
If no quoted text is present, the name of the link will be
used as the text:<br />
<code>&lt;a
HREF="http://foo.com/"&gt;http://foo.com&lt;/a&gt;</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. &lt;hr&gt;<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>
&lt;A HREF="/maps/imagemap1.map"&gt;<br />
&lt;IMG ISMAP SRC="/images/imagemap1.gif"&gt;<br />
&lt;/A&gt;
</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>