Bring these docs into line with "The Standard" and clean them up a

little.

PR:
Obtained from:
Submitted by:
Reviewed by:


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

1 files changed, 110 insertions, 123 deletions

diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html
index 72b2ea0e55..a9983f63a3 100644
--- a/docs/manual/mod/mod_headers.html
+++ b/docs/manual/mod/mod_headers.html
@@ -15,7 +15,7 @@
 <!--#include virtual="header.html" -->
 <H1 ALIGN="CENTER">Module mod_headers</H1>
 
-<p>This module provides for the customization of HTTP
+<p>This module provides for the customization of HTTP request and
 response headers.</p>
 
 <P><A
@@ -52,6 +52,76 @@ replaced or removed.
 <LI><A HREF="#header">Header</A>
 </UL>
 
+<H2>Order of Processing</H2>
+
+<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:
+<OL>
+<LI>main server
+<LI>virtual host
+<LI>&lt;Directory&gt; sections and .htaccess
+<LI>&lt;Location&gt;
+<LI>&lt;Files&gt;
+</OL>
+
+<p>Order is important. These two headers have a different effect if
+reversed:</p>
+
+<blockquote><code>
+RequestHeader append MirrorID "mirror 12"<br>
+RequestHeader unset MirrorID
+</code></blockquote>
+
+<p>This way round, the MirrorID header is not set. If reversed, the
+MirrorID header is set to "mirror 12".</P>
+
+<H2>Examples</H2>
+<OL>
+<LI>Copy all request headers that begin with "TS" to the response headers:</LI>
+<PRE>
+   Header echo ^TS*
+</PRE>
+
+<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.</LI>
+<PRE>
+   Header add MyHeader "%D %t"
+</PRE>
+results in this header being added to the response:
+<PRE>
+   MyHeader: D=3775428 t=991424704447256
+</PRE>
+<LI>Say hello to Joe</LI>
+<PRE>
+   Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."
+</PRE>
+results in this header being added to the response:
+<PRE>
+   MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
+</PRE>
+
+<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.</LI>
+<PRE>
+   SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<BR>
+   Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
+</PRE> 
+If the header "MyRequestHeader: value" is present on the HTTP request, the response
+will contain the following header:
+<PRE>
+   MyHeader: D=3775428 t=991424704447256 mytext
+</PRE>
+</OL>
+
 <HR>
 
 <H2><A NAME="requestheader">RequestHeader</A> directive</H2>
@@ -82,10 +152,11 @@ replaced or removed.
  REL="Help"
 ><STRONG>Module:</STRONG></A> mod_header<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>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>
@@ -108,42 +179,17 @@ argument. This can be one of the following values:
   multiple headers of the same name, all will be removed.
 </UL>
 
-This argument is followed by a header name, which can include the
+<p>This argument is followed by a header name, which can include the
 final colon, but it is not required. Case is ignored. For
-add, append and set 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.
-
-<H3>Order of Processing</H3>
-
-The RequestHeader (and Header) directives can occur almost anywhere within 
-the server configuration. It is 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>
-The RequestHeader directives are processed in the following order:
-<OL>
-<LI>main server
-<LI>virtual host
-<LI>&lt;Directory&gt; sections and .htaccess
-<LI>&lt;Location&gt;
-<LI>&lt;Files&gt;
-</OL>
+<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>
 
-Order is important. These two headers have a different effect if reversed:
-<PRE>
-RequestHeader append MirrorID "mirror 12"
-RequestHeader unset MirrorID
-</PRE>
-
-This way round, the MirrorID header is not set. If reversed, the MirrorID
-header is set to "mirror 12".
-<P>
-
-The RequestHeader 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>
+<p>The <code>RequestHeader</code> 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>
 
 <HR>
 
@@ -179,10 +225,11 @@ the browser, or by Apache input filters to be overridden or modified.
  REL="Help"
 ><STRONG>Module:</STRONG></A> mod_header<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>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>
@@ -210,13 +257,14 @@ by the first argument. This can be one of the following values:
   <EM>header</EM> may be a regular expression. 
 </UL>
 
-This argument is followed by a <EM>header</EM> name, which can include the
+<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>
-add, append and set take a <EM>value</EM> as the third argument. If 
-<EM>value</EM> contains spaces, it should be surrounded by doublequotes. 
+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>:
@@ -228,83 +276,22 @@ are supported in <EM>value</EM>:
         headers are sent on the wire. This is a measure of the
 	duration of the request. The value is preceeded by "D=".
 </PRE>
-add, append and set may take an optional <EM>conditional clause</EM>
-as the fourth argument. The header action (add, append, set) is 
-done only if the <EM>conditional clause</EM> evaluates as TRUE.
 
-<H3>Order of Processing</H3>
+<p>When the <code>Header</code> 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 <code>Header</code>
+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>
 
-The Header (like the RequestHeader) directives can occur almost anywhere within 
-the server configuration. It is 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>
-The Header directives are processed in the following order:
-<OL>
-<LI>main server
-<LI>virtual host
-<LI>&lt;Directory&gt; sections and .htaccess
-<LI>&lt;Location&gt;
-<LI>&lt;Files&gt;
-</OL>
-
-Order is important. These two headers have a different effect if reversed:
-<PRE>
-Header append Author "John P. Doe"
-Header unset Author
-</PRE>
-
-This way round, the Author header is not set. If reversed, the Author
-header is set to "John P. Doe".
-<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>
-<HR>
-<H2>Examples</H2>
-<OL>
-<LI>Copy all request headers that begin with "TS" to the response headers:</LI>
-<PRE>
-   Header echo ^TS*
-</PRE>
-
-<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.</LI>
-<PRE>
-   Header add MyHeader "%D %t"
-</PRE>
-results in this header being added to the response:
-<PRE>
-   MyHeader: D=3775428 t=991424704447256
-</PRE>
-<LI>Say hello to Joe</LI>
-<PRE>
-   Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."
-</PRE>
-results in this header being added to the response:
-<PRE>
-   MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
-</PRE>
-
-<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.</LI>
-<PRE>
-   SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<BR>
-   Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
-</PRE> 
-If the header "MyRequestHeader: value" is present on the HTTP request, the response
-will contain the following header:
-<PRE>
-   MyHeader: D=3775428 t=991424704447256 mytext
-</PRE>
-</OL>
 <!--#include virtual="footer.html" -->
 </BODY>
 </HTML>