Editorial review of first half of Apache chapter.

Some reshuffling to improve flow.
Add descriptions for virtual hosting and modules.
Add URLs to module config docs.

Sponsored by:	iXsystems

1 files changed, 204 insertions, 201 deletions

diff --git a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
index fa4619f2f2..c7648bea20 100644
--- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
@@ -4249,18 +4249,19 @@ $include Kexample.com.+005+nnnnn.ZSK.key    ; ZSK</programlisting>
   </sect1>
 
   <sect1 xml:id="network-apache">
-    <!--
-    <sect1info>
+    <info>
+    <title>Apache HTTP Server</title>
+
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Murray</firstname>
 	  <surname>Stokely</surname>
+	  </personname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
-    </sect1info>
-    -->
-    <title>Apache HTTP Server</title>
+    </info>
 
     <indexterm><primary>web servers</primary>
       <secondary>setting up</secondary></indexterm>
@@ -4273,7 +4274,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key    ; ZSK</programlisting>
 
     <para>This section summarizes how to configure and start version
       2.<replaceable>x</replaceable> of the <application>Apache HTTP
-	Server</application>, the most widely used version, on &os;.
+	Server</application> on &os;.
       For more detailed information about
       <application>Apache</application>&nbsp;2.X and its configuration
       directives, refer to <link
@@ -4287,8 +4288,9 @@ $include Kexample.com.+005+nnnnn.ZSK.key    ; ZSK</programlisting>
 
       <para>In &os;, the main <application>Apache HTTP
 	  Server</application> configuration file is installed as
-	<filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>.
-	This ASCII text file begins comment lines with the
+	<filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>,
+	where <replaceable>x</replaceable> represents the version number.
+	This <acronym>ASCII</acronym> text file begins comment lines with a
 	<literal>#</literal>.  The most frequently modified directives
 	are:</para>
 
@@ -4301,30 +4303,36 @@ $include Kexample.com.+005+nnnnn.ZSK.key    ; ZSK</programlisting>
 	      <application>Apache</application> installation.
 	      Binaries are stored in the <filename>bin</filename> and
 	      <filename>sbin</filename> subdirectories of the server
-	      root, and configuration files are stored in
+	      root and configuration files are stored in the
 	      <filename
-		class="directory">etc/apache2<replaceable>x</replaceable></filename>.</para>
+		class="directory">etc/apache2<replaceable>x</replaceable></filename>
+	      subdirectory.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
-	  <term><literal>ServerAdmin you@your.address</literal></term>
+	  <term><literal>ServerAdmin you@example.com</literal></term>
 
 	  <listitem>
-	    <para>The email address to receive problems with the
+	    <para>Change this to the email address to receive problems with the
 	      server.  This address also appears on some
 	      server-generated pages, such as error documents.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
-	  <term><literal>ServerName www.example.com</literal></term>
+	  <term><literal>ServerName www.example.com:80</literal></term>
 
 	  <listitem>
-	    <para>Allows an administrator to set a host name which is
+	    <para>Allows an administrator to set a hostname which is
 	      sent back to clients for the server.  For example,
 	      <systemitem>www</systemitem> can be used instead of the
-	      actual host name.</para>
+	      actual hostname.  If the system does not have a
+	      registered<acronym>DNS</acronym> name, enter its
+	      <acronym>IP</acronym> address instead.  If the server
+	      will listen on an alternate report, change
+	      <literal>80</literal> to the alternate port
+	      number.</para>
 	  </listitem>
 	</varlistentry>
 
@@ -4342,106 +4350,102 @@ $include Kexample.com.+005+nnnnn.ZSK.key    ; ZSK</programlisting>
 	</varlistentry>
       </variablelist>
 
-      <para>It is always a good idea to make backup copies of the
+      <para>It is always a good idea to make a backup copy of the default
 	<application>Apache</application> configuration file before
 	making changes.  When the configuration of
-	<application>Apache</application>, is complete, save the
-	file and verify the configuration using apachectl(8).
+	<application>Apache</application> is complete, save the
+	file and verify the configuration using <command>apachectl</command>.
 	Running <command>apachectl configtest</command> should return
 	<literal>Syntax OK</literal>.</para>
 
       <indexterm><primary>Apache</primary>
 	<secondary>starting or stopping</secondary></indexterm>
 
