Bug 232096 - documenting content-type parameter for attachment.cgi.

docs/en/xml/using.xml

@@ -3,17 +3,16 @@
 <chapter id="using">
   <title>Using Bugzilla</title>
 
-  <section id="how">
-    <title>How do I use Bugzilla?</title>
-
+  <section id="using-intro">
+    <title>Introduction</title>
     <para>This section contains information for end-users of Bugzilla. 
     There is a Bugzilla test installation, called 
-    <ulink url="http://landfill.bugzilla.org/">Landfill</ulink>, 
+    <ulink url="http://landfill.bugzilla.org/bugzilla-tip/">Landfill</ulink>, 
     which you are welcome to play with (if it's up.) 
     However, it does not necessarily
-    have all Bugzilla features enabled, and often runs cutting-edge versions
-    of Bugzilla for testing, so some things may work slightly differently
-    than mentioned here.</para>
+    have all Bugzilla features enabled, and runs an up-to-the-minute version, 
+    so some things may not quite work as this document describes.</para>
+  </section>
       
   <section id="myaccount">
     <title>Create a Bugzilla Account</title>
@@ -39,16 +38,16 @@
 
       <listitem>
         <para>Within moments, you should receive an email to the address
-          you provided above, which contains your login name (generally the
-          same as the email address), and a password you can use to access
-          your account. This password is randomly generated, and can be
+        you provided, which contains your login name (generally the
+        same as the email address), and a password. 
+        This password is randomly generated, but can be
         changed to something more memorable.</para>
       </listitem>
 
       <listitem>
         <para>Click the 
         <quote>Log In</quote>
-          link in the yellow area at the bottom of the page in your browser,
+        link in the footer at the bottom of the page in your browser,
         enter your email address and password into the spaces provided, and
         click 
         <quote>Login</quote>.
@@ -57,9 +56,9 @@
       </listitem>
     </orderedlist>
 
-      <para>You are now logged in. Bugzilla uses cookies for authentication
-      so, unless your IP address changes, you should not have to log in
-      again.</para>
+    <para>You are now logged in. Bugzilla uses cookies to remember you are
+    logged in so, unless you have cookies disabled or your IP address changes, 
+    you should not have to log in again.</para>
   </section>
 
   <section id="bug_page">
@@ -273,23 +272,21 @@
     <para>The Search page has controls for selecting different possible
     values for all of the fields in a bug, as described above. For some
     fields, multiple values can be selected. In those cases, Bugzilla
-      returns bugs where the content of the field matches one of the selected
+    returns bugs where the content of the field matches any one of the selected
     values. If none is selected, then the field can take any value.</para>
 
-      <para>Once you've defined a search, you can either run it, or save it
-      as a Remembered Query, which can optionally appear in the footer of
-      your pages.</para>
+    <para>Once you've run a search, you can save it as a Saved Search, which 
+    appears in the page footer.</para>
 
-      <para>Highly advanced querying is done using Boolean Charts.</para>
+    <para>Highly advanced querying is done using Boolean Charts. See the
+    Boolean Charts help link on the Search page for more information.</para>
   </section>
 
   <section id="list">
     <title>Bug Lists</title>
 
     <para>If you run a search, a list of matching bugs will be returned.
-      The default search is to return all open bugs on the system - don't try
-      running this search on a Bugzilla installation with a lot of
-      bugs!</para>
+    </para>
 
     <para>The format of the list is configurable. For example, it can be
     sorted by clicking the column headings. Other useful features can be
@@ -302,6 +299,12 @@
       of each bug.</member>
 
       <member>
+      <emphasis>CSV:</emphasis>
+
+      get the buglist as comma-separated values, for import into e.g.
+      a spreadsheet.</member>
+      
+      <member>
       <emphasis>Change Columns:</emphasis>
 
       change the bug attributes which appear in the list.</member>
@@ -319,11 +322,18 @@
       Sends mail to the owners of all bugs on the list.</member>
 
       <member>
-        <emphasis>Edit this query:</emphasis>
+      <emphasis>Edit Search:</emphasis>
 
       If you didn't get exactly the results you were looking for, you can
       return to the Query page through this link and make small revisions
       to the query you just made so you get more accurate results.</member>
+      
+      <member>
+      <emphasis>Remember Search As:</emphasis>
+
+      You can give a search a name and remember it; a link will appear
+      in your page footer giving you quick access to run it again later.
+      </member>
     </simplelist>
     </para>
   </section>
@@ -371,6 +381,24 @@
         <para>Select "Commit" and send in your bug report.</para>
       </listitem>
     </orderedlist>
+    
+      <para>Try to make sure that everything said in the summary is also 
+      said in the first comment. Summaries are often updated and this will
+      ensure your original information is easily accessible.
+      </para>
+      
+      <para>
+      You do not need to put "any" or similar strings in the URL field.
+      If there is no specific URL associated with the bug, leave this 
+      field blank.
+      </para> 
+
+      <para>If you feel a bug you filed was incorrectly marked as a
+      DUPLICATE of another, please question it in your bug, not      
+      the bug it was duped to. Feel free to CC the person who duped it 
+      if they are not already CCed.
+      </para>
+      
   </section>
 
   <section id="patchviewer">
@@ -465,7 +493,6 @@
     </section>
 
   </section>
-  </section>
 
   <section id="hintsandtips">
     <title>Hints and Tips</title>
@@ -475,15 +502,16 @@
 
     <section>
       <title>Autolinkification</title>
-      <para>Bugzilla comments are plain text - so posting HTML will result
-      in literal HTML tags rather than being interpreted by a browser.
+      <para>Bugzilla comments are plain text - so typing &lt;U&gt; will
+      produce less-than, U, greater-than rather than underlined text.
       However, Bugzilla will automatically make hyperlinks out of certain
       sorts of text in comments. For example, the text 
-      http://www.bugzilla.org will be turned into
+      "http://www.bugzilla.org" will be turned into a link:
       <ulink url="http://www.bugzilla.org"/>.
       Other strings which get linkified in the obvious manner are:
       <simplelist>
         <member>bug 12345</member>
+        <member>comment 7</member>
         <member>bug 23456, comment 53</member>
         <member>attachment 4321</member>
         <member>mailto:george@example.com</member>
@@ -532,7 +560,7 @@
       
       <para>
       Don't use sigs in comments. Signing your name ("Bill") is acceptable,
-      particularly if you do it out of habit, but full mail/news-style
+      if you do it out of habit, but full mail/news-style
       four line ASCII art creations are not.
       </para>      
     </section>
@@ -557,26 +585,11 @@
       attached files. This way, the test case works immediately 
       out of the bug.
       </para>
-    </section>
-    
-    <section>
-      <title>Filing Bugs</title>
-      
-      <para>Try to make sure that everything said in the summary is also 
-      said in the first comment. Summaries are often updated and this will
-      ensure your original information is easily accessible.
-      </para>
-      
-      <para>
-      You do not need to put "any" or similar strings in the URL field.
-      If there is no specific URL associated with the bug, leave this 
-      field blank.
-      </para> 
-
-      <para>If you feel a bug you filed was incorrectly marked as a
-      DUPLICATE of another, please question it in your bug, not      
-      the bug it was duped to. Feel free to CC the person who duped it 
-      if they are not already CCed.
+      <para>Bugzilla stores and uses a Content-Type for each attachment 
+      (e.g. text/html). To download an attachment as a different 
+      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>     
     </section>
   </section>
@@ -586,7 +599,7 @@
 
     <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 four tabs:</para>
+    The preferences are split into three tabs:</para>
 
     <section id="accountsettings" xreflabel="Account Settings">
       <title>Account Settings</title>
@@ -608,9 +621,16 @@
 
       <para>On this tab you can reduce or increase the amount of email sent
       you from Bugzilla, opting in our out depending on your relationship to
-      the bug and the change that was made to it. (Note that you can also do
-      client-side filtering using the X-Bugzilla-Reason header which Bugzilla
-      adds to all bugmail.)</para>
+      the bug and the change that was made to it. 
+      </para>
+      
+      <para>
+      You can also do further filtering on the client side by 
+      using the X-Bugzilla-Reason mail header which Bugzilla
+      adds to all bugmail. This tells you what relationship you have to the
+      bug in question,
+      and can be any of Owner, Reporter, QAcontact, CClist, Voter and
+      WatchingComponent.</para>
 
       <para>By entering user email names, delineated by commas, into the
       "Users to watch" text entry box you can receive a copy of all the
@@ -625,15 +645,6 @@
       </note>
     </section>
 
-    <section id="footersettings">
-      <title>Page Footer</title>
-      
-      <para>On the Search page, you can store queries in Bugzilla, so if you
-      regularly run a particular query it is just a drop-down menu away. 
-      Once you have a stored query, you can come
-      here to request that it also be displayed in your page footer.</para>
-    </section>
-
     <section id="permissionsettings">
       <title>Permissions</title>
       
@@ -643,6 +654,11 @@
       functions.</para>
     </section>
   </section>
+  <section id="reporting">
+    <title>Reports</title>
+    <para><emphasis>To be written</emphasis></para>
+  </section>
+  
 </chapter>
 
 <!-- Keep this comment at the end of the file