The source files for the Bugzilla Guide have long been using the XML version of DocBook but still residing in the sgml/ directory with an extension of .sgml.

In an effort to maintain CVS history, the raw files were copied on the CVS server to the xml/ directory and renamed to have .xml for the extension; any checkins before this one did have the .sgml extension.

13 files changed, 293 insertions, 188 deletions

diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml
index a9fcf097a..fd7353e8d 100644
--- a/docs/en/xml/Bugzilla-Guide.xml
+++ b/docs/en/xml/Bugzilla-Guide.xml
@@ -1,23 +1,23 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [
 
 <!-- Include macros -->
-<!ENTITY about SYSTEM "about.sgml">
-<!ENTITY conventions SYSTEM "conventions.sgml">
-<!ENTITY doc-index SYSTEM "index.sgml">
-<!ENTITY faq SYSTEM "faq.sgml">
-<!ENTITY gfdl SYSTEM "gfdl.sgml">
-<!ENTITY glossary SYSTEM "glossary.sgml">
-<!ENTITY installation SYSTEM "installation.sgml">
-<!ENTITY administration SYSTEM "administration.sgml">
-<!ENTITY using SYSTEM "using.sgml">
-<!ENTITY integration SYSTEM "integration.sgml">
-<!ENTITY future SYSTEM "future.sgml">
-<!ENTITY index SYSTEM "index.sgml">
-<!ENTITY database SYSTEM "database.sgml">
-<!ENTITY patches SYSTEM "patches.sgml">
-<!ENTITY variants SYSTEM "variants.sgml">
-<!ENTITY introduction SYSTEM "introduction.sgml">
-<!ENTITY revhistory SYSTEM "revhistory.sgml">
+<!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 future SYSTEM "future.xml">
+<!ENTITY index SYSTEM "index.xml">
+<!ENTITY database SYSTEM "database.xml">
+<!ENTITY patches SYSTEM "patches.xml">
+<!ENTITY variants SYSTEM "variants.xml">
+<!ENTITY introduction SYSTEM "introduction.xml">
+<!ENTITY revhistory SYSTEM "revhistory.xml">
 
 <!-- Things to change for a stable release:
      * bz-ver to current stable
@@ -70,7 +70,7 @@
 <!-- Coding standards for this document 
 
 *  Other than the GFDL, please use the "section" tag instead of "sect1", "sect2", etc.
-*  Use Entities to include files for new chapters in Bugzilla-Guide.sgml.
+*  Use Entities to include files for new chapters in Bugzilla-Guide.xml.
 *  Try to use Entities for frequently-used passages of text as well.
 *  Ensure all documents compile cleanly to HTML after modification.
 The warning, "DTDDECL catalog types not supported" is normal.
@@ -79,7 +79,7 @@ The warning, "DTDDECL catalog types not supported" is normal.
 *  Follow coding standards at http://www.tldp.org, and
 check out the KDE guidelines (they are nice, too)
 http://i18n.kde.org/doc/markup.html
-*  All tags should be lowercase (needsfix)
+*  All tags should be lowercase.
 *  Please use sensible spacing.  The comments at the very end of each
 file define reasonable defaults for PSGML mode in EMACS.
 Double-indent tags, use double spacing whenever possible, and
@@ -120,7 +120,7 @@ try to avoid clutter and feel free to waste space in the code to make it more re
 
       <para>  
 	      This documentation is maintained in DocBook 4.1.2 XML format.
-        Changes are best submitted as plain text or SGML diffs, attached
+        Changes are best submitted as plain text or XML diffs, attached
         to a bug filed in the &bzg-bugs; compontent.
       </para>
       <![%bz-devel;[
@@ -198,7 +198,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/about.xml b/docs/en/xml/about.xml
index b4349644a..f3a9a1c5f 100644
--- a/docs/en/xml/about.xml
+++ b/docs/en/xml/about.xml
@@ -1,5 +1,5 @@
 <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-<!ENTITY conventions SYSTEM "conventions.sgml"> ] > -->
+<!ENTITY conventions SYSTEM "conventions.xml"> ] > -->
 
 <chapter id="about">
 <title>About This Guide</title>
@@ -7,14 +7,14 @@
   <section id="copyright">
     <title>Copyright Information</title>
     <blockquote>
-      <attribution>Copyright (c) 2000-2002 Matthew P. Barnson and &bzg-auth;</attribution>
+      <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
 	Free Software Foundation; with no Invariant Sections, no
 	Front-Cover Texts, and  with no Back-Cover Texts.  A copy of
-	the license is included below.
+	the license is included in <xref linkend="gfdl"/>.
       </para>
     </blockquote>
     <para>
@@ -22,11 +22,6 @@
       copyright, or publishing this document in non-electronic form,
       please contact &bzg-auth;. 
     </para>
-
-
-    <!-- The GNU Free Documentation License -->
-    &gfdl;
-
   </section>
 
   <section id="disclaimer">
@@ -79,29 +74,27 @@
   <section id="newversions">
     <title>New Versions</title>
     <para>
-      This is the &bzg-ver; version of The Bugzilla Guide. It is so named 
-      to match the current version of Bugzilla. If you are
+      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.
     </para>
     <para>
-      This document can be found in the following places:
+      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.
     </para>
     <para>
-      <itemizedlist>
-	<listitem>
-	  <para>
-	    <ulink url="http://www.bugzilla.org/">bugzilla.org</ulink>
-	  </para>
-	</listitem>
-	<listitem>
-	  <para>
-	    <ulink url="http://www.linuxdoc.org/">The Linux
-	      Documentation Project</ulink>
-	  </para>
-	</listitem>
-      </itemizedlist>
+      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>.
     </para>
     <para>
       The latest version of this document can always be checked out via CVS.
@@ -125,43 +118,87 @@
       numerous e-mail and IRC support sessions, and overall excellent
       contribution to the Bugzilla community:
     </para>
-    <para>
-      <ulink url="mailto://mbarnson@sisna.com">Matthew P. Barnson</ulink>
-      for the Herculaean task of pulling together the Bugzilla Guide and
-      shepherding it to 2.14.
-    </para>
-    <para>
-      <ulink url="mailto://terry@mozilla.org">Terry Weissman</ulink>
-      for initially writing Bugzilla and creating the
-      README upon which the UNIX installation documentation is largely based.
-    </para>
-    <para>
-      <ulink url="mailto://tara@tequilarista.org">Tara Hernandez</ulink>  
-      for keeping Bugzilla development going
-      strong after Terry left mozilla.org
-    </para>
-    <para>
-      <ulink url="mailto://dkl@redhat.com">Dave Lawrence</ulink> 
-      for providing insight into the key differences between Red Hat's
-      customized Bugzilla, and being largely responsible for the "Red
-      Hat Bugzilla" appendix
-    </para>
-    <para>
-      <ulink url="mailto://endico@mozilla.org">Dawn Endico</ulink> for
-      being a hacker extraordinaire and putting up with my incessant
-      questions and arguments on irc.mozilla.org in #mozwebtools
-    </para>
+
+    <!-- TODO: This is evil... there has to be a valid way to get this look -->
+    <variablelist>
+      <varlistentry>
+        <term>Matthew P. Barnson <email>mbarnson@sisna.com</email></term>
+        <listitem>
+          <para>for the Herculaean task of pulling together the Bugzilla Guide
+          and shepherding it to 2.14.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Terry Weissman <email>terry@mozilla.org</email></term>
+        <listitem>
+          <para>for initially writing Bugzilla and creating the README upon
+          which the UNIX installation documentation is largely based.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Tara Hernandez <email>tara@tequilarists.org</email></term>
+        <listitem>
+          <para>for keeping Bugzilla development going strong after Terry left
+          mozilla.org and for running landfill.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <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="variant-redhat"/>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Dawn Endico <email>endico@mozilla.org</email></term>
+        <listitem>
+          <para>for being a hacker extraordinaire and putting up with Matthew's
+          incessant questions and arguments on irc.mozilla.org in #mozwebtools
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Jacob Steenhagen <email>jake@bugzilla.org</email></term>
+        <listitem>
+          <para>for taking over documentation during the 2.17 development
+          period.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
     <para>
       Last but not least, all 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.
+      <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 no particular order):
-    </para>
-    <para>
-      Zach Liption, Andrew Pearson, Spencer Smith, Eric Hanson, Kevin Brannen,
-      Ron Teitelbaum, Jacob Steenhagen, Joe Robins, Gervase Markham.
+      to this documentation (in alphabetical order):
+      <simplelist type="inline">
+        <member>Andrew Pearson</member>
+        <member>Ben FrantzDale</member>
+        <member>Eric Hanson</member>
+        <member>Gervase Markham</member>
+        <member>Joe Robins</member>
+        <member>Kevin Brannen</member>
+        <member>Ron Teitelbaum</member>
+        <member>Spencer Smith</member>
+        <member>Zach Liption</member>
+      </simplelist>
+      .
     </para>
   </section>
 
@@ -184,7 +221,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/administration.xml b/docs/en/xml/administration.xml
index f04e2b5ce..afe50c789 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -1632,7 +1632,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/conventions.xml b/docs/en/xml/conventions.xml
index 5e761d9f4..7e9eb5b04 100644
--- a/docs/en/xml/conventions.xml
+++ b/docs/en/xml/conventions.xml
@@ -171,7 +171,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/gfdl.xml b/docs/en/xml/gfdl.xml
index 047646411..ae19501d2 100644
--- a/docs/en/xml/gfdl.xml
+++ b/docs/en/xml/gfdl.xml
@@ -1,5 +1,5 @@
 <!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
-<section id="gfdl">
+<appendix id="gfdl">
   <title>GNU Free Documentation License</title>
 
 <!-- - GNU Project - Free Software Foundation (FSF) -->
@@ -423,7 +423,7 @@
     software license, such as the GNU General Public License, to permit their
     use in free software.</para>
   </section>
-</section>
+</appendix>
 
 <!-- Keep this comment at the end of the file
 Local variables:
@@ -440,7 +440,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 15b7fe948..807b7e647 100644
--- a/docs/en/xml/glossary.xml
+++ b/docs/en/xml/glossary.xml
@@ -129,8 +129,7 @@
   </glossdiv>
 
   <glossdiv id="gloss-c">
-    <title>
-    </title>
+    <title>C</title>
 
     <glossentry id="gloss-cgi">
       <glossterm>Common Gateway Interface</glossterm>
@@ -252,14 +251,31 @@
         should familiarize yourself with all of the documentation, some high
         points are:
         </para>
-        <itemizedlist>
-          <listitem>
-            <para><ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html">MySQL
-            Privilege System</ulink> - Much more detailed information about
-            the suggestions in <xref linkend="security-mysql"/>.
-            </para>
-          </listitem>
-        </itemizedlist>
+        <variablelist>
+          <varlistentry>
+            <term><ulink url="http://www.mysql.com/doc/en/Backup.html">Backup</ulink></term>
+            <listitem>
+              <para>Methods for backing up your Bugzilla database.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><ulink url="http://www.mysql.com/doc/en/Option_files.html">Option Files</ulink></term>
+            <listitem>
+              <para>Information about how to configure MySQL using
+              <filename>my.cnf</filename>.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><ulink url="http://www.mysql.com/doc/en/Privilege_system.html">Privilege System</ulink></term>
+            <listitem>
+              <para>Much more detailed information about the suggestions in
+              <xref linkend="security-mysql"/>.
+              </para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
       </glossdef>
     </glossentry>
   </glossdiv>
@@ -410,13 +426,34 @@
   <glossdiv id="gloss-z">
     <title>Z</title>
 
-    <glossentry id="zarro-boogs-found" xreflabel="Zarro Boogs Found">
+    <glossentry id="gloss-zarro">
       <glossterm>Zarro Boogs Found</glossterm>
 
       <glossdef>
-        <para>This is the cryptic response sent by Bugzilla when a query
-        returned no results. It is just a goofy way of saying "Zero Bugs
-        Found".</para>
+        <para>This is just a goofy way of saying that there were no bugs
+        found matching your query. When asked to explain this message,
+        Terry had the following to say:
+        </para>
+
+        <blockquote>
+          <attribution>Terry Weissman</attribution>
+          <para>I've been asked to explain this ... way back when, when
+          Netscape released version 4.0 of its browser, we had a release
+          party.  Naturally, there had been a big push to try and fix every
+          known bug before the release. Naturally, that hadn't actually
+          happened.  (This is not unique to Netscape or to 4.0; the same thing
+          has happened with every software project I've ever seen.)  Anyway,
+          at the release party, T-shirts were handed out that said something
+          like "Netscape 4.0: Zarro Boogs". Just like the software, the
+          T-shirt had no known bugs.  Uh-huh.
+          </para>
+
+          <para>So, when you query for a list of bugs, and it gets no results,
+          you can think of this as a friendly reminder.  Of *course* there are
+          bugs matching your query, they just aren't in the bugsystem yet...
+          </para>
+        </blockquote>
+
       </glossdef>
     </glossentry>
   </glossdiv>
@@ -437,7 +474,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/index.xml b/docs/en/xml/index.xml
index 7ca578cfc..7fc1a4c14 100644
--- a/docs/en/xml/index.xml
+++ b/docs/en/xml/index.xml
@@ -13,8 +13,9 @@ 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 b9fee2cc8..89dfc224c 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1165,7 +1165,7 @@ my $webservergid = '8'
       <command>look GD</command>. 
       This should go through the motions of downloading the latest version of
       the GD module, then it will open a shell and drop you into the build
-      directory. Apply <ulink url="../sgml/gd-makefile.patch">this patch</ulink> 
+      directory. Apply <ulink url="../xml/gd-makefile.patch">this patch</ulink> 
       to the Makefile.PL file (save the
       patch into a file and use the command 
       <command>patch &lt; patchfile</command>.)
@@ -1561,7 +1561,7 @@ at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.
       <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 patch in <xref linkend="trouble-filetemp-patch"/>. The patch is also
-      available as a <ulink url="../sgml/filetemp.patch">patch file</ulink>.
+      available as a <ulink url="../xml/filetemp.patch">patch file</ulink>.
       </para>
 
       <figure id="trouble-filetemp-patch">
@@ -1607,7 +1607,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/integration.xml b/docs/en/xml/integration.xml
index 1b0489fd9..514064d26 100644
--- a/docs/en/xml/integration.xml
+++ b/docs/en/xml/integration.xml
@@ -93,7 +93,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/introduction.xml b/docs/en/xml/introduction.xml
index 3968702c6..8b09fe2b5 100644
--- a/docs/en/xml/introduction.xml
+++ b/docs/en/xml/introduction.xml
@@ -1,39 +1,25 @@
 <chapter id="introduction">
   <title>Introduction</title>
 
-  <section id="what-is-bugzilla">
+  <section id="whatis">
     <title>What is Bugzilla?</title>
 
     <para>
     Bugzilla is a bug- or issue-tracking system. Bug-tracking
     systems allow individual or groups of developers effectively to keep track
-    of outstanding problems with their products. 
+    of outstanding problems with their product. 
+    Bugzilla was originally
+    written by Terry Weissman in a programming language called TCL, to
+    replace a rudimentary bug-tracking database used internally by Netscape
+    Communications. Terry later ported Bugzilla to Perl from TCL, and in Perl
+    it remains to this day. Most commercial defect-tracking software vendors
+    at the time charged enormous licensing fees, and Bugzilla quickly became
+    a favorite of the open-source crowd (with its genesis in the open-source
+    browser project, Mozilla). It is now the de-facto standard
+    defect-tracking system against which all others are measured.
     </para>
-    
-    <para><emphasis>Do we need more here?</emphasis></para>
-    
-  </section>
-
-  <section id="why-tracking">
-    <title>Why use a bug-tracking system?</title>
-    
-    <para>Those who do not use a bug-tracking system tend to rely on
-    shared lists, email, spreadsheets and/or Post-It notes to monitor the 
-    status of defects. This procedure
-    is usually error-prone and tends to cause those bugs judged least 
-    significant by developers to be dropped or ignored.</para>
-
-    <para>Integrated defect-tracking systems make sure that nothing gets
-    swept under the carpet; they provide a method of creating, storing,
-    arranging and processing defect reports and enhancement requests.</para>
-    
-  </section>
-    
-  <section id="why-bugzilla">
-    <title>Why use Bugzilla?</title>
 
-    <para>Bugzilla is the leading open-source/free software bug tracking 
-    system. It boasts many advanced features, including: 
+    <para>Bugzilla boasts many advanced features. These include: 
     <itemizedlist>
       <listitem>
         <para>Powerful searching</para>
@@ -68,12 +54,12 @@
       </listitem>
 
       <listitem>
-        <para>Completely customizable and/or localizable web user
-        interface</para>
+        <para>Web, XML, email and console interfaces</para>
       </listitem>
 
       <listitem>
-        <para>Additional XML, email and console interfaces</para>
+        <para>Completely customisable and/or localisable web user
+        interface</para>
       </listitem>
 
       <listitem>
@@ -85,7 +71,34 @@
       </listitem>
     </itemizedlist>
     </para>
-    
+  </section>
+
+  <section id="why">
+    <title>Why Should We Use Bugzilla?</title>
+
+    <para>For many years, defect-tracking software has remained principally
+    the domain of large software development houses. Even then, most shops
+    never bothered with bug-tracking software, and instead simply relied on
+    shared lists and email to monitor the status of defects. This procedure
+    is error-prone and tends to cause those bugs judged least significant by
+    developers to be dropped or ignored.</para>
+
+    <para>These days, many companies are finding that integrated
+    defect-tracking systems reduce downtime, increase productivity, and raise
+    customer satisfaction with their systems. Along with full disclosure, an
+    open bug-tracker allows manufacturers to keep in touch with their clients
+    and resellers, to communicate about problems effectively throughout the
+    data management chain. Many corporations have also discovered that
+    defect-tracking helps reduce costs by providing IT support
+    accountability, telephone support knowledge bases, and a common,
+    well-understood system for accounting for unusual system or software
+    issues.</para>
+
+    <para>But why should 
+    <emphasis>you</emphasis>
+
+    use Bugzilla?</para>
+
     <para>Bugzilla is very adaptable to various situations. Known uses
     currently include IT support queues, Systems Administration deployment
     management, chip design and development problem tracking (both
@@ -95,7 +108,22 @@
     <ulink url="http://www.cvshome.org">CVS</ulink>, 
     <ulink url="http://www.mozilla.org/bonsai.html">Bonsai</ulink>, or 
     <ulink url="http://www.perforce.com">Perforce SCM</ulink>, Bugzilla
-    provides a powerful, easy-to-use configuration management solution.</para>
+    provides a powerful, easy-to-use solution to configuration management and
+    replication problems.</para>
+
+    <para>Bugzilla can dramatically increase the productivity and
+    accountability of individual employees by providing a documented workflow
+    and positive feedback for good performance. How many times do you wake up
+    in the morning, remembering that you were supposed to do 
+    <emphasis>something</emphasis>
+    today, but you just can't quite remember? Put it in Bugzilla, and you
+    have a record of it from which you can extrapolate milestones, predict
+    product versions for integration, and  follow the discussion trail 
+    that led to critical decisions.</para>
+
+    <para>Ultimately, Bugzilla puts the power in your hands to improve your
+    value to your employer or business while providing a usable framework for
+    your natural attention to detail and knowledge store to flourish.</para>
   </section>
 </chapter>
 
diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml
index 43f816758..84d83d333 100644
--- a/docs/en/xml/patches.xml
+++ b/docs/en/xml/patches.xml
@@ -1,4 +1,4 @@
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<!-- <!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>
 
@@ -105,7 +105,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/requiredsoftware.xml b/docs/en/xml/requiredsoftware.xml
index e36b6184a..95988ec83 100644
--- a/docs/en/xml/requiredsoftware.xml
+++ b/docs/en/xml/requiredsoftware.xml
@@ -1,69 +1,70 @@
 <!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
-
 <appendix id="downloadlinks">
   <title>Software Download Links</title>
-  <para>
-    All of these sites are current as of April, 2001.  Hopefully
-    they'll stay current for a while.
-  </para>
-  <para>
-    Apache Web Server: <ulink url="http://www.apache.org/">http://www.apache.org</ulink>
-    Optional web server for Bugzilla, but recommended because of broad user base and support.
-  </para>
-  <para>
-    Bugzilla: <ulink url="http://www.mozilla.org/projects/bugzilla/">
-      http://www.mozilla.org/projects/bugzilla/</ulink>
-  </para>
-  <para>
-    MySQL: <ulink url="http://www.mysql.com/">http://www.mysql.com/</ulink>
+
+  <para>All of these sites are current as of April, 2001. Hopefully they'll
+  stay current for a while.</para>
+
+  <para>Apache Web Server: 
+  <ulink url="http://www.apache.org/">http://www.apache.org</ulink>
+
+  Optional web server for Bugzilla, but recommended because of broad user
+  base and support.</para>
+
+  <para>Bugzilla: 
+  <ulink url="http://www.bugzilla.org/">
+  http://www.bugzilla.org/</ulink>
   </para>
-  <para>
-    Perl: <ulink url="http://www.perl.org">http://www.perl.org/</ulink>
+
+  <para>MySQL: 
+  <ulink url="http://www.mysql.com/">http://www.mysql.com/</ulink>
   </para>
-  <para>
-    CPAN: <ulink url="http://www.cpan.org/">http://www.cpan.org/</ulink>
+
+  <para>Perl: 
+  <ulink url="http://www.perl.org">http://www.perl.org/</ulink>
   </para>
-  <para>
-    DBI Perl module: 
-    <ulink url="ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/DBI/">
-      ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/DBI/</ulink>
+
+  <para>CPAN: 
+  <ulink url="http://www.cpan.org/">http://www.cpan.org/</ulink>
   </para>
-  <para>
-    Data::Dumper module: 
-    <ulink url="ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Data/">
-      ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Data/</ulink>
+
+  <para>DBI Perl module: 
+  <ulink url="http://www.cpan.org/modules/by-module/DBI/">
+  http://www.cpan.org/modules/by-module/DBI/</ulink>
   </para>
-  <para>
-    MySQL related Perl modules:
-    <ulink url="ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Mysql/">
-      ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Mysql/</ulink>
+
+  <para>Data::Dumper module: 
+  <ulink url="http://www.cpan.org/modules/by-module/Data/">
+  http://www.cpan.org/modules/by-module/Data/</ulink>
   </para>
-  <para>
-    TimeDate Perl module collection:
-    <ulink url="ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Date/">
-      ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Date/</ulink>
+
+  <para>MySQL related Perl modules: 
+  <ulink url="http://www.cpan.org/modules/by-module/Mysql/">
+  http://www.cpan.org/modules/by-module/Mysql/</ulink>
   </para>
-  <para>
-    GD Perl module:
-    <ulink url="ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/GD/">
-      ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/GD/</ulink>
-    Alternately, you should be able to find the latest version of
-    GD at <ulink url="http://www.boutell.com/gd/">http://www.boutell.com/gd/</ulink>
+
+  <para>TimeDate Perl module collection: 
+  <ulink url="http://www.cpan.org/modules/by-module/Date/">
+  http://www.cpan.org/modules/by-module/Date/</ulink>
   </para>
-  <para>
-    Chart::Base module:
-    <ulink url="ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Chart/">
-    ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Chart/</ulink>
+
+  <para>GD Perl module: 
+  <ulink url="http://www.cpan.org/modules/by-module/GD/">
+  http://www.cpan.org/modules/by-module/GD/</ulink>
+
+  Alternately, you should be able to find the latest version of GD at 
+  <ulink url="http://www.boutell.com/gd/">http://www.boutell.com/gd/</ulink>
   </para>
-  <para>
-    LinuxDoc Software: 
-    <ulink url="http://www.linuxdoc.org/">http://www.linuxdoc.org/</ulink>
-    (for documentation maintenance)
+
+  <para>Chart::Base module: 
+  <ulink url="http://www.cpan.org/modules/by-module/Chart/">
+  http://www.cpan.org/modules/by-module/Chart/</ulink>
   </para>
 
+  <para>(But remember, Bundle::Bugzilla will install all the modules for you.)
+  </para>
 </appendix>
 
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
@@ -79,8 +80,9 @@ 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/using.xml b/docs/en/xml/using.xml
index a3986c27d..b5dab9d0a 100644
--- a/docs/en/xml/using.xml
+++ b/docs/en/xml/using.xml
@@ -572,7 +572,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: