Documentation conversion complete

1 files changed, 194 insertions, 187 deletions

diff --git a/Documentation/manual.xml b/Documentation/manual.xml
index fe13daa..daafd69 100644
--- a/Documentation/manual.xml
+++ b/Documentation/manual.xml
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <?xml-stylesheet href="file://localhost/home/urkle/Documents/DocBook/docbook.css" type="text/css"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "file:/usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-8/docbookx.dtd">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "file:/usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-8/docbookx.dtd" [
+<!ENTITY MaintainerContact "the maintainer, Edward Rudd at <email>eddie &lt;at&gt; omegaware &lt;dot&gt; com</email>">
+]>
 <article>
   <articleinfo>
     <title>mod_log_sql Manual</title>
@@ -34,6 +36,11 @@
     </copyright>
     <revhistory>
       <revision>
+        <revnumber>1.1</revnumber>
+        <date>2004-03-02</date>
+        <revremark>Updated for mod_log_sql v1.96</revremark>
+      </revision>
+      <revision>
         <revnumber>1.0</revnumber>
         <date>2004-01-22</date>
         <revremark>Initial Conversion from Lyx to Docbook</revremark>
@@ -44,7 +51,7 @@
     <title>Introduction</title>
     <sect2>
       <title>Summary</title>
-      <para>This Apache module will permit you to log to a SQL database; it can log each access request as well as data associated with each request: cookies, notes, and inbound/outbound headers. Unlike logging to a flat text file -- which is standard in Apache -- a SQL-based log exhibits tremendous flexibility and power of data extraction. (See section [sub:why] in the FAQ for further discussion and examples of the advantages to SQL.)</para>
+      <para>This Apache module will permit you to log to a SQL database; it can log each access request as well as data associated with each request: cookies, notes, and inbound/outbound headers. Unlike logging to a flat text file -- which is standard in Apache -- a SQL-based log exhibits tremendous flexibility and power of data extraction. (See section <link linkend="WhyLogToSQL"></link> in the FAQ for further discussion and examples of the advantages to SQL.)</para>
       <para>This module can either replace or happily coexist with mod_log_config, Apache's text file logging facility. In addition to being more configurable than the standard module, mod_log_sql is much more flexible.</para>
     </sect2>
     <sect2 id="copyright">
@@ -52,11 +59,11 @@
       <para>This project was formerly known as "mod_log_mysql." It was renamed "mod_log_sql" in order to reflect the project goal of database in-specificity. The module currently supports MySQL, but support for other database back-ends is underway.</para>
       <para>In order to save speed and overhead, links are kept alive in between queries. This module uses one dedicated SQL link per httpd child, opened by each child process when it is born. Among other things, this means that this module supports logging into only one MySQL server, and for now, also, only one SQL database. But that's a small tradeoff compared to the blinding speed of this module. Error reporting is robust throughout the module and will inform the administrator of database issues in the Apache ErrorLog for the server/virtual server.</para>
       <para>Virtual hosts are supported in the same manner they are in the regular logging modules. The administrator defines some basic 'global' directives in the main server config, then defines more specific 'local' directives inside each VirtualHost stanza.</para>
-      <para>A robust "preserve" capability has now been implemented. This permits the module to preserve any failed INSERT commands to a local file on its machine. In any situation that the database is unavailable -- e.g. the network fails or the database host is rebooted -- mod_log_sql will note this in the error log and begin appending its log entries to the preserve file (which is created with the user &amp; group ID of the running Apache process, e.g. "nobody/nobody" on many Linux installations). When database availability returns, mod_log_sql seamlessly resumes logging to it. When convenient for the sysadmin, he/she can easily import the preserve file into the database because it is simply a series of SQL insert statements.</para>
+      <para>A robust "preserve" capability has now been implemented. This permits the module to preserve any failed INSERT commands to a local file on its machine. In any situation that the database is unavailable -- e.g. the network fails or the database host is rebooted -- mod_log_sql will note this in the error log and begin appending its log entries to the preserve file (which is created with the user and group ID of the running Apache process, e.g. "nobody/nobody" on many Linux installations). When database availability returns, mod_log_sql seamlessly resumes logging to it. When convenient for the sysadmin, he/she can easily import the preserve file into the database because it is simply a series of SQL insert statements.</para>
     </sect2>
     <sect2>
       <title>What gets logged by default?</title>
-      <para>All the data that would be contained in the "Combined Log Format" is logged by default, plus a little extra. Your best bet is to begin by accepting this default, then later customize the log configuration based on your needs. The documentation of the run-time directives includes a full explanation of what you can log, including examples -- see section [sec:ConfRef].</para>
+      <para>All the data that would be contained in the "Combined Log Format" is logged by default, plus a little extra. Your best bet is to begin by accepting this default, then later customize the log configuration based on your needs. The documentation of the run-time directives includes a full explanation of what you can log, including examples -- see section <link endterm="Configuration.title" linkend="ConfigReference"></link>.</para>
     </sect2>
     <sect2>
       <title>Miscellaneous Notes</title>
@@ -87,6 +94,7 @@
       <para>The MySQL routines and directives were added by Zeev Suraski &lt;bourbon@netvision.net.il&gt;. </para>
       <para>All changes from 1.06+ and the new documentation were added by Chris Powell <email>chris &lt;at&gt; grubbybaby &lt;dot&gt; com</email>. It seems that the module had fallen into the "un-maintained" category -- it had not been updated since 1998 -- so Chris adopted it as the new maintainer.</para>
       <para>In December of 2003, Edward Rudd <email>eddie &lt;at&gt; omegaware &lt;dot&gt; com</email> porting the module to Apache 2.0, cleaning up the code, converting the documentation to DocBook, optimizing the main logging loop, and added the much anticipated database abstraction layer.</para>
+      <para>As of February 2004, Chris Powell handed over maintenance of the module over to Edward Rudd. So you should contact Edward Rudd about the module from now on.</para>
     </sect2>
   </sect1>
   <sect1>
@@ -113,9 +121,10 @@
     </sect2>
     <sect2>
       <title>Platform Specific Notes</title>
-      <para><remark>This section is currently not applicable as the new autoconf setup should autodetect everything for your server..Win32 system, however, need to be updated.</remark>These installation documents assume a relatively modern GNU/Linux scenario. mod_log_sql has been ported to other platforms; following are notes on compiling the module for those platforms.</para>
-      <sect3>
-        <title>&lt;sub:Solaris&gt;Solaris</title>
+      <remark>This section is currently not applicable as the new autoconf setup should auto-detect everything for your server. The win32 compilation, however, is still on my todo list. This section needs to be overhauled so do not rely completely on any information presented in it. And anyone who compiles the mod_log_sql on these platforms, please report any issues/resolutions to compiling the module.</remark>
+      <para>These installation documents assume a relatively modern GNU/Linux scenario. mod_log_sql has been ported to other platforms; following are notes on compiling the module for those platforms.</para>
+      <sect3 id="Solaris">
+        <title id="Solaris.title">Solaris</title>
         <para>The nanosleep() function used in mod_log_sql relies on linking aginst the librt library. Make the following alterations before proceeding: </para>
         <orderedlist>
           <listitem>
@@ -128,11 +137,11 @@
       </sect3>
       <sect3>
         <title>BSD</title>
-        <para>No notes are available at present, but they are desired. If you have successfully ported mod_log_sql to BSD, please contact [(chris@grubbybaby.com)||the maintaniner, Chris Powell] and help fill in this section.</para>
+        <para>No notes are available at present, but they are desired. If you have successfully ported mod_log_sql to BSD, please contact &MaintainerContact; and help fill in this section.</para>
       </sect3>
       <sect3>
         <title>Win32</title>
-        <para>No notes are available at present, but they are desired. If you have successfully ported mod_log_sql to Win32, please contact [(chris@grubbybaby.com)||the maintaniner, Chris Powell] and help fill in this section.</para>
+        <para>No notes are available at present, but they are desired. If you have successfully ported mod_log_sql to Win32, please contact &MaintainerContact; and help fill in this section.</para>
       </sect3>
       <sect3>
         <title>OS X</title>
@@ -142,14 +151,15 @@
       </sect3>
       <sect3>
         <title>Digital Unix</title>
-        <para>Digital Unix, like Solaris, needs to be linked against librt; see section [sub:Solaris]. Here are further notes from a user successfully running the module on Digital Unix:</para>
+        <para>Digital Unix, like Solaris, needs to be linked against librt; see section <link endterm="Solaris.title" linkend="Solaris"></link>. Here are further notes from a user successfully running the module on Digital Unix:</para>
         <para>Instead of trying to get the module to remember where the MySQL libraries were, I instead compiled apache with the information: LDFLAGS='-rpath /isp/mysql/lib/mysql' ./configure ... Everything worked as expected after that. (The error I got without this was "/sbin/loader: Fatal Error: cannot map libmysqlclient.so" ) Digital Unix (v4.0f, at least ) appears to follow the same requirements needed by Solaris, so simply adding librt to the module made it compile without errors. As for the warnings, here's the text: mod_log_sql.c: In function `extract_request_duration': mod_log_sql.c:292: warning: long int format, different type arg (arg 4) mod_log_sql.c: In function `extract_request_timestamp': mod_log_sql.c:497: warning: long int format, different type arg (arg 4) Poking around in the code, it looks like the compiler was complaining that what time() is returning doesn't play nicely with %ld by default. I just typecast them as (long)'s and the warnings went away ( not that the module wasn't working correctly without them ). The module works very well so far in testing... hasn't dropped a single log entry yet. </para>
         <para>My thanks to Jim Turner for permitting me to quote him here, and for being the first known user of mod_log_sql on Digital Unix</para>
       </sect3>
     </sect2>
     <sect2>
       <title>Do I want a DSO or a static module</title>
-      <para><remark>This section is no longer applicable, as the new autoconf setup only allows DSO with Apache 1.3 and 2.0.</remark>You need to know the answer to this question before you proceed. The answer is pretty straightforward: what have you done in the past? If you like all your Apache modules to be dynamic, then you should keep doing that. If you're more of an old-school type and prefer to compile the modules right into apache, do that. Both methods work equally well. </para>
+      <remark>This section is no longer applicable, as the new autoconf setup only allows DSO with Apache 1.3 and 2.0. This section will be removed shortly.</remark>
+      <para>You need to know the answer to this question before you proceed. The answer is pretty straightforward: what have you done in the past? If you like all your Apache modules to be dynamic, then you should keep doing that. If you're more of an old-school type and prefer to compile the modules right into apache, do that. Both methods work equally well. </para>
       <para>FWIW, the DSO method is more modern and increasing in popularity because apxs takes care of a lot of dirty little details for you. As you'll see below, the static-module method is a little more complex.</para>
     </sect2>
     <sect2>
@@ -254,12 +264,12 @@ AddModule mod_log_sql_ssl.c
       </orderedlist>
     </sect2>
   </sect1>
-  <sect1>
-    <title>&lt;sec:Configuration&gt;Configuration</title>
-    <sect2>
-      <title>&lt;sub:PrepDb&gt;Preparing MySQL for logging</title>
+  <sect1 id="Configuration">
+    <title id="Configuration.title">Configuration</title>
+    <sect2 id="Preperation">
+      <title id="Preperation.title">Preparing MySQL for logging</title>
       <para>You have to prepare the database to receive data from <application>mod_log_sql</application>, and set up run-time directives in <filename>httpd.conf</filename> to control how and what <application>mod_log_sql</application> logs.</para>
-      <para>This section will discuss how to get started with a basic configuration. Full documentation of all available run-time directives is available in section [sec:ConfRef].</para>
+      <para>This section will discuss how to get started with a basic configuration. Full documentation of all available run-time directives is available in section <link endterm="ConfigReference.title" linkend="ConfigReference"></link>.</para>
       <orderedlist>
         <listitem>
           <para>mod_log_sql can make its own tables on-the-fly, or you can pre-make the tables by hand. The advantage of letting the module make the tables is ease-of-use, but for raw performance you will want to pre-make the tables in order to save some overhead. In this basic setup we'll just let the module create tables for us.</para>
@@ -270,8 +280,8 @@ AddModule mod_log_sql_ssl.c
 Enter password:
 mysql&gt; create database apachelogs;</screen>
         </listitem>
-        <listitem>
-          <para>&lt;part:CrTbl&gt;If you want to hand-create the tables, run the enclosed 'create-tables' SQL script as follows ("create_tables.sql" needs to be in your current working directory).</para>
+        <listitem id="CreateTable">
+          <para>If you want to hand-create the tables, run the enclosed 'create-tables' SQL script as follows ("create_tables.sql" needs to be in your current working directory).</para>
           <screen>mysql&gt; use apachelogs
 Database changed
 mysql&gt; source create_tables.sql</screen>
@@ -281,11 +291,11 @@ mysql&gt; source create_tables.sql</screen>
           <screen>mysql&gt; grant insert,create on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';</screen>
         </listitem>
         <listitem>
-          <para>You may be especially security-paranoid and want "loguser" to not have "create" capability within the "apachelogs" database. You can disable that privilege, but the cost is that you will not be able to use the module's on-the-fly table creation feature. If that cost is acceptable, hand-create the tables as described in step [part:CrTbl] and use the following GRANT statement instead of the one above:</para>
+          <para>You may be especially security-paranoid and want "loguser" to not have "create" capability within the "apachelogs" database. You can disable that privilege, but the cost is that you will not be able to use the module's on-the-fly table creation feature. If that cost is acceptable, hand-create the tables as described in step <link endterm="CreateTable" linkend="CreateTable"></link> and use the following GRANT statement instead of the one above:</para>
           <screen>mysql&gt; grant insert on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';</screen>
         </listitem>
-        <listitem>
-          <para>&lt;step:EnaLog&gt;Enable full logging of your <application>MySQL</application> daemon (at least temporarily for debugging purposes) if you don't do this already. Edit /etc/my.cnf and add the following line to your [mysqld] section:</para>
+        <listitem id="EnableLogging">
+          <para>Enable full logging of your <application>MySQL</application> daemon (at least temporarily for debugging purposes) if you don't do this already. Edit /etc/my.cnf and add the following line to your [mysqld] section:</para>
           <programlisting>log=/var/log/mysql-messages</programlisting>
           <para>Then restart <application>MySQL</application></para>
           <screen># /etc/rc.d/init.d/mysql restart</screen>
@@ -332,7 +342,7 @@ LogSQLCreateTables on</programlisting>
           <para>Visit your web site in a browser to trigger some hits, then confirm that the entries are being successfully logged:</para>
           <screen># mysql -hdbmachine.foo.com -umysqladmin -p -e "select * from access_log" apachelogs 
 Enter password:</screen>
-          <para>Several lines of output should follow, corresponding to your hits on the site. You now have basic functionality. Don't disable your regular Apache logs until you feel comfortable that the database is behaving as you'd like and that things are going well. If you do not see any entries in the access_log, please consult section [faq:NothingLogged] of the FAQ on how to debug and fix the situation.</para>
+          <para>Several lines of output should follow, corresponding to your hits on the site. You now have basic functionality. Don't disable your regular Apache logs until you feel comfortable that the database is behaving as you'd like and that things are going well. If you do not see any entries in the access_log, please consult section <link linkend="NothingLogged"></link> of the FAQ on how to debug and fix the situation.</para>
         </listitem>
         <listitem>
           <para>You can now activate the advanced features of mod_log_sql, which are described in the next section.</para>
@@ -344,7 +354,7 @@ Enter password:</screen>
       <sect3>
         <title>Instructing the module what to log</title>
         <para>The most basic directive for the module is LogSQLTransferLogFormat, which tells the module which information to send to the database; logging to the database will not take place without it. Place a LogSQLTransferLogFormat directive in the VirtualHost stanza of each virtual host that you want to activate.</para>
-        <para>After LogSQLTransferLogFormat you supply a string of characters that tell the module what information to log. In the configuration directive reference (section [sub:Frmat]) there is a table which clearly defines all the possible things to log. Let's say you want to log only the "request time," the "remote host," and the "request"; you'd use:</para>
+        <para>After LogSQLTransferLogFormat you supply a string of characters that tell the module what information to log. In the configuration directive reference (section <link endterm="TLogFormat.title" linkend="TLogFormat"></link>) there is a table which clearly defines all the possible things to log. Let's say you want to log only the "request time," the "remote host," and the "request"; you'd use:</para>
         <programlisting>LogSQLTransferLogFormat hUS</programlisting>
         <para>But a more appropriate string to use is</para>
         <programlisting>LogSQLTransferLogFormat AbHhmRSsTUuv</programlisting>
@@ -360,8 +370,8 @@ Enter password:</screen>
           </listitem>
         </itemizedlist>
       </sect3>
-      <sect3>
-        <title>&lt;sub:Ignore&gt;Instructing the module what NOT to log using filtering directives</title>
+      <sect3 id="Ignore">
+        <title id="Ignore.title">Instructing the module what NOT to log using filtering directives</title>
         <para>One "accept" and two "ignore" directives allow you to fine-tune what the module should not log. These are very handy for keeping your database as uncluttered as possible and keeping your statistics free of unneeded numbers. Think of each one as a gatekeeper.</para>
         <para><emphasis>It is important to remember that each of these three directives is purely optional. mod_log_sql's default is to log everything.</emphasis></para>
         <para>When a request comes in, the contents of LogSQLRequestAccept are evaluated first. This optional, "blanket" directive lets you specify that only certain things are to be accepted for logging, and everything else discarded. Because it is evaluated before LogSQLRequestIgnore and LogSQLRemhostIgnore it can halt logging before those two filtering directives "get their chance." </para>
@@ -428,8 +438,8 @@ LogSQLRequestIgnore statistics.html bluedot.jpg</programlisting>
         <para>There are numerous benefits. The admin will not need to create new tables for every new VirtualHost. (Although the admin will still need to drop the tables of virtual hosts that are removed.) The admin will not need to set LogSQLTransferLogTable for each virtual host -- it will be configured automatically based on the host's name. Because each virtual host will log to its own segregated table, data about one virtual server will segregate from others; an admin can grant users access to the tables they need, and they will be unable to view data about another user's virtual host.</para>
         <para>In an ISP scenario the admin is likely to have a cluster of many front-end webservers logging to a back-end database. mod_log_sql has a feature that permits analysis of how well the web servers are loadbalancing: the LogSQLMachineID directive. The administrator uses this directive to assign a unique identifier to each machine in the web cluster, e.g. "LogSQLMachineID web01," "LogSQLMachineID web02," etc. Used in conjunction with the 'M' character in LogSQLTransferLogFormat, each entry in the SQL log will include the machine ID of the machine that created the entry. This permits the administrator to count the entries made by each particular machine and thereby analyze the front-end loadbalancing algorithm.</para>
       </sect3>
-      <sect3>
-        <title>&lt;secMulTable&gt;Logging many-to-one data in separate tables</title>
+      <sect3 id="MultiTable">
+        <title id="MultiTable.title">Logging many-to-one data in separate tables</title>
         <para>A given HTTP request can have a one-to-many relationship with certain kinds of data. For example, a single HTTP request can have 4 cookies, 3 headers and 5 "mod_gzip" notes associated with it. mod_log_sql is capable of logging these relationships due to the elegance of SQL relational data.</para>
         <para>You already have a single table containing access requests. One of the columns in that table is 'id' which is intended to contain the unique request ID supplied by the standard Apache module mod_unique_id -- all you need to do is compile in that module and employ the LogSQLTransferLogFormat character 'I'. Thereafter, each request gets a unique ID that can be thought of as a primary key within the database, useful for joining multiple tables. So let's envision several new tables: a notes table, a cookies table, and a table for inbound and outbound headers.</para>
         <table>
@@ -593,8 +603,8 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
         <para>It is wasteful and potentially confusing to permit this internal test data to clutter the database, and a solution to the problem is the proper use of the LogSQLMachineID directive. Assume a scenario where the production webservers have IDs like "web01," "web02," and so on -- and the test webservers have IDs like "test01," "test02," etc. Because entries in the log database are distinguished by their source machine, an administrator may purge unneeded test data from the access log as follows:</para>
         <programlisting>delete from access_log where machine_id like 'test%';</programlisting>
       </sect3>
-      <sect3>
-        <title>&lt;sub:DelayedIns&gt;Optimizing for a busy database</title>
+      <sect3 id="DelayedInsert">
+        <title id="DelayedInsert.title">Optimizing for a busy database</title>
         <para>A busy MySQL database will have SELECT statements running concurrently with INSERT and UPDATE statements. A long-running SELECT can in certain circumstances block INSERTs and therefore block mod_log_sql. A workaround is to enable mod_log_sql for "delayed inserts," which are described as follows in the MySQL documentation.</para>
         <para>The DELAYED option for the INSERT statement is a MySQL-specific option that is very useful if you have clients that can't wait for the INSERT to complete. This is a common problem when you use MySQL for logging and you also periodically run SELECT and UPDATE statements that take a long time to complete. DELAYED was introduced in MySQL Version 3.22.15. It is a MySQL extension to ANSI SQL92.</para>
         <para>INSERT DELAYED only works with ISAM and MyISAM tables. Note that as MyISAM tables supports concurrent SELECT and INSERT, if there is no free blocks in the middle of the data file, you very seldom need to use INSERT DELAYED with MyISAM. </para>
@@ -610,13 +620,13 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           </listitem>
         </orderedlist>
         <warning>
-          <para>The MySQL documentation concludes, "This means that you should only use INSERT DELAYED when you are really sure you need it!" Furthermore, the current state of error return from a failed INSERT DELAYED seems to be in flux, and may behave in unpredictable ways between different MySQL versions. See section [sub:DelayedInsFAQ] in the FAQ -- you have been warned.</para>
+          <para>The MySQL documentation concludes, "This means that you should only use INSERT DELAYED when you are really sure you need it!" Furthermore, the current state of error return from a failed INSERT DELAYED seems to be in flux, and may behave in unpredictable ways between different MySQL versions. See section <link linkend="DelayedInsertFAQ"></link> in the FAQ -- you have been warned.</para>
         </warning>
         <para>If you are experiencing issues which could be solved by delayed inserts, then set LogSqlDelayedInserts On in the <filename>httpd.conf</filename>. All regular INSERT statements are now INSERT DELAYED, and you should see no more blocking of the module.</para>
       </sect3>
     </sect2>
-    <sect2>
-      <title>&lt;sec:ConfRef&gt;Configuration directive reference</title>
+    <sect2 id="ConfigReference">
+      <title id="ConfigReference.title">Configuration Directive Reference</title>
       <para>It is imperative that you understand which directives are used only once in the main server config, and which are used inside VirtualHost stanzas and therefore multiple times within httpd.conf. The "context" listed with each entry informs you of this.</para>
       <variablelist>
         <varlistentry>
@@ -739,16 +749,14 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLMachineID</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLMachineID</command>
+              <arg choice="req">machineID</arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLMachineID web01</simpara>
+            <simpara>Context: main server config</simpara>
+            <para>If you have a farm of webservers then you may wish to know which particular machine made each entry; this is useful for analyzing your load-balancing methodology. LogSQLMachineID permits you to distinguish each machine's entries if you assign each machine its own LogSQLMachineID: for example, the first webserver gets ``LogSQLMachineID web01,'' the second gets ``LogSQLMachineID web02,'' etc.</para>
             <note>
-              <para><filename></filename></para>
+              <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
             </note>
           </listitem>
         </varlistentry>
@@ -756,16 +764,27 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLMassVirtualHosting</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLMassVirtualHosting</command>
+              <arg choice="req">flag</arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLMassVirtualHosting On</simpara>
+            <simpara>Default: Off</simpara>
+            <simpara>Context: main server config</simpara>
+            <para>If you administer a site hosting many, many virtual hosts then this option will appeal to you. If you turn on LogSQLMassVirtualHosting then several things happen:</para>
+            <itemizedlist>
+              <listitem>
+                <para>the on-the-fly table creation feature is activated automatically</para>
+              </listitem>
+              <listitem>
+                <para>the transfer log table name is dynamically set from the virtual host's name after stripping out SQL-unfriendly characters (example: a virtual host www.grubbybaby.com gets logged to table access_www_grubbybaby_com)</para>
+              </listitem>
+              <listitem>
+                <para>which, in turn, means that each virtual host logs to its own segregated table. Because there is no data shared between virtual servers you can grant your users access to the tables they need; they will be unable to view others' data.</para>
+              </listitem>
+            </itemizedlist>
+            <para>This is a huge boost in convenience for sites with many virtual servers. Activating LogSQLMassVirtualHosting obviates the need to create every virtual server's table and provides more granular security possibilities.</para>
             <note>
-              <para><filename></filename></para>
+              <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
             </note>
           </listitem>
         </varlistentry>
@@ -773,16 +792,15 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLNotesLogTable</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLNotesLogTable</command>
+              <arg choice="req"><replaceable>table-name</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLNotesLogTable notes-log</simpara>
+            <simpara>Default: notes</simpara>
+            <simpara>Context: virtual_host</simpara>
+            <para>Defines which table is used for logging of notes. Working in conjunction with LogSQLWhichNotes, you can log many of each request's associated notes to a separate table. For meaningful data retrieval the notes table is keyed to the access table by the unique request ID supplied by the standard Apache module mod_unique_id.</para>
             <note>
-              <para><filename></filename></para>
+              <para>This table must be created (see create-tables.sql included in the package), or LogSQLCreateTables must be set to 'On'.</para>
             </note>
           </listitem>
         </varlistentry>
@@ -790,84 +808,75 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQlPreserveFile</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLPreserveFile</command>
+              <arg choice="req"><replaceable>filename</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
-            <note>
-              <para><filename></filename></para>
-            </note>
+            <simpara>Example: LogSQLPreserveFile offline-preserve</simpara>
+            <simpara>Default: /tmp/sql-preserve</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>mod_log_sql writes queries to this local preserve file in the event that it cannot reach the database, and thus ensures that your high-availability web frontend does not lose logs during a temporary database outage. This could happen for a number of reasons: the database goes offline, the network breaks, etc. You will not lose entries since the module has this backup. The file consists of a series of SQL statements that can be imported into your database at your convenience; furthermore, because the SQL queries contain the access timestamps you do not need to worry about out-of-order data after the import, which is done in a simple manner:</para>
+            <screen># mysql -uadminuser -p mydbname &lt; /tmp/sql-preserve</screen>
+            <para>If you do not define LogSQLPreserveFile then all virtual servers will log to the same default preserve file (<filename>/tmp/sql-preserve</filename>). You can redefine this on a virtual-host basis in order to segregate your preserve files if you desire. Note that segregation is not usually necessary, as the SQL statements that are written to the preserve file already distinguish between different virtual hosts if you include the 'v' character in your LogSQLTransferLogFormat directive. It is only necessary to segregate preserve-files by virualhost if you also segregate access logs by virtualhost.</para>
+            <para>The module will log to Apache's ErrorLog when it notices a database outage, and upon database return. You will therefore know when the preserve file is being used, although it is your responsibility to import the file.</para>
+            <para>The file does not need to be created in advance. It is safe to remove or rename the file without interrupting Apache, as the module closes the filehandle immediately after completing the write. The file is created with the user &amp; group ID of the running Apache process (e.g. 'nobody' on many Linux distributions).</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term>LogSQLRemhostIgnore</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLRemhostIgnore</command>
+              <arg choice="req" rep="repeat"><replaceable>hostname</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
-            <note>
-              <para><filename></filename></para>
-            </note>
+            <simpara>Example: LogSQLRemhostIgnore localnet.com</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Lists a series of strings that, if present in the REMOTE_HOST, will cause that request to <emphasis>not</emphasis> be logged. This directive is useful for cutting down on log clutter when you are certain that you want to ignore requests from certain hosts, such as your own internal network machines. See section <link endterm="Ignore.title" linkend="Ignore"></link> for some tips for using this directive.</para>
+            <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the REMOTE_HOST using strstr(). The comparison is case sensitive.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term>LogSQLRequestAccept</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLRequestAccept</command>
+              <arg choice="req" rep="repeat"><replaceable>hostname</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
-            <note>
-              <para><filename></filename></para>
-            </note>
+            <simpara>Example: LogSQLRequestAccept .html .php .jpg</simpara>
+            <simpara>Default: if not specified, all requests are 'accepted'</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Lists a series of strings that, if present in the URI, will permit that request to be considered for logging (depending on additional filtering by the "ignore" directives). Any request that fails to match one of the LogSQLRequestAccept entries will be discarded.</para>
+            <para>This directive is useful for cutting down on log clutter when you are certain that you only want to log certain kinds of requests, and just blanket-ignore everything else. See section <link endterm="Ignore.title" linkend="Ignore"></link> for some tips for using this directive.</para>
+            <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the URI using strstr(). The comparison is case sensitive.</para>
+            <para>This directive is completely optional. It is more general than LogSQLRequestIgnore and is evaluated before LogSQLRequestIgnore . If this directive is not used, <emphasis>all</emphasis> requests are accepted and passed on to the other filtering directives. Therefore, only use this directive if you have a specific reason to do so.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term>LogSQLRequestIgnore</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLRequestIgnore</command>
+              <arg choice="req" rep="repeat"><replaceable>hostname</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
-            <note>
-              <para><filename></filename></para>
-            </note>
+            <simpara>Example: LogSQLRequestIgnore root.exe cmd.exe default.ida favicon.ico</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Lists a series of strings that, if present in the URI, will cause that request to <emphasis>NOT</emphasis> be logged. This directive is useful for cutting down on log clutter when you are certain that you want to ignore requests for certain objects. See section <link endterm="Ignore.title" linkend="Ignore"></link> for some tips for using this directive.</para>
+            <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the URI using strstr(). The comparison is case sensitive.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term>LogSQLSocketFile</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQlSocketFile</command>
+              <arg choice="req"><replaceable>filename</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLSocketFile /tmp/mysql.sock</simpara>
+            <simpara>Default: /var/lib/mysql/mysql.sock</simpara>
+            <simpara>Context: main server config</simpara>
+            <para>At Apache runtime you can specify the MySQL socket file to use. Set this once in your main server config to override the default value. This value is irrelevant if your database resides on a separate machine.</para>
+            <para>mod_log_sql will automatically employ the socket for db communications if the database resides on the local host. If the db resides on a separate host the module will automatically use TCP/IP. This is a function of the MySQL API and is not user-configurable.</para>
             <note>
-              <para><filename></filename></para>
+              <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
             </note>
           </listitem>
         </varlistentry>
@@ -875,50 +884,45 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLTCPPort</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLTCPPort</command>
+              <arg choice="req"><replaceable>port-number</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLTCPPort 3309</simpara>
+            <simpara>Default: 3306</simpara>
+            <simpara>Context: main server config</simpara>
+            <para>Your database may listen on a different port than the default. If so, use this directive to instruct the module which port to use. This directive only applies if the database is on a different machine connected via TCP/IP.</para>
             <note>
-              <para><filename></filename></para>
+              <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
             </note>
           </listitem>
         </varlistentry>
-        <varlistentry>
-          <term>&lt;sub:Frmat&gt;LogSQLTransferLogFormat </term>
+        <varlistentry id="TLogFormat">
+          <term id="TLogFormat.title">LogSQLTransferLogFormat </term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLTransferLogFormat</command>
+              <arg choice="req"><replaceable>format-string</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
-            <note>
-              <para><filename></filename></para>
-            </note>
+            <simpara>Example: LogSQLTransferLogFormat huSUTv</simpara>
+            <simpara>Default: AbHhmRSsTUuv</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Each character in the format-string defines an attribute of the request that you wish to log. The default logs the information required to create Combined Log Format logs, plus several extras. Here is the full list of allowable keys, which sometimes resemble their Apache counterparts, but do not always:</para>
+            <para>TODO: Insert Log Format Types Table</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term>LogSQLTransferLogTable</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLTransferLogTable</command>
+              <arg choice="req"><replaceable>table-name</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLTransferLogTable access_log_table</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Defines which table is used for logging of Apache's transfers; this is analogous to Apache's TransferLog directive. table-name must be a valid table within the database defined in LogSQLDatabase.</para>
+            <para>This directive is <emphasis>not</emphasis> necessary if you declare LogSQLMassVirtualHosting On, since that directive activates dynamically-named tables. If you attempt to use LogSqlTransferlogTable at the same time a warning will be logged and it will be ignored, since LogSQLMassVirtualHosting takes priority.</para>
             <note>
-              <para><filename></filename></para>
+              <para>Requires unless LogSQLMassVirtualHosting is set to On</para>
             </note>
           </listitem>
         </varlistentry>
@@ -926,16 +930,16 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLWhichCookie</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLWhichCookie</command>
+              <arg choice="req"><replaceable>cookiename</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example; LogSQLWhichCookie Clicks</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>In HTTP, cookies have names to distinguish them from each other. Using mod_usertrack, for example, you can give your user-tracking cookies a name with the CookieName directive.</para>
+            <para>mod_log_sql allows you to log cookie information. LogSQL_WhichCookie tells mod_log_sql which cookie to log. This is necessary because you will usually be setting and receiving more than one cookie from a client.</para>
             <note>
-              <para><filename></filename></para>
+              <para>You must include a 'c' character in LogSQLTransferLogFormat for this directive to take effect.</para>
+              <para>although this was origintally intended for people using mod_usertrack to create user-tracking cookies, you are not restricted in any way. You can choose which cookie you wish to log to the database - any cookie at all - and it does not necessarily have to have anything to do with mod_usertrack.</para>
             </note>
           </listitem>
         </varlistentry>
@@ -943,16 +947,14 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLWhichCookies</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLWhichCookies</command>
+              <arg choice="req" rep="repeat"><replaceable>cookie-name</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: logSQLWhichCookies userlogin cookie1 cookie2</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Defines the list of cookies you would like logged. This works in conjunction with LogSQLCookieLogTable. This directive does <emphasis>not</emphasis> require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate cookie table with data.</para>
             <note>
-              <para><filename></filename></para>
+              <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para>
             </note>
           </listitem>
         </varlistentry>
@@ -960,16 +962,14 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLWhichHeadersIn</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLWhichHeadersIn</command>
+              <arg choice="req" rep="repeat"><replaceable>header-name</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLWhichHeadersIn UserAgent Accept-Encodeing Host</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Defines the list of inbound headers you would like logged. This works in conjunction with LogSQLHeadersInLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate inbound-headers table with data.</para>
             <note>
-              <para><filename></filename></para>
+              <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para>
             </note>
           </listitem>
         </varlistentry>
@@ -977,16 +977,14 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLWhichHeadersOut</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLWhichHeadersOut</command>
+              <arg choice="req" rep="repeat"><replaceable>header-name</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLWhichHeadersOut Expires Content-Type Cache-Control</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Defines the list of outbound headers you would like logged. This works in conjunction with LogSQLHeadersOutLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate outbound-headers table with data.</para>
             <note>
-              <para><filename></filename></para>
+              <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para>
             </note>
           </listitem>
         </varlistentry>
@@ -994,20 +992,29 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
           <term>LogSQLWhichNotes</term>
           <listitem>
             <cmdsynopsis>
-              <command></command>
-              <arg></arg>
+              <command>LogSQLWhichNotes</command>
+              <arg choice="req" rep="repeat"><replaceable>note-name</replaceable></arg>
             </cmdsynopsis>
-            <simpara></simpara>
-            <simpara></simpara>
-            <simpara></simpara>
-            <para></para>
-            <para></para>
+            <simpara>Example: LogSQLWhichNotes mod_gzip_result mod_gzip_ompression_ratio</simpara>
+            <simpara>Context: virtual host</simpara>
+            <para>Defines the list of notes you would like logged. This works in conjunction with LogSQLNotesLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate notes table with data.</para>
             <note>
-              <para><filename></filename></para>
+              <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para>
             </note>
           </listitem>
         </varlistentry>
       </variablelist>
+      <sect3>
+        <title>DataBase Configuration</title>
+        <variablelist>
+          <varlistentry>
+            <term></term>
+            <listitem>
+              <para></para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </sect3>
     </sect2>
   </sect1>
   <sect1>
@@ -1015,7 +1022,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
     <qandaset>
       <qandadiv>
         <title>General module questions</title>
-        <qandaentry>
+        <qandaentry id="WhyLogToSQL">
           <question>
             <para>Why log to an SQL database?</para>
           </question>
@@ -1183,7 +1190,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
             <para>Who's using mod_log_sql?</para>
           </question>
           <answer>
-            <para>Good question! It would be great to find out! If you are a production-level mod_log_sql user, please contact [(chris@grubbybaby.com)||the maintainer, Chris Powell] so that you can be mentioned here.</para>
+            <para>Good question! It would be great to find out! If you are a production-level mod_log_sql user, please contact &MaintainerContact; so that you can be mentioned here.</para>
           </answer>
         </qandaentry>
         <qandaentry>
@@ -1233,7 +1240,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
             <para>I have discovered a bug. Who can I contact?</para>
           </question>
           <answer>
-            <para>Please contact [(chris@grubbybaby.com)||the maintainer], or post a message to the mod_log_sql mailing list. Your comments, suggestions, bugfixes, bug catches, and usage testimonials are always welcome. As free software, mod_log_sql is intended to be a community effort -- any code contributions or other ideas will be fully and openly credited, of course.</para>
+            <para>Please contact &MaintainerContact;, or post a message to the mod_log_sql mailing list. Your comments, suggestions, bugfixes, bug catches, and usage testimonials are always welcome. As free software, mod_log_sql is intended to be a community effort -- any code contributions or other ideas will be fully and openly credited, of course.</para>
           </answer>
         </qandaentry>
       </qandadiv>
@@ -1248,9 +1255,9 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
             <para>PHP and mod_log_sql can be configured to happily coexist. The solution is to configure PHP to link against the real MySQL libraries: recompile PHP using --with-mysql=/your/path. Apache will run properly once the modules are all using the same version of the MySQL libraries.</para>
           </answer>
         </qandaentry>
-        <qandaentry>
+        <qandaentry id="NothingLogged">
           <question>
-            <para>&lt;faq:NothingLogged&gt;Apache appears to start up fine, but nothing is getting logged in the database</para>
+            <para>Apache appears to start up fine, but nothing is getting logged in the database</para>
           </question>
           <answer>
             <para>If you do not see any entries in the access_log, then something is preventing the inserts from happening. This could be caused by several things:</para>
@@ -1269,7 +1276,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
               </listitem>
             </itemizedlist>
             <remark>It is improper to ask for help before you have followed these steps.</remark>
-            <para>First examine the MySQL log that you established in step [step:EnaLog] of section [sub:PrepDb]. Ensure that the INSERT statements are not being rejected because of a malformed table name or other typographical error. By enabling that log, you instructed MySQL to log every connection and command it receives -- if you see no INSERT attempts in the log, the module isn't successfully connecting to the database. If you see nothing at all in the log -- not even a record of your administrative connection attempts, then you did not enable the log correctly. If you do see INSERT attempts but they are failing, the log should tell you why.</para>
+            <para>First examine the MySQL log that you established in step <link linkend="EnableLogging"></link> of section <link linkend="Preperation"></link>. Ensure that the INSERT statements are not being rejected because of a malformed table name or other typographical error. By enabling that log, you instructed MySQL to log every connection and command it receives -- if you see no INSERT attempts in the log, the module isn't successfully connecting to the database. If you see nothing at all in the log -- not even a record of your administrative connection attempts, then you did not enable the log correctly. If you do see INSERT attempts but they are failing, the log should tell you why.</para>
             <para>Second, confirm that your LogSQL* directives are all correct.</para>
             <para>Third, examine the Apache error logs for messages from mod_log_sql; the module will offer hints as to why it cannot connect, etc. </para>
             <para>The next thing to do is to change the LogLevel directive <emphasis>in the main server config as well as in each VirtualHost config:</emphasis></para>
@@ -1422,9 +1429,9 @@ mysql&gt; optimize table access_log; </screen>
             <para>If you have exhausted all the tuning possibilities on your existing server, it is probably time you evaluated the benefits of clustering two or more webservers together in a load-balanced fashion. In fact, users of such a setup are mod_log_sql's target audience!</para>
           </answer>
         </qandaentry>
-        <qandaentry>
-          <question>
-            <para>&lt;sub:DelayedInsFAQ&gt;What is the issue with activating delayed inserts?</para>
+        <qandaentry id="DelayedInsertFAQ">
+          <question id="DelayedInsertFAQ.title">
+            <para>What is the issue with activating delayed inserts?</para>
           </question>
           <answer>
             <para>INSERT DELAYED is a specific syntax to MySQL and is not supported by any other database. Ergo, why is it needed, and what MySQL deficiency is it working around? INSERT DELAYED is a kluge.</para>
@@ -1442,7 +1449,7 @@ mysql&gt; optimize table access_log; </screen>
             <para>Instead of delayed inserts, you may wish to utilize InnoDB tables (instead of the standard MyISAM tables). InnoDB tables suppot row-level locking and are recommended for high-volume databases.</para>
           </answer>
           <answer>
-            <para>If after understanding these problems you still wish to enable delayed inserts, section [sub:DelayedIns] discusses how.</para>
+            <para>If after understanding these problems you still wish to enable delayed inserts, section <link linkend="DelayedInsert"></link> discusses how.</para>
           </answer>
         </qandaentry>
       </qandadiv>
@@ -1467,9 +1474,9 @@ rm -f /var/log/httpd/templog</programlisting>
             <para>See? Easy.</para>
           </answer>
         </qandaentry>
-        <qandaentry>
+        <qandaentry id="QnACookie">
           <question>
-            <para>&lt;sec:cookie&gt;How can I log mod_usertrack cookies?</para>
+            <para>How can I log mod_usertrack cookies?</para>
           </question>
           <answer>
             <para>A number of people like to log mod_usertrack cookies in their Apache TransferLog to aid in understanding their visitors' clickstreams. This is accomplished, for example, with a statement as follows:</para>
@@ -1525,8 +1532,8 @@ rm -f /var/log/httpd/templog</programlisting>
           </question>
           <answer>
             <para>As of version 1.17, you have a choice in how you want cookie logging handled.</para>
-            <para>If you are interested in logging only one cookie per request, follow the instructions in section [sec:cookie] above. That cookie will be logged to a column in the regular access_log table, and the actual cookie you want to log is specified with LogSQLWhichCookie. Don't forget to specify the 'c' character in LogSQLTransferLogFormat.</para>
-            <para>If, however, you need to log multiple cookies per request, you must employ the LogSQLWhichCookies (note the plural) directive. The cookies you specify will be logged to a separate table (as discussed in section [secMulTable]), and entries in that table will be linked to the regular access_log entries via the unique ID that is supplied by mod_unique_id. Without mod_unique_id the information will still be logged but you will be unable to correlate which cookies go with which access-requests. Furthermore, with LogSQLWhichCookies, you do not need to include the 'c' character in LogSQLTransferLogFormat.</para>
+            <para>If you are interested in logging only one cookie per request, follow the instructions in section <link endterm="QnACookie" linkend="QnACookie"></link> above. That cookie will be logged to a column in the regular access_log table, and the actual cookie you want to log is specified with LogSQLWhichCookie. Don't forget to specify the 'c' character in LogSQLTransferLogFormat.</para>
+            <para>If, however, you need to log multiple cookies per request, you must employ the LogSQLWhichCookies (note the plural) directive. The cookies you specify will be logged to a separate table (as discussed in section <link endterm="MultiTable.title" linkend="MultiTable"></link>), and entries in that table will be linked to the regular access_log entries via the unique ID that is supplied by mod_unique_id. Without mod_unique_id the information will still be logged but you will be unable to correlate which cookies go with which access-requests. Furthermore, with LogSQLWhichCookies, you do not need to include the 'c' character in LogSQLTransferLogFormat.</para>
             <para>LogSQLWhichCookie and LogSQLWhichCookies can coexist without conflict because they operate on entireley different tables, but you're better off choosing the one you need.</para>
           </answer>
         </qandaentry>
@@ -1549,7 +1556,7 @@ mysql&gt; alter table access_log add column ssl_maxkeysize smallint unsigned;</s
  LogSQLTransferLogFormat AbHhmRSsTUuvcQqz 
 &lt;/VirtualHost&gt;</programlisting>
             <para>You also need to make sure you have the mod_log_sql_ssl module loaded as well.</para>
-            <para>The last three characters (Qqz) in the directive are the SSL ones; see section [sub:Frmat] in the directives documentation for details of the LogSQLTransferLogFormat directive.</para>
+            <para>The last three characters (Qqz) in the directive are the SSL ones; see section <link linkend="TLogFormat"></link> in the directives documentation for details of the LogSQLTransferLogFormat directive.</para>
             <para>Restart Apache, then perform some hits on your server. Then run the following select statement:</para>
             <screen>mysql&gt; select remote_host,request_uri,ssl_cipher,ssl_keysize,ssl_maxkeysize from access_log where ssl_cipher is not null;</screen>
             <table>