-      <para>The <package>www/apache24</package> port
-	installs an &man.rc.8; script to aid in starting, stopping,
-	and restarting <application>Apache</application>, which can be
-	found in <filename>/usr/local/etc/rc.d/</filename>.</para>
-
       <para>To launch <application>Apache</application> at system
 	startup, add the following line to
 	<filename>/etc/rc.conf</filename>:</para>
 
-      <programlisting>apache24_enable="YES"</programlisting>
+      <programlisting>apache<replaceable>24</replaceable>_enable="YES"</programlisting>
 
       <para>If <application>Apache</application> should be started
 	with non-default options, the following line may be added to
 	<filename>/etc/rc.conf</filename> to specify the needed
 	flags:</para>
 
-      <programlisting>apache24_flags=""</programlisting>
-
-      <para>The <application>Apache</application> configuration can be
-	tested for errors after making subsequent configuration
-	changes while <command>httpd</command> is running.  This can
-	be done by the &man.rc.8; script directly, or by the
-	&man.service.8; utility by issuing one of the following
-	commands:</para>
-
-      <screen>&prompt.root; <userinput>service apache24 configtest</userinput></screen>
-
-      <note>
-	<para>It is important to note that the
-	  <literal>configtest</literal> is not an &man.rc.8; standard,
-	  and should not be expected to work for all &man.rc.8;
-	  startup scripts.</para>
-      </note>
+      <programlisting>apache<replaceable>24</replaceable>_flags=""</programlisting>
 
-      <para>If <application>Apache</application> does not report
+      <para>If <application>apachectl</application> does not report
 	configuration errors, start <command>httpd</command>
-	with &man.service.8;:</para>
+	now:</para>
 
-      <screen>&prompt.root; <userinput>service apache24 start</userinput></screen>
+      <screen>&prompt.root; <userinput>service apache<replaceable>24</replaceable> start</userinput></screen>
 
       <para>The <command>httpd</command> service can be tested by
 	entering
 	<literal>http://<replaceable>localhost</replaceable></literal>
 	in a web browser, replacing
 	<replaceable>localhost</replaceable> with the fully-qualified
-	domain name of the machine running <command>httpd</command>,
-	if it is not the local machine.  The default web page that is
+	domain name of the machine running <command>httpd</command>.
+	The default web page that is
 	displayed is
-	<filename>/usr/local/www/apache24/data/index.html</filename>.</para>
+	<filename>/usr/local/www/apache<replaceable>24</replaceable>/data/index.html</filename>.</para>
+
+      <para>The <application>Apache</application> configuration can be
+	tested for errors after making subsequent configuration
+	changes while <command>httpd</command> is running using
+	the following
+	command:</para>
+
+      <screen>&prompt.root; <userinput>service apache<replaceable>24</replaceable> configtest</userinput></screen>
+
+      <note>
+	<para>It is important to note that
+	  <literal>configtest</literal> is not an &man.rc.8; standard,
+	  and should not be expected to work for all
+	  startup scripts.</para>
+      </note>    
     </sect2>
 
     <sect2>
       <title>Virtual Hosting</title>
 
-      <para><application>Apache</application> supports two different
-	types of Virtual Hosting.  The first method is Name-based
-	Virtual Hosting.  Name-based virtual hosting uses the clients
-	HTTP/1.1 headers to figure out the hostname.  This allows many
-	different domains to share the same <acronym>IP</acronym>
+      <para>Virtual hosting allows multiple websites to run on one
+	<application>Apache</application> server.  The virtual hosts
+	can be <firstterm>IP-based</firstterm> or
+	<firstterm>name-based</firstterm>.  <acronym>IP</acronym>-based
+	virtual hosting uses a different <acronym>IP</acronym> address
+	for each website.  Name-based virtual hosting uses the clients
+	HTTP/1.1 headers to figure out the hostname, which allows the
+	websites to share the same <acronym>IP</acronym>
 	address.</para>
 
       <para>To setup <application>Apache</application> to use
-	Name-based Virtual Hosting add an entry like the following to
-	<filename>httpd.conf</filename>:</para>
-
-      <programlisting>NameVirtualHost *</programlisting>
-
-      <para>If the webserver was named <systemitem
-	  class="fqdomainname">www.domain.tld</systemitem> and
-	a virtual domain for <systemitem
-	  class="fqdomainname">www.someotherdomain.tld</systemitem>
-	then add the following entries to
+	name-based virtual hosting, add a
+	<literal>VirtualHost</literal> block for each website.  For
+	example, for the webserver named <systemitem
+	  class="fqdomainname">www.domain.tld</systemitem> with
+	a virtual domain of <systemitem
+	  class="fqdomainname">www.someotherdomain.tld</systemitem>,
+	add the following entries to
 	<filename>httpd.conf</filename>:</para>
 
       <screen>&lt;VirtualHost *&gt;
-ServerName www.domain.tld
-DocumentRoot /www/domain.tld
+ServerName <replaceable>www.domain.tld</replaceable>
+DocumentRoot <replaceable>/www/domain.tld</replaceable>
 &lt;/VirtualHost&gt;
 
 &lt;VirtualHost *&gt;
-ServerName www.someotherdomain.tld
-DocumentRoot /www/someotherdomain.tld
+ServerName <replaceable>www.someotherdomain.tld</replaceable>
+DocumentRoot <replaceable>/www/someotherdomain.tld</replaceable>
 &lt;/VirtualHost&gt;</screen>
 
-      <para>Replace the addresses with the addresses needed and the
-	path to the documents with what are being used.</para>
+      <para>For each virtual host, replace the values for
+	<literal>ServerName</literal> and
+	<literal>DocumentRoot</literal> with the values to be
+	used.</para>
 
       <para>For more information about setting up virtual hosts,
-	please consult the official <application>Apache</application>
+	consult the official <application>Apache</application>
 	documentation at: <uri
 	  xlink:href="http://httpd.apache.org/docs/vhosts/">http://httpd.apache.org/docs/vhosts/</uri>.</para>
     </sect2>
@@ -4452,14 +4456,25 @@ DocumentRoot /www/someotherdomain.tld
       <indexterm><primary>Apache</primary>
 	<secondary>modules</secondary></indexterm>
 
-      <para>There are many different <application>Apache</application>
-	modules available to add functionality to the basic server.
-	The &os; Ports Collection provides an easy way to install
-	<application>Apache</application> together with some of the
-	more popular add-on modules.</para>
+      <para><application>Apache</application> uses
+	modules to augment the functionality provided by the basic
+	server. Refer to <uri
+	  xlink:href="http://httpd.apache.org/docs/current/mod/">http://httpd.apache.org/docs/current/mod/</uri>
+	for a complete listing of and the configuration details for
+	the available modules.</para>
+
+      <para>In &os;, some modules can be compiled with the
+	<package>www/apache24</package> port.  Type <command>make
+	  config</command> within
+	<filename>/usr/ports/www/apache24</filename> to see which
+	modules are available and which are enabled by
+	default.  If the module is not compiled with the port, the
+	&os; Ports Collection provides an easy way to install
+	many modules.  This section describes three of the most
+	commonly used modules.</para>
 
       <sect3>
-	<title><application>mod_ssl</application></title>
+	<title><filename>mod_ssl</filename></title>
 
 	<indexterm>
 	  <primary>web servers</primary>
@@ -4468,157 +4483,56 @@ DocumentRoot /www/someotherdomain.tld
 	<indexterm><primary>SSL</primary></indexterm>
 	<indexterm><primary>cryptography</primary></indexterm>
 
-	<para>The <application>mod_ssl</application> module uses the
-	  OpenSSL library to provide strong cryptography via the
-	  Secure Sockets Layer (SSL v2/v3) and Transport Layer
-	  Security (TLS v1) protocols.  This module provides
+	<para>The <filename>mod_ssl</filename> module uses the
+	  <application>OpenSSL</application> library to provide strong cryptography via the
+	  Secure Sockets Layer (<acronym>SSLv3</acronym>) and Transport Layer
+	  Security (<acronym>TLSv1</acronym>) protocols.  This module provides
 	  everything necessary to request a signed certificate from a
 	  trusted certificate signing authority to run a secure web
 	  server on &os;.</para>
 
-	<para>The <application>mod_ssl</application> module is built
-	  by default, but can be enabled by specifying
-	  <literal>-DWITH_SSL</literal> at compile time.</para>
-      </sect3>
-
-      <sect3>
-	<title>Language Bindings</title>
-
-	<para>There are Apache modules for most major scripting
-	  languages.  These modules typically make it possible to
-	  write <application>Apache</application> modules entirely in
-	  a scripting language.  They are also often used as a
-	  persistent interpreter embedded into the server that avoids
-	  the overhead of starting an external interpreter and the
-	  startup-time penalty for dynamic websites, as described in
-	  the next section.</para>
-      </sect3>
-    </sect2>
-
-    <sect2>
-      <title>Dynamic Websites</title>
-
-      <indexterm>
-	<primary>web servers</primary>
-	<secondary>dynamic</secondary>
-      </indexterm>
-
-      <para>In the last decade, more businesses have turned to the
-	Internet in order to enhance their revenue and increase
-	exposure.  This has also increased the need for interactive
-	web content.  While some companies, such as &microsoft;,
-	have introduced solutions into their proprietary products,
-	the open source community answered the call.  Modern options
-	for dynamic web content include Django, Ruby on Rails,
-	<application>mod_perl2</application>, and
-	<application>mod_php</application>.</para>
-
-      <sect3>
-	<title>Django</title>
-
-	<indexterm><primary>Python</primary></indexterm>
-	<indexterm><primary>Django</primary></indexterm>
-
-	<para>Django is a BSD licensed framework designed to allow
-	  developers to write high performance, elegant web
-	  applications quickly.  It provides an object-relational
-	  mapper so that data types are developed as Python objects,
-	  and a rich dynamic database-access API is provided for those
-	  objects without the developer ever having to write SQL.  It
-	  also provides an extensible template system so that the
-	  logic of the application is separated from the HTML
-	  presentation.</para>
-
-	<para>Django depends on <application>mod_python</application>,
-	  <application>Apache</application>, and an SQL database
-	  engine.  The &os; Port will install all of
-	  these pre-requisites with the appropriate
-	  flags.</para>
-
-	<example xml:id="network-www-django-install">
-	  <title>Installing Django with
-	    <application>Apache2</application>,
-	    <application>mod_python3</application>, and
-	    <application>PostgreSQL</application></title>
-
-	  <screen>&prompt.root; <userinput>cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL</userinput></screen>
-	</example>
-
-	<para>Once Django and these pre-requisites are installed,
-	  the application will need a Django project directory along
-	  with the Apache configuration to use the embedded Python
-	  interpreter.  This will be the interpreter to
-	  call the application for specific URLs on the site.</para>
-
-	<example xml:id="network-www-django-apache-config">
-	  <title>Apache Configuration for Django/mod_python</title>
-
-	  <para>A line must be added to the apache
-	    <filename>httpd.conf</filename> file to configure Apache
-	    to pass requests for certain URLs to the web
-	    application:</para>
-
-	  <screen>&lt;Location "/"&gt;
-    SetHandler python-program
-    PythonPath "['/dir/to/the/django/packages/'] + sys.path"
-    PythonHandler django.core.handlers.modpython
-    SetEnv DJANGO_SETTINGS_MODULE mysite.settings
-    PythonAutoReload On
-    PythonDebug On
-&lt;/Location&gt;</screen>
-	</example>
-      </sect3>
-
-      <sect3>
-	<title>Ruby on Rails</title>
-
-	<indexterm><primary>Ruby on Rails</primary></indexterm>
-
-	<para>Ruby on Rails is another open source web framework that
-	  provides a full development stack and is optimized to make
-	  web developers more productive and capable of writing
-	  powerful applications quickly.  It can be installed easily
-	  from the ports system.</para>
-
-	<screen>&prompt.root; <userinput>cd /usr/ports/www/rubygem-rails; make all install clean</userinput></screen>
+	<para>In &os;, <filename>mod_ssl</filename> module is enabled
+	  by default in both the package and the port.  The available
+	  configuration directives are explained at <uri
+	    xlink:href="http://httpd.apache.org/docs/current/mod/mod_ssl.html">http://httpd.apache.org/docs/current/mod/mod_ssl.html</uri>.</para>
       </sect3>
 
       <sect3>
-	<title><application>mod_perl2</application></title>
+	<title><filename>mod_perl2</filename></title>
 
 	<indexterm>
 	  <primary>mod_perl2</primary>
 	  <secondary>Perl</secondary>
 	</indexterm>
 
-	<para>The <application>Apache</application>/Perl integration
-	  project brings together the full power of the Perl
-	  programming language and the
-	  <application>Apache HTTP Server</application>.  With the
-	  <application>mod_perl2</application> module it is possible
-	  to write <application>Apache</application> modules entirely
-	  in Perl.  In addition, the persistent interpreter embedded
+	<para>The
+	  <filename>mod_perl2</filename> module makes it possible
+	  to write <application>Apache</application> modules
+	  in <application>Perl</application>.  In addition, the persistent interpreter embedded
 	  in the server avoids the overhead of starting an external
-	  interpreter and the penalty of Perl start-up time.</para>
+	  interpreter and the penalty of <application>Perl</application> start-up time.</para>
 
-	<para><application>mod_perl2</application> is available in the
-	  <package>www/mod_perl2</package>
-	  port.</para>
+	<para>The <filename>mod_perl2</filename> can be installed using the
+	  <package>www/mod_perl2</package> package or
+	  port.  Documentation for using this module can be found at
+	  <uri
+	    xlink:href="http://perl.apache.org/docs/2.0/index.html">http://perl.apache.org/docs/2.0/index.html</uri>.</para>
       </sect3>
 
       <sect3>
-	<!--
-	<sect3info>
+	<info>
+	<title><application>mod_php</application></title>
+
 	  <authorgroup>
 	    <author>
+	    <personname>
 	      <firstname>Tom</firstname>
 	      <surname>Rhodes</surname>
+	    </personname>
 	      <contrib>Written by </contrib>
 	    </author>
 	  </authorgroup>
-	</sect3info>
-	-->
-	<title><application>mod_php</application></title>
+	</info>
 
 	<indexterm>
 	  <primary>mod_php</primary>
@@ -4717,6 +4631,95 @@ DocumentRoot /www/someotherdomain.tld
 	<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>
       </sect3>
     </sect2>
+
+    <sect2>
+      <title>Dynamic Websites</title>
+
+      <indexterm>
+	<primary>web servers</primary>
+	<secondary>dynamic</secondary>
+      </indexterm>
+
+      <para>In the last decade, more businesses have turned to the
+	Internet in order to enhance their revenue and increase
+	exposure.  This has also increased the need for interactive
+	web content.  While some companies, such as &microsoft;,
+	have introduced solutions into their proprietary products,
+	the open source community answered the call.  Modern options
+	for dynamic web content include Django, Ruby on Rails,
+	<application>mod_perl2</application>, and
+	<application>mod_php</application>.</para>
+
+      <sect3>
+	<title>Django</title>
+
+	<indexterm><primary>Python</primary></indexterm>
+	<indexterm><primary>Django</primary></indexterm>
+
+	<para>Django is a BSD licensed framework designed to allow
+	  developers to write high performance, elegant web
+	  applications quickly.  It provides an object-relational
+	  mapper so that data types are developed as Python objects,
+	  and a rich dynamic database-access API is provided for those
+	  objects without the developer ever having to write SQL.  It
+	  also provides an extensible template system so that the
+	  logic of the application is separated from the HTML
+	  presentation.</para>
+
+	<para>Django depends on <application>mod_python</application>,
+	  <application>Apache</application>, and an SQL database
+	  engine.  The &os; Port will install all of
+	  these pre-requisites with the appropriate
+	  flags.</para>
+
+	<example xml:id="network-www-django-install">
+	  <title>Installing Django with
+	    <application>Apache2</application>,
+	    <application>mod_python3</application>, and
+	    <application>PostgreSQL</application></title>
+
+	  <screen>&prompt.root; <userinput>cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL</userinput></screen>
+	</example>
+
+	<para>Once Django and these pre-requisites are installed,
+	  the application will need a Django project directory along
+	  with the Apache configuration to use the embedded Python
+	  interpreter.  This will be the interpreter to
+	  call the application for specific URLs on the site.</para>
+
+	<example xml:id="network-www-django-apache-config">
+	  <title>Apache Configuration for Django/mod_python</title>
+
+	  <para>A line must be added to the apache
+	    <filename>httpd.conf</filename> file to configure Apache
+	    to pass requests for certain URLs to the web
+	    application:</para>
+
+	  <screen>&lt;Location "/"&gt;
+    SetHandler python-program
+    PythonPath "['/dir/to/the/django/packages/'] + sys.path"
+    PythonHandler django.core.handlers.modpython
+    SetEnv DJANGO_SETTINGS_MODULE mysite.settings
+    PythonAutoReload On
+    PythonDebug On
+&lt;/Location&gt;</screen>
+	</example>
+      </sect3>
+
+      <sect3>
+	<title>Ruby on Rails</title>
+
+	<indexterm><primary>Ruby on Rails</primary></indexterm>
+
+	<para>Ruby on Rails is another open source web framework that
+	  provides a full development stack and is optimized to make
+	  web developers more productive and capable of writing
+	  powerful applications quickly.  It can be installed easily
+	  from the ports system.</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/ports/www/rubygem-rails; make all install clean</userinput></screen>
+      </sect3>
+    </sect2>
   </sect1>
 
   <sect1 xml:id="network-ftp">