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

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

Bug 232378: switch from entities to XIncludes for inclusion of modular docs files
164b989e · mozilla%colinogilvie.co.uk · 6e7c6391 · 164b989e · 164b989e · 164b989e
Commit 164b989e authored Apr 04, 2008 by mozilla%colinogilvie.co.uk
14 changed files
--- a/docs/en/xml/Bugzilla-Guide.xml
+++ b/docs/en/xml/Bugzilla-Guide.xml
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-<!-- Include macros -->
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY about SYSTEM "about.xml">
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
-<!ENTITY conventions SYSTEM "conventions.xml">
+    %myents;
-<!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">
 <!-- 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:
 -->
--- a/docs/en/xml/about.xml
+++ b/docs/en/xml/about.xml
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
-<!-- <!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),
+    Each component has a default assignee and (if you turned it on in the parameters),
-    a QA Contact. The owner should be the primary person who fixes bugs in
+    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>

--- a/docs/en/xml/conventions.xml
+++ b/docs/en/xml/conventions.xml
-<!-- <!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>File or directory name</entry>
-          <entry>
-            <filename>file.extension</filename>
-          </entry>
-        </row>
-        <row>
-          <entry>Directory Names</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>
+          Normal user's prompt under bash shell</entry>
-          of users command under bash shell</entry>
          <entry>bash$</entry>
        </row>
        <row>
          <entry>
-          <foreignphrase>Prompt</foreignphrase>
+          Root user's prompt under bash shell</entry>
-          of root users command under bash shell</entry>
          <entry>bash#</entry>
        </row>
        <row>
          <entry>
-          <foreignphrase>Prompt</foreignphrase>
+          Normal user's prompt under tcsh shell</entry>
-          of user command 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>
+            <programlisting><sgmltag class="starttag">para</sgmltag>
-            <sgmltag class="starttag">para</sgmltag>
+Beginning and end of paragraph
+<sgmltag class="endtag">para</sgmltag></programlisting>
-            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:

--- a/docs/en/xml/customization.xml
+++ b/docs/en/xml/customization.xml
-<!-- <!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 -->
+<!-- Integrating Bugzilla with Third-Party Tools -->
-  &integration;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="integration.xml" />
 </chapter>

--- a/docs/en/xml/gfdl.xml
+++ b/docs/en/xml/gfdl.xml
-<!-- <!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/">
+    <ulink url="http://www.gnu.org/copyleft/"/>.</para>
-    http://www.gnu.org/copyleft/</ulink>
-    .</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:

--- a/docs/en/xml/glossary.xml
+++ b/docs/en/xml/glossary.xml
-<!-- <!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
+        on a system. The <ulink url="http://search.cpan.org/dist/MailTools/Mail/Mailer.pm">Mail::Mailer</ulink>
-        <ulink url="http://www.sendmail.org">sendmail</ulink> which is what
+        Perl module, which Bugzilla uses to send email, can be configured to
-        Bugzilla expects to find by default at <filename>/usr/sbin/sendmail</filename>.
+        use many different underlying implementations for actually sending the
-        Many other MTA's will work, but they all require that 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>

--- 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:
 -->
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
+<?xml version="1.0"?>
-<!-- $Id: installation.xml,v 1.107 2008/04/04 06:47:37 mozilla%colinogilvie.co.uk Exp $ -->
+<!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>

--- a/docs/en/xml/modules.xml
+++ b/docs/en/xml/modules.xml
-<!-- <!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>

--- a/docs/en/xml/patches.xml
+++ b/docs/en/xml/patches.xml
--- a/docs/en/xml/security.xml
+++ b/docs/en/xml/security.xml
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
+<?xml version="1.0"?>
-<!-- $Id: security.xml,v 1.6 2008/04/04 06:48:13 zach%zachlipton.com Exp $ -->
+<!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
+      <para>If you installed Bugzilla version 2.22 or later from scratch,
-      set encoding ambiguities to inject HTML into Bugzilla comments. This
+      then the <emphasis>utf8</emphasis> parameter is switched on by default.
-      could include malicious scripts. 
+      This makes Bugzilla explicitly set the character encoding, following
-      Due to internationalization concerns, we are unable to
-      incorporate by default the code changes suggested by 
      <ulink
-      url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">the
+      url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">a
-      CERT advisory</ulink> on this issue.
+      CERT advisory</ulink> recommending exactly this.
-      Making the change in <xref linkend="security-bugzilla-charset-ex"/> will
+      The following therefore does not apply to you; just keep
-      prevent this problem. 
+      <emphasis>utf8</emphasis> turned on.
      </para>
-      <example id="security-bugzilla-charset-ex">
+      <para>If you've upgraded from an older version, then it may be possible
-      <title>Forcing Bugzilla to output a charset</title>
+      for a Bugzilla user to take advantage of character set encoding
+      ambiguities to inject HTML into Bugzilla comments.
-        <para>Locate the following line in
+      This could include malicious scripts. 
-        <filename>Bugzilla/CGI.pm</filename>:
+      This is because due to internationalization concerns, we are unable to
-        <programlisting>$self->charset('');</programlisting>
+      turn the <emphasis>utf8</emphasis> parameter on by default for upgraded
-        and change it to:
+      installations.
-        <programlisting>$self->charset('UTF-8');</programlisting>
+      Turning it on manually will prevent this problem.
-        </para>
+      </para>
-      </example>
    </section>    
  </section>

--- a/docs/en/xml/troubleshooting.xml
+++ b/docs/en/xml/troubleshooting.xml
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
+<?xml version="1.0"?>
-<!-- $Id: troubleshooting.xml,v 1.1 2008/04/03 19:05:43 lpsolit%gmail.com Exp $ -->
+<!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.
+	<para>The permissions on your library directories are set incorrectly.
-        They must, at the very least, be readable by the web server user or
+	They must, at the very least, be readable by the webserver user or
-        group. It is recommended that they be world readable.
+	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.

--- a/docs/en/xml/using.xml
+++ b/docs/en/xml/using.xml