More documentation updates.

1 files changed, 258 insertions, 28 deletions

diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml
index 6b755cbce..540109feb 100644
--- a/docs/en/xml/patches.xml
+++ b/docs/en/xml/patches.xml
@@ -1,42 +1,185 @@
-<!-- <!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>Contrib</title>
+  <title>Useful Patches and Utilities for Bugzilla</title>
 
-  <para>There are a number of unofficial Bugzilla add-ons in the 
-  <filename class="directory">$BUGZILLA_ROOT/contrib/</filename>
-  directory. This section documents them.</para>
+  <para>Are you looking for a way to put your Bugzilla into overdrive? Catch
+  some of the niftiest tricks here in this section.</para>
+
+  <section id="rewrite" xreflabel="Apache mod_rewrite magic">
+    <title>Apache 
+    <filename>mod_rewrite</filename>
+
+    magic</title>
+
+    <para>Apache's 
+    <filename>mod_rewrite</filename>
+
+    module lets you do some truly amazing things with URL rewriting. Here are
+    a couple of examples of what you can do.</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Make it so if someone types 
+        <computeroutput>http://www.foo.com/12345</computeroutput>
+
+        , Bugzilla spits back http://www.foo.com/show_bug.cgi?id=12345. Try
+        setting up your VirtualHost section for Bugzilla with a rule like
+        this:</para>
+
+        <programlisting>
+<![CDATA[
+<VirtualHost 12.34.56.78>
+RewriteEngine On
+RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R]
+</VirtualHost>
+]]>
+        </programlisting>
+      </listitem>
+
+      <listitem>
+        <para>There are many, many more things you can do with mod_rewrite.
+        As time goes on, I will include many more in the Guide. For now,
+        though, please refer to the mod_rewrite documentation at 
+        <ulink url="http://www.apache.org">http://www.apache.org</ulink>
+        </para>
+      </listitem>
+    </orderedlist>
+  </section>
+
+  <section id="setperl" xreflabel="The setperl.csh Utility">
+    <title>The setperl.csh Utility</title>
+
+    <para>You can use the "setperl.csh" utility to quickly and easily change
+    the path to perl on all your Bugzilla files. This is a C-shell script; if
+    you do not have "csh" or "tcsh" in the search path on your system, it
+    will not work!</para>
+
+    <procedure>
+      <step>
+        <para>Download the "setperl.csh" utility to your Bugzilla directory
+        and make it executable.</para>
+
+        <substeps>
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash#</prompt>
+
+                <command>cd /your/path/to/bugzilla</command>
+              </computeroutput>
+            </para>
+          </step>
+
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash#</prompt>
+
+                <command>wget -O setperl.csh
+                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=10795'</command>
+              </computeroutput>
+            </para>
+          </step>
+
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash#</prompt>
+
+                <command>chmod u+x setperl.csh</command>
+              </computeroutput>
+            </para>
+          </step>
+        </substeps>
+      </step>
+
+      <step>
+        <para>Prepare (and fix) Bugzilla file permissions.</para>
+
+        <substeps>
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash#</prompt>
+
+                <command>chmod u+w *</command>
+              </computeroutput>
+            </para>
+          </step>
+
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash#</prompt>
+
+                <command>chmod u+x duplicates.cgi</command>
+              </computeroutput>
+            </para>
+          </step>
+
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash#</prompt>
+
+                <command>chmod a-x bug_status.html</command>
+              </computeroutput>
+            </para>
+          </step>
+        </substeps>
+      </step>
+
+      <step>
+        <para>Run the script:</para>
+
+        <para>
+          <computeroutput>
+            <prompt>bash#</prompt>
+
+            <command>./setperl.csh /your/path/to/perl</command>
+          </computeroutput>
+
+          <example>
+            <title>Using Setperl to set your perl path</title>
+
+            <para>
+              <computeroutput>
+                <prompt>bash#</prompt>
+
+                <command>./setperl.csh /usr/bin/perl</command>
+              </computeroutput>
+            </para>
+          </example>
+        </para>
+      </step>
+    </procedure>
+  </section>
 
   <section id="cmdline">
