[3418] Changes to installation instructions made as part of review.

doc/guide/install.xml

@@ -26,8 +26,8 @@
     <section id="install-hierarchy">
       <title>Install Hierarchy</title>
       <para>
-        The following is the standard, common layout of the
-        complete Kea installation:
+        The following is the directory layout of the complete Kea installation
+        (all directories paths are relative to the installation directory):
         <itemizedlist>
           <listitem>
            <simpara>
@@ -109,25 +109,36 @@
             Some operating systems have split their distribution packages into
             a run-time and a development package.  You will need to install
             the development package versions, which include header files and
-            libraries, to build Kea from source code.
+            libraries, to build Kea from the source code.
           </simpara>
         </note>
 
         <para>
-          Building from source code requires the Boost
-          build-time headers
+          Building from source code requires the following software installed
+          on the system:</para>
+          <itemizedlist>
+            <listitem>
+                <para>Boost build-time headers
           (<ulink url="http://www.boost.org/"/>).
           At least Boost version 1.35 is required.
   <!-- TODO: we don't check for this version -->
   <!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
         </para>
+        </listitem>
 
+            <listitem>
         <para>
-          To build Kea, also install the Botan (at least version
-          1.8) and the log4cplus (at least version 1.0.3)
+          Botan (at least version
+          1.8).</para>
+          </listitem>
+
+          <listitem>
+          <para>
+            log4cplus (at least version 1.0.3)
           development include headers.
 	  <!-- @todo: Add OpenSSL note here once #2406 is merged -->
         </para>
+        </listitem>
 
 <!--
 TODO
@@ -138,13 +149,24 @@ Debian and Ubuntu:
 <!-- NOTE: _sqlite3 is only needed at test time; it is already listed
 as a dependency earlier -->
 
+        <listitem>
         <para>
-          Building Kea also requires a C++ compiler and
-          standard development headers, make, and pkg-config.
+          A C++ compiler and
+          standard development headers.
           Kea builds have been tested with GCC g++ 3.4.3, 4.1.2,
           4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
 	  <!-- @todo update this list -->
         </para>
+        </listitem>
+
+        <listitem>
+        <para>
+          The development tools "make" and "pkg-config".
+	  <!-- @todo update this list -->
+        </para>
+        </listitem>
+
+        </itemizedlist>
 
         <para>
           Visit the user-contributed wiki at <ulink
@@ -155,7 +177,7 @@ as a dependency earlier -->
     </section>
 
     <section id="install">
-      <title>Installation from source</title>
+      <title>Installation from Source</title>
       <para>
         Kea is open source software written in C++ (some components of the
         BIND 10 framework are written in Python).
@@ -171,7 +193,7 @@ as a dependency earlier -->
         <para>
           Kea 0.8 is available as a part of BIND10 1.2 release, which is a final
           release of BIND10 from ISC. This release can be downloaded from:
-          <ulink url="ftp://ftp.isc.org/isc/bind10/"/>. Upcoming Kea 0.9 and all
+          <ulink url="ftp://ftp.isc.org/isc/bind10/"/>. The upcoming Kea 0.9 and all
 	  following releases will be shipped as a stand-alone tarball.
         </para>
       </section>
@@ -186,15 +208,15 @@ as a dependency earlier -->
 
         <note>
           <para>
-            When using source code retrieved via Git, additional
-            software will be required:  automake (v1.11 or newer),
-            libtoolize, and autoconf (2.59 or newer).
+            When building from source code retrieved via Git, additional
+            software will be required:  automake (v1.11 or later),
+            libtoolize, and autoconf (2.59 or later).
             These may need to be installed.
           </para>
         </note>
 
         <para>
-          The latest development code (and temporary experiments
+          The latest development code (together with temporary experiments
           and un-reviewed code) is available via the Kea code revision
           control system. This is powered by Git and all the Kea
           development is public.
@@ -203,15 +225,13 @@ as a dependency earlier -->
         </para>
         <para>
           The code can be checked out from
-          <filename>git://git.kea.isc.org/kea</filename>;
-          for example:
+          <filename>git://git.kea.isc.org/kea</filename>:
 
         <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
         </para>
 
         <para>
-          When checking out the code from
-          the code version control system, it doesn't include the
+          The code checked out from the git repository doesn't include the
           generated configure script, Makefile.in files, nor their
           related build files.
           They can be created by running <command>autoreconf</command>
@@ -245,7 +265,7 @@ as a dependency earlier -->
             <term>--prefix</term>
             <listitem>
               <simpara>Define the installation location (the
-                default is <filename>/usr/local/</filename>).
+                default is <filename>/usr/local</filename>).
               </simpara>
             </listitem>
           </varlistentry>
@@ -263,7 +283,7 @@ as a dependency earlier -->
             <listitem>
               <simpara>Define the path to Python 3.x if it is not in the
                 standard execution path. Python 3.x is mandatory for Kea 0.8,
-		but is no longer required for upcoming Kea 0.9.
+		but will not be required for the upcoming Kea 0.9.
               </simpara>
             </listitem>
           </varlistentry>
@@ -271,9 +291,11 @@ as a dependency earlier -->
           <varlistentry>
             <term>--with-gtest</term>
             <listitem>
-              <simpara>Enable building the C++ Unit Tests using the
-                Google Tests framework. Optionally this can define the
-                path to the gtest header files and library.
+              <simpara>Enable the building of the C++ Unit Tests using the
+                Google Test framework. Optionally this can define the
+                path to the gtest header files and library. (If the framework
+                is not already installed on your system, it can be downloaded
+                from <ulink url="https://code.google.com/p/googletest"/>.)
               </simpara>
             </listitem>
           </varlistentry>
@@ -283,7 +305,7 @@ as a dependency earlier -->
             <listitem>
               <simpara>Disable the default use of the
 		<option>-Werror</option> compiler flag so that
-		compiler warnings aren't build failures.
+		compiler warnings do not result in build failures.
               </simpara>
             </listitem>
           </varlistentry>
@@ -301,9 +323,10 @@ as a dependency earlier -->
   <!-- TODO: lcov -->
 
         <para>
-          For example, the following configures it to find the Boost headers,
-          specifies that PostgreSQL support should be enabled, and sets the
-          installation location:
+          For example, the following command configures Kea to find the
+          Boost headers in /usr/pkg/include, specifies that PostgreSQL
+          support should be enabled, and sets the installation location
+          to /opt/kea:
 
           <screen>$ <userinput>./configure \
       --with-boost-include=/usr/pkg/include \
@@ -322,8 +345,8 @@ as a dependency earlier -->
       <section>
         <title>Build</title>
         <para>
-    After the configure step is complete, to build the executables
-    from the C++ code and prepare the Python scripts, run:
+    After the configure step is complete, build the executables
+    from the C++ code and prepare the Python scripts by running the command:
 
           <screen>$ <userinput>make</userinput></screen>
         </para>
@@ -333,13 +356,13 @@ as a dependency earlier -->
         <title>Install</title>
         <para>
           To install the Kea executables, support files,
-          and documentation, run:
+          and documentation, issue the command:
           <screen>$ <userinput>make install</userinput></screen>
         </para>
         <para>
-          Please don't use any form of parallel or job server options
+          Do not use any form of parallel or job server options
           (such as GNU make's <command>-j</command> option) when
-          performing this step. Doing so may cause errors.
+          performing this step: doing so may cause errors.
         </para>
         <note>
           <para>The install step may require superuser privileges.</para>
@@ -369,11 +392,12 @@ as a dependency earlier -->
     </section>
 
     <section id="dhcp-config-backend">
-      <title>Selecting configuration backend</title>
-      <para>Kea 0.9 introduces configuration backends that are switchable during
-      compilation phase. There is a new parameter for configure script:
-      --with-kea-config. It currently supports two values: BIND10 and
-      JSON. This is currently only supported by DHCPv6 component.</para>
+      <title>Selecting the Configuration Backend</title>
+      <para>Kea 0.9 introduces configuration backends that are
+      switchable during compilation phase. The backend is chosen using
+      the --with-kea-config switch when running the configure script. It
+      currently supports two values: BIND10 and JSON. This is currently
+      only supported by DHCPv6 component.</para>
 
       <variablelist>
 
@@ -412,7 +436,7 @@ as a dependency earlier -->
       <para>
         Kea stores its leases in a lease database.  The software has been written in
         a way that makes it possible to choose which database product should be used to
-        store the lease information.  At present, Kea supports 3 database backends: MySQL,
+        store the lease information.  At present, Kea supports three database backends: MySQL,
         PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL
         support are disabled by default and only Memfile (which is implemented in pure C++)
         is available. Support for a given database backend must be explicitly included when
@@ -420,7 +444,7 @@ as a dependency earlier -->
         and the creation of the lease database.
       </para>
       <section>
-        <title>Building with MySQL support</title>
+        <title>Building with MySQL Support</title>
         <para>
           Install MySQL according to the instructions for your system.  The client development
           libraries must be installed.
@@ -438,7 +462,7 @@ as a dependency earlier -->
         </para>
       </section>
       <section id="dhcp-mysql-database-create">
-        <title>Create MySQL Database and Kea User</title>
+        <title>Create the MySQL Database and the Kea User</title>
         <para>
           The next task is to create both the lease database and the user under which the servers will
           access it. A number of steps are required:
@@ -456,12 +480,12 @@ mysql></screen>
           ... <replaceable>database-name</replaceable> is the name you have chosen for the database.
         </para>
          <para>
-          3. Create the database tables:
+          3. Create the database tables by running the dhcpdb_create.mysql script supplied as part of Kea:
           <screen>mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
 mysql> <userinput>SOURCE <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.mysql</userinput></screen>
         </para>
          <para>
-          4. Create the user under which BIND 10 will access the database (and give it a password), then grant it access to the database tables:
+          4. Create the user under which Kea will access the database (and give it a password), then grant it access to the database tables:
           <screen>mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
 mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput></screen>
         </para>
@@ -531,7 +555,7 @@ Bye<userinput/>
 $</screen>
        </para>
        <para>
-        5. Create the database tables using the new user's credentials.
+        5. Create the database tables using the new user's credentials and the dhcpdb_create.pgsql script supplied with Kea.
         After entering the following command, you will be prompted for the new
         user's password. When the command completes you will be returned to
         the shell prompt. You should see output similar to following:
@@ -556,13 +580,13 @@ $
 </screen>
   </para>
   <para>
-  If instead you encounter an error such as shown below:
+  If instead you encounter an error like:
   </para>
 <screen>
 psql: FATAL:  no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
 </screen>
   <para>
-  This indicates that the PostgreSQL configuration needs to be modified.
+  ... you will need to alter the PostgreSQL configuration.
   Kea uses password authentication when connecting to the database and must
   have the appropriate entries added to PostgreSQL's pg_hba.conf file.  This
   file is normally located in the primary data directory for your PostgreSQL