Bug 274173 : The Params that are listed in section 3.1 (parameters) should use a <varlist/>

Patch by Shane H. W. Travis <travis@sedsystems.ca>  r=colin.ogilvie

1 files changed, 252 insertions, 211 deletions

diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index 67f818e1f..3b84f40c8 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -16,244 +16,285 @@
       <primary>checklist</primary>
     </indexterm>
 
-    <procedure>
-      <step>
-        <para> 
-          <command>maintainer</command>:
-
-          The maintainer parameter is the email address of the person 
-          responsible for maintaining this Bugzilla installation.
-          The address need not be that of a valid Bugzilla account.
-        </para>
-      </step>
-
-      <step>
-        <para>
-          <command>urlbase</command>:
-
-          This parameter defines the fully qualified domain name and web 
-          server path to your Bugzilla installation.
-        </para>
+    <variablelist>
+      <varlistentry>
+        <term>
+          maintainer
+        </term>
+        <listitem>
+          <para> 
+            The maintainer parameter is the email address of the person 
+            responsible for maintaining this Bugzilla installation.
+            The address need not be that of a valid Bugzilla account.
+          </para>
+        </listitem>
+      </varlistentry>
 
-        <para>
-          For example, if your Bugzilla query page is
-          <filename>http://www.foo.com/bugzilla/query.cgi</filename>, 
-          set your <quote>urlbase</quote>
-          to <filename>http://www.foo.com/bugzilla/</filename>.
-        </para>
-      </step>
+      <varlistentry>
+        <term>
+          urlbase
+        </term>
+        <listitem>
+          <para>
+            This parameter defines the fully qualified domain name and web 
+            server path to your Bugzilla installation.
+          </para>
 
-      <step>
-        <para>
-          <command>makeproductgroups</command>:
+          <para>
+            For example, if your Bugzilla query page is
+            <filename>http://www.foo.com/bugzilla/query.cgi</filename>, 
+            set your <quote>urlbase</quote>
+            to <filename>http://www.foo.com/bugzilla/</filename>.
+          </para>
+        </listitem>
+      </varlistentry>
 
-          This dictates whether or not to automatically create groups
-          when new products are created.
-        </para>
-      </step>
+      <varlistentry>
+        <term>
+          makeproductgroups
+        </term>
+        <listitem>
+          <para>
+            This dictates whether or not to automatically create groups
+            when new products are created.
+          </para>
+        </listitem>
+      </varlistentry>
 
-      <step>
-        <para>
-          <command>useentrygroupdefault</command>:
-
-          Bugzilla products can have a group associated with them, so that
-          certain users can only see bugs in certain products. When this 
-          parameter is set to <quote>on</quote>, this 
-          causes the initial group controls on newly created products 
-          to place all newly-created bugs in the group 
-          having the same name as the product immediately.
-          After a product is initially created, the group controls
-          can be further adjusted without interference by 
-          this mechanism.
-        </para>
-      </step>
+      <varlistentry>
+        <term>
+          useentrygroupdefault
+        </term>
+        <listitem>
+          <para>
+            Bugzilla products can have a group associated with them, so that
+            certain users can only see bugs in certain products. When this 
+            parameter is set to <quote>on</quote>, this 
+            causes the initial group controls on newly created products 
+            to place all newly-created bugs in the group 
+            having the same name as the product immediately.
+            After a product is initially created, the group controls
+            can be further adjusted without interference by 
+            this mechanism.
+          </para>
+        </listitem>
+      </varlistentry>
 
-      <step>
-        <para>
-          <command>shadowdb</command>:
-
-          You run into an interesting problem when Bugzilla reaches a
-          high level of continuous activity. MySQL supports only table-level
-          write locking. What this means is that if someone needs to make a
-          change to a bug, they will lock the entire table until the operation
-          is complete. Locking for write also blocks reads until the write is
-          complete. Note that more recent versions of mysql support row level
-          locking using different table types. These types are slower than the
-          standard type, and Bugzilla does not yet take advantage of features
-          such as transactions which would justify this speed decrease. The
-          Bugzilla team are, however, happy to hear about any experiences with
-          row level locking and Bugzilla.
-        </para>
+      <varlistentry>
+        <term>
+          shadowdb
+        </term>
+        <listitem>
+          <para>
+            You run into an interesting problem when Bugzilla reaches a
+            high level of continuous activity. MySQL supports only table-level
+            write locking. What this means is that if someone needs to make a
+            change to a bug, they will lock the entire table until the operation
+            is complete. Locking for write also blocks reads until the write is
+            complete. Note that more recent versions of mysql support row level
+            locking using different table types. These types are slower than the
+            standard type, and Bugzilla does not yet take advantage of features
+            such as transactions which would justify this speed decrease. The
+            Bugzilla team are, however, happy to hear about any experiences with
+            row level locking and Bugzilla.
+          </para>
 
-        <para>
-          The <quote>shadowdb</quote> parameter was designed to get around
-          this limitation. While only a single user is allowed to write to
-          a table at a time, reads can continue unimpeded on a read-only
-          shadow copy of the database. Although your database size will
-          double, a shadow database can cause an enormous performance
-          improvement when implemented on extremely high-traffic Bugzilla
-          databases.
-        </para>
+          <para>
+            The <quote>shadowdb</quote> parameter was designed to get around
+            this limitation. While only a single user is allowed to write to
+            a table at a time, reads can continue unimpeded on a read-only
+            shadow copy of the database. Although your database size will
+            double, a shadow database can cause an enormous performance
+            improvement when implemented on extremely high-traffic Bugzilla
+            databases.
+          </para>
         
-        <para>
-          As a guide, on reasonably old hardware, mozilla.org began needing 
-          <quote>shadowdb</quote> when they reached around 40,000 Bugzilla
-          users with several hundred Bugzilla bug changes and comments per day.
-        </para>
-
-        <para>
-          The value of the parameter defines the name of the shadow bug
-          database. You will need to set the host and port settings from
-          the params page, and set up replication in your database server
-          so that updates reach this readonly mirror. Consult your database
-          documentation for more detail.
-        </para>
-      </step>
-
-      <step>
-        <para>
-          <command>shutdownhtml</command>:
-
-          If you need to shut down Bugzilla to perform administration, enter
-          some descriptive text (with embedded HTML codes, if you'd like)
-          into this box. Anyone who tries to use Bugzilla (including admins)
-          will receive a page displaying this text. Users can neither log in
-          nor log out while shutdownhtml is enabled.
-        </para>
-
-        <note>
           <para>
-            Although regular log-in capability is disabled while 'shutdownhtml'
-            is enabled, safeguards are in place to protect the unfortunate 
-            admin who loses connection to Bugzilla. Should this happen to you,
-            go directly to the <filename>editparams.cgi</filename> (by typing
-            the URL in manually, if necessary). Doing this will prompt you to
-            log in, and your name/password will be accepted here (but nowhere
-            else). 
+            As a guide, on reasonably old hardware, mozilla.org began needing 
+            <quote>shadowdb</quote> when they reached around 40,000 Bugzilla
+            users with several hundred Bugzilla bug changes and comments per day.
           </para>
-        </note>
-      </step>
-
-      <step>
-        <para>
-          <command>passwordmail</command>:
-
-          Every time a user creates an account, the text of this parameter
-          (with substitutions) is sent to the new user along with their
-          password message.
-        </para>
 
-        <para>
-          Add any text you wish to the "passwordmail" parameter box. For
-          instance, many people choose to use this box to give a quick 
-          training blurb about how to use Bugzilla at your site.
-        </para>
-      </step>
-
-
-      <step>
-        <para>
-          <command>movebugs</command>:
-
-          This option is an undocumented feature to allow moving bugs
-          between separate Bugzilla installations.  You will need to understand
-          the source code in order to use this feature.  Please consult
-          <filename>movebugs.pl</filename> in your Bugzilla source tree for
-          further documentation, such as it is.
-        </para>
-      </step>
+          <para>
+            The value of the parameter defines the name of the shadow bug
+            database. You will need to set the host and port settings from
+            the params page, and set up replication in your database server
+            so that updates reach this readonly mirror. Consult your database
+            documentation for more detail.
+          </para>
+        </listitem>
+      </varlistentry>
 
-      <step>
-        <para>
-          <command>useqacontact</command>:
+      <varlistentry>
+        <term>
+          shutdownhtml
+        </term>
+        <listitem>
+          <para>
+            If you need to shut down Bugzilla to perform administration, enter
+            some descriptive text (with embedded HTML codes, if you'd like)
+            into this box. Anyone who tries to use Bugzilla (including admins)
+            will receive a page displaying this text. Users can neither log in
+            nor log out while shutdownhtml is enabled.
+          </para>
 
-          This allows you to define an email address for each component, 
-          in addition to that of the default owner, who will be sent
-          carbon copies of incoming bugs.
-        </para>
-      </step>
+          <note>
+            <para>
+              Although regular log-in capability is disabled while 'shutdownhtml'
+              is enabled, safeguards are in place to protect the unfortunate 
+              admin who loses connection to Bugzilla. Should this happen to you,
+              go directly to the <filename>editparams.cgi</filename> (by typing
+              the URL in manually, if necessary). Doing this will prompt you to
+              log in, and your name/password will be accepted here (but nowhere
+              else). 
+            </para>
+          </note>
+        </listitem>
+      </varlistentry>
 
-      <step>
-        <para>
-          <command>usestatuswhiteboard</command>:
+      <varlistentry>
+        <term>
+          passwordmail
+        </term>
+        <listitem>
+          <para>
+            Every time a user creates an account, the text of this parameter
+            (with substitutions) is sent to the new user along with their
+            password message.
+          </para>
 
-          This defines whether you wish to have a free-form, overwritable field
-          associated with each bug. The advantage of the Status Whiteboard is
-          that it can be deleted or modified with ease, and provides an
-          easily-searchable field for indexing some bugs that have some trait
-          in common.         
-        </para>
-      </step>
+          <para>
+            Add any text you wish to the "passwordmail" parameter box. For
+            instance, many people choose to use this box to give a quick 
+            training blurb about how to use Bugzilla at your site.
+          </para>
+        </listitem>
+      </varlistentry>
 
-      <step>
-        <para>
-          <command>whinedays</command>:
+      <varlistentry>
+        <term>
+          movebugs
+        </term>
+        <listitem>
+          <para>
+            This option is an undocumented feature to allow moving bugs
+            between separate Bugzilla installations.  You will need to understand
+            the source code in order to use this feature.  Please consult
+            <filename>movebugs.pl</filename> in your Bugzilla source tree for
+            further documentation, such as it is.
+          </para>
+        </listitem>
+      </varlistentry>
 
-          Set this to the number of days you want to let bugs go
-          in the NEW or REOPENED state before notifying people they have
-          untouched new bugs. If you do not plan to use this feature, simply 
-          do not set up the whining cron job described in the installation
-          instructions, or set this value to "0" (never whine).
-        </para>
-      </step>
+      <varlistentry>
+        <term>
+          useqacontact
+        </term>
+        <listitem>
+          <para>
+            This allows you to define an email address for each component, 
+            in addition to that of the default owner, who will be sent
+            carbon copies of incoming bugs.
+          </para>
+        </listitem>
+      </varlistentry>
 
-      <step>
-        <para>
-          <command>commenton*</command>:
-
-          All these fields allow you to dictate what changes can pass
-          without comment, and which must have a comment from the
-          person who changed them.  Often, administrators will allow
-          users to add themselves to the CC list, accept bugs, or
-          change the Status Whiteboard without adding a comment as to
-          their reasons for the change, yet require that most other
-          changes come with an explanation.
-        </para>
+      <varlistentry>
+        <term>
+          usestatuswhiteboard
+        </term>
+        <listitem>
+          <para>
+            This defines whether you wish to have a free-form, overwritable field
+            associated with each bug. The advantage of the Status Whiteboard is
+            that it can be deleted or modified with ease, and provides an
+            easily-searchable field for indexing some bugs that have some trait
+            in common.         
+          </para>
+        </listitem>
+      </varlistentry>
 
-        <para>
-          Set the "commenton" options according to your site policy. It
-          is a wise idea to require comments when users resolve, reassign, or
-          reopen bugs at the very least. 
-        </para>
+      <varlistentry>
+        <term>
+          whinedays
+        </term>
+        <listitem>
+          <para>
+            Set this to the number of days you want to let bugs go
+            in the NEW or REOPENED state before notifying people they have
+            untouched new bugs. If you do not plan to use this feature, simply 
+            do not set up the whining cron job described in the installation
+            instructions, or set this value to "0" (never whine).
+          </para>
+        </listitem>
+      </varlistentry>
 
-        <note>
+      <varlistentry>
+        <term>
+          commenton*
+        </term>
+        <listitem>
           <para>
-            It is generally far better to require a developer comment
-            when resolving bugs than not. Few things are more annoying to bug
-            database users than having a developer mark a bug "fixed" without
-            any comment as to what the fix was (or even that it was truly
-            fixed!)
+            All these fields allow you to dictate what changes can pass
+            without comment, and which must have a comment from the
+            person who changed them.  Often, administrators will allow
+            users to add themselves to the CC list, accept bugs, or
+            change the Status Whiteboard without adding a comment as to
+            their reasons for the change, yet require that most other
+            changes come with an explanation.
           </para>
-        </note>
-      </step>
 
-      <step>
-        <para>
-          <command>supportwatchers</command>:
+          <para>
+            Set the "commenton" options according to your site policy. It
+            is a wise idea to require comments when users resolve, reassign, or
+            reopen bugs at the very least. 
+          </para>
 
-          Turning on this option allows users to ask to receive copies 
-          of bug mail sent to another user.  Watching a user with
-          different group permissions is not a way to 'get around' the
-          system; copied emails are still subject to the normal groupset
-          permissions of a bug, and <quote>watchers</quote> will only be 
-          copied on emails from bugs they would normally be allowed to view. 
-        </para> 
-      </step>
+          <note>
+            <para>
+              It is generally far better to require a developer comment
+              when resolving bugs than not. Few things are more annoying to bug
+              database users than having a developer mark a bug "fixed" without
+              any comment as to what the fix was (or even that it was truly
+              fixed!)
+            </para>
+          </note>
+        </listitem>
+      </varlistentry>
 
+      <varlistentry>
+        <term>
+          supportwatchers
+        </term>
+        <listitem>
+          <para>
+            Turning on this option allows users to ask to receive copies 
+            of bug mail sent to another user.  Watching a user with
+            different group permissions is not a way to 'get around' the
+            system; copied emails are still subject to the normal groupset
+            permissions of a bug, and <quote>watchers</quote> will only be 
+            copied on emails from bugs they would normally be allowed to view. 
+          </para> 
+        </listitem>
+      </varlistentry>
 
-      <step>
-        <para>
-          <command>noresolveonopenblockers</command>:
 
-          This option will prevent users from resolving bugs as FIXED if
-          they have unresolved dependencies. Only the FIXED resolution
-          is affected. Users will be still able to resolve bugs to
-          resolutions other than FIXED if they have unresolved dependent
-          bugs.
-        </para>
-      </step>
+      <varlistentry>
+        <term>
+          noresolveonopenblockers
+        </term>
+        <listitem>
+          <para>
+            This option will prevent users from resolving bugs as FIXED if
+            they have unresolved dependencies. Only the FIXED resolution
+            is affected. Users will be still able to resolve bugs to
+            resolutions other than FIXED if they have unresolved dependent
+            bugs.
+          </para>
+        </listitem>
+      </varlistentry>
 
-    </procedure>
+    </variablelist>
   </section>
 
   <section id="useradmin">