Documentation patch for bug 245075: Document command-line script to send unsent…

docs/xml/patches.xml

@@ -2,53 +2,106 @@
 <appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
   <title>Contrib</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>
+    There are a number of unofficial Bugzilla add-ons in the 
+    <filename class="directory">$BUGZILLA_ROOT/contrib/</filename>
+    directory. This section documents them.
+  </para>
 
   <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>
+      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.
+      There are three files - <filename>query.conf</filename>,
+     <filename>buglist</filename> and <filename>bugs</filename>.
+    </para>
+
+    <warning>
+      These files pre-date the templatisation work done as part of the
+      2.16 release, and have not been updated. 
+    </warning>
     
-    <para><filename>query.conf</filename> 
-    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><filename>buglist</filename>
-    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.
-    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>
-
-    <para><filename>bugs</filename> is a simple shell script which calls
-    <filename>buglist</filename> 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>
+      <filename>query.conf</filename> contains the mapping from
+      options to field names and comparison types. Quoted option names
+      are <quote>grepped</quote> 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 <quote>option</quote>.
+    </para>
+
+    <para>
+      <filename>buglist</filename> is a shell script that submits a
+      Bugzilla query and writes the resulting HTML page to stdout.
+      It supports both short options, (such as <quote>-Afoo</quote>
+      or <quote>-Rbar</quote>) and long options (such
+      as <quote>--assignedto=foo</quote> or <quote>--reporter=bar</quote>).
+      If the first character of an option is not <quote>-</quote>, it is
+      treated as if it were prefixed with <quote>--default=</quote>.
+    </para>
+
+    <para>
+      The column list is taken from the COLUMNLIST environment variable.
+      This is equivalent to the <quote>Change Columns</quote> option
+      that is available 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>
+
+    <para>
+      <filename>bugs</filename> is a simple shell script which calls
+      <filename>buglist</filename> and extracts the
+      bug numbers from the output. Adding the prefix
+      <quote>http://bugzilla.mozilla.org/buglist.cgi?bug_id=</quote>
+      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 Peck says she has good results piping 
+      <filename>buglist</filename> output through 
+      <command>w3m -T text/html -dump</command>
     </para>
 
-    <para>Akkana Peck says she has good results piping 
-    <filename>buglist</filename> output through 
-    <command>w3m -T text/html -dump</command>
+  </section>
+
+  <section id="cmdline-bugmail">
+    <title>Command-line 'Send Unsent Bug-mail' tool</title>
+
+    <para>
+      Within the <filename class="directory">contrib</filename> directory
+      exists a utility with the descriptive (if compact) name
+      of <filename>sendunsentbugmail.pl</filename>. The purpose of this
+      script is, simply, to send out any bug-related mail that should
+      have been sent by now, but for one reason or another has not.
     </para>
 
+    <para>
+      To accomplish this task, <filename>sendunsentbugmail.pl</filename> uses
+      the same mechanism as the <filename>sanitycheck.cgi<filename> script; it
+      it scans through the entire database looking for bugs with changes that
+      were made more than 30 minutes ago, but where there is no record of
+      anyone related to that bug having been sent mail. Having compiled a list,
+      it then uses the standard rules to determine who gets mail, and sends it
+      out.
+    </para>
+
+    <para>
+      As the script runs, it indicates the bug for which it is currently
+      sending mail; when it has finished, it gives a numerical count of how
+      many mails were sent and how many people were excluded. (Individual
+      user names are not recorded or displayed.) If the script produces
+      no output, that means no unsent mail was detected.
+    </para>
+
+    <para>
+      USAGE: move the sendunsentbugmail.pl script up into the main directory,
+      ensure it has execute permission, and run it from the command line (or
+      from a cron job) with no parameters.
+    </para>
   </section>
 
 </appendix>