-    <title>Command-line Search Interface</title>
-
-    <para>There are a suite of Unix utilities for searching Bugzilla from the 
-    command line. They live in the 
-    <filename class="directory">contrib/cmdline</filename> 
-    directory. However, they
-    have not yet been updated to work with 2.16 (post-templatisation.).
-    There are three files - <filename>query.conf</filename>, 
-    <filename>buglist</filename> and <filename>bugs</filename>.</para>
-    
-    <para><filename>query.conf</filename> 
-    contains the mapping from options to field
+    <title>Command-line Bugzilla Queries</title>
+
+    <para>Users can query Bugzilla from the command line using this suite of
+    utilities.</para>
+
+    <para>The query.conf file contains the mapping from options to field
     names and comparison types. Quoted option names are "grepped" for, so it
     should be easy to edit this file. Comments (#) have no effect; you must
-    make sure these lines do not contain any quoted "option".</para>
+    make sure these lines do not contain any quoted "option"</para>
 
-    <para><filename>buglist</filename>
-    is a shell script which submits a Bugzilla query and writes
+    <para>buglist is a shell script which submits a Bugzilla query and writes
     the resulting HTML page to stdout. It supports both short options, (such
     as "-Afoo" or "-Rbar") and long options (such as "--assignedto=foo" or
     "--reporter=bar"). If the first character of an option is not "-", it is
     treated as if it were prefixed with "--default=".</para>
 
-    <para>The column list is taken from the COLUMNLIST environment variable.
+    <para>The columlist is taken from the COLUMNLIST environment variable.
     This is equivalent to the "Change Columns" option when you list bugs in
-    buglist.cgi. If you have already used Bugzilla, grep for COLUMNLIST
-    in your cookies file to see your current COLUMNLIST setting.</para>
+    buglist.cgi. If you have already used Bugzilla, use 
+    <command>grep COLUMLIST ~/.netscape/cookies</command>
 
-    <para><filename>bugs</filename> is a simple shell script which calls
-    <filename>buglist</filename> and extracts the
+    to see your current COLUMNLIST setting.</para>
+
+    <para>bugs is a simple shell script which calls buglist and extracts the
     bug numbers from the output. Adding the prefix
     "http://bugzilla.mozilla.org/buglist.cgi?bug_id=" turns the bug list into
     a working link if any bugs are found. Counting bugs is easy. Pipe the
@@ -44,13 +187,100 @@
     <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command>
     </para>
 
-    <para>Akkana Peck says she has good results piping 
-    <filename>buglist</filename> output through 
+    <para>Akkana says she has good results piping buglist output through 
     <command>w3m -T text/html -dump</command>
     </para>
 
+    <procedure>
+      <step>
+        <para>Download three files:</para>
+
+        <substeps>
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash$</prompt>
+
+                <command>wget -O query.conf
+                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26157'</command>
+              </computeroutput>
+            </para>
+          </step>
+
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash$</prompt>
+
+                <command>wget -O buglist
+                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26944'</command>
+              </computeroutput>
+            </para>
+          </step>
+
+          <step>
+            <para>
+              <computeroutput>
+                <prompt>bash#</prompt>
+
+                <command>wget -O bugs
+                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26215'</command>
+              </computeroutput>
+            </para>
+          </step>
+        </substeps>
+      </step>
+
+      <step>
+        <para>Make your utilities executable: 
+        <computeroutput>
+          <prompt>bash$</prompt>
+
+          <command>chmod u+x buglist bugs</command>
+        </computeroutput>
+        </para>
+      </step>
+    </procedure>
   </section>
 
+  <section id="quicksearch">
+    <title>The Quicksearch Utility</title>
+
+    <para>Quicksearch is a new, experimental feature of the 2.12 release. It
+    consist of two Javascript files, "quicksearch.js" and "localconfig.js",
+    and two documentation files, "quicksearch.html" and
+    "quicksearchhack.html"</para>
+
+    <para>The index.html page has been updated to include the QuickSearch
+    text box.</para>
+
+    <para>To take full advantage of the query power, the Bugzilla maintainer
+    must edit "localconfig.js" according to the value sets used in the local
+    installation.</para>
+
+    <para>Currently, keywords must be hard-coded in localconfig.js. If they
+    are not, keywords are not automatically recognized. This means, if
+    localconfig.js is left unconfigured, that searching for a bug with the
+    "foo" keyword will only find bugs with "foo" in the summary, status
+    whiteboard, product or component name, but not those with the keyword
+    "foo".</para>
+
+    <para>Workarounds for Bugzilla users: 
+    <simplelist>
+      <member>search for '!foo' (this will find only bugs with the keyword
+      "foo"</member>
+
+      <member>search 'foo,!foo' (equivalent to 'foo OR keyword:foo')</member>
+    </simplelist>
+    </para>
+
+    <para>When this tool is ported from client-side JavaScript to server-side
+    Perl, the requirement for hard-coding keywords can be fixed. 
+    <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=70907">This
+    bug</ulink>
+
+    has details.</para>
+  </section>
 </appendix>
 
 <!-- Keep this comment at the end of the file
@@ -68,7 +298,7 @@ sgml-local-ecat-files:nil
 sgml-minimize-attributes:nil
 sgml-namecase-general:t
 sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End: