Fixed another bundle of 2.16 documentation bugs.

8 files changed, 254 insertions, 160 deletions

diff --git a/docs/sgml/administration.sgml b/docs/sgml/administration.sgml
index 8c85bd05f..66489469d 100644
--- a/docs/sgml/administration.sgml
+++ b/docs/sgml/administration.sgml
@@ -928,7 +928,8 @@
         each installed localisation. The default English templates are
         therefore in <filename>en</filename>. Underneath that, there
         are two directories - <filename>default</filename> and 
-        <filename>custom</filename>. The <filename>default</filename>
+        <filename>custom</filename> (you may have to create
+        <filename>custom</filename> yourself.) The <filename>default</filename>
         directory contains all the templates shipped with Bugzilla.
       </para>
 
@@ -948,15 +949,34 @@
         the contents of this directory will not be touched during an upgrade,
         and you can then decide whether to continue using your own templates,
         or make the effort to merge your changes into the new versions by
-        hand.
+        hand. This is also the correct method to use if you upgrade Bugzilla
+        by untarring tarballs over the top, rather than using CVS. It's perfectly
+        acceptable to mix and match these two methods.
       </para>
 
       <para>
+        Editing templates is a good way of doing a "poor man's custom fields".
+        For example, if you don't use the Status Whiteboard, but want to have
+        a free-form text entry box for "Build Identifier", then you can just
+        edit the templates to change the field labels. It's still be called
+        status_whiteboard internally, but your users don't need to know that.
+      </para>
+      
+      <para>
+        If you are making changes to contribute back to Bugzilla (and we'd
+        love to have them), then please read the 
+        <ulink url="http://www.bugzilla.org/developerguide.html">Developers 
+        Guide</ulink> first.
+      </para>
+      
+     <para>
         The syntax of the Template Toolkit language is beyond the scope of
         this guide. It's reasonably easy to pick up by looking at the current 
         templates; or, you can read the manual, available on the
         <ulink url="http://www.template-toolkit.org">Template Toolkit home
-        page</ulink>.
+        page</ulink>. However, you should particularly remember (for security
+        reasons) to always HTML filter things which come from the database or
+        user input, to prevent cross-site scripting attacks.
       </para>
       
       <note>
@@ -967,7 +987,57 @@
         </para>
       </note>
     </section>
-        
+            
+    
+    <section>
+      <title>Template Formats</title>
+      
+      <para>
+        Some CGIs have the ability to use more than one template. For
+        example, buglist.cgi can output bug lists as RDF or two
+        different forms of HTML (complex and simple). (Try this out
+        by appending <filename>&amp;format=simple</filename> to a buglist.cgi
+        URL on your Bugzilla installation.) This
+        mechanism, called template 'formats', is extensible.
+      </para>
+      
+      <para>
+        To see if a CGI supports multiple output formats, grep the
+        CGI for "ValidateOutputFormat". If it's not present, adding
+        multiple format support isn't too hard - see how it's done in
+        other CGIs.
+      </para>
+      
+      <para>
+        To make a new format template for a CGI which supports this, 
+        open a current template for
+        that CGI and take note of the INTERFACE comment (if present.) This 
+        comment defines what variables are passed into this template. If 
+        there isn't one, I'm afraid you'll have to read the template and
+        the code to find out what information you get. 
+      </para>     
+  
+      <para>
+        Write your template in whatever markup or text style is appropriate.
+      </para>
+      
+      <para>
+        You now need to decide what content type you want your template
+        served as. Open up the <filename>localconfig</filename> file and find the 
+        <filename>$contenttypes</filename>
+        variable. If your content type is not there, add it. Remember
+        the three- or four-letter tag assigned to you content type. 
+        This tag will be part of the template filename.
+      </para>
+      
+      <para>
+        Save the template as <filename>&lt;stubname&gt;-&lt;formatname&gt;.&lt;contenttypetag&gt;.tmpl</filename>. 
+        Try out the template by calling the CGI as 
+        <filename>&lt;cginame&gt;.cgi?format=&lt;formatname&gt;</filename> .
+      </para>       
+    </section>
+    
+    
     <section>
       <title>Particular Templates</title>
       
@@ -977,6 +1047,11 @@
       </para>
       
       <para>
+        <command>index.html.tmpl</command>:
+        This is the Bugzilla front page.
+      </para>      
+
+      <para>
         <command>global/header.html.tmpl</command> and
         <command>global/footer.html.tmpl</command>:
         These define the header and footer that go on all Bugzilla pages.
@@ -992,15 +1067,18 @@
         field in the database. The bug entry system has been designed in an
         extensible fashion to enable you to define arbitrary fields and widgets,
         and have their values appear formatted in the initial
-        Description (rather than in database fields.)
+        Description, rather than in database fields. An example of this
+        is the mozilla.org 
+        <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided 
+        bug submission form</ulink>.
       </para>
         
       <para>
         To make this work, create a custom template for 
         <filename>enter_bug.cgi</filename> (the default template, on which you
         could base it, is <filename>create.html.tmpl</filename>),
-        and either call it <filename>create.html.tmpl</filename> or
-        <filename>create-&lt;formatname&gt;.html.tmpl</filename>.
+        and either call it <filename>create.html.tmpl</filename> or use a format and
+        call it <filename>create-&lt;formatname&gt;.html.tmpl</filename>.
         Put it in the <filename class="directory">custom/bug/create</filename>
         directory. In it, add widgets for each piece of information you'd like
         collected - such as a build number, or set of steps to reproduce.
@@ -1008,7 +1086,8 @@
 
       <para>
         Then, create a template like 
-        <filename>custom/bug/create/comment.txt.tmpl</filename>, which
+        <filename>custom/bug/create/comment.txt.tmpl</filename>, also named
+        after your format if you are using one, which
         references the form fields you have created. When a bug report is
         submitted, the initial comment attached to the bug report will be
         formatted according to the layout of this template.
@@ -1016,66 +1095,13 @@
 
       <para>
         For example, if your enter_bug template had a field
-        <programlisting>
-        &lt;input type="text" name="buildid" size="30"&gt;
-        </programlisting>
+        <programlisting>&lt;input type="text" name="buildid" size="30"&gt;</programlisting>
         and then your comment.txt.tmpl had
-        <programlisting>
-        BuildID: [% form.buildid %]
-        </programlisting>
+        <programlisting>BuildID: [% form.buildid %]</programlisting>
         then
-        <programlisting>
-        BuildID: 20020303
-        </programlisting>
+        <programlisting>BuildID: 20020303</programlisting>
         would appear in the initial checkin comment.
       </para>        
-    </section>
-    
-    <section>
-      <title>Template Formats</title>
-      
-      <para>
-        Some CGIs have the ability to use more than one template. For
-        example, buglist.cgi can output bug lists as RDF or two
-        different forms of HTML (complex and simple). (Try this out
-        by appending <filename>&amp;format=simple</filename> to a buglist.cgi
-        URL on your Bugzilla installation.) This
-        mechanism, called template 'formats', is extensible.
-      </para>
-      
-      <para>
-        To see if a CGI supports multiple output formats, grep the
-        CGI for "ValidateOutputFormat". If it's not present, adding
-        multiple format support isn't too hard - see how it's done in
-        other CGIs.
-      </para>
-      
-      <para>
-        To make a new format template for a CGI which supports this, 
-        open a current template for
-        that CGI and take note of the INTERFACE comment (if present.) This 
-        comment defines what variables are passed into this template. If 
-        there isn't one, I'm afraid you'll have to read the template and
-        the code to find out what information you get. 
-      </para>     
-  
-      <para>
-        Write your template in whatever markup or text style is appropriate.
-      </para>
-      
-      <para>
-        You now need to decide what content type you want your template
-        served as. Open up the localconfig file and find the $contenttypes
-        variable. If your content type is not there, add it. Remember
-        the three- or four-letter tag assigned to you content type. 
-        This tag will be part of the template filename.
-      </para>
-      
-      <para>
-        Save the template as <filename>&lt;stubname&gt;-&lt;formatname&gt;.&lt;contenttypetag&gt;.tmpl</filename>. 
-        Try out the template by calling the CGI as 
-        <filename>&lt;cginame&gt;.cgi?format=&lt;formatname&gt;</filename> .
-      </para>       
     </section>          
     
   </section>
@@ -1084,17 +1110,25 @@
     <title>Upgrading to New Releases</title>
 
     <para>A plain Bugzilla is fairly easy to upgrade from one version to a
