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.

14 files changed, 354 insertions, 223 deletions

diff --git a/docs/en/README.docs b/docs/en/README.docs
index 4ccd7044d..18c4126b8 100644
--- a/docs/en/README.docs
+++ b/docs/en/README.docs
@@ -3,34 +3,32 @@ You'll find these directories and files here:
 
 README.docs	# This README file
 html/		# The compiled HTML docs from SGML sources (do not edit)
-sgml/		# The original SGML doc sources (edit these)
+xml/		# The original XML doc sources (edit these)
 txt/		# The compiled text docs from SGML sources
-ps/		# The compiled PostScript docs from SGML sources
-pdf/		# The compiled Adobe PDF docs from SGML sources
-
-A note about SGML:
-  The documentation is written in DocBook 3.1/4.1 SGML, and attempts to adhere
-to the LinuxDoc standards everywhere applicable (http://www.linuxdoc.org).
-Please consult "The LDP Author Guide" at linuxdoc.org for details on how
-to set up your personal environment for compiling SGML files.
+
+A note about the XML:
+  The documentation is written in DocBook 4.1.2, and attempts to adhere
+to the LinuxDoc standards everywhere applicable (http://www.tldp.org).
+Please consult "The LDP Author Guide" at tldp.org for details on how
+to set up your personal environment for compiling XML files.
   If you need to make corrections to typographical errors, or other minor
-editing duties, feel free to use any text editor to make the changes.  SGML
+editing duties, feel free to use any text editor to make the changes.  XML
 is not rocket science -- simply make sure your text appears between 
 appropriate tags (like <para>This is a paragraph</para>) and we'll be fine.
 If you are making more extensive changes, please ensure you at least validate
-your SGML before checking it in with something like:
-	nsgmls -s Bugzilla-Guide.sgml
+your XML before checking it in with something like:
+	nsgmls -s $JADE_PUB/xml.dcl Bugzilla-Guide.xml
 
-  When you validate, please validate the master document (Bugzilla-Guide.sgml)
+  When you validate, please validate the master document (Bugzilla-Guide.xml)
 as well as the document you edited to ensure there are no critical errors.
 The following errors are considered "normal" when validating with nsgmls:
 
  DTDDECL catalog entries are not supported
  "DOCTYPE" declaration not allowed in instance
 
-  The reason these occur is that free sgml validators do not yet support
+  The reason these occur is that free sgml/xml validators do not yet support
 the DTDDECL catalog entries, and I've included DOCTYPE declarations in
-entities referenced from Bugzilla-Guide.sgml so these entities can compile
+entities referenced from Bugzilla-Guide.xml so these entities can compile
 individually, if necessary.  I suppose I ought to comment them out at some
 point, but for now they are convenient and don't hurt anything.
 
@@ -39,13 +37,13 @@ documentation.  Please address comments and questions to the newsgroup:
 news://news.mozilla.org/netscape/public/mozilla/webtools .
 
 ==========
-HOW TO SET UP YOUR OWN SGML EDITING ENVIRONMENT:
+HOW TO SET UP YOUR OWN XML EDITING ENVIRONMENT:
 ==========
 
-Trying to set up an SGML/XML Docbook editing environment the 
+Trying to set up an XML Docbook editing environment the 
 first time can be a daunting task.
 I use Linux-Mandrake, in part, because it has a fully-functional
-SGML/XML Docbook editing environment included as part of the
+XML Docbook editing environment included as part of the
 distribution CD's.  If you have easier instructions for how to
 do this for a particular Linux distribution or platform, please
 let the team know at the mailing list: mozilla-webtools@mozilla.org.
@@ -62,68 +60,96 @@ rpms:
 
 openjade
 jadetex
-docbook-dtd41-sgml
+docbook-dtds
 docbook-style-dsssl
-docbook-dtd31-sgml
 docbook-style-dsssl-doc
+docbook-utils
 xemacs
 psgml
 sgml-tools
 sgml-common
 
-Set up environment:
 
-in your .bashrc add this line (after installing above RPMS):
-export SGML_CATALOG_FILES=/etc/sgml/catalog
+If you're getting these from RedHat, make sure you get the ones in the
+rawhide area.  The ones in the 7.2 distribution are too old and don't
+include the XML stuff.  The packages distrubuted with RedHat 8.0 and 9
+and known to work.
 
-Download "ldp.dsl" from the Resources page on linuxdoc.org.  This is the 
+Download "ldp.dsl" from the Resources page on tldp.org.  This is the 
 stylesheet I use to get the HTML and text output.  It works well, and has a 
 nice, consistent look with the rest of the linuxdoc documents.  You'll have to 
 adjust the paths in ldp.dsl at the top of the file to reflect the actual 
 locations of your docbook catalog files.  I created a directory, 
 /usr/share/sgml/docbook/ldp, and put the ldp.dsl file there.  I then edited 
 ldp.dsl and changed two lines near the top:
-<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets-1.62/html/docbook.dsl" CDATA 
+<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets/html/docbook.dsl" CDATA 
 dsssl>
 ...and...
-<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets-1.62/print/docbook.dsl" CDATA
+<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets/print/docbook.dsl" CDATA
 dsssl>
 
 Note the difference is the top one points to the HTML docbook stylesheet, 
 and the next one points to the PRINT docbook stylesheet.
 
-  You know, this sure looks awful involved.  Anyway, once you have this in 
+Also note that modifying ldp.dsl doesn't seem to be needed on RedHat 9.
+
+  You know, this sure looks awful involved.  Anyway, once you have this in
 place, add to your .bashrc:
+export SGML_CATALOG_FILES=/etc/sgml/catalog
 export LDP_HOME=/usr/share/sgml/docbook/ldp
+export JADE_PUB=/usr/share/doc/openjade-1.3.1/pubtext
+
+or in .tcshrc:
+setenv SGML_CATALOG_FILES /etc/sgml/catalog
+setenv LDP_HOME /usr/share/sgml/docbook/ldp
+setenv JADE_PUB /usr/share/doc/openjade-1.3.1/pubtext
 
-  I suggest xemacs for editing your SGML/XML Docbook documents.  The darn
-thing just works, and generally includes PSGML mode by default.  You can
-download psgml at http://www.sourceforge.net/projects/psgml.
+  If you have root access and want to set this up for anyone on your box,
+you can add those lines to /etc/profile for bash users and /etc/csh.login
+for tcsh users.
+
+  Make sure you edit the paths in the above environment variables if those
+folders are anywhere else on your system (for example, the openjade version
+might change if you get a new version at some point).
+
+  I suggest xemacs for editing your XML Docbook documents.  The darn
+thing just works, and generally includes PSGML mode by default.  Not to
+mention you can validate the SGML from right within it without having to
+remember the command-line syntax for nsgml (not that it's that hard
+anyway).  If not, you can download psgml at
+http://www.sourceforge.net/projects/psgml.
+
+  Another good editor is the latest releases of vim and gvim.  Vim will
+recognize DocBook tags and give them a different color than unreconized tags.
 
 ==========
 NOTES:
 ==========
 
   Here are the commands I use to maintain this documentation.
-  You MUST have DocBook 4.1 set up correctly in order for this to work.
-  Substitute your own path to "ldp.dsl" for "$LDP_HOME".
+  You MUST have DocBook 4.1.2 set up correctly in order for this to work.
 
+  These commands can be run all at once using the ./makedocs.pl script.
 
 To create HTML documentation:
 bash$ cd html
 bash$ jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html \
-../sgml/Bugzilla-Guide.sgml
+$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml
 
 To create HTML documentation as a single big HTML file:
 bash$ cd html
 bash$ jade -V nochunks -t sgml -i html -d $LDP_HOME/ldp.dsl\#html \
-../sgml/Bugzilla-Guide.sgml >Bugzilla-Guide.html
+$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml >Bugzilla-Guide.html
 
 To create TXT documentation as a single big TXT file:
 bash$ cd txt
 bash$ lynx -dump -nolist ../html/Bugzilla-Guide.html >Bugzilla-Guide.txt
 
+
 Sincerely,
  Matthew P. Barnson
  The Bugzilla "Doc Knight"
- barnboy@trilobyte.net
+ mbarnson@sisna.com
+
+ with major edits by Dave Miller <justdave@syndicomm.com> based on
+ experience setting this up on the Landfill test server.
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: