Bug 232378: switch from entities to XIncludes for inclusion of modular docs files

Patch by Colin Ogilvie <colin.ogilvie@gmail.com>; r=vladd

1 files changed, 95 insertions, 264 deletions

diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml
index 540109feb..f3e17290c 100644
--- a/docs/en/xml/patches.xml
+++ b/docs/en/xml/patches.xml
@@ -1,286 +1,117 @@
-<!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>
-
-  <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>
+<?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;
+]>
 
-        <para>
-          <computeroutput>
-            <prompt>bash#</prompt>
-
-            <command>./setperl.csh /your/path/to/perl</command>
-          </computeroutput>
-
-          <example>
-            <title>Using Setperl to set your perl path</title>
+<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
+  <title>Contrib</title>
 
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
-
-                <command>./setperl.csh /usr/bin/perl</command>
-              </computeroutput>
-            </para>
-          </example>
-        </para>
-      </step>
-    </procedure>
-  </section>
+  <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 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>
+    <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.
+      There are three files - <filename>query.conf</filename>,
+      <filename>buglist</filename> and <filename>bugs</filename>.
     </para>
 
-    <para>Akkana says she has good results piping buglist output through 
-    <command>w3m -T text/html -dump</command>
+    <warning>
+      <para>
+        These files pre-date the templatisation work done as part of the
+        2.16 release, and have not been updated.
+      </para>
+    </warning>
+    
+    <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>
 
-    <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>
+    <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>
 
-          <step>
-            <para>
-              <computeroutput>
-                <prompt>bash#</prompt>
+    <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>
 
-                <command>wget -O bugs
-                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26215'</command>
-              </computeroutput>
-            </para>
-          </step>
-        </substeps>
-      </step>
+    <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>
 
-      <step>
-        <para>Make your utilities executable: 
-        <computeroutput>
-          <prompt>bash$</prompt>
+    <para>
+      Akkana Peck says she has good results piping 
+      <filename>buglist</filename> output through 
+      <command>w3m -T text/html -dump</command>
+    </para>
 
-          <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>
+  <section id="cmdline-bugmail">
+    <title>Command-line 'Send Unsent Bug-mail' tool</title>
 
-    <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>
+    <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>
 
-      <member>search 'foo,!foo' (equivalent to 'foo OR keyword:foo')</member>
-    </simplelist>
+    <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>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>
+    <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>
 
-    has details.</para>
+    <para>
+      <emphasis>Usage</emphasis>: 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>
 
 <!-- Keep this comment at the end of the file
@@ -298,7 +129,7 @@ sgml-local-ecat-files:nil
 sgml-minimize-attributes:nil
 sgml-namecase-general:t
 sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End: