Bug 400629: The "User Preferences" doc page has no information about saved searches - Patch by Sam Folk-Williams <sam.folkwilliams@gmail.com> r=LpSolit

1 files changed, 220 insertions, 66 deletions

diff --git a/docs/xml/using.xml b/docs/xml/using.xml
index 626a209a3..10c492ca6 100644
--- a/docs/xml/using.xml
+++ b/docs/xml/using.xml
@@ -1009,7 +1009,7 @@
 
     <para>Once you have logged in, you can customize various aspects of
     Bugzilla via the "Edit prefs" link in the page footer.
-    The preferences are split into three tabs:</para>
+    The preferences are split into five tabs:</para>
 
     <section id="accountpreferences" xreflabel="Account Preferences">
       <title>Account Preferences</title>
@@ -1017,9 +1017,7 @@
       <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
-      <emphasis>current</emphasis>
-      password into the
-      <quote>Password</quote>
+      <emphasis>current</emphasis> password into the <quote>Password</quote>
       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
@@ -1030,46 +1028,41 @@
       <title>General Preferences</title>
 
       <para>
-        This tab allows you to change several Bugzilla behavior.
+        This tab allows you to change several default settings of Bugzilla.
       </para>
 
       <itemizedlist spacing="compact">
         <listitem>
           <para>
             Field separator character for CSV files -
-            This controls separator character used in CSV formatted Bug List.
+            Select between a comma and semi-colon for exported CSV bug lists.
           </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.
+            After changing a bug - This controls what page is displayed after
+            changes to a bug are submitted. The options include to show the bug
+            just modified, to show the next bug in your list, or to do nothing.
           </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.
+            Add individual bugs to saved searches - enable or disable the ability
+            to add individual bugs to saved searches.
           </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>
+            controls the order of comments. Options include "Oldest
+            to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the
+            bug description at the top".
           </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.
+            Show a quip at the top of each bug list - controls
+            whether a quip will be shown on the Bug list page.
           </para>
         </listitem>
       </itemizedlist>
@@ -1079,31 +1072,8 @@
       <title>Email Preferences</title>
 
       <para>
-        This tab controls the amount of email Bugzilla sends you.
-      </para>
-
-      <para>
-        The first item on this page is marked <quote>Users to watch</quote>.
-        When you enter one or more comma-delineated user accounts (usually email
-        addresses) into the text entry box, you will receive a copy of all the
-        bugmail those users are sent (security settings permitting).
-        This powerful functionality enables seamless transitions as developers
-        change projects or users go on holiday.
-      </para>
-
-      <note>
-        <para>
-          The ability to watch other users may not be available in all
-          Bugzilla installations. If you don't see this feature, and feel
-          that you need it, speak to your administrator.
-        </para>
-      </note>
-
-      <para>
-        Each user listed in the <quote>Users watching you</quote> field
-        has you listed in their <quote>Users to watch</quote> list
-        and can get bugmail according to your relationship to the bug and
-        their <quote>Field/recipient specific options</quote> setting.
+        This tab allows you to enable or disable email notification on
+        specific events.
       </para>
 
       <para>
@@ -1116,15 +1086,24 @@
 
       <note>
         <para>
-          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 
+          A 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 user's individual mail preferences.
         </para>
       </note>
   
       <para>
+        There are two global options -- <quote>Email me when someone
+        asks me to set a flag</quote> and <quote>Email me when someone
+        sets a flag I asked for</quote>. These define how you want to
+        receive bugmail with regards to flags. Their use is quite
+        straightforward; enable the checkboxes if you want Bugzilla to
+        send you mail under either of the above conditions.
+      </para>
+
+      <para>
         If you'd like to set your bugmail to something besides
         'Completely ON' and 'Completely OFF', the
         <quote>Field/recipient specific options</quote> table
@@ -1174,7 +1153,6 @@
         </listitem>
       </itemizedlist>
 
-
       <note>
         <para>
           Some columns may not be visible for your installation, depending
@@ -1207,31 +1185,207 @@
       </note>
 
       <para>
-        Two items not in the table (<quote>Email me when someone
-        asks me to set a flag</quote> and <quote>Email me when someone
-        sets a flag I asked for</quote>) define how you want to
-        receive bugmail with regards to flags. Their use is quite
-        straightforward; enable the checkboxes if you want Bugzilla to
-        send you mail under either of the above conditions.
+        Bugzilla has a feature called <quote>Users Watching</quote>.
+        When you enter one or more comma-delineated user accounts (usually email
+        addresses) into the text entry box, you will receive a copy of all the
+        bugmail those users are sent (security settings permitting).
+        This powerful functionality enables seamless transitions as developers
+        change projects or users go on holiday.
       </para>
 
+      <note>
+        <para>
+          The ability to watch other users may not be available in all
+          Bugzilla installations. If you don't see this feature, and feel
+          that you need it, speak to your administrator.
+        </para>
+      </note>
+
       <para>
-        By default, Bugzilla sends out email regardless of who made the
-        change... even if you were the one responsible for generating
-        the email in the first place. If you don't care to receive bugmail
-        from your own changes, check the box marked <quote>Only email me
-        reports of changes made by other people</quote>.
+        Each user listed in the <quote>Users watching you</quote> field
+        has you listed in their <quote>Users to watch</quote> list
+        and can get bugmail according to your relationship to the bug and
+        their <quote>Field/recipient specific options</quote> setting.
       </para>
 
     </section>
 
+    <section id="savedsearches" xreflabel="Saved Searches">
+      <title>Saved Searches</title>
+      <para>
+      On this tab you can view and run any Saved Searches that you have
+      created.
+      Saved Searches can be added to the page footer from this screen.
+      </para>
+    </section>
+
     <section id="permissionsettings">
       <title>Permissions</title>
       
-      <para>This is a purely informative page which outlines your current
-      permissions on this installation of Bugzilla - what product groups you
-      are in, and whether you can edit bugs or perform various administration
-      functions.</para>
+      <para>
+      This is a purely informative page which outlines your current
+      permissions on this installation of Bugzilla.
+      </para>
+
+      <para>
+      A complete list of permissions is below. Only users with
+      <emphasis>editusers</emphasis> privileges can change the permissions
+      of other users.
+      </para>
+
+      <variablelist>
+        <varlistentry>
+          <term>
+            admin
+          </term>
+          <listitem>
+            <para>
+             Indicates user is an Administrator.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            bz_canusewhineatothers
+          </term>
+          <listitem>
+            <para>
+             Indicates user can configure whine reports for other users.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+             bz_canusewhines
+          </term>
+          <listitem>
+            <para>
+             Indicates user can configure whine reports for self.
+            </para>
+          </listitem>
+        </varlistentry>
+ 
+        <varlistentry>
+          <term>
+             bz_sudoers
+          </term>
+          <listitem>
+            <para>
+             Indicates user can perform actions as other users.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+             bz_sudo_protect
+          </term>
+          <listitem>
+            <para>
+             Indicates user can not be impersonated by other users.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+             canconfirm
+          </term>
+          <listitem>
+            <para>
+             Indicates user can confirm a bug or mark it a duplicate.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+             creategroups
+          </term>
+          <listitem>
+            <para>
+             Indicates user can create and destroy groups.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+             editbugs
+          </term>
+          <listitem>
+            <para>
+             Indicates user can edit all bug fields.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+             editclassifications
+          </term>
+          <listitem>
+            <para>
+             Indicates user can create, destroy, and edit classifications.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+             editcomponents
+          </term>
+          <listitem>
+            <para>
+             Indicates user can create, destroy, and edit components.
+            </para>
+          </listitem>
+        </varlistentry>
+ 
+        <varlistentry>
+          <term>
+             editkeywords
+          </term>
+          <listitem>
+            <para>
+             Indicates user can create, destroy, and edit keywords.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+             editusers
+          </term>
+          <listitem>
+            <para>
+             Indicates user can edit or disable users.
+            </para>
+          </listitem>
+        </varlistentry>
+	
+        <varlistentry>
+          <term>
+             tweakparams
+          </term>
+          <listitem>
+            <para>
+             Indicates user can change Parameters.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+       <note>
+        <para>
+        For more information on how permissions work in Bugzilla (i.e. who can
+        change what), see  <xref linkend="cust-change-permissions"/>.
+        </para>
+       </note>
+
     </section>
   </section>