Bug 271360 - Moving the Troubleshooting section into an appendix instead. Also, moved a few items out of the FAQ and into this new appendix.

2 files changed, 7 insertions, 194 deletions

diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml
index d12f6a817..619f7e95b 100644
--- a/docs/en/xml/Bugzilla-Guide.xml
+++ b/docs/en/xml/Bugzilla-Guide.xml
@@ -14,6 +14,7 @@
 <!ENTITY integration SYSTEM "integration.xml">
 <!ENTITY index SYSTEM "index.xml">
 <!ENTITY customization SYSTEM "customization.xml">
+<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
 <!ENTITY patches SYSTEM "patches.xml">
 <!ENTITY introduction SYSTEM "introduction.xml">
 <!ENTITY modules SYSTEM "modules.xml">
@@ -156,6 +157,9 @@
 <!-- Appendix: The Frequently Asked Questions -->
 &faq;
 
+<!-- Appendix: Troubleshooting -->
+&troubleshooting;
+
 <!-- Appendix: Custom Patches -->
 &patches;
 
@@ -193,4 +197,5 @@ sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End:
--->
\ No newline at end of file
+-->
+
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index ab7600432..27c807adc 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1,5 +1,5 @@
 <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.82 2008/04/04 06:47:12 jake%bugzilla.org Exp $ -->
+<!-- $Id: installation.xml,v 1.83 2008/04/04 06:47:13 jake%bugzilla.org Exp $ -->
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -1738,198 +1738,6 @@ pid-file=/home/foo/mymysql/the.pid
     </section>
   </section>
 
-  <section id="troubleshooting">
-    <title>Troubleshooting</title>
-    
-    <para>This section gives solutions to common Bugzilla installation
-    problems. If none of the section headings seems to match your
-    problem, read the general advice.
-    </para>
-    
-    <section id="general-advice">
-      <title>General Advice</title>
-      <para>
-        If you can't get <filename>checksetup.pl</filename> to run to 
-        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/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 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
-        fix the problem. If not, see below for some commonly-encountered 
-        errors. If that doesn't help, post the errors to the newsgroup.
-      </para>
-    </section>
-        
-    <section>
-      <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 webserver is configured properly for
-        Bugzilla.
-      </para>
-<programlisting><![CDATA[./testserver.pl http://landfill.bugzilla.org/bugzilla-tip
-TEST-OK Webserver is running under group id in $webservergroup.
-TEST-OK Got ant picture.
-TEST-OK Webserver is executing CGIs.
-TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig.
-]]></programlisting>
-    </section>
-
-    <section>
-      <title>I installed a Perl module, but 
-      <filename>checksetup.pl</filename> claims it's not installed!</title>
-      
-      <para>
-        You have two versions of Perl on your machine. You are installing
-        modules into one, and Bugzilla is using the other. Rerun the CPAN
-        commands (or manual compile) using the full path to Perl from the 
-        top of <filename>checksetup.pl</filename>. This will make sure you 
-        are installing the modules in the right place.
-      </para>
-    </section>
-    
-    <section>
-      <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>
-      <title>DBD::Sponge::db prepare failed</title>
-      
-      <para>
-        The following error message may appear due to a bug in DBD::mysql
-        (over which the Bugzilla team have no control):
-      </para>
-      
-<programlisting><![CDATA[ DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248.
-  SV = NULL(0x0) at 0x20fc444
-  REFCNT = 1
-  FLAGS = (PADBUSY,PADMY)
-]]></programlisting>
-
-      <para>
-        To fix this, go to 
-        <filename>&lt;path-to-perl&gt;/lib/DBD/sponge.pm</filename> 
-        in your Perl installation and replace
-      </para>
-        
-<programlisting><![CDATA[ my $numFields;
- if ($attribs->{'NUM_OF_FIELDS'}) {
-     $numFields = $attribs->{'NUM_OF_FIELDS'};
- } elsif ($attribs->{'NAME'}) {
-     $numFields = @{$attribs->{NAME}};
-]]></programlisting>
-
-      <para>
-        by
-      </para>
-
-<programlisting><![CDATA[ my $numFields;
- if ($attribs->{'NUM_OF_FIELDS'}) {
-     $numFields = $attribs->{'NUM_OF_FIELDS'};
- } elsif ($attribs->{'NAMES'}) {
-     $numFields = @{$attribs->{NAMES}};
-]]></programlisting>
-
-      <para>
-        (note the S added to NAME.)      
-      </para>
-    </section>
-    
-    <section id="paranoid-security">
-      <title>cannot chdir(/var/spool/mqueue)</title>
-
-      <para>If you are installing Bugzilla on SuSE Linux, or some other
-      distributions with 
-      <quote>paranoid</quote>
-      security options, it is possible that the checksetup.pl script may fail
-      with the error: 
-<programlisting><![CDATA[cannot chdir(/var/spool/mqueue): Permission denied
-]]></programlisting>
-      </para>
-      
-      <para>
-      This is because your 
-      <filename>/var/spool/mqueue</filename>
-      directory has a mode of 
-      <quote>drwx------</quote>. Type 
-      <command>chmod 755 
-      <filename>/var/spool/mqueue</filename>
-      </command>
-      as root to fix this problem.
-      </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>
 </chapter>
 
 <!-- Keep this comment at the end of the file