More documentation updates.

1 files changed, 236 insertions, 428 deletions

diff --git a/docs/sgml/patches.sgml b/docs/sgml/patches.sgml
index 31d867e86..540109feb 100644
--- a/docs/sgml/patches.sgml
+++ b/docs/sgml/patches.sgml
@@ -1,480 +1,287 @@
 <!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>		
+  <title>Useful Patches and Utilities for Bugzilla</title>
 
-  <para>Are you looking for a way to put your Bugzilla into overdrive?  Catch some of the niftiest tricks here in this section.</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>
+    <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>
+        <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>
-
+        </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>
+        <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">
+  <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>	
+
+    <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>
+        <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>
+        <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>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>
+          </example>
+        </para>
       </step>
     </procedure>
   </section>
 
   <section id="cmdline">
     <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>
-    <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 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, use
-      <command>grep COLUMLIST ~/.netscape/cookies</command> 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 results through <command>sed -e 's/,/ /g' | wc |
-	awk '{printf $2 "\n"}'</command>
+
+    <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>
+
+    <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 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, use 
+    <command>grep COLUMLIST ~/.netscape/cookies</command>
+
+    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
+    results through 
+    <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command>
     </para>
-    <para>
-      Akkana says she has good results piping buglist output through
-      <command>w3m -T text/html -dump</command>
+
+    <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>
+        <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>
+        <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>
 
-  <section id="bzhacking">
-    <title>Hacking Bugzilla</title>
-    <para>
-      The following is a guide for reviewers when checking code into Bugzilla's
-      CVS repostory at mozilla.org.  If you wish to submit patches to Bugzilla,
-      you should follow the rules and style conventions below.  Any code that
-      does not adhere to these basic rules will not be added to Bugzilla's
-      codebase.
+    <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>
-    <section>
-      <title>Things that have caused problems and should be avoided</title>
-      <orderedlist>
-        <listitem>
-          <para>
-            Usage of variables in Regular Expressions
-          </para>
-          <para>
-            It is very important that you don't use a variable in a regular
-            expression unless that variable is supposed to contain an expression.
-            This especially applies when using grep.  You should use:
-          </para>
-          <para>
-            <programlisting>
-grep ($_ eq $value, @array);
-            </programlisting>
-          </para>
-          <para>
-            -- NOT THIS --
-          </para>
-          <para>
-            <programlisting>
-grep (/$value/, @array);
-            </programlisting>
-          </para>
-          <note>
-            <para>
-              If you need to use a non-expression variable inside of an expression, be
-              sure to quote it properly (using <function>\Q..\E</function>).
-            </para>
-          </note>
-        </listitem>
-      </orderedlist>
-    </section>
-    <section>
-      <title>Coding Style for Bugzilla</title>
-      <para>
-        While it's true that not all of the code currently in Bugzilla adheres to
-        this (or any) styleguide, it is something that is being worked toward.  Therefore,
-        we ask that all new code (submitted patches and new files) follow this guide
-        as closely as possible (if you're only changing 1 or 2 lines, you don't have
-        to reformat the entire file :).
-      </para>
-      <para>
-        The Bugzilla development team has decided to adopt the perl style guide as
-        published by Larry Wall.  This giude can be found in <quote>Programming
-        Perl</quote> (the camel book) or by typing <command>man perlstyle</command> at
-        your favorite shell prompt.
-      </para>
-      <para>
-        What appears below if a brief summary, please refer to the perl style
-        guide if you don't see your question covered here.  It is much better to submit
-	a patch which fails these criteria than no patch at all, but please try to meet
-	these minimum standards when submitting code to Bugzilla.
-      </para>
-      <itemizedlist>
-        <listitem>
-          <para>
-            Whitespace
-          </para>
-          <para>
-            Bugzilla's preferred indentation is 4 spaces (no tabs, please).
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            Curly braces.
-          </para>
-          <para>
-            The opening brace of a block should be on the same line as the statement
-            that is causing the block and the closing brace should be at the same
-            indentation level as that statement, for example:
-          </para>
-          <para>
-            <programlisting>
-if ($var) {
-    print "The variable is true";
-}
-else {
-    print "Try again";
-}
-            </programlisting>
-          </para>
-          <para>
-            -- NOT THIS --
-          </para>
-          <para>
-            <programlisting>
-if ($var)
-{
-    print "The variable is true";
-}
-else
-{
-    print "Try again";
-}
-            </programlisting>
-          </para>
-        </listitem>
-
-	<listitem>
-	  <para>
-	    Cookies
-	  </para>
-	  <para>
-	    Bugzilla uses cookies to ease the user experience, but no new patches
-	    should <emphasis>require</emphasis> user-side cookies.
-	  </para>
-	</listitem>
-
-        <listitem>
-          <para>
-            File Names
-          </para>
-          <para>
-            File names for bugzilla code and support documention should be legal across
-            multiple platforms. <computeroutput>\ / : * ? &quot; &lt; &gt;</computeroutput>
-            and <computeroutput>|</computeroutput> are all illegal characters for filenames
-            on various platforms.  Also, file names should not have spaces in them as they
-            can cause confusion in CVS and other mozilla.org utilities.
-          </para>
-        </listitem>
-
-	<listitem>
-	  <para>
-	    Javascript dependencies
-	  </para>
-	  <para>
-	    While Bugzilla uses Javascript to make the user experience easier, no patch
-	    to Bugzilla should <emphasis>require</emphasis> Javascript.
-	  </para>
-	</listitem>
-
-	<listitem>
-	  <para>
-	    Patch Format
-	  </para>
-	  <para>
-	    All patches submitted for inclusion into Bugzilla should be in the form of a
-	    <quote>unified diff</quote>.  This comes from using <quote>diff -u</quote>
-	    instead of simply <quote>diff</quote> when creating your patch.  This will
-	    result in quicker acceptance of the patch.
-	  </para>
-	</listitem>
-
-	<listitem>
-	  <para>
-	    Schema Changes
-	  </para>
-	  <para>
-	    If you make schema changes, you should modify <filename>sanitycheck.cgi</filename>
-	    to support the new schema.  All referential columns should be checked.
-	  </para>
-	</listitem>
-
-	<listitem>
-	  <para>
-	    Taint Mode
-	  </para>
-	  <para>
-	    All new cgis must run in Taint mode (Perl taint and DBI taint), and existing cgi's
-	    which run in taint mode must not have taint mode turned off.
-	  </para>
-	</listitem>
-
-	<listitem>
-	  <para>
-	    Templatization
-	  </para>
-	  <para>
-	    Patches to Bugzilla need to support templates so they do not force user interface choices
-	    on Bugzilla administrators.
-	  </para>
-	</listitem>
-
-        <listitem>
-          <para>
-            Variable Names
-          </para>
-          <para>
-            If a variable is scoped globally (<computeroutput>$::variable</computeroutput>)
-            its name should be descriptive of what it contains.  Local variables can be named
-            a bit looser, provided the context makes their content obvious.  For example,
-            <computeroutput>$ret</computeroutput> could be used as a staging variable for a
-             routine's return value as the line <computeroutput>return $ret;</computeroutput>
-             will make it blatantly obvious what the variable holds and most likely be shown
-             on the same screen as <computeroutput>my $ret = "";</computeroutput>.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Cross Database Compatability
-          </para>
-          <para>
-            Bugzilla was originally written to work with MySQL and therefore took advantage
-            of some of its features that aren't contained in other RDBMS software.  These
-            should be avoided in all new code.  Examples of these features are enums and
-            <function>encrypt()</function>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            Cross Platform Compatability
-          </para>
-          <para>
-            While Bugzilla was written to be used on Unix based systems (and Unix/Linux is
-            still the only officially supported platform) there are many who desire/need to
-            run Bugzilla on Microsoft Windows boxes.  Whenever possible, we should strive
-            not to make the lives of these people any more complicated and avoid doing things
-            that break Bugzilla's ability to run on multiple operating systems.
-          </para>
-        </listitem>
-      </itemizedlist>
-    </section>
-  </section>
 
-</appendix>
+    <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
 Local variables:
@@ -496,3 +303,4 @@ sgml-shorttag:t
 sgml-tag-region-if-active:t
 End:
 -->
+