Bug 423496: Compile the documentation with xmlto + dblatex instead of openjade

r=glob a=LpSolit

13 files changed, 212 insertions, 287 deletions

diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml
index 4265677ed..b20962358 100644
--- a/docs/en/xml/Bugzilla-Guide.xml
+++ b/docs/en/xml/Bugzilla-Guide.xml
@@ -1,51 +1,9 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     <!ENTITY % myents SYSTEM "bugzilla.ent">
     %myents;
-
-<!-- Include macros -->
-<!ENTITY about SYSTEM "about.xml">
-<!ENTITY conventions SYSTEM "conventions.xml">
-<!ENTITY doc-index SYSTEM "index.xml">
-<!ENTITY gfdl SYSTEM "gfdl.xml">
-<!ENTITY glossary SYSTEM "glossary.xml">
-<!ENTITY installation SYSTEM "installation.xml">
-<!ENTITY administration SYSTEM "administration.xml">
-<!ENTITY security SYSTEM "security.xml">
-<!ENTITY using SYSTEM "using.xml">
-<!ENTITY index SYSTEM "index.xml">
-<!ENTITY customization SYSTEM "customization.xml">
-<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
-<!ENTITY patches SYSTEM "patches.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
-     * landfillbase to the branch install
-     * Remove the BZ-DEVEL comments
-     - COMPILE DOCS AND CHECKIN -
-       Also, tag and tarball before completing
-     * bz-ver to devel version
- 
-     For a devel release, simple bump bz-ver and bz-date
--->
-
-<!ENTITY bz-ver "4.3">
-<!ENTITY bz-nextver "5.0">
-<!ENTITY bz-date "2011-08-04">
-<!ENTITY current-year "2011">
-
-<!ENTITY landfillbase "http://landfill.bugzilla.org/bugzilla-tip/">
-<!ENTITY bz "http://www.bugzilla.org/">
-<!ENTITY bzg-bugs "<ulink url='https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&amp;component=Documentation'>Bugzilla Documentation</ulink>">
-<!ENTITY mysql "http://www.mysql.com/">
-
-<!ENTITY min-perl-ver "5.8.1">
 ]>
 
-
 <!-- Coding standards for this document 
 
 *  Other than the GFDL, please use the "section" tag instead of "sect1", 
@@ -114,41 +72,37 @@
   </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 -->
-&security;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security.xml"/>
 
 <!-- Using Bugzilla -->
-&using;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="using.xml"/>
 
 <!-- Customizing Bugzilla -->
-&customization;
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="customization.xml"/>
 
 <!-- Appendix: Troubleshooting -->
-&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;
-
-<!-- Index -->
-&index;
-
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml"/>
 
 </book>
 
diff --git a/docs/en/xml/about.xml b/docs/en/xml/about.xml
index a6cebe0e0..ffc52e9f9 100644
--- a/docs/en/xml/about.xml
+++ b/docs/en/xml/about.xml
@@ -1,5 +1,9 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-<!ENTITY conventions SYSTEM "conventions.xml"> ] > -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
 
 <chapter id="about">
 <title>About This Guide</title>
@@ -190,8 +194,8 @@
   </section>
 
   <!-- conventions used here (didn't want to give it a chapter of its own) -->
-&conventions;
- </chapter> 
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conventions.xml" />
+</chapter>
 
 <!-- Keep this comment at the end of the file 
 Local variables: 
diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index c50ccbb3b..3796c8caf 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <chapter id="administration">
   <title>Administering Bugzilla</title>
 
@@ -24,10 +30,6 @@
           deploying a new Bugzilla installation.
         </para>
 
-        <indexterm>
-          <primary>checklist</primary>
-        </indexterm>
-
         <variablelist>
 
           <varlistentry>
diff --git a/docs/en/xml/conventions.xml b/docs/en/xml/conventions.xml
index 70e6624f7..6a8f8b47e 100644
--- a/docs/en/xml/conventions.xml
+++ b/docs/en/xml/conventions.xml
@@ -1,144 +1,65 @@
-<!-- <!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>
 
-  <indexterm zone="conventions">
-    <primary>conventions</primary>
-  </indexterm>
-
   <para>This document uses the following conventions:</para>
 
-  <informaltable frame="none">
-    <tgroup cols="2">
-      <thead>
-        <row>
-          <entry>Descriptions</entry>
-
-          <entry>Appearance</entry>
-        </row>
-      </thead>
-
-      <tbody>
-        <row>
-          <entry>Caution</entry>
-
-          <entry>
-            <caution>
-              <para>Don't run with scissors!</para>
-            </caution>
-          </entry>
-        </row>
-
-        <row>
-          <entry>Hint or Tip</entry>
-
-          <entry>
-            <tip>
-              <para>For best results... </para>
-            </tip>
-          </entry>
-        </row>
-
-        <row>
-          <entry>Note</entry>
-
-          <entry>
-            <note>
-              <para>Dear John...</para>
-            </note>
-          </entry>
-        </row>
-
-        <row>
-          <entry>Warning</entry>
-
-          <entry>
-            <warning>
-              <para>Read this or the cat gets it.</para>
-            </warning>
-          </entry>
-        </row>
-
-        <row>
-          <entry>File or directory name</entry>
+  <caution>
+    <para>This is a caution. Make sure to read this to not be in trouble!</para>
+  </caution>
 
-          <entry>
-            <filename>filename</filename>
-          </entry>
-        </row>
+  <tip>
+    <para>This is a hint or tip, especially about some configuration tweaks.</para>
+  </tip>
 
-        <row>
-          <entry>Command to be typed</entry>
+  <note>
+    <para>This is just a note, for your information.</para>
+  </note>
 
-          <entry>
-            <command>command</command>
-          </entry>
-        </row>
+  <warning>
+    <para>This is a warning, something you should take care of.</para>
+  </warning>
 
-        <row>
-          <entry>Application name</entry>
-
-          <entry>
-            <application>application</application>
-          </entry>
-        </row>
-
-        <row>
-          <entry>
-          Normal user's prompt under bash shell</entry>
-
-          <entry>bash$</entry>
-        </row>
-
-        <row>
-          <entry>
-          Root user's prompt under bash shell</entry>
-
-          <entry>bash#</entry>
-        </row>
-
-        <row>
-          <entry>
-          Normal user's prompt under tcsh shell</entry>
-
-          <entry>tcsh$</entry>
-        </row>
-
-        <row>
-          <entry>Environment variables</entry>
+  <para>
+    A filename or a path to a filename is displayed like this:
+    <filename>/path/to/filename.ext</filename>
+  </para>
 
-          <entry>
-            <envar>VARIABLE</envar>
-          </entry>
-        </row>
+  <para>
+    A command to type in the shell is displayed like this:
+    <command>command --arguments</command>
+  </para>
 
-        <row>
-          <entry>Term found in the glossary</entry>
+  <para>bash$ represents a normal user's prompt under bash shell</para>
 
-          <entry>
-            <glossterm linkend="gloss-bugzilla">Bugzilla</glossterm>
-          </entry>
-        </row>
+  <para>bash# represents a root user's prompt under bash shell</para>
 
-        <row>
-          <entry>Code example</entry>
+  <para>
+    A word which is in the glossary will appear like this:
+    <glossterm linkend="gloss-bugzilla">Bugzilla</glossterm>
+  </para>
 
-          <entry>
-            <programlisting><sgmltag class="starttag">para</sgmltag>
-Beginning and end of paragraph
-<sgmltag class="endtag">para</sgmltag></programlisting>
-          </entry>
-        </row>
-      </tbody>
-    </tgroup>
-  </informaltable>
+  <para>
+    A sample of code is illustrated like this:
+    <programlisting>
+First Line of Code
+Second Line of Code
+...
+    </programlisting>
+  </para>
 
-  <para>  
-	  This documentation is maintained in DocBook 4.1.2 XML format.
+  <para>
+    This documentation is maintained in DocBook 4.2 XML format.
     Changes are best submitted as plain text or XML diffs, attached
-    to a bug filed in the &bzg-bugs; component.
+    to a bug filed in the <ulink url="&bzg-bugs;">Bugzilla Documentation</ulink>
+    component.
   </para>
-  
 </section>
 
 <!-- Keep this comment at the end of the file
diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml
index 9b62b1d0b..1cfa0c548 100644
--- a/docs/en/xml/customization.xml
+++ b/docs/en/xml/customization.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <chapter id="customization">
   <title>Customizing Bugzilla</title>
 
@@ -14,7 +20,7 @@
     </para>
 
     <para>
-      See the <ulink url="api/Bugzilla/Extension.html">Bugzilla Extension
+	  See the <ulink url="../html/api/Bugzilla/Extension.html">Bugzilla Extension
       documentation</ulink> for information on how to write an Extension.
     </para>
   </section>
@@ -391,7 +397,7 @@
 
       <para>  
         An example of this is the mozilla.org 
-        <ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&amp;format=guided">guided 
+        <ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided">guided
         bug submission form</ulink>. The code for this comes with the Bugzilla
         distribution as an example for you to copy. It can be found in the
         files 
diff --git a/docs/en/xml/gfdl.xml b/docs/en/xml/gfdl.xml
index 1d84d1255..0de66acd3 100644
--- a/docs/en/xml/gfdl.xml
+++ b/docs/en/xml/gfdl.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <appendix id="gfdl">
   <title>GNU Free Documentation License</title>
 
diff --git a/docs/en/xml/glossary.xml b/docs/en/xml/glossary.xml
index aef3ab395..8d0c0e58d 100644
--- a/docs/en/xml/glossary.xml
+++ b/docs/en/xml/glossary.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > -->
+<?xml version="1.0"?>
+<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <glossary id="glossary">
   <glossdiv>
     <title>0-9, high ascii</title>
@@ -42,7 +48,7 @@
           <title>Useful Directives when configuring Bugzilla</title>
 
           <varlistentry>
-            <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#addhandler">AddHandler</ulink></computeroutput></term>
+            <term><computeroutput><ulink url="http://httpd.apache.org/docs/2.0/mod/mod_mime.html#addhandler">AddHandler</ulink></computeroutput></term>
             <listitem>
               <para>Tell Apache that it's OK to run CGI scripts.</para>
             </listitem>
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index e43c567b8..cdff751d4 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//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="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -169,16 +175,17 @@
       <para>Installed Version Test: view the default welcome page at
       http://&lt;your-machine&gt;/</para>
       
-      <para>You have freedom of choice here, pretty much any web server that
-      is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
-      scripts will work.
-       However, we strongly recommend using the Apache web server
-       (either 1.3.x or 2.x), and 
-       the installation instructions usually assume you are
-        using it. If you have got Bugzilla working using another web server,
-        please share your experiences with us by filing a bug in &bzg-bugs;.
+      <para>
+        You have freedom of choice here, pretty much any web server that
+        is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
+        scripts will work.
+        However, we strongly recommend using the Apache web server
+        (either 1.3.x or 2.x), and the installation instructions usually assume
+        you are using it. If you have got Bugzilla working using another web server,
+        please share your experiences with us by filing a bug in
+        <ulink url="&bzg-bugs;">Bugzilla Documentation</ulink>.
       </para>
-      
+
       <para>
       If you don't have Apache and your OS doesn't provide official packages, 
       visit <ulink url="http://httpd.apache.org/"/>.
@@ -732,9 +739,9 @@ max_allowed_packet=4M
           This can be done by modifying the <filename>/etc/my.cnf</filename>
           according to the example below:</para>
 
-          <screen>  [mysqld]
-  # Allow small words in full-text indexes
-  ft_min_word_len=2</screen>
+          <screen>[mysqld]
+# Allow small words in full-text indexes
+ft_min_word_len=2</screen>
 
           <para>Rebuilding the indexes can be done based on documentation found at
           <ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>.
@@ -770,11 +777,11 @@ max_allowed_packet=4M
           </para>
 
           <screen>
-    <prompt>mysql&gt;</prompt> GRANT SELECT, INSERT,
-           UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
-           CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
-           TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
-    <prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
+<prompt>mysql&gt;</prompt> GRANT SELECT, INSERT,
+       UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
+       CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
+       TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
+<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
           </screen>
         </section>
 
@@ -796,8 +803,8 @@ max_allowed_packet=4M
           </para>
 
           <screen>
-    <prompt>mysql&gt;</prompt> use <replaceable>$bugs_db</replaceable>
-    <prompt>mysql&gt;</prompt> ALTER TABLE attachments
+<prompt>mysql&gt;</prompt> use <replaceable>$bugs_db</replaceable>
+<prompt>mysql&gt;</prompt> ALTER TABLE attachments
            AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
           </screen>
 
@@ -832,11 +839,11 @@ max_allowed_packet=4M
           <para>On most systems, to create the user in PostgreSQL, you will need to
           login as the root user, and then</para>
 
-          <screen> <prompt>bash#</prompt> su - postgres</screen>
+          <screen><prompt>bash#</prompt> su - postgres</screen>
 
           <para>As the postgres user, you then need to create a new user: </para>
             
-          <screen> <prompt>bash$</prompt> createuser -U postgres -dRSP bugs</screen>
+          <screen><prompt>bash$</prompt> createuser -U postgres -dRSP bugs</screen>
  
           <para>When asked for a password, provide the password which will be set as
           <replaceable>$db_pass</replaceable> in <filename>localconfig</filename>.
@@ -880,9 +887,9 @@ max_allowed_packet=4M
           </para>
 
           <programlisting>
-    CREATE TABLESPACE bugs
-    DATAFILE '<replaceable>$path_to_datafile</replaceable>' SIZE 500M
-    AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
+CREATE TABLESPACE bugs
+DATAFILE '<replaceable>$path_to_datafile</replaceable>' SIZE 500M
+AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
           </programlisting>
 
           <para>
@@ -907,17 +914,17 @@ max_allowed_packet=4M
           </para>
 
           <programlisting>
-    CREATE USER bugs
-    IDENTIFIED BY "<replaceable>$db_pass</replaceable>"
-    DEFAULT TABLESPACE bugs
-    TEMPORARY TABLESPACE TEMP
-    PROFILE DEFAULT;
-    -- GRANT/REVOKE ROLE PRIVILEGES
-    GRANT CONNECT TO bugs;
-    GRANT RESOURCE TO bugs;
-    -- GRANT/REVOKE SYSTEM PRIVILEGES
-    GRANT UNLIMITED TABLESPACE TO bugs;
-    GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
+CREATE USER bugs
+IDENTIFIED BY "<replaceable>$db_pass</replaceable>"
+DEFAULT TABLESPACE bugs
+TEMPORARY TABLESPACE TEMP
+PROFILE DEFAULT;
+-- GRANT/REVOKE ROLE PRIVILEGES
+GRANT CONNECT TO bugs;
+GRANT RESOURCE TO bugs;
+-- GRANT/REVOKE SYSTEM PRIVILEGES
+GRANT UNLIMITED TABLESPACE TO bugs;
+GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
           </programlisting>
         </section>
 
@@ -930,8 +937,8 @@ max_allowed_packet=4M
           </para>
 
           <programlisting>
-    SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/
-    SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/
+SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/
+SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/
           </programlisting>
 
           <para>
@@ -1040,12 +1047,12 @@ max_allowed_packet=4M
                 </para>
     
                 <programlisting>
-    &lt;Directory /var/www/html/bugzilla&gt;
-    AddHandler cgi-script .cgi
-    Options +Indexes +ExecCGI
-    DirectoryIndex index.cgi
-    AllowOverride Limit FileInfo Indexes
-    &lt;/Directory&gt;
+&lt;Directory /var/www/html/bugzilla&gt;
+AddHandler cgi-script .cgi
+Options +Indexes +ExecCGI
+DirectoryIndex index.cgi
+AllowOverride Limit FileInfo Indexes
+&lt;/Directory&gt;
                 </programlisting>
     
                 <para>
@@ -1101,9 +1108,7 @@ max_allowed_packet=4M
                 (the same one as in the step above):
                 </para>
     
-                <programlisting>
-    +FollowSymLinks
-                </programlisting>
+                <programlisting>+FollowSymLinks</programlisting>
     
                 <para>
                 Without this directive, Apache will not follow symbolic links
@@ -1142,10 +1147,10 @@ max_allowed_packet=4M
                 <para>You should also ensure that you have disabled <literal>KeepAlive</literal>
                 support in your Apache install when utilizing Bugzilla under mod_perl</para>
                 </warning> 
-                
+
                 <programlisting>
-    PerlSwitches -w -T
-    PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
+PerlSwitches -w -T
+PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
                 </programlisting>
             </step>
 			
@@ -1521,8 +1526,8 @@ AddType application/rdf+xml .rdf</screen>
     and the utilities available to make it easier.
     </para>
 
-    <para>If you have anything to add or notes for an operating system not
-    covered, please file a bug in &bzg-bugs;. 
+    <para>If you have anything to add or notes for an operating system not covered,
+    please file a bug in <ulink url="&bzg-bugs;">Bugzilla Documentation</ulink>.
     </para>
 
     <section id="os-win32">
@@ -1855,13 +1860,11 @@ pid-file=/home/foo/mymysql/the.pid
             <para>After your mysqld program is built and any .my.cnf file is 
             in place, you must initialize the databases (ONCE).</para>
             <screen>
-              <prompt>bash$</prompt>
-              <command>mysql_install_db</command>
+<prompt>bash$</prompt> <command>mysql_install_db</command>
             </screen>
             <para>Then start the daemon with</para>
             <screen>
-              <prompt>bash$</prompt>
-              <command>safe_mysql &amp;</command>
+<prompt>bash$</prompt> <command>safe_mysql &amp;</command>
             </screen>
             <para>After you start mysqld the first time, you then connect to
             it as "root" and <command>GRANT</command> permissions to other
@@ -1883,7 +1886,6 @@ pid-file=/home/foo/mymysql/the.pid
             </warning>
           </section>
       </section>
-
     </section>
 
     <section>
@@ -1897,16 +1899,11 @@ pid-file=/home/foo/mymysql/the.pid
       </para>
 
       <screen>
-        <prompt>bash$</prompt>
-        <command>wget http://perl.org/CPAN/src/stable.tar.gz</command>
-        <prompt>bash$</prompt>
-        <command>tar zvxf stable.tar.gz</command>
-        <prompt>bash$</prompt>
-        <command>cd perl-5.8.1</command> (or whatever the version of Perl is called)
-        <prompt>bash$</prompt>
-        <command>sh Configure -de -Dprefix=/home/foo/perl</command>
-        <prompt>bash$</prompt>
-        <command>make &amp;&amp; make test &amp;&amp; make install</command>
+<prompt>bash$</prompt> <command>wget http://perl.org/CPAN/src/stable.tar.gz</command>
+<prompt>bash$</prompt> <command>tar zvxf stable.tar.gz</command>
+<prompt>bash$</prompt> <command>cd perl-&min-perl-ver;</command>
+<prompt>bash$</prompt> <command>sh Configure -de -Dprefix=/home/foo/perl</command>
+<prompt>bash$</prompt> <command>make &amp;&amp; make test &amp;&amp; make install</command>
       </screen>
 
       <para>
@@ -1923,7 +1920,7 @@ pid-file=/home/foo/mymysql/the.pid
       Installing the Perl modules as a non-root user is accomplished by
       running the <filename>install-module.pl</filename>
       script. For more details on this script, see 
-      <ulink url="api/install-module.html"><filename>install-module.pl</filename>
+      <ulink url="../html/api/install-module.html"><filename>install-module.pl</filename>
       documentation</ulink>
       </para>
     </section>
@@ -2000,10 +1997,12 @@ pid-file=/home/foo/mymysql/the.pid
         shell commands after running <command>./checksetup.pl</command>,
         every time you run it (or modify <filename>checksetup.pl</filename>
         to do them for you via the system() command).
-        <programlisting>        for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done
-        for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done
-        find . -name .htaccess -exec chmod o+r {} \;
-        chmod o+x . data data/webdot</programlisting>
+        <programlisting>
+for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done
+for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done
+find . -name .htaccess -exec chmod o+r {} \;
+chmod o+x . data data/webdot
+        </programlisting>
         Pay particular attention to the number of semicolons and dots.
         They are all important.  A future version of Bugzilla will
         hopefully be able to do this for you out of the box.</para>
diff --git a/docs/en/xml/modules.xml b/docs/en/xml/modules.xml
index 933c9de5b..a578f9f16 100644
--- a/docs/en/xml/modules.xml
+++ b/docs/en/xml/modules.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <appendix id="install-perlmodules-manual">
   <title>Manual Installation of Perl Modules</title>
   
diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml
index 12efb0ca4..e5a6a8c47 100644
--- a/docs/en/xml/patches.xml
+++ b/docs/en/xml/patches.xml
@@ -1,4 +1,10 @@
-<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
+
 <appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
   <title>Contrib</title>
 
diff --git a/docs/en/xml/security.xml b/docs/en/xml/security.xml
index b234dd993..270b8a72c 100644
--- a/docs/en/xml/security.xml
+++ b/docs/en/xml/security.xml
@@ -1,4 +1,9 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//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="security">
 <title>Bugzilla Security</title>
diff --git a/docs/en/xml/troubleshooting.xml b/docs/en/xml/troubleshooting.xml
index fff90a9e1..f42436d2e 100644
--- a/docs/en/xml/troubleshooting.xml
+++ b/docs/en/xml/troubleshooting.xml
@@ -1,4 +1,9 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//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="troubleshooting">
 <title>Troubleshooting</title>
@@ -173,17 +178,17 @@ TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-t
 
     <blockquote>
       <literallayout>
-        urlbase is <ulink url="http://bugzilla.mozilla.org/"/>
-        cookiepath is /
+urlbase is http://bugzilla.mozilla.org/
+cookiepath is /
 
-        urlbase is <ulink url="http://tools.mysite.tld/bugzilla/"/>
-                but you have http://tools.mysite.tld/someotherapp/ which shares
-                authentication with your Bugzilla
-        cookiepath is /
+urlbase is http://tools.mysite.tld/bugzilla/
+        but you have http://tools.mysite.tld/someotherapp/ which shares
+        authentication with your Bugzilla
+cookiepath is /
       </literallayout>
     </blockquote>
   </example>
-          
+
    <para>On the other hand, if you have more than one Bugzilla running on the
    server (some people do - we do on landfill) then you need to have the
    cookiepath restricted enough so that the different Bugzillas don't
@@ -195,11 +200,11 @@ TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-t
    <title>Examples of urlbase/cookiepath pairs to restrict the login cookie</title>
       <blockquote>
         <literallayout>
-        urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-tip/"/>
-        cookiepath is /bugzilla-tip/
+urlbase is http://landfill.bugzilla.org/bugzilla-tip/
+cookiepath is /bugzilla-tip/
 
-        urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-2.16-branch/"/>
-        cookiepath is /bugzilla-2.16-branch/
+urlbase is http://landfill.bugzilla.org/bugzilla-4.0-branch/
+cookiepath is /bugzilla-4.0-branch/
         </literallayout>
       </blockquote>
     </example>
diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml
index 6d575c0c1..e832dea7a 100644
--- a/docs/en/xml/using.xml
+++ b/docs/en/xml/using.xml
@@ -1,4 +1,9 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+    <!ENTITY % myents SYSTEM "bugzilla.ent">
+    %myents;
+]>
 
 <chapter id="using">
   <title>Using Bugzilla</title>
@@ -377,7 +382,7 @@
       <title>Lifecycle of a Bugzilla Bug</title>
       <mediaobject>
         <imageobject>
-          <imagedata fileref="../images/bzLifecycle.png" scale="66" />
+          <imagedata fileref="../images/bzLifecycle.png"/>
         </imageobject>
       </mediaobject>
     </figure>