Bug 232378: switch from entities to XIncludes for inclusion of modular docs files

Patch by Colin Ogilvie <colin.ogilvie@gmail.com>; r=vladd

14 files changed, 777 insertions, 546 deletions

diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml
index aee8b790e..72db6e7fa 100644
--- a/docs/en/xml/Bugzilla-Guide.xml
+++ b/docs/en/xml/Bugzilla-Guide.xml
@@ -1,70 +1,22 @@
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [
-
-<!-- Include macros -->
-<!ENTITY about SYSTEM "about.xml">
-<!ENTITY conventions SYSTEM "conventions.xml">
-<!ENTITY doc-index SYSTEM "index.xml">
-<!ENTITY faq SYSTEM "faq.xml">
-<!ENTITY gfdl SYSTEM "gfdl.xml">
-<!ENTITY glossary SYSTEM "glossary.xml">
-<!ENTITY installation SYSTEM "installation.xml">
-<!ENTITY administration SYSTEM "administration.xml">
-<!ENTITY using SYSTEM "using.xml">
-<!ENTITY integration SYSTEM "integration.xml">
-<!ENTITY index SYSTEM "index.xml">
-<!ENTITY customization SYSTEM "customization.xml">
-<!ENTITY patches SYSTEM "patches.xml">
-<!ENTITY introduction SYSTEM "introduction.xml">
-<!ENTITY modules SYSTEM "modules.xml">
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
 
 <!-- Things to change for a stable release:
      * bz-ver to current stable
      * bz-nexver to next stable
      * bz-date to the release date
-     * bz-devel to "IGNORE"
+     * Remove the BZ-DEVEL comments
      - COMPILE DOCS AND CHECKIN -
        Also, tag and tarball before completing
      * bz-ver to devel version
-     * bz-devel to "INCLUDE"
  
      For a devel release, simple bump bz-ver and bz-date
 -->
 
-<!ENTITY bz-ver "2.18rc1">
-<!ENTITY bz-nextver "2.18">
-<!ENTITY bz-date "2004-07-10">
-<!ENTITY % bz-devel "IGNORE">
-
-<!ENTITY landfillbase "http://landfill.bugzilla.org/bugzilla-2.18-branch/">
-<!ENTITY bz "http://www.bugzilla.org/">
-<!ENTITY bzg-bugs "<ulink url='http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&amp;component=Documentation'>Bugzilla Documentation</ulink>">
-<!ENTITY mysql "http://www.mysql.com/">
-<!ENTITY newest-perl-ver "5.8.3">
-
-<!-- For minimum versions -->
-<!ENTITY min-mysql-ver "3.23.41">
-<!ENTITY min-perl-ver "5.6.0">
-<!ENTITY min-template-ver "2.08">
-<!ENTITY min-file-temp-ver "any">
-<!ENTITY min-appconfig-ver "1.52">
-<!ENTITY min-text-wrap-ver "2001.0131">
-<!ENTITY min-file-spec-ver "0.82">
-<!ENTITY min-data-dumper-ver "any">
-<!ENTITY min-dbd-mysql-ver "2.1010">
-<!ENTITY min-dbi-ver "1.32">
-<!ENTITY min-date-format-ver "2.21">
-<!ENTITY min-cgi-ver "2.93">
-<!-- Optional modules -->
-<!ENTITY min-gd-ver "1.20">
-<!ENTITY min-gd-graph-ver "any">
-<!ENTITY min-gd-text-align-ver "any">
-<!ENTITY min-chart-base-ver "1.0">
-<!ENTITY min-xml-parser-ver "any">
-<!ENTITY min-mime-parser-ver "any">
-<!ENTITY min-patchreader-ver "0.9.4">
-
-]>
-
 
 <!-- Coding standards for this document 
 
@@ -94,7 +46,8 @@
 
   <bookinfo>
     <title>The Bugzilla Guide - &bz-ver; 
-    <![%bz-devel;[Development ]]>Release</title>
+    <!-- BZ-DEVEL -->Development <!-- /BZ-DEVEL -->
+    Release</title>
 
     <authorgroup>
       <corpauthor>The Bugzilla Team</corpauthor>
@@ -133,37 +86,43 @@
   </bookinfo>
 
 <!-- About This Guide -->
-&about;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="about.xml" /> 
 
 <!-- Installing Bugzilla -->
-&installation;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="installation.xml" />
 
 <!-- Administering Bugzilla -->
-&administration;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="administration.xml" />
+
+<!-- Securing Bugzilla -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security.xml" />
 
 <!-- Customizing Bugzilla -->
-&customization;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="customization.xml" />
 
 <!-- Using Bugzilla -->
-&using;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="using.xml" />
 
 <!-- Appendix: The Frequently Asked Questions -->
-&faq;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="faq.xml" />
+
+<!-- Appendix: Troubleshooting -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="troubleshooting.xml" />
 
 <!-- Appendix: Custom Patches -->
-&patches;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="patches.xml" />
 
 <!-- Appendix: Manually Installing Perl Modules -->
-&modules;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules.xml" />
 
 <!-- Appendix: GNU Free Documentation License -->
-&gfdl;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gfdl.xml" />
 
 <!-- Glossary -->
-&glossary;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml" />
 
 <!-- Index -->
-&index;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="index.xml" />
 
 
 </book>
@@ -188,3 +147,4 @@ sgml-shorttag:t
 sgml-tag-region-if-active:t
 End:
 -->
+
diff --git a/docs/en/xml/about.xml b/docs/en/xml/about.xml
index c6c849539..b1dab24f6 100644
--- a/docs/en/xml/about.xml
+++ b/docs/en/xml/about.xml
@@ -1,26 +1,33 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-<!ENTITY conventions SYSTEM "conventions.sgml"> ] > -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
 
 <chapter id="about">
 <title>About This Guide</title>
 
   <section id="copyright">
     <title>Copyright Information</title>
+
+    <para>This document is copyright (c) 2000-&current-year; by the various
+    Bugzilla contributors who wrote it.</para>
+    
     <blockquote>
-      <attribution>Copyright (c) 2000-2003 Matthew P. Barnson and &bzg-auth;</attribution>
       <para>
 	Permission is granted to copy, distribute and/or modify this
 	document under the terms of the GNU Free Documentation
-	License, Version 1.1 or any later version published  by the
+	License, Version 1.1 or any later version published by the
 	Free Software Foundation; with no Invariant Sections, no
-	Front-Cover Texts, and  with no Back-Cover Texts.  A copy of
+	Front-Cover Texts, and with no Back-Cover Texts. A copy of
 	the license is included in <xref linkend="gfdl"/>.
       </para>
     </blockquote>
     <para>
       If you have any questions regarding this document, its
       copyright, or publishing this document in non-electronic form,
-      please contact &bzg-auth;. 
+      please contact the Bugzilla Team. 
     </para>
   </section>
 
@@ -28,7 +35,7 @@
     <title>Disclaimer</title>
     <para>
       No liability for the contents of this document can be accepted.
-      Use the concepts, examples, and other content at your own risk.
+      Follow the instructions herein at your own risk.
       This document may contain errors
       and inaccuracies that may damage your system, cause your partner 
       to leave you, your boss to fire you, your cats to
@@ -36,35 +43,20 @@
       war. Proceed with caution.
     </para>
     <para>
-      All copyrights are held by their respective owners, unless
-      specifically noted otherwise.  Use of a term in this document
-      should not be regarded as affecting the validity of any
-      trademark or service mark.
-    </para>
-    <para>
       Naming of particular products or brands should not be seen as
-      endorsements, with the exception of the term "GNU/Linux".  We
-      wholeheartedly endorse the use of GNU/Linux in every situation
-      where it is appropriate.  It is an extremely versatile, stable,
+      endorsements, with the exception of the term "GNU/Linux". We
+      wholeheartedly endorse the use of GNU/Linux; it is an extremely 
+      versatile, stable,
       and robust operating system that offers an ideal operating
       environment for Bugzilla.
     </para>
     <para>
-      You are strongly recommended to make a backup of your system
-      before installing Bugzilla and at regular intervals thereafter.
-      If you implement any suggestion in this Guide, implement this one!
-    </para>
-    <para>
       Although the Bugzilla development team has taken great care to
-      ensure that all easily-exploitable bugs or options are
-      documented or fixed in the code, security holes surely exist.
-      Great care should be taken both in the installation and usage of
-      this software. Carefully consider the implications of installing
-      other network services with Bugzilla.  The Bugzilla development
-      team members, Netscape Communications, America Online Inc., and
-      any affiliated developers or sponsors assume no liability for
-      your use of this product.  You have the source code to this
-      product, and are responsible for auditing it yourself to ensure
+      ensure that all exploitable bugs have been fixed, security holes surely 
+      exist in any piece of code. Great care should be taken both in 
+      the installation and usage of this software. The Bugzilla development
+      team members assume no liability for your use of Bugzilla. You have 
+      the source code, and are responsible for auditing it yourself to ensure
       your security needs are met.
     </para>
   </section>
@@ -76,36 +68,41 @@
     <para>
       This is the &bz-ver; version of The Bugzilla Guide. It is so named 
       to match the current version of Bugzilla. 
-      <![%bz-devel;[
-        This version of the guide, like its associated Bugzilla version is a
-        development version. Information is subject to change between now and
-        when &bz-nextver; is released.
-      ]]>
-      If you are
-      reading this from any source other than those below, please
-      check one of these mirrors to make sure you are reading an
-      up-to-date version of the Guide.
+      <!-- BZ-DEVEL --> This version of the guide, like its associated Bugzilla version, is a
+      development version.<!-- /BZ-DEVEL --> 
     </para>
     <para>
-      The newest version of this guide can always be found at <ulink
-      url="http://www.bugzilla.org">bugzilla.org</ulink>; including
-      documentation for past releases and the current development version.
+      The latest version of this guide can always be found at <ulink
+      url="http://www.bugzilla.org"/>, or checked out via CVS by
+      following the <ulink url="http://www.mozilla.org/cvs.html">Mozilla 
+      CVS</ulink> instructions and check out the 
+      <filename>mozilla/webtools/bugzilla/docs/</filename>
+      subtree. However, you should read the version
+      which came with the Bugzilla release you are using.
     </para>
     <para>
-      The documentation for the most recent stable release of Bugzilla can also
-      be found at
-      <ulink url="http://www.tldp.org">The Linux Documentation Project</ulink>.
+      The Bugzilla Guide, or a section of it, is also available in
+      the following languages:
+      <ulink url="http://bugzilla-de.sourceforge.net/docs/html/">German</ulink>.
     </para>
-    <para>
-      The latest version of this document can always be checked out via CVS.
-	    Please follow the instructions available at 
-      <ulink url="http://www.mozilla.org/cvs.html">the Mozilla CVS page</ulink>,
-      and check out the <filename>mozilla/webtools/bugzilla/docs/</filename>
-      subtree.
+    
+    <para>  
+      In addition, there are Bugzilla template localisation projects in
+      the following languages. They may have translated documentation 
+      available: 
+      <ulink url="http://sourceforge.net/projects/bugzilla-be/">Belarusian</ulink>,
+      <ulink url="http://sourceforge.net/projects/bugzilla-br/">Brazilian Portuguese</ulink>,
+      <ulink url="http://sourceforge.net/projects/bugzilla-cn/">Chinese</ulink>,
+      <ulink url="http://sourceforge.net/projects/bugzilla-fr/">French</ulink>,
+      <ulink url="http://sourceforge.net/projects/bugzilla-de/">German</ulink>,
+      <ulink url="http://sourceforge.net/projects/bugzilla-kr/">Korean</ulink>,
+      <ulink url="http://sourceforge.net/projects/bugzilla-ru/">Russian</ulink> and
+      <ulink url="http://sourceforge.net/projects/bugzilla-es/">Spanish</ulink>.
     </para>
-    <para>
-      The Bugzilla Guide is currently only available in English. 
-      If you would like to volunteer to translate it, please contact
+    
+    <para>  
+      If you would like to volunteer to translate the Guide into additional
+      languages, please contact
       <ulink url="mailto:justdave@syndicomm.com">Dave Miller</ulink>.
     </para>
   </section>
@@ -152,8 +149,7 @@
         <term>Dave Lawrence <email>dkl@redhat.com</email></term>
         <listitem>
           <para>for providing insight into the key differences between Red
-          Hat's customized Bugzilla, and being largely responsible for
-          <xref linkend="varient-redhat"/>.
+          Hat's customized Bugzilla.
           </para>
         </listitem>
       </varlistentry>
@@ -176,35 +172,49 @@
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+	<term>Dave Miller <email>justdave@bugzilla.org</email></term>
+	<listitem>
+          <para>for taking over as project lead when Tara stepped down and
+	  continually pushing for the documentation to be the best it can be.
+          </para>
+        </listitem>
+      </varlistentry>
+
     </variablelist>
 
-    <para>
-      Last but not least, all the members of the 
-      <ulink url="news://news.mozilla.org/netscape/public/mozilla/webtools"/>
-      newsgroup.  Without your discussions, insight, suggestions, and patches,
-      this could never have happened.
-    </para>
+
     <para>
       Thanks also go to the following people for significant contributions 
-      to this documentation (in alphabetical order):
+      to this documentation:
       <simplelist type="inline">
-        <member>Andrew Pearson</member>
+        <member>Kevin Brannen</member>
+        <member>Vlad Dascalu</member>
         <member>Ben FrantzDale</member>
         <member>Eric Hanson</member>
+        <member>Zach Lipton</member>
         <member>Gervase Markham</member>
+        <member>Andrew Pearson</member>
         <member>Joe Robins</member>
-        <member>Kevin Brannen</member>
-        <member>Ron Teitelbaum</member>
         <member>Spencer Smith</member>
-        <member>Zach Liption</member>
-      </simplelist>
-      .
+        <member>Ron Teitelbaum</member>
+        <member>Shane Travis</member>
+        <member>Martin Wulffeld</member>
+      </simplelist>.
+    </para>
+    
+    <para>
+      Also, thanks are due to the members of the 
+      <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">
+      netscape.public.mozilla.webtools</ulink>
+      newsgroup. Without your discussions, insight, suggestions, and patches,
+      this could never have happened.
     </para>
   </section>
 
-  <!-- conventions used here (didn't want to give it a chapter of its own) -->
-&conventions;
- </chapter> 
+<!-- conventions used here (didn't want to give it a chapter of its own) -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conventions.xml" /> 
+</chapter> 
 
 <!-- Keep this comment at the end of the file 
 Local variables: 
@@ -221,7 +231,8 @@ sgml-local-ecat-files:nil
 sgml-minimize-attributes:nil
 sgml-namecase-general:t 
 sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
 sgml-shorttag:t 
 sgml-tag-region-if-active:t 
 End: -->
+
diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index f0ccf027e..99fd98c88 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <chapter id="administration">
   <title>Administering Bugzilla</title>
 
@@ -82,6 +88,22 @@
 
       <varlistentry>
         <term>
+          maildeliverymethod
+        </term>
+        <listitem>
+          <para>
+            This is used to specify how email is sent, or if it is sent at 
+            all.  There are several options included for different MTAs, 
+            along with two additional options that disable email sending.  
+            "testfile" does not send mail, but instead saves it in 
+            <filename>data/mailer.testfile</filename> for later review.  
+            "none" disables email sending entirely.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
           shadowdb
         </term>
         <listitem>
@@ -193,7 +215,7 @@
         <listitem>
           <para>
             This allows you to define an email address for each component, 
-            in addition to that of the default owner, who will be sent
+            in addition to that of the default assignee, who will be sent
             carbon copies of incoming bugs.
           </para>
         </listitem>
@@ -520,6 +542,46 @@
           </listitem>
         </itemizedlist>
       </section>
+      
+      <section id="impersonatingusers">
+        <title>Impersonating Users</title>
+        
+        <para>
+        There may be times when an administrator would like to do something as
+        another user.  The <command>sudo</command> feature may be used to do 
+        this.
+        </para>
+        
+        <note>
+          <para>
+          To use the sudo feature, you must be in the
+          <emphasis>bz_sudoers</emphasis> group.  By default, all
+          administrators are in this group.</para>
+        </note>
+        
+        <para>
+        If you have access to this feature, you may start a session by
+        going to the Edit Users page, Searching for a user and clicking on 
+        their login.  You should see a link below their login name titled 
+        "Impersonate this user".  Click on the link.  This will take you 
+        to a page where you will see a description of the feature and 
+        instructions for using it.  After reading the text, simply 
+        enter the login of the user you would like to impersonate, provide 
+        a short message explaining why you are doing this, and press the 
+        button.</para>
+        
+        <para>
+        As long as you are using this feature, everything you do will be done 
+        as if you were logged in as the user you are impersonating.</para>
+        
+        <warning>
+          <para>
+          The user you are impersonating will not be told about what you are 
+          doing.  If you do anything that results in mail being sent, that 
+          mail will appear to be from the user you are impersonating.  You 
+          should be extremely careful while using this feature.</para>
+        </warning>
+      </section>
     </section>
   </section>
 
@@ -580,12 +642,12 @@
     company.</para>
 
     <para>
-    Each component has a owner and (if you turned it on in the parameters),
-    a QA Contact. The owner should be the primary person who fixes bugs in
+    Each component has a default assignee and (if you turned it on in the parameters),
+    a QA Contact. The default assignee should be the primary person who fixes bugs in
     that component. The QA Contact should be the person who will ensure
-    these bugs are completely fixed. The Owner, QA Contact, and Reporter
+    these bugs are completely fixed. The Assignee, QA Contact, and Reporter
     will get email when new bugs are created in this Component and when
-    these bugs change. Default Owner and Default QA Contact fields only
+    these bugs change. Default Assignee and Default QA Contact fields only
     dictate the 
     <emphasis>default assignments</emphasis>; 
     these can be changed on bug submission, or at any later point in
@@ -605,9 +667,9 @@
 
       <listitem>
         <para>Fill out the "Component" field, a short "Description", 
-        the "Initial Owner" and "Initial QA Contact" (if enabled.) 
+        the "Default Assignee" and "Default QA Contact" (if enabled.) 
         The Component and Description fields may contain HTML; 
-        the "Initial Owner" field must be a login name
+        the "Default Assignee" field must be a login name
         already existing in the database. 
         </para>
       </listitem>
@@ -672,7 +734,7 @@
       <listitem>
         <para>Enter the name of the Milestone in the "Milestone" field. You
         can optionally set the "sortkey", which is a positive or negative
-        number (-255 to 255) that defines where in the list this particular
+        number (-32768 to 32767) that defines where in the list this particular
         milestone appears. This is because milestones often do not 
         occur in alphanumeric order For example, "Future" might be
         after "Release 1.2". Select "Add".</para>
@@ -874,7 +936,7 @@
        </para>
        <para>
          Only users with the ability to edit the bug may 
-         set flags on bugs. This includes the owner, reporter, and 
+         set flags on bugs. This includes the assignee, reporter, and 
          any user with the <computeroutput>editbugs</computeroutput> 
          permission.
        </para>
@@ -902,7 +964,7 @@
        
         <para>
           When you click on the <quote>Create a Flag Type for...</quote>
-          link, you will be presented with a form. Here is what the felds in 
+          link, you will be presented with a form. Here is what the fields in 
           the form mean:
         </para>
 
@@ -919,7 +981,7 @@
           <title>Description</title>
           <para>
             This describes the flag in more detail. At present, this doesn't
-            whos up anywhere helpful; ideally, it would be nice to have
+            show up anywhere helpful; ideally, it would be nice to have
             it show up as a tooltip. This field 
             can be as long as you like, and can contain any character you want.
           </para>
@@ -1255,7 +1317,9 @@
              resulted in a user acquiring permanent membership in a group.
              To remove a user from a group the user was in due to a regular
              expression in version 2.16 or earlier, the user must be explicitly
-             removed from the group.</para>
+             removed from the group. This can easily be done by pressing
+             buttons named 'Remove Memberships' or 'Remove Memberships
+             included in regular expression' under the table.</para>
            </note>
            <warning>
              <para>If specifying a domain in the regexp, make sure you end
@@ -1354,7 +1418,7 @@
       </orderedlist>
       <para>These controls are often described in this order, so a 
       product that requires a user to be a member of group "foo" 
-      to enter a bug and then requires that the bug stay resticted
+      to enter a bug and then requires that the bug stay restricted
       to group "foo" at all times and that only members of group "foo"
       can edit the bug even if they otherwise could see the bug would 
       have its controls summarized by...</para>
diff --git a/docs/en/xml/conventions.xml b/docs/en/xml/conventions.xml
index f6aa00338..9f92a4755 100644
--- a/docs/en/xml/conventions.xml
+++ b/docs/en/xml/conventions.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <section id="conventions">
   <title>Document Conventions</title>
 
@@ -6,7 +12,7 @@
     <primary>conventions</primary>
   </indexterm>
 
-  <para>This document uses the following conventions</para>
+  <para>This document uses the following conventions:</para>
 
   <informaltable frame="none">
     <tgroup cols="2">
@@ -20,7 +26,7 @@
 
       <tbody>
         <row>
-          <entry>Warnings</entry>
+          <entry>Warning</entry>
 
           <entry>
             <caution>
@@ -34,13 +40,13 @@
 
           <entry>
             <tip>
-              <para>Warm jar lids under the hot tap to loosen them.</para>
+              <para>Would you like a breath mint?</para>
             </tip>
           </entry>
         </row>
 
         <row>
-          <entry>Notes</entry>
+          <entry>Note</entry>
 
           <entry>
             <note>
@@ -60,23 +66,15 @@
         </row>
 
         <row>
-          <entry>File Names</entry>
-
-          <entry>
-            <filename>file.extension</filename>
-          </entry>
-        </row>
-
-        <row>
-          <entry>Directory Names</entry>
+          <entry>File or directory name</entry>
 
           <entry>
-            <filename class="directory">directory</filename>
+            <filename>filename</filename>
           </entry>
         </row>
 
         <row>
-          <entry>Commands to be typed</entry>
+          <entry>Command to be typed</entry>
 
           <entry>
             <command>command</command>
@@ -84,7 +82,7 @@
         </row>
 
         <row>
-          <entry>Applications Names</entry>
+          <entry>Application name</entry>
 
           <entry>
             <application>application</application>
@@ -93,33 +91,27 @@
 
         <row>
           <entry>
-          <foreignphrase>Prompt</foreignphrase>
-
-          of users command under bash shell</entry>
+          Normal user's prompt under bash shell</entry>
 
           <entry>bash$</entry>
         </row>
 
         <row>
           <entry>
-          <foreignphrase>Prompt</foreignphrase>
-
-          of root users command under bash shell</entry>
+          Root user's prompt under bash shell</entry>
 
           <entry>bash#</entry>
         </row>
 
         <row>
           <entry>
-          <foreignphrase>Prompt</foreignphrase>
-
-          of user command under tcsh shell</entry>
+          Normal user's prompt under tcsh shell</entry>
 
           <entry>tcsh$</entry>
         </row>
 
         <row>
-          <entry>Environment Variables</entry>
+          <entry>Environment variables</entry>
 
           <entry>
             <envar>VARIABLE</envar>
@@ -127,28 +119,32 @@
         </row>
 
         <row>
-          <entry>Emphasized word</entry>
+          <entry>Term found in the glossary</entry>
 
           <entry>
-            <emphasis>word</emphasis>
+            <glossterm linkend="gloss-bugzilla">Bugzilla</glossterm>
           </entry>
         </row>
 
         <row>
-          <entry>Code Example</entry>
+          <entry>Code example</entry>
 
           <entry>
-            <programlisting>
-            <sgmltag class="starttag">para</sgmltag>
-
-            Beginning and end of paragraph
-            <sgmltag class="endtag">para</sgmltag>
-            </programlisting>
+            <programlisting><sgmltag class="starttag">para</sgmltag>
+Beginning and end of paragraph
+<sgmltag class="endtag">para</sgmltag></programlisting>
           </entry>
         </row>
       </tbody>
     </tgroup>
   </informaltable>
+
+  <para>  
+	  This documentation is maintained in DocBook 4.1.2 XML format.
+    Changes are best submitted as plain text or XML diffs, attached
+    to a bug filed in the &bzg-bugs; component.
+  </para>
+  
 </section>
 
 <!-- Keep this comment at the end of the file
@@ -166,7 +162,7 @@ sgml-local-ecat-files:nil
 sgml-minimize-attributes:nil
 sgml-namecase-general:t
 sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End:
diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml
index 1eef16673..b677ce804 100644
--- a/docs/en/xml/customization.xml
+++ b/docs/en/xml/customization.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <chapter id="customization">
   <title>Customising Bugzilla</title>
 
@@ -153,7 +159,7 @@
         to properly HTML filter data that has been passed into the template.
         This means that if the data can possibly contain special HTML characters
         such as &lt;, and the data was not intended to be HTML, they need to be
-        converted to entity form, ie &amp;lt;.  You use the 'html' filter in the
+        converted to entity form, i.e. &amp;lt;.  You use the 'html' filter in the
         Template Toolkit to do this.  If you forget, you may open up
         your installation to cross-site scripting attacks.
       </para>
@@ -162,7 +168,7 @@
         Also note that Bugzilla adds a few filters of its own, that are not
         in standard Template Toolkit.  In particular, the 'url_quote' filter
         can convert characters that are illegal or have special meaning in URLs,
-        such as &amp;, to the encoded form, ie %26.  This actually encodes most
+        such as &amp;, to the encoded form, i.e. %26.  This actually encodes most
         characters (but not the common ones such as letters and numbers and so
         on), including the HTML-special characters, so there's never a need to
         HTML filter afterwards.
@@ -202,7 +208,7 @@
       
       <para>
         To see if a CGI supports multiple output formats and types, grep the
-        CGI for <quote>GetFormat</quote>. If it's not present, adding
+        CGI for <quote>get_format</quote>. If it's not present, adding
         multiple format/type support isn't too hard - see how it's done in
         other CGIs, e.g. config.cgi.
       </para>
@@ -1093,8 +1099,8 @@ this. But you need to know this stuff anyway, right?
     </section>
   </section>
 
-  <!-- Integrating Bugzilla with Third-Party Tools -->
-  &integration;
+<!-- Integrating Bugzilla with Third-Party Tools -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="integration.xml" />
 
 </chapter>
 
diff --git a/docs/en/xml/gfdl.xml b/docs/en/xml/gfdl.xml
index fdfdb4bc5..0de66acd3 100644
--- a/docs/en/xml/gfdl.xml
+++ b/docs/en/xml/gfdl.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <appendix id="gfdl">
   <title>GNU Free Documentation License</title>
 
@@ -16,7 +22,7 @@
   </blockquote>
 
   <section label="0" id="gfdl-0">
-    <title>PREAMBLE</title>
+    <title>Preamble</title>
 
     <para>The purpose of this License is to make a manual, textbook, or other
     written document "free" in the sense of freedom: to assure everyone the
@@ -41,7 +47,7 @@
   </section>
 
   <section label="1" id="gfdl-1">
-    <title>APPLICABILITY AND DEFINITIONS</title>
+    <title>Applicability and Definition</title>
 
     <para>This License applies to any manual or other work that contains a
     notice placed by the copyright holder saying it can be distributed under
@@ -101,7 +107,7 @@
   </section>
 
   <section label="2" id="gfdl-2">
-    <title>VERBATIM COPYING</title>
+    <title>Verbatim Copying</title>
 
     <para>You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
@@ -118,7 +124,7 @@
   </section>
 
   <section label="3" id="gfdl-3">
-    <title>COPYING IN QUANTITY</title>
+    <title>Copying in Quantity</title>
 
     <para>If you publish printed copies of the Document numbering more than
     100, and the Document's license notice requires Cover Texts, you must
@@ -157,7 +163,7 @@
   </section>
 
   <section label="4" id="gfdl-4">
-    <title>MODIFICATIONS</title>
+    <title>Modifications</title>
 
     <para>You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you release
@@ -287,7 +293,7 @@
   </section>
 
   <section label="5" id="gfdl-5">
-    <title>COMBINING DOCUMENTS</title>
+    <title>Combining Documents</title>
 
     <para>You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for modified
@@ -313,7 +319,7 @@
   </section>
 
   <section label="6" id="gfdl-6">
-    <title>COLLECTIONS OF DOCUMENTS</title>
+    <title>Collections of Documents</title>
 
     <para>You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual copies
@@ -329,7 +335,7 @@
   </section>
 
   <section label="7" id="gfdl-7">
-    <title>AGGREGATION WITH INDEPENDENT WORKS</title>
+    <title>Aggregation with Independent Works</title>
 
     <para>A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of a
@@ -348,7 +354,7 @@
   </section>
 
   <section label="8" id="gfdl-8">
-    <title>TRANSLATION</title>
+    <title>Translation</title>
 
     <para>Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section 4.
@@ -363,7 +369,7 @@
   </section>
 
   <section label="9" id="gfdl-9">
-    <title>TERMINATION</title>
+    <title>Termination</title>
 
     <para>You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License. Any other attempt to
@@ -375,16 +381,13 @@
   </section>
 
   <section label="10" id="gfdl-10">
-    <title>FUTURE REVISIONS OF THIS LICENSE</title>
+    <title>Future Revisions of this License</title>
 
     <para>The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time. Such new versions
     will be similar in spirit to the present version, but may differ in
     detail to address new problems or concerns. See 
-    <ulink url="http://www.gnu.org/copyleft/">
-    http://www.gnu.org/copyleft/</ulink>
-
-    .</para>
+    <ulink url="http://www.gnu.org/copyleft/"/>.</para>
 
     <para>Each version of the License is given a distinguishing version
     number. If the Document specifies that a particular numbered version of
@@ -440,7 +443,7 @@ sgml-local-ecat-files:nil
 sgml-minimize-attributes:nil
 sgml-namecase-general:t
 sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End:
diff --git a/docs/en/xml/glossary.xml b/docs/en/xml/glossary.xml
index 08ad45524..980835053 100644
--- a/docs/en/xml/glossary.xml
+++ b/docs/en/xml/glossary.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > -->
+<?xml version="1.0"?>
+<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <glossary id="glossary">
   <glossdiv>
     <title>0-9, high ascii</title>
@@ -269,10 +275,11 @@
 
       <glossdef>
         <para>A Message Transport Agent is used to control the flow of email
-        on a system. Many unix based systems use
-        <ulink url="http://www.sendmail.org">sendmail</ulink> which is what
-        Bugzilla expects to find by default at <filename>/usr/sbin/sendmail</filename>.
-        Many other MTA's will work, but they all require that the
+        on a system. The <ulink url="http://search.cpan.org/dist/MailTools/Mail/Mailer.pm">Mail::Mailer</ulink>
+        Perl module, which Bugzilla uses to send email, can be configured to
+        use many different underlying implementations for actually sending the
+        mail using the <option>mail_delivery_method</option> parameter.
+        Implementations other than <literal>sendmail</literal> require that the
         <option>sendmailnow</option> param be set to <literal>on</literal>.
         </para>
       </glossdef>
diff --git a/docs/en/xml/index.xml b/docs/en/xml/index.xml
index 3b3516e14..e8a228493 100644
--- a/docs/en/xml/index.xml
+++ b/docs/en/xml/index.xml
@@ -13,9 +13,8 @@ sgml-local-ecat-files:nil
 sgml-minimize-attributes:nil
 sgml-namecase-general:t
 sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End:
 -->
-
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index 364df0db5..e6d35544f 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1,5 +1,10 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.107 2008/04/04 06:47:37 mozilla%colinogilvie.co.uk Exp $ -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
diff --git a/docs/en/xml/modules.xml b/docs/en/xml/modules.xml
index 59c58530e..ac5040f02 100644
--- a/docs/en/xml/modules.xml
+++ b/docs/en/xml/modules.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <appendix id="install-perlmodules-manual">
   <title>Manual Installation of Perl Modules</title>
   
diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml
index 540109feb..f3e17290c 100644
--- a/docs/en/xml/patches.xml
+++ b/docs/en/xml/patches.xml
@@ -1,286 +1,117 @@
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
-<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
-  <title>Useful Patches and Utilities for Bugzilla</title>
-
-  <para>Are you looking for a way to put your Bugzilla into overdrive? Catch
-  some of the niftiest tricks here in this section.</para>
-
-  <section id="rewrite" xreflabel="Apache mod_rewrite magic">
-    <title>Apache 
-    <filename>mod_rewrite</filename>
-
-    magic</title>
-
-    <para>Apache's 
-    <filename>mod_rewrite</filename>
-
-    module lets you do some truly amazing things with URL rewriting. Here are
-    a couple of examples of what you can do.</para>
-
-    <orderedlist>
-      <listitem>
-        <para>Make it so if someone types 
-        <computeroutput>http://www.foo.com/12345</computeroutput>
-
-        , Bugzilla spits back http://www.foo.com/show_bug.cgi?id=12345. Try
-        setting up your VirtualHost section for Bugzilla with a rule like
-        this:</para>
-
-        <programlisting>
-<![CDATA[
-<VirtualHost 12.34.56.78>
-RewriteEngine On
-RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R]
-</VirtualHost>
-]]>
-        </programlisting>
-      </listitem>
-
-      <listitem>
-        <para>There are many, many more things you can do with mod_rewrite.
-        As time goes on, I will include many more in the Guide. For now,
-        though, please refer to the mod_rewrite documentation at 
-        <ulink url="http://www.apache.org">http://www.apache.org</ulink>
-        </para>
-      </listitem>
-    </orderedlist>
-  </section>
-
-  <section id="setperl" xreflabel="The setperl.csh Utility">
-    <title>The setperl.csh Utility</title>
-
-    <para>You can use the "setperl.csh" utility to quickly and easily change
-    the path to perl on all your Bugzilla files. This is a C-shell script; if
-    you do not have "csh" or "tcsh" in the search path on your system, it
-    will not work!</para>
-
-    <procedure>
-      <step>
-        <para>Download the "setperl.csh" utility to your Bugzilla directory
-        and make it executable.</para>
-
-        <substeps>
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
-
-                <command>cd /your/path/to/bugzilla</command>
-              </computeroutput>
-            </para>
-          </step>
-
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
-
-                <command>wget -O setperl.csh
-                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=10795'</command>
-              </computeroutput>
-            </para>
-          </step>
-
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
-
-                <command>chmod u+x setperl.csh</command>
-              </computeroutput>
-            </para>
-          </step>
-        </substeps>
-      </step>
-
-      <step>
-        <para>Prepare (and fix) Bugzilla file permissions.</para>
-
-        <substeps>
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
-
-                <command>chmod u+w *</command>
-              </computeroutput>
-            </para>
-          </step>
-
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
-
-                <command>chmod u+x duplicates.cgi</command>
-              </computeroutput>
-            </para>
-          </step>
-
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
-
-                <command>chmod a-x bug_status.html</command>
-              </computeroutput>
-            </para>
-          </step>
-        </substeps>
-      </step>
-
-      <step>
-        <para>Run the script:</para>
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
 
-        <para>
-          <computeroutput>
-            <prompt>bash#</prompt>
-
-            <command>./setperl.csh /your/path/to/perl</command>
-          </computeroutput>
-
-          <example>
-            <title>Using Setperl to set your perl path</title>
+<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
+  <title>Contrib</title>
 
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
-
-                <command>./setperl.csh /usr/bin/perl</command>
-              </computeroutput>
-            </para>
-          </example>
-        </para>
-      </step>
-    </procedure>
-  </section>
+  <para>
+    There are a number of unofficial Bugzilla add-ons in the 
+    <filename class="directory">$BUGZILLA_ROOT/contrib/</filename>
+    directory. This section documents them.
+  </para>
 
   <section id="cmdline">
-    <title>Command-line Bugzilla Queries</title>
-
-    <para>Users can query Bugzilla from the command line using this suite of
-    utilities.</para>
-
-    <para>The query.conf file contains the mapping from options to field
-    names and comparison types. Quoted option names are "grepped" for, so it
-    should be easy to edit this file. Comments (#) have no effect; you must
-    make sure these lines do not contain any quoted "option"</para>
-
-    <para>buglist is a shell script which submits a Bugzilla query and writes
-    the resulting HTML page to stdout. It supports both short options, (such
-    as "-Afoo" or "-Rbar") and long options (such as "--assignedto=foo" or
-    "--reporter=bar"). If the first character of an option is not "-", it is
-    treated as if it were prefixed with "--default=".</para>
-
-    <para>The columlist is taken from the COLUMNLIST environment variable.
-    This is equivalent to the "Change Columns" option when you list bugs in
-    buglist.cgi. If you have already used Bugzilla, use 
-    <command>grep COLUMLIST ~/.netscape/cookies</command>
-
-    to see your current COLUMNLIST setting.</para>
-
-    <para>bugs is a simple shell script which calls buglist and extracts the
-    bug numbers from the output. Adding the prefix
-    "http://bugzilla.mozilla.org/buglist.cgi?bug_id=" turns the bug list into
-    a working link if any bugs are found. Counting bugs is easy. Pipe the
-    results through 
-    <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command>
+    <title>Command-line Search Interface</title>
+
+    <para>
+      There are a suite of Unix utilities for searching Bugzilla from the 
+      command line. They live in the 
+      <filename class="directory">contrib/cmdline</filename> directory.
+      There are three files - <filename>query.conf</filename>,
+      <filename>buglist</filename> and <filename>bugs</filename>.
     </para>
 
-    <para>Akkana says she has good results piping buglist output through 
-    <command>w3m -T text/html -dump</command>
+    <warning>
+      <para>
+        These files pre-date the templatisation work done as part of the
+        2.16 release, and have not been updated.
+      </para>
+    </warning>
+    
+    <para>
+      <filename>query.conf</filename> contains the mapping from
+      options to field names and comparison types. Quoted option names
+      are <quote>grepped</quote> for, so it should be easy to edit this
+      file. Comments (#) have no effect; you must make sure these lines
+      do not contain any quoted <quote>option</quote>.
     </para>
 
-    <procedure>
-      <step>
-        <para>Download three files:</para>
-
-        <substeps>
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash$</prompt>
-
-                <command>wget -O query.conf
-                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26157'</command>
-              </computeroutput>
-            </para>
-          </step>
-
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash$</prompt>
-
-                <command>wget -O buglist
-                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26944'</command>
-              </computeroutput>
-            </para>
-          </step>
+    <para>
+      <filename>buglist</filename> is a shell script that submits a
+      Bugzilla query and writes the resulting HTML page to stdout.
+      It supports both short options, (such as <quote>-Afoo</quote>
+      or <quote>-Rbar</quote>) and long options (such
+      as <quote>--assignedto=foo</quote> or <quote>--reporter=bar</quote>).
+      If the first character of an option is not <quote>-</quote>, it is
+      treated as if it were prefixed with <quote>--default=</quote>.
+    </para>
 
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
+    <para>
+      The column list is taken from the COLUMNLIST environment variable.
+      This is equivalent to the <quote>Change Columns</quote> option
+      that is available when you list bugs in buglist.cgi. If you have
+      already used Bugzilla, grep for COLUMNLIST in your cookies file
+      to see your current COLUMNLIST setting.
+    </para>
 
-                <command>wget -O bugs
-                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26215'</command>
-              </computeroutput>
-            </para>
-          </step>
-        </substeps>
-      </step>
+    <para>
+      <filename>bugs</filename> is a simple shell script which calls
+      <filename>buglist</filename> and extracts the
+      bug numbers from the output. Adding the prefix
+      <quote>http://bugzilla.mozilla.org/buglist.cgi?bug_id=</quote>
+      turns the bug list into a working link if any bugs are found.
+      Counting bugs is easy. Pipe the results through 
+      <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command>
+    </para>
 
-      <step>
-        <para>Make your utilities executable: 
-        <computeroutput>
-          <prompt>bash$</prompt>
+    <para>
+      Akkana Peck says she has good results piping 
+      <filename>buglist</filename> output through 
+      <command>w3m -T text/html -dump</command>
+    </para>
 
-          <command>chmod u+x buglist bugs</command>
-        </computeroutput>
-        </para>
-      </step>
-    </procedure>
   </section>
 
-  <section id="quicksearch">
-    <title>The Quicksearch Utility</title>
-
-    <para>Quicksearch is a new, experimental feature of the 2.12 release. It
-    consist of two Javascript files, "quicksearch.js" and "localconfig.js",
-    and two documentation files, "quicksearch.html" and
-    "quicksearchhack.html"</para>
-
-    <para>The index.html page has been updated to include the QuickSearch
-    text box.</para>
+  <section id="cmdline-bugmail">
+    <title>Command-line 'Send Unsent Bug-mail' tool</title>
 
-    <para>To take full advantage of the query power, the Bugzilla maintainer
-    must edit "localconfig.js" according to the value sets used in the local
-    installation.</para>
-
-    <para>Currently, keywords must be hard-coded in localconfig.js. If they
-    are not, keywords are not automatically recognized. This means, if
-    localconfig.js is left unconfigured, that searching for a bug with the
-    "foo" keyword will only find bugs with "foo" in the summary, status
-    whiteboard, product or component name, but not those with the keyword
-    "foo".</para>
-
-    <para>Workarounds for Bugzilla users: 
-    <simplelist>
-      <member>search for '!foo' (this will find only bugs with the keyword
-      "foo"</member>
+    <para>
+      Within the <filename class="directory">contrib</filename> directory
+      exists a utility with the descriptive (if compact) name
+      of <filename>sendunsentbugmail.pl</filename>. The purpose of this
+      script is, simply, to send out any bug-related mail that should
+      have been sent by now, but for one reason or another has not.
+    </para>
 
-      <member>search 'foo,!foo' (equivalent to 'foo OR keyword:foo')</member>
-    </simplelist>
+    <para>
+      To accomplish this task, <filename>sendunsentbugmail.pl</filename> uses
+      the same mechanism as the <filename>sanitycheck.cgi</filename> script; it
+      it scans through the entire database looking for bugs with changes that
+      were made more than 30 minutes ago, but where there is no record of
+      anyone related to that bug having been sent mail. Having compiled a list,
+      it then uses the standard rules to determine who gets mail, and sends it
+      out.
     </para>
 
-    <para>When this tool is ported from client-side JavaScript to server-side
-    Perl, the requirement for hard-coding keywords can be fixed. 
-    <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=70907">This
-    bug</ulink>
+    <para>
+      As the script runs, it indicates the bug for which it is currently
+      sending mail; when it has finished, it gives a numerical count of how
+      many mails were sent and how many people were excluded. (Individual
+      user names are not recorded or displayed.) If the script produces
+      no output, that means no unsent mail was detected.
+    </para>
 
-    has details.</para>
+    <para>
+      <emphasis>Usage</emphasis>: move the sendunsentbugmail.pl script
+      up into the main directory, ensure it has execute permission, and run it
+      from the command line (or from a cron job) with no parameters.
+    </para>
   </section>
+
 </appendix>
 
 <!-- Keep this comment at the end of the file
@@ -298,7 +129,7 @@ sgml-local-ecat-files:nil
 sgml-minimize-attributes:nil
 sgml-namecase-general:t
 sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End:
diff --git a/docs/en/xml/security.xml b/docs/en/xml/security.xml
index bc8aae657..a1f2f5770 100644
--- a/docs/en/xml/security.xml
+++ b/docs/en/xml/security.xml
@@ -1,5 +1,9 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: security.xml,v 1.6 2008/04/04 06:48:13 zach%zachlipton.com Exp $ -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
 
 <chapter id="security">
 <title>Bugzilla Security</title>
@@ -207,14 +211,6 @@ skip-networking
               </simplelist>
               </para>
             </listitem>
-            <listitem>
-              <para>But allow:
-              <simplelist type="inline">
-                <member><filename>localconfig.js</filename></member>
-                <member><filename>localconfig.rdf</filename></member>
-              </simplelist>
-              </para>
-            </listitem>
           </itemizedlist>
         </listitem>
 
@@ -360,28 +356,25 @@ skip-networking
     <section id="security-bugzilla-charset">
     <title>Prevent users injecting malicious Javascript</title>
 
-      <para>It is possible for a Bugzilla user to take advantage of character
-      set encoding ambiguities to inject HTML into Bugzilla comments. This
-      could include malicious scripts. 
-      Due to internationalization concerns, we are unable to
-      incorporate by default the code changes suggested by 
+      <para>If you installed Bugzilla version 2.22 or later from scratch,
+      then the <emphasis>utf8</emphasis> parameter is switched on by default.
+      This makes Bugzilla explicitly set the character encoding, following
       <ulink
-      url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">the
-      CERT advisory</ulink> on this issue.
-      Making the change in <xref linkend="security-bugzilla-charset-ex"/> will
-      prevent this problem. 
+      url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">a
+      CERT advisory</ulink> recommending exactly this.
+      The following therefore does not apply to you; just keep
+      <emphasis>utf8</emphasis> turned on.
       </para>
 
-      <example id="security-bugzilla-charset-ex">
-      <title>Forcing Bugzilla to output a charset</title>
-
-        <para>Locate the following line in
-        <filename>Bugzilla/CGI.pm</filename>:
-        <programlisting>$self->charset('');</programlisting>
-        and change it to:
-        <programlisting>$self->charset('UTF-8');</programlisting>
-        </para>
-      </example>
+      <para>If you've upgraded from an older version, then it may be possible
+      for a Bugzilla user to take advantage of character set encoding
+      ambiguities to inject HTML into Bugzilla comments.
+      This could include malicious scripts. 
+      This is because due to internationalization concerns, we are unable to
+      turn the <emphasis>utf8</emphasis> parameter on by default for upgraded
+      installations.
+      Turning it on manually will prevent this problem.
+      </para>
     </section>    
     
   </section>
diff --git a/docs/en/xml/troubleshooting.xml b/docs/en/xml/troubleshooting.xml
index 13a756a3b..10ad59f1c 100644
--- a/docs/en/xml/troubleshooting.xml
+++ b/docs/en/xml/troubleshooting.xml
@@ -1,5 +1,9 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: troubleshooting.xml,v 1.1 2008/04/03 19:05:43 lpsolit%gmail.com Exp $ -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
 
 <appendix id="troubleshooting">
 <title>Troubleshooting</title>
@@ -15,14 +19,14 @@
     completion, it normally explains what's wrong and how to fix it.
     If you can't work it out, or if it's being uncommunicative, post 
     the errors in the 
-    <ulink url="news://news.mozilla.org/mozilla.support.bugzilla">mozilla.support.bugzilla</ulink>
+    <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">netscape.public.mozilla.webtools</ulink>
     newsgroup.
     </para>
 
     <para>If you have made it all the way through
     <xref linkend="installation"/> (Installation) and
     <xref linkend="configuration"/> (Configuration) but accessing the Bugzilla
-    URL doesn't work, the first thing to do is to check your web server error
+    URL doesn't work, the first thing to do is to check your webserver error
     log. For Apache, this is often located at
     <filename>/etc/logs/httpd/error_log</filename>. The error messages
     you see may be self-explanatory enough to enable you to diagnose and
@@ -32,7 +36,7 @@
 
     <para>
       Bugzilla can also log all user-based errors (and many code-based errors)
-      that occur, without polluting the web server's error log.  To enable
+      that occur, without polluting the web server error log.  To enable
       Bugzilla error logging, create a file that Bugzilla can write to, named
       <filename>errorlog</filename>, in the Bugzilla <filename>data</filename>
       directory.  Errors will be logged as they occur, and will include the type
@@ -45,10 +49,10 @@
   </section>
         
   <section id="trbl-testserver">
-  <title>The Apache web server is not serving Bugzilla pages</title>
+  <title>The Apache webserver is not serving Bugzilla pages</title>
     <para>After you have run <command>checksetup.pl</command> twice,
     run <command>testserver.pl http://yoursite.yourdomain/yoururl</command>
-    to confirm that your web server is configured properly for
+    to confirm that your webserver is configured properly for
     Bugzilla.
     </para>
     <programlisting>
@@ -75,13 +79,31 @@ TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-t
         </para>
       </listitem>
       <listitem>
-        <para>The permissions on your library directories are set incorrectly.
-        They must, at the very least, be readable by the web server user or
-        group. It is recommended that they be world readable.
+	<para>The permissions on your library directories are set incorrectly.
+	They must, at the very least, be readable by the webserver user or
+	group. It is recommended that they be world readable.
         </para>
       </listitem>
     </orderedlist>
   </section>
+    
+  <section id="trbl-bundleBugzilla">
+  <title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title>
+
+    <para>Try executing <command>perl -MCPAN -e 'install CPAN'</command>
+    and then continuing.
+    </para>
+      
+    <para>Certain older versions of the CPAN toolset were somewhat naive about
+    how to upgrade Perl modules. When a couple of modules got rolled into the
+    core Perl distribution for 5.6.1, CPAN thought that the best way to get
+    those modules up to date was to haul down the Perl distribution itself and
+    build it. Needless to say, this has caused headaches for just about
+    everybody. Upgrading to a newer version of CPAN with the
+    commandline above should fix things.
+    </para>
+  </section>
+
 
   <section id="trbl-dbdSponge">
   <title>DBD::Sponge::db prepare failed</title>
@@ -139,12 +161,55 @@ TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-t
     </para>
   </section>    
 
+  <section id="trouble-filetemp">
+  <title>Your vendor has not defined Fcntl macro O_NOINHERIT</title>
+
+    <para>This is caused by a bug in the version of
+    <productname>File::Temp</productname> that is distributed with perl
+    5.6.0. Many minor variations of this error have been reported:
+    </para>
+
+    <programlisting>Your vendor has not defined Fcntl macro O_NOINHERIT, used 
+at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208.
+
+Your vendor has not defined Fcntl macro O_EXLOCK, used 
+at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210.
+
+Your vendor has not defined Fcntl macro O_TEMPORARY, used 
+at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.</programlisting>
+
+    <para>Numerous people have reported that upgrading to version 5.6.1
+    or higher solved the problem for them. A less involved fix is to apply
+    the following patch, which is also
+    available as a <ulink url="../xml/filetemp.patch">patch file</ulink>.
+    </para>
+
+    <programlisting><![CDATA[--- File/Temp.pm.orig   Thu Feb  6 16:26:00 2003
++++ File/Temp.pm        Thu Feb  6 16:26:23 2003
+@@ -205,6 +205,7 @@
+     # eg CGI::Carp
+     local $SIG{__DIE__} = sub {};
+     local $SIG{__WARN__} = sub {};
++    local *CORE::GLOBAL::die = sub {};
+     $bit = &$func();
+     1;
+   };
+@@ -226,6 +227,7 @@
+     # eg CGI::Carp
+     local $SIG{__DIE__} = sub {};
+     local $SIG{__WARN__} = sub {};
++    local *CORE::GLOBAL::die = sub {};
+     $bit = &$func();
+     1;
+   };]]></programlisting>
+  </section>
+
   <section id="trbl-relogin-everyone">
   <title>Everybody is constantly being forced to relogin</title>
   
   <para>The most-likely cause is that the <quote>cookiepath</quote> parameter
   is not set correctly in the Bugzilla configuration.  You can change this (if
-  you're a Bugzilla administrator) from the editparams.cgi page via the web interface.
+  you're a Bugzilla administrator) from the editparams.cgi page via the web.
   </para>
 
   <para>The value of the cookiepath parameter should be the actual directory
@@ -213,7 +278,7 @@ TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-t
     </para>
   </section>
 
-  <section id="trbl-relogin-some">
+  <section>
   <title>Some users are constantly being forced to relogin</title>
 
     <para>First, make sure cookies are enabled in the user's browser.
diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml
index 4e63bac86..8f50cfa44 100644
--- a/docs/en/xml/using.xml
+++ b/docs/en/xml/using.xml
@@ -1,4 +1,9 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
 
 <chapter id="using">
   <title>Using Bugzilla</title>
@@ -234,8 +239,12 @@
       <listitem>
         <para>
         <emphasis>Attachments:</emphasis>
-        You can attach files (e.g. testcases or patches) to bugs. If there
-        are any attachments, they are listed in this section.</para>
+          You can attach files (e.g. testcases or patches) to bugs. If there
+          are any attachments, they are listed in this section.  Attachments are
+          normally stored in the Bugzilla database, unless they are marked as
+          Big Files, which are stored directly on disk and (unlike attachments
+          kept in the database) may be deleted at some future time.
+        </para>
       </listitem>
 
       <listitem>
@@ -286,7 +295,7 @@
   <section id="query">
     <title>Searching for Bugs</title>
 
-    <para>The Bugzilla Search page is is the interface where you can find
+    <para>The Bugzilla Search page is the interface where you can find
     any bug report, comment, or patch currently in the Bugzilla system. You
     can play with it here: 
     <ulink url="&landfillbase;query.cgi"/>.</para>
@@ -721,11 +730,12 @@
       summary and status whiteboard of a bug; adding 
       "<filename>:BazProduct</filename>" would
       search only in that product.
+      You can use it to find a bug by its number or its alias, too.
       </para>
 
-      <para>You'll find the Quicksearch box on Bugzilla's
-      front page, along with a 
-      <ulink url="../../quicksearch.html">Help</ulink> 
+      <para>You'll find the Quicksearch box in Bugzilla's footer area.
+      On Bugzilla's front page, there is an additional
+      <ulink url="../../page.cgi?id=quicksearch.html">Help</ulink>
       link which details how to use it.</para>
     </section>
     
@@ -774,34 +784,93 @@
       Content-Type (e.g. application/xhtml+xml), you can override this 
       using a 'content-type' parameter on the URL, e.g.
       <filename>&amp;content-type=text/plain</filename>.
-      </para>     
+      </para> 
+
+      <para>
+        If you have a really large attachment, something that does not need to
+        be recorded forever (as most attachments are), you can mark your
+        attachment as a Big File, Assuming the administrator of the
+        installation has enabled this feature.  Big Files are stored directly on
+        disk instead of in the database, and can be deleted when it is no longer
+        needed.  The maximum size of a Big File is normally larger than the
+        maximum size of a regular attachment.
+      </para>
     </section>
   </section>
   
   <section id="userpreferences">
     <title>User Preferences</title>
 
-    <para>Once you have logged in, you can customise various aspects of 
+    <para>Once you have logged in, you can customise various aspects of
     Bugzilla via the "Edit prefs" link in the page footer.
     The preferences are split into three tabs:</para>
 
-    <section id="accountsettings" xreflabel="Account Settings">
-      <title>Account Settings</title>
+    <section id="accountpreferences" xreflabel="Account Preferences">
+      <title>Account Preferences</title>
 
       <para>On this tab, you can change your basic account information,
       including your password, email address and real name. For security
-      reasons, in order to change anything on this page you must type your 
+      reasons, in order to change anything on this page you must type your
       <emphasis>current</emphasis>
-      password into the 
+      password into the
       <quote>Password</quote>
-      field at the top of the page. 
+      field at the top of the page.
       If you attempt to change your email address, a confirmation
       email is sent to both the old and new addresses, with a link to use to
       confirm the change. This helps to prevent account hijacking.</para>
     </section>
 
-    <section id="emailsettings">
-      <title>Email Settings</title>
+    <section id="generalpreferences" xreflabel="General Preferences">
+      <title>General Preferences</title>
+
+      <para>
+        This tab allows you to change several Bugzilla behavior.
+      </para>
+
+      <itemizedlist spacing="compact">
+        <listitem>
+          <para>
+            Field separator character for CSV files -
+            This controls separator character used in CSV formatted Bug List.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            After changing bugs - This controls which bugs or no bugs
+            are shown in the page after you changed bugs.
+            You can select the bug you've changed this time, or the next
+            bug of the list.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Add individual bugs to saved searches - this controls
+            whether you can add individual bugs to saved searches
+            or you can't.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            When viewing a bug, show comments in this order -
+            This controls the order of comments, you can select below:
+            <simplelist>
+              <member>Initial description, comment 1, comment 2, ...</member>
+              <member>Initial description, last comment, ..., comment 2, comment 1.</member>
+              <member>Initial last comment, ..., comment 2, comment 1, description.</member>
+            </simplelist>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Show a quip at the top of each bug list - This controls
+            whether a quip will be shown on the Bug list page or not.
+          </para>
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section id="emailpreferences">
+      <title>Email Preferences</title>
 
       <para>
         This tab controls the amount of email Bugzilla sends you.
@@ -837,7 +906,7 @@
           Your Bugzilla administrator can stop a user from receiving
           bugmail by adding the user's name to the 
           <filename>data/nomail</filename> file. This is a drastic step
-          best taken only for disabled accounts, as it overrides the 
+          best taken only for disabled accounts, as it overrides 
           the user's individual mail preferences.
         </para>
       </note>
@@ -1158,6 +1227,222 @@
       appended to the flag name within parentheses.  For example, if Jack
       asks Jill for review, it appears as Jack: review [ ? ] (Jill).
     </para>
+
+    <para>
+      You can browse through open requests made of you and by you by selecting
+      'My Requests' from the footer. You can also look at open requests limited
+      by other requesters, requestees, products, components, and flag names from
+      this page. Note that you can use '-' for requestee to specify flags with
+      'no requestee' set.
+    </para>
+  </section>
+
+  <section id="whining">
+    <title>Whining</title>
+
+    <para>
+      Whining is a feature in Bugzilla that can regularly annoy users at 
+      specified times.  Using this feature, users can execute saved searches 
+      at specific times (i.e. the 15th of the month at midnight) or at 
+      regular intervals (i.e. every 15 minutes on Sundays).  The results of the
+      searches are sent to the user, either as a single email or as one email 
+      per bug, along with some descriptive text.
+    </para>
+
+    <warning>
+      <para>
+        Throughout this section it will be assumed that all users are members 
+        of the bz_canusewhines group, membership in which is required in order 
+        to use the Whining system.  You can easily make all users members of 
+        the bz_canusewhines group by setting the User RegExp to ".*" (without 
+        the quotes).
+      </para>
+
+      <para>
+        Also worth noting is the bz_canusewhineatothers group.  Members of this
+        group can create whines for any user or group in Bugzilla using a 
+        extended form of the whining interface.  Features only available to 
+        members of the bz_canusewhineatothers group will be noted in the 
+        appropriate places.
+      </para>
+    </warning>
+
+    <note>
+      <para>
+        For whining to work, a special Perl script must be executed at regular
+        intervals.  More information on this is available in 
+        <xref linkend="installation-whining"/>.
+      </para>
+    </note>
+
+    <note>
+      <para>
+        This section does not cover the whineatnews.pl script.  See
+        <xref linkend="installation-whining-cron"/> for more information on 
+        The Whining Cron.
+      </para>
+    </note>
+
+    <section id="whining-overview">
+      <title>The Event</title>
+
+      <para>
+        The whining system defines an "Event" as one or more queries being 
+        executed at regular intervals, with the results of said queries (if
+        there are any) being emailed to the user.  Events are created by 
+        clicking on the "Add new event" button.
+      </para>
+
+      <para>
+        Once a new event is created, the first thing to set is the "Email 
+        subject line".  The contents of this field will be used in the subject
+        line of every email generated by this event.  In addition to setting a 
+        subject, space is provided to enter some descriptive text that will be 
+        included at the top of each message (to help you in understanding why 
+        you received the email in the first place).
+      </para>
+
+      <para>
+        The next step is to specify when the Event is to be run (the Schedule) 
+        and what searches are to be performed (the Queries).
+      </para>
+
+    </section>
+
+    <section id="whining-schedule">
+      <title>Whining Schedule</title>
+
+      <para>
+         Each whining event is associated with zero or more schedules.  A 
+         schedule is used to specify when the query (specified below) is to be
+         run.  A new event starts out with no schedules (which means it will 
+         never run, as it is not scheduled to run).  To add a schedule, press
+         the "Add a new schedule" button.
+      </para>
+
+      <para>
+         Each schedule includes an interval, which you use to tell Bugzilla 
+         when the event should be run.  An event can be run on certain days of
+         the week, certain days of the month, during weekdays (defined as 
+         Monday through Friday), or every day.
+      </para>
+
+      <warning>
+        <para>
+          Be careful if you set your event to run on the 29th, 30th, or 31st of
+          the month, as your event may not run exactly when expected.  If you 
+          want your event to run on the last day of the month, select "Last day
+          of the month" as the interval.
+        </para>
+      </warning>
+
+      <para>
+        Once you have specified the day(s) on which the event is to be run, you
+        should now specify the time at which the event is to be run.  You can 
+        have the event run at a certain hour on the specified day(s), or 
+        every hour, half-hour, or quarter-hour on the specified day(s).
+      </para>
+
+      <para>
+        If a single schedule does not execute an event as many times as you 
+        would want, you can create another schedule for the same event.  For 
+        example, if you want to run an event on days whose numbers are
+        divisible by seven, you would need to add four schedules to the event,
+        setting the schedules to run on the 7th, 14th, 21st, and 28th (one day 
+        per schedule) at whatever time (or times) you choose.
+      </para>
+
+      <note>
+        <para>
+          If you are a member of the bz_canusewhineatothers group, then you
+          will be presented with another option: "Mail to".  Using this you 
+          can control who will receive the emails generated by this event.  You
+          can choose to send the emails to a single user (identified by email 
+          address) or a single group (identified by group name).  To send to 
+          multiple users or groups, create a new schedule for each additional 
+          user/group.
+        </para>
+      </note>
+    </section>
+
+    <section id="whining-query">
+      <title>Whining Queries</title>
+
+      <para>
+        Each whining event is associated with zero or more queries.  A query is
+        a saved search that is executed on the schedule specified (see above).
+        You start out with zero queries attached to the event (which means that
+        the event will not run, as there will never be any results to return).
+        To add a query, press the "Add a new query" button.
+      </para>
+
+      <para>
+        The first field to examine in your new query is the Sort field.  Queries
+        are executed, and results returned, in the order specified by the Sort 
+        field.  Queries with lower Sort values will run before queries with 
+        higher Sort values.
+      </para>
+
+      <para>
+        The next field to examine is the Search field.  This is where you 
+        choose the actual search that is to be run.  Instead of defining search
+        parameters here, you are asked to choose from the list of saved 
+        searches (the same list that appears at the bottom of every Bugzilla 
+        page).  You are only allowed to choose from searches that you have 
+        saved yourself (the default saved search, "My Bugs", is not a valid 
+        choice).  If you do not have any saved searches, you can take this 
+        opportunity to create one (see <xref linkend="list"/>).
+      </para>
+
+      <note>
+        <para>
+          When running queries, the whining system acts as if you are the user
+          executing the query.  This means that the whining system will ignore
+          bugs that match your query, but that you can not access.
+        </para>
+      </note>
+
+      <para>
+        Once you have chosen the saved search to be executed, give the query a 
+        descriptive title.  This title will appear in the email, above the 
+        results of the query.  If you choose "One message per bug", the query 
+        title will appear at the top of each email that contains a bug matching
+        your query.
+      </para>
+
+      <para>
+        Finally, decide if the results of the query should be sent in a single
+        email, or if each bug should appear in its own email.
+      </para>
+
+      <warning>
+        <para>
+          Think carefully before checking the "One message per bug" box.  If
+          you create a query that matches thousands of bugs, you will receive 
+          thousands of emails!
+        </para>
+      </warning>
+    </section>
+
+    <section>
+      <title>Saving Your Changes</title>
+
+      <para>
+        Once you have defined at least one schedule, and created at least one 
+        query, go ahead and "Update/Commit".  This will save your Event and make
+        it available for immediate execution.
+      </para>
+
+      <note>
+        <para>
+          If you ever feel like deleting your event, you may do so using the 
+          "Remove Event" button in the upper-right corner of each Event.  You 
+          can also modify an existing event, so long as you "Update/Commit" 
+          after completing your modifications.
+        </para>
+      </note>
+    </section>
+
   </section>
 
 </chapter>