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, 302 insertions, 17 deletions

diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml
index 4e63bac86..8f50cfa44 100644
--- a/docs/en/xml/using.xml
+++ b/docs/en/xml/using.xml
@@ -1,4 +1,9 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<?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;
+]>
 
 <chapter id="using">
   <title>Using Bugzilla</title>
@@ -234,8 +239,12 @@
       <listitem>
         <para>
         <emphasis>Attachments:</emphasis>
-        You can attach files (e.g. testcases or patches) to bugs. If there
-        are any attachments, they are listed in this section.</para>
+          You can attach files (e.g. testcases or patches) to bugs. If there
+          are any attachments, they are listed in this section.  Attachments are
+          normally stored in the Bugzilla database, unless they are marked as
+          Big Files, which are stored directly on disk and (unlike attachments
+          kept in the database) may be deleted at some future time.
+        </para>
       </listitem>
 
       <listitem>
@@ -286,7 +295,7 @@
   <section id="query">
     <title>Searching for Bugs</title>
 
-    <para>The Bugzilla Search page is is the interface where you can find
+    <para>The Bugzilla Search page is the interface where you can find
     any bug report, comment, or patch currently in the Bugzilla system. You
     can play with it here: 
     <ulink url="&landfillbase;query.cgi"/>.</para>
@@ -721,11 +730,12 @@
       summary and status whiteboard of a bug; adding 
       "<filename>:BazProduct</filename>" would
       search only in that product.
+      You can use it to find a bug by its number or its alias, too.
       </para>
 
-      <para>You'll find the Quicksearch box on Bugzilla's
-      front page, along with a 
-      <ulink url="../../quicksearch.html">Help</ulink> 
+      <para>You'll find the Quicksearch box in Bugzilla's footer area.
+      On Bugzilla's front page, there is an additional
+      <ulink url="../../page.cgi?id=quicksearch.html">Help</ulink>
       link which details how to use it.</para>
     </section>
     
@@ -774,34 +784,93 @@
       Content-Type (e.g. application/xhtml+xml), you can override this 
       using a 'content-type' parameter on the URL, e.g.
       <filename>&amp;content-type=text/plain</filename>.
-      </para>     
+      </para> 
+
+      <para>
+        If you have a really large attachment, something that does not need to
+        be recorded forever (as most attachments are), you can mark your
+        attachment as a Big File, Assuming the administrator of the
+        installation has enabled this feature.  Big Files are stored directly on
+        disk instead of in the database, and can be deleted when it is no longer
+        needed.  The maximum size of a Big File is normally larger than the
+        maximum size of a regular attachment.
+      </para>
     </section>
   </section>
   
   <section id="userpreferences">
     <title>User Preferences</title>
 
-    <para>Once you have logged in, you can customise various aspects of 
+    <para>Once you have logged in, you can customise various aspects of
     Bugzilla via the "Edit prefs" link in the page footer.
     The preferences are split into three tabs:</para>
 
-    <section id="accountsettings" xreflabel="Account Settings">
-      <title>Account Settings</title>
+    <section id="accountpreferences" xreflabel="Account Preferences">
+      <title>Account Preferences</title>
 
       <para>On this tab, you can change your basic account information,
       including your password, email address and real name. For security
-      reasons, in order to change anything on this page you must type your 
+      reasons, in order to change anything on this page you must type your
       <emphasis>current</emphasis>
-      password into the 
+      password into the
       <quote>Password</quote>
-      field at the top of the page. 
+      field at the top of the page.
       If you attempt to change your email address, a confirmation
       email is sent to both the old and new addresses, with a link to use to
       confirm the change. This helps to prevent account hijacking.</para>
     </section>
 
-    <section id="emailsettings">
-      <title>Email Settings</title>
+    <section id="generalpreferences" xreflabel="General Preferences">
+      <title>General Preferences</title>
+
+      <para>
+        This tab allows you to change several Bugzilla behavior.
+      </para>
+
+      <itemizedlist spacing="compact">
+        <listitem>
+          <para>
+            Field separator character for CSV files -
+            This controls separator character used in CSV formatted Bug List.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            After changing bugs - This controls which bugs or no bugs
+            are shown in the page after you changed bugs.
+            You can select the bug you've changed this time, or the next
+            bug of the list.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Add individual bugs to saved searches - this controls
+            whether you can add individual bugs to saved searches
+            or you can't.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            When viewing a bug, show comments in this order -
+            This controls the order of comments, you can select below:
+            <simplelist>
+              <member>Initial description, comment 1, comment 2, ...</member>
+              <member>Initial description, last comment, ..., comment 2, comment 1.</member>
+              <member>Initial last comment, ..., comment 2, comment 1, description.</member>
+            </simplelist>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Show a quip at the top of each bug list - This controls
+            whether a quip will be shown on the Bug list page or not.
+          </para>
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section id="emailpreferences">
+      <title>Email Preferences</title>
 
       <para>
         This tab controls the amount of email Bugzilla sends you.
@@ -837,7 +906,7 @@
           Your Bugzilla administrator can stop a user from receiving
           bugmail by adding the user's name to the 
           <filename>data/nomail</filename> file. This is a drastic step
-          best taken only for disabled accounts, as it overrides the 
+          best taken only for disabled accounts, as it overrides 
           the user's individual mail preferences.
         </para>
       </note>
@@ -1158,6 +1227,222 @@
       appended to the flag name within parentheses.  For example, if Jack
       asks Jill for review, it appears as Jack: review [ ? ] (Jill).
     </para>
+
+    <para>
+      You can browse through open requests made of you and by you by selecting
+      'My Requests' from the footer. You can also look at open requests limited
+      by other requesters, requestees, products, components, and flag names from
+      this page. Note that you can use '-' for requestee to specify flags with
+      'no requestee' set.
+    </para>
+  </section>
+
+  <section id="whining">
+    <title>Whining</title>
+
+    <para>
+      Whining is a feature in Bugzilla that can regularly annoy users at 
+      specified times.  Using this feature, users can execute saved searches 
+      at specific times (i.e. the 15th of the month at midnight) or at 
+      regular intervals (i.e. every 15 minutes on Sundays).  The results of the
+      searches are sent to the user, either as a single email or as one email 
+      per bug, along with some descriptive text.
+    </para>
+
+    <warning>
+      <para>
+        Throughout this section it will be assumed that all users are members 
+        of the bz_canusewhines group, membership in which is required in order 
+        to use the Whining system.  You can easily make all users members of 
+        the bz_canusewhines group by setting the User RegExp to ".*" (without 
+        the quotes).
+      </para>
+
+      <para>
+        Also worth noting is the bz_canusewhineatothers group.  Members of this
+        group can create whines for any user or group in Bugzilla using a 
+        extended form of the whining interface.  Features only available to 
+        members of the bz_canusewhineatothers group will be noted in the 
+        appropriate places.
+      </para>
+    </warning>
+
+    <note>
+      <para>
+        For whining to work, a special Perl script must be executed at regular
+        intervals.  More information on this is available in 
+        <xref linkend="installation-whining"/>.
+      </para>
+    </note>
+
+    <note>
+      <para>
+        This section does not cover the whineatnews.pl script.  See
+        <xref linkend="installation-whining-cron"/> for more information on 
+        The Whining Cron.
+      </para>
+    </note>
+
+    <section id="whining-overview">
+      <title>The Event</title>
+
+      <para>
+        The whining system defines an "Event" as one or more queries being 
+        executed at regular intervals, with the results of said queries (if
+        there are any) being emailed to the user.  Events are created by 
+        clicking on the "Add new event" button.
+      </para>
+
+      <para>
+        Once a new event is created, the first thing to set is the "Email 
+        subject line".  The contents of this field will be used in the subject
+        line of every email generated by this event.  In addition to setting a 
+        subject, space is provided to enter some descriptive text that will be 
+        included at the top of each message (to help you in understanding why 
+        you received the email in the first place).
+      </para>
+
+      <para>
+        The next step is to specify when the Event is to be run (the Schedule) 
+        and what searches are to be performed (the Queries).
+      </para>
+
+    </section>
+
+    <section id="whining-schedule">
+      <title>Whining Schedule</title>
+
+      <para>
+         Each whining event is associated with zero or more schedules.  A 
+         schedule is used to specify when the query (specified below) is to be
+         run.  A new event starts out with no schedules (which means it will 
+         never run, as it is not scheduled to run).  To add a schedule, press
+         the "Add a new schedule" button.
+      </para>
+
+      <para>
+         Each schedule includes an interval, which you use to tell Bugzilla 
+         when the event should be run.  An event can be run on certain days of
+         the week, certain days of the month, during weekdays (defined as 
+         Monday through Friday), or every day.
+      </para>
+
+      <warning>
+        <para>
+          Be careful if you set your event to run on the 29th, 30th, or 31st of
+          the month, as your event may not run exactly when expected.  If you 
+          want your event to run on the last day of the month, select "Last day
+          of the month" as the interval.
+        </para>
+      </warning>
+
+      <para>
+        Once you have specified the day(s) on which the event is to be run, you
+        should now specify the time at which the event is to be run.  You can 
+        have the event run at a certain hour on the specified day(s), or 
+        every hour, half-hour, or quarter-hour on the specified day(s).
+      </para>
+
+      <para>
+        If a single schedule does not execute an event as many times as you 
+        would want, you can create another schedule for the same event.  For 
+        example, if you want to run an event on days whose numbers are
+        divisible by seven, you would need to add four schedules to the event,
+        setting the schedules to run on the 7th, 14th, 21st, and 28th (one day 
+        per schedule) at whatever time (or times) you choose.
+      </para>
+
+      <note>
+        <para>
+          If you are a member of the bz_canusewhineatothers group, then you
+          will be presented with another option: "Mail to".  Using this you 
+          can control who will receive the emails generated by this event.  You
+          can choose to send the emails to a single user (identified by email 
+          address) or a single group (identified by group name).  To send to 
+          multiple users or groups, create a new schedule for each additional 
+          user/group.
+        </para>
+      </note>
+    </section>
+
+    <section id="whining-query">
+      <title>Whining Queries</title>
+
+      <para>
+        Each whining event is associated with zero or more queries.  A query is
+        a saved search that is executed on the schedule specified (see above).
+        You start out with zero queries attached to the event (which means that
+        the event will not run, as there will never be any results to return).
+        To add a query, press the "Add a new query" button.
+      </para>
+
+      <para>
+        The first field to examine in your new query is the Sort field.  Queries
+        are executed, and results returned, in the order specified by the Sort 
+        field.  Queries with lower Sort values will run before queries with 
+        higher Sort values.
+      </para>
+
+      <para>
+        The next field to examine is the Search field.  This is where you 
+        choose the actual search that is to be run.  Instead of defining search
+        parameters here, you are asked to choose from the list of saved 
+        searches (the same list that appears at the bottom of every Bugzilla 
+        page).  You are only allowed to choose from searches that you have 
+        saved yourself (the default saved search, "My Bugs", is not a valid 
+        choice).  If you do not have any saved searches, you can take this 
+        opportunity to create one (see <xref linkend="list"/>).
+      </para>
+
+      <note>
+        <para>
+          When running queries, the whining system acts as if you are the user
+          executing the query.  This means that the whining system will ignore
+          bugs that match your query, but that you can not access.
+        </para>
+      </note>
+
+      <para>
+        Once you have chosen the saved search to be executed, give the query a 
+        descriptive title.  This title will appear in the email, above the 
+        results of the query.  If you choose "One message per bug", the query 
+        title will appear at the top of each email that contains a bug matching
+        your query.
+      </para>
+
+      <para>
+        Finally, decide if the results of the query should be sent in a single
+        email, or if each bug should appear in its own email.
+      </para>
+
+      <warning>
+        <para>
+          Think carefully before checking the "One message per bug" box.  If
+          you create a query that matches thousands of bugs, you will receive 
+          thousands of emails!
+        </para>
+      </warning>
+    </section>
+
+    <section>
+      <title>Saving Your Changes</title>
+
+      <para>
+        Once you have defined at least one schedule, and created at least one 
+        query, go ahead and "Update/Commit".  This will save your Event and make
+        it available for immediate execution.
+      </para>
+
+      <note>
+        <para>
+          If you ever feel like deleting your event, you may do so using the 
+          "Remove Event" button in the upper-right corner of each Event.  You 
+          can also modify an existing event, so long as you "Update/Commit" 
+          after completing your modifications.
+        </para>
+      </note>
+    </section>
+
   </section>
 
 </chapter>