-    newer one. However, things get a bit more complicated if you've made
-    changes to Bugzilla's code. In this case, you may have to re-make or
-    reapply those changes. It is recommended that you take a backup of your
-    database and your entire Bugzilla installation before attempting an
+    newer one. Always read the release notes to see if there are any issues
+    that you might need to take note of. It is recommended that you take a 
+    backup of your database and your entire Bugzilla installation before attempting an
     upgrade. You can upgrade a 'clean' installation by untarring a new
     tarball over the old installation. If you are upgrading from 2.12 or
-    later, you can type 
-    <filename>cvs -z3 update</filename>, 
-    and resolve conflicts if there are any.</para>
-
-    <para>Because the developers of Bugzilla are constantly adding new
+    later, and have cvs installed, you can type <filename>cvs -z3 update</filename>, 
+    and resolve conflicts if there are any.
+    </para>
+    
+    <para>However, things get a bit more complicated if you've made
+    changes to Bugzilla's code. In this case, you may have to re-make or
+    reapply those changes. One good method is to take a diff of your customised
+    version against the original, so you can survey all that you've changed.
+    Hopefully, templatisation will reduce the need for
+    this in the future.</para>
+
+    <para>From version 2.8 onwards, Bugzilla databases can be automatically
+    carried forward during an upgrade. However, because the developers of
+    Bugzilla are constantly adding new
     tables, columns and fields, you'll probably get SQL errors if you just
     update the code and attempt to use Bugzilla. Always run the
     <filename>checksetup.pl</filename> 
diff --git a/docs/sgml/faq.sgml b/docs/sgml/faq.sgml
index db7f68b2f..91380863f 100644
--- a/docs/sgml/faq.sgml
+++ b/docs/sgml/faq.sgml
@@ -223,12 +223,11 @@
     </qandadiv>
 
     <qandadiv id="faq-phb">
-      <title>Pointy-Haired-Boss Questions</title>
+      <title>Managerial Questions</title>
       <para>
 	<note>
 	  <para>
-	    The title of this section doesn't mean you're a PHB -- it just means
-	    you probably HAVE a PHB who wants to know this :)
+	    Questions likely to be asked by managers. :-)
 	  </para>
 	</note>
       </para>
@@ -345,7 +344,7 @@
 	  <para>
 	    Yes.  Look at <ulink url="http://bugzilla.mozilla.org/reports.cgi">
 	    http://bugzilla.mozilla.org/reports.cgi</ulink> for basic reporting
-	    facilities.
+	    and graphing facilities.
 	  </para>
 	  <para>
 	    For more advanced reporting, I recommend hooking up a professional
@@ -552,8 +551,7 @@
 	<answer>
 	  <para>
 	    If Bugzilla is set up correctly from the start, continuing maintenance
-      needs
-	    are minimal and can be completed by unskilled labor.
+      needs are minimal and can be done easily using the web interface.
 	  </para>
 	  <para>
 	    Commercial Bug-tracking software typically costs somewhere upwards
diff --git a/docs/sgml/installation.sgml b/docs/sgml/installation.sgml
index 096626389..d9297ce47 100644
--- a/docs/sgml/installation.sgml
+++ b/docs/sgml/installation.sgml
@@ -485,6 +485,20 @@
       Note that earlier versions that 0.99c used GIFs, which are no longer
       supported by the latest versions of GD.</para>
     </section>
+    
+    <section>
+      <title>Template Toolkit</title>
+
+      <para>When you install Template Toolkit, you'll get asked various
+      questions about features to enable. The defaults are fine, except
+      that it is recommended you use the high speed XS Stash of the Template
+      Toolkit, in order to achieve best performance.  However, there are
+      known problems with XS Stash and Perl 5.005_02 and lower.  If you
+      wish to use these older versions of Perl, please use the regular
+      stash.</para>
+    </section> 
+
+    
   </section>
   
     <section>
@@ -639,7 +653,7 @@
       and enter &lt;new_password&gt;. Remember that MySQL user names have
       nothing to do with Unix user names (login names).</para>
 
-      <para>Next, we create the 
+      <para>Next, we use an SQL <command>GRANT</command> command to create a 
       <quote>bugs</quote>
 
       user, and grant sufficient permissions for checksetup.pl, which we'll
diff --git a/docs/sgml/using.sgml b/docs/sgml/using.sgml
index fc7268d28..74cca3825 100644
--- a/docs/sgml/using.sgml
+++ b/docs/sgml/using.sgml
@@ -399,6 +399,7 @@
         <member>bug 23456, comment 53</member>
         <member>attachment 4321</member>
         <member>mailto:george@example.com</member>
+        <member>george@example.com</member>
         <member>ftp://ftp.mozilla.org</member>
         <member>Most other sorts of URL</member>
       </simplelist>
diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index 8c85bd05f..66489469d 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -928,7 +928,8 @@
         each installed localisation. The default English templates are
         therefore in <filename>en</filename>. Underneath that, there
         are two directories - <filename>default</filename> and 
-        <filename>custom</filename>. The <filename>default</filename>
+        <filename>custom</filename> (you may have to create
+        <filename>custom</filename> yourself.) The <filename>default</filename>
         directory contains all the templates shipped with Bugzilla.
       </para>
 
@@ -948,15 +949,34 @@
         the contents of this directory will not be touched during an upgrade,
         and you can then decide whether to continue using your own templates,
         or make the effort to merge your changes into the new versions by
-        hand.
+        hand. This is also the correct method to use if you upgrade Bugzilla
+        by untarring tarballs over the top, rather than using CVS. It's perfectly
+        acceptable to mix and match these two methods.
       </para>
 
       <para>
+        Editing templates is a good way of doing a "poor man's custom fields".
+        For example, if you don't use the Status Whiteboard, but want to have
+        a free-form text entry box for "Build Identifier", then you can just
+        edit the templates to change the field labels. It's still be called
+        status_whiteboard internally, but your users don't need to know that.
+      </para>
+      
+      <para>
+        If you are making changes to contribute back to Bugzilla (and we'd
+        love to have them), then please read the 
+        <ulink url="http://www.bugzilla.org/developerguide.html">Developers 
+        Guide</ulink> first.
+      </para>
+      
+     <para>
         The syntax of the Template Toolkit language is beyond the scope of
         this guide. It's reasonably easy to pick up by looking at the current 
         templates; or, you can read the manual, available on the
         <ulink url="http://www.template-toolkit.org">Template Toolkit home
-        page</ulink>.
+        page</ulink>. However, you should particularly remember (for security
+        reasons) to always HTML filter things which come from the database or
+        user input, to prevent cross-site scripting attacks.
       </para>
       
       <note>
@@ -967,7 +987,57 @@
         </para>
       </note>
     </section>
-        
+            
+    
+    <section>
+      <title>Template Formats</title>
+      
+      <para>
+        Some CGIs have the ability to use more than one template. For
+        example, buglist.cgi can output bug lists as RDF or two
+        different forms of HTML (complex and simple). (Try this out
+        by appending <filename>&amp;format=simple</filename> to a buglist.cgi
+        URL on your Bugzilla installation.) This
+        mechanism, called template 'formats', is extensible.
+      </para>
+      
+      <para>
+        To see if a CGI supports multiple output formats, grep the
+        CGI for "ValidateOutputFormat". If it's not present, adding
+        multiple format support isn't too hard - see how it's done in
+        other CGIs.
+      </para>
+      
+      <para>
+        To make a new format template for a CGI which supports this, 
+        open a current template for
+        that CGI and take note of the INTERFACE comment (if present.) This 
+        comment defines what variables are passed into this template. If 
+        there isn't one, I'm afraid you'll have to read the template and
+        the code to find out what information you get. 
+      </para>     
+  
+      <para>
+        Write your template in whatever markup or text style is appropriate.
+      </para>
+      
+      <para>
+        You now need to decide what content type you want your template
+        served as. Open up the <filename>localconfig</filename> file and find the 
+        <filename>$contenttypes</filename>
+        variable. If your content type is not there, add it. Remember
+        the three- or four-letter tag assigned to you content type. 
+        This tag will be part of the template filename.
+      </para>
+      
+      <para>
+        Save the template as <filename>&lt;stubname&gt;-&lt;formatname&gt;.&lt;contenttypetag&gt;.tmpl</filename>. 
+        Try out the template by calling the CGI as 
+        <filename>&lt;cginame&gt;.cgi?format=&lt;formatname&gt;</filename> .
+      </para>       
+    </section>
+    
+    
     <section>
       <title>Particular Templates</title>
       
@@ -977,6 +1047,11 @@
       </para>
       
       <para>
+        <command>index.html.tmpl</command>:
+        This is the Bugzilla front page.
+      </para>      
+
+      <para>
         <command>global/header.html.tmpl</command> and
         <command>global/footer.html.tmpl</command>:
         These define the header and footer that go on all Bugzilla pages.
@@ -992,15 +1067,18 @@
         field in the database. The bug entry system has been designed in an
         extensible fashion to enable you to define arbitrary fields and widgets,
         and have their values appear formatted in the initial
-        Description (rather than in database fields.)
+        Description, rather than in database fields. An example of this
+        is the mozilla.org 
+        <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided 
+        bug submission form</ulink>.
       </para>
         
       <para>
         To make this work, create a custom template for 
         <filename>enter_bug.cgi</filename> (the default template, on which you
         could base it, is <filename>create.html.tmpl</filename>),
-        and either call it <filename>create.html.tmpl</filename> or
-        <filename>create-&lt;formatname&gt;.html.tmpl</filename>.
+        and either call it <filename>create.html.tmpl</filename> or use a format and
+        call it <filename>create-&lt;formatname&gt;.html.tmpl</filename>.
         Put it in the <filename class="directory">custom/bug/create</filename>
         directory. In it, add widgets for each piece of information you'd like
         collected - such as a build number, or set of steps to reproduce.
@@ -1008,7 +1086,8 @@
 
       <para>
         Then, create a template like 
-        <filename>custom/bug/create/comment.txt.tmpl</filename>, which
+        <filename>custom/bug/create/comment.txt.tmpl</filename>, also named
+        after your format if you are using one, which
         references the form fields you have created. When a bug report is
         submitted, the initial comment attached to the bug report will be
         formatted according to the layout of this template.
@@ -1016,66 +1095,13 @@
 
       <para>
         For example, if your enter_bug template had a field
-        <programlisting>
-        &lt;input type="text" name="buildid" size="30"&gt;
-        </programlisting>
+        <programlisting>&lt;input type="text" name="buildid" size="30"&gt;</programlisting>
         and then your comment.txt.tmpl had
-        <programlisting>
-        BuildID: [% form.buildid %]
-        </programlisting>
+        <programlisting>BuildID: [% form.buildid %]</programlisting>
         then
-        <programlisting>
-        BuildID: 20020303
-        </programlisting>
+        <programlisting>BuildID: 20020303</programlisting>
         would appear in the initial checkin comment.
       </para>        
-    </section>
-    
-    <section>
-      <title>Template Formats</title>
-      
-      <para>
-        Some CGIs have the ability to use more than one template. For
-        example, buglist.cgi can output bug lists as RDF or two
-        different forms of HTML (complex and simple). (Try this out
-        by appending <filename>&amp;format=simple</filename> to a buglist.cgi
-        URL on your Bugzilla installation.) This
-        mechanism, called template 'formats', is extensible.
-      </para>
-      
-      <para>
-        To see if a CGI supports multiple output formats, grep the
-        CGI for "ValidateOutputFormat". If it's not present, adding
-        multiple format support isn't too hard - see how it's done in
-        other CGIs.
-      </para>
-      
-      <para>
-        To make a new format template for a CGI which supports this, 
-        open a current template for
-        that CGI and take note of the INTERFACE comment (if present.) This 
-        comment defines what variables are passed into this template. If 
-        there isn't one, I'm afraid you'll have to read the template and
-        the code to find out what information you get. 
-      </para>     
-  
-      <para>
-        Write your template in whatever markup or text style is appropriate.
-      </para>
-      
-      <para>
-        You now need to decide what content type you want your template
-        served as. Open up the localconfig file and find the $contenttypes
-        variable. If your content type is not there, add it. Remember
-        the three- or four-letter tag assigned to you content type. 
-        This tag will be part of the template filename.
-      </para>
-      
-      <para>
-        Save the template as <filename>&lt;stubname&gt;-&lt;formatname&gt;.&lt;contenttypetag&gt;.tmpl</filename>. 
-        Try out the template by calling the CGI as 
-        <filename>&lt;cginame&gt;.cgi?format=&lt;formatname&gt;</filename> .
-      </para>       
     </section>          
     
   </section>
@@ -1084,17 +1110,25 @@
     <title>Upgrading to New Releases</title>
 
     <para>A plain Bugzilla is fairly easy to upgrade from one version to a
-    newer one. However, things get a bit more complicated if you've made
-    changes to Bugzilla's code. In this case, you may have to re-make or
-    reapply those changes. It is recommended that you take a backup of your
-    database and your entire Bugzilla installation before attempting an
+    newer one. Always read the release notes to see if there are any issues
+    that you might need to take note of. It is recommended that you take a 
+    backup of your database and your entire Bugzilla installation before attempting an
     upgrade. You can upgrade a 'clean' installation by untarring a new
     tarball over the old installation. If you are upgrading from 2.12 or
-    later, you can type 
-    <filename>cvs -z3 update</filename>, 
-    and resolve conflicts if there are any.</para>
-
-    <para>Because the developers of Bugzilla are constantly adding new
+    later, and have cvs installed, you can type <filename>cvs -z3 update</filename>, 
+    and resolve conflicts if there are any.
+    </para>
+    
+    <para>However, things get a bit more complicated if you've made
+    changes to Bugzilla's code. In this case, you may have to re-make or
+    reapply those changes. One good method is to take a diff of your customised
+    version against the original, so you can survey all that you've changed.
+    Hopefully, templatisation will reduce the need for
+    this in the future.</para>
+
+    <para>From version 2.8 onwards, Bugzilla databases can be automatically
+    carried forward during an upgrade. However, because the developers of
+    Bugzilla are constantly adding new
     tables, columns and fields, you'll probably get SQL errors if you just
     update the code and attempt to use Bugzilla. Always run the
     <filename>checksetup.pl</filename> 
diff --git a/docs/xml/faq.xml b/docs/xml/faq.xml
index db7f68b2f..91380863f 100644
--- a/docs/xml/faq.xml
+++ b/docs/xml/faq.xml
@@ -223,12 +223,11 @@
     </qandadiv>
 
     <qandadiv id="faq-phb">
-      <title>Pointy-Haired-Boss Questions</title>
+      <title>Managerial Questions</title>
       <para>
 	<note>
 	  <para>
-	    The title of this section doesn't mean you're a PHB -- it just means
-	    you probably HAVE a PHB who wants to know this :)
+	    Questions likely to be asked by managers. :-)
 	  </para>
 	</note>
       </para>
@@ -345,7 +344,7 @@
 	  <para>
 	    Yes.  Look at <ulink url="http://bugzilla.mozilla.org/reports.cgi">
 	    http://bugzilla.mozilla.org/reports.cgi</ulink> for basic reporting
-	    facilities.
+	    and graphing facilities.
 	  </para>
 	  <para>
 	    For more advanced reporting, I recommend hooking up a professional
@@ -552,8 +551,7 @@
 	<answer>
 	  <para>
 	    If Bugzilla is set up correctly from the start, continuing maintenance
-      needs
-	    are minimal and can be completed by unskilled labor.
+      needs are minimal and can be done easily using the web interface.
 	  </para>
 	  <para>
 	    Commercial Bug-tracking software typically costs somewhere upwards
diff --git a/docs/xml/installation.xml b/docs/xml/installation.xml
index 096626389..d9297ce47 100644
--- a/docs/xml/installation.xml
+++ b/docs/xml/installation.xml
@@ -485,6 +485,20 @@
       Note that earlier versions that 0.99c used GIFs, which are no longer
       supported by the latest versions of GD.</para>
     </section>
+    
+    <section>
+      <title>Template Toolkit</title>
+
+      <para>When you install Template Toolkit, you'll get asked various
+      questions about features to enable. The defaults are fine, except
+      that it is recommended you use the high speed XS Stash of the Template
+      Toolkit, in order to achieve best performance.  However, there are
+      known problems with XS Stash and Perl 5.005_02 and lower.  If you
+      wish to use these older versions of Perl, please use the regular
+      stash.</para>
+    </section> 
+
+    
   </section>
   
     <section>
@@ -639,7 +653,7 @@
       and enter &lt;new_password&gt;. Remember that MySQL user names have
       nothing to do with Unix user names (login names).</para>
 
-      <para>Next, we create the 
+      <para>Next, we use an SQL <command>GRANT</command> command to create a 
       <quote>bugs</quote>
 
       user, and grant sufficient permissions for checksetup.pl, which we'll
diff --git a/docs/xml/using.xml b/docs/xml/using.xml
index fc7268d28..74cca3825 100644
--- a/docs/xml/using.xml
+++ b/docs/xml/using.xml
@@ -399,6 +399,7 @@
         <member>bug 23456, comment 53</member>
         <member>attachment 4321</member>
         <member>mailto:george@example.com</member>
+        <member>george@example.com</member>
         <member>ftp://ftp.mozilla.org</member>
         <member>Most other sorts of URL</member>
       </simplelist>