[deployment-guide/comm-rel: 515/727] Updated the KeepAlive directive description.

[Jaromir Hradilek]

commit 03e59ae2b0638928e54b074e1e8a351670593d62
Author: Jaromir Hradilek <jhradile at redhat.com>
Date:   Mon Aug 30 18:00:14 2010 +0200

    Updated the KeepAlive directive description.

 en-US/The_Apache_HTTP_Server.xml |   87 +++++++++++++++++++++++++-------------
 1 files changed, 57 insertions(+), 30 deletions(-)
---
diff --git a/en-US/The_Apache_HTTP_Server.xml b/en-US/The_Apache_HTTP_Server.xml
index de55ee3..0750871 100644
--- a/en-US/The_Apache_HTTP_Server.xml
+++ b/en-US/The_Apache_HTTP_Server.xml
@@ -728,7 +728,7 @@ AddIcon /icons/blank.png ^^BLANKICON^^</screen>
             </para>
             <screen>CacheNegotiatedDocs <replaceable>option</replaceable></screen>
             <para>
-              The <replaceable>option</replaceable> has to be a valid boolean as described in <xref linkend="table-apache-httpdconf-cachenegotiateddocs" />. Since the content-negotiated documents may change over time or because of the input from the requester, the default option is <option>Off</option>.
+              The <replaceable>option</replaceable> has to be a valid keyword as described in <xref linkend="table-apache-httpdconf-cachenegotiateddocs" />. Since the content-negotiated documents may change over time or because of the input from the requester, the default option is <option>Off</option>.
             </para>
             <table id="table-apache-httpdconf-cachenegotiateddocs">
               <title>Available <option>CacheNegotiatedDocs</option> options</title>
@@ -924,7 +924,7 @@ ErrorDocument 404 /404-not_found.html</screen>
             </para>
             <screen>ExtendedStatus <replaceable>option</replaceable></screen>
             <para>
-              The <replaceable>option</replaceable> has to be a valid boolean as described in <xref linkend="table-apache-httpdconf-extendedstatus" />. The default option is <option>Off</option>.
+              The <replaceable>option</replaceable> has to be a valid keyword as described in <xref linkend="table-apache-httpdconf-extendedstatus" />. The default option is <option>Off</option>.
             </para>
             <table id="table-apache-httpdconf-extendedstatus">
               <title>Available options</title>
@@ -1096,6 +1096,61 @@ ErrorDocument 404 /404-not_found.html</screen>
             </example>
           </listitem>
         </varlistentry>
+        <!-- TODO: Add the IndexOptions directive description here. -->
+        <varlistentry>
+          <term><option>KeepAlive</option></term>
+          <listitem>
+            <para>
+              The <option>KeepAlive</option> directive allows you to enable persistent connections. It takes the following form: 
+            </para>
+            <screen>KeepAlive <replaceable>option</replaceable></screen>
+            <para>
+              The <replaceable>option</replaceable> has to be a valid keyword as described in <xref linkend="table-apache-httpdconf-keepalive" />. The default option is <option>Off</option>.
+            </para>
+            <table id="table-apache-httpdconf-keepalive">
+              <title>Available <option>KeepAlive</option> options</title>
+              <tgroup cols="2">
+                <colspec colname="option" colnum="1" colwidth="20*" />
+                <colspec colname="description" colnum="2" colwidth="60*" />
+                <thead>
+                  <row>
+                    <entry>
+                      Option
+                    </entry>
+                    <entry>
+                      Description
+                    </entry>
+                  </row>
+                </thead>
+                <tbody>
+                  <row>
+                    <entry>
+                      <option>On</option>
+                    </entry>
+                    <entry>
+                      Enables the persistent connections. In this case, the server will accept more than one request per connection.
+                    </entry>
+                  </row>
+                  <row>
+                    <entry>
+                      <option>Off</option>
+                    </entry>
+                    <entry>
+                      Disables the keep-alive connections.
+                    </entry>
+                  </row>
+                </tbody>
+              </tgroup>
+            </table>
+            <para>
+              Note that when the persistent connections are enabled, on a busy server, the number of child processes can increase rapidly and eventually reach the maximum limit, slowing down the server significantly. To reduce the risk, it is recommended that you set <option>KeepAliveTimeout</option> to a low number, and monitor the <filename>/var/log/httpd/error_log</filename> log file carefully.
+            </para>
+            <example id="example-apache-httpdconf-keepalive">
+              <title>Using the <option>KeepAlive</option> directive</title>
+              <screen>KeepAlive Off</screen>
+            </example>
+          </listitem>
+        </varlistentry>
       </variablelist>
       <formalpara id="s2-apache-indexoptions">
         <title>IndexOptions</title>
@@ -1123,34 +1178,6 @@ ErrorDocument 404 /404-not_found.html</screen>
       <para>
         <command>IndexOptions</command> has a number of other parameters which can be set to control the appearance of server generated directories. The <command>IconHeight</command> and <command>IconWidth</command> parameters require the server to include HTML <command>HEIGHT</command> and <command>WIDTH</command> tags for the icons in server generated webpages. The <command>IconsAreLinks</command> parameter combines the graphical icon with the HTML link anchor, which contains the URL link target.
       </para>
-      <formalpara id="s2-apache-keepalive">
-        <title>KeepAlive</title>
-        <indexterm>
-          <primary><command>KeepAlive</command></primary>
-          <secondary>Apache configuration directive</secondary>
-        </indexterm>
-        <indexterm>
-          <primary>configuration directives, Apache</primary>
-          <secondary><command>KeepAlive</command></secondary>
-          <tertiary>troubleshooting</tertiary>
-        </indexterm>
-        <indexterm>
-          <primary>configuration directives, Apache</primary>
-          <secondary><command>KeepAlive</command></secondary>
-          <seealso><command>KeepAliveTimeout</command></seealso>
-        </indexterm>
-        <indexterm>
-          <primary>Apache HTTP Server</primary>
-          <secondary>log files</secondary>
-          <tertiary>troubleshooting with</tertiary>
-        </indexterm>
-        <para>
-          <command>KeepAlive</command> sets whether the server allows more than one request per connection and can be used to prevent any one client from consuming too much of the server's resources.
-        </para>
-      </formalpara>
-      <para>
-        By default <command>Keepalive</command> is set to <command>off</command>. If <command>Keepalive</command> is set to <command>on</command> and the server becomes very busy, the server can quickly spawn the maximum number of child processes. In this situation, the server slows down significantly. If <command>Keepalive</command> is enabled, it is a good idea to set the the <command>KeepAliveTimeout</command> low (refer to <xref linkend="s2-apache-keepalivetimeout" /> for more information about the <command>KeepAliveTimeout</command> directive) and monitor the <filename>/var/log/httpd/error_log</filename> log file on the server. This log reports when the server is running out of child processes.
-      </para>
       <formalpara id="s2-apache-keepalivetimeout">
         <title>KeepAliveTimeout</title>
         <indexterm>