Bug 361564: Attachments should have their own section in the docs, and info about PatchReader should be a sub-section of it - Patch by Frédéric Buclin <LpSolit@gmail.com> r=Colin

1 files changed, 109 insertions, 117 deletions

diff --git a/docs/xml/using.xml b/docs/xml/using.xml
index da271519e..ee9616e2f 100644
--- a/docs/xml/using.xml
+++ b/docs/xml/using.xml
@@ -749,97 +749,127 @@
       
   </section>
 
-  <section id="patchviewer">
-    <title>Patch Viewer</title>
+  <section id="attachments">
+    <title>Attachments</title>
 
-    <para>Viewing and reviewing patches in Bugzilla is often difficult due to
-    lack of context, improper format and the inherent readability issues that
-    raw patches present.  Patch Viewer is an enhancement to Bugzilla designed
-    to fix that by offering increased context, linking to sections, and
-    integrating with Bonsai, LXR and CVS.</para>
+    <para>
+      You should use attachments, rather than comments, for large chunks of ASCII
+      data, such as trace, debugging output files, or log files. That way, it
+      doesn't bloat the bug for everyone who wants to read it, and cause people to
+      receive fat, useless mails.
+    </para>
 
-    <para>Patch viewer allows you to:</para>
+    <para>You should make sure to trim screenshots. There's no need to show the
+      whole screen if you are pointing out a single-pixel problem.
+    </para>
 
-    <simplelist>
-      <member>View patches in color, with side-by-side view rather than trying
-      to interpret the contents of the patch.</member>
-      <member>See the difference between two patches.</member>
-      <member>Get more context in a patch.</member>
-      <member>Collapse and expand sections of a patch for easy
-      reading.</member>
-      <member>Link to a particular section of a patch for discussion or
-      review</member>
-      <member>Go to Bonsai or LXR to see more context, blame, and
-      cross-references for the part of the patch you are looking at</member>
-      <member>Create a rawtext unified format diff out of any patch, no
-      matter what format it came from</member>
-    </simplelist>
+    <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 id="patchviewer_view">
-      <title>Viewing Patches in Patch Viewer</title>
-      <para>The main way to view a patch in patch viewer is to click on the
-      "Diff" link next to a patch in the Attachments list on a bug. You may
-      also do this within the edit window by clicking the "View Attachment As
-      Diff" button in the Edit Attachment screen.</para>
-    </section>
+    <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 &quote;Big File&quote;, 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 &quote;Big File&quote; is normally larger
+      than the maximum size of a regular attachment.
+    </para>
 
-    <section id="patchviewer_diff">
-      <title>Seeing the Difference Between Two Patches</title>
-      <para>To see the difference between two patches, you must first view the
-      newer patch in Patch Viewer.  Then select the older patch from the
-      dropdown at the top of the page ("Differences between [dropdown] and
-      this patch") and click the "Diff" button. This will show you what
-      is new or changed in the newer patch.</para>
-    </section>
+    <section id="patchviewer">
+      <title>Patch Viewer</title>
 
-    <section id="patchviewer_context">
-      <title>Getting More Context in a Patch</title>
-      <para>To get more context in a patch, you put a number in the textbox at
-      the top of Patch Viewer ("Patch / File / [textbox]") and hit enter.
-      This will give you that many lines of context before and after each
-      change. Alternatively, you can click on the "File" link there and it
-      will show each change in the full context of the file. This feature only
-      works against files that were diffed using "cvs diff".</para>
-    </section>
+      <para>Viewing and reviewing patches in Bugzilla is often difficult due to
+      lack of context, improper format and the inherent readability issues that
+      raw patches present.  Patch Viewer is an enhancement to Bugzilla designed
+      to fix that by offering increased context, linking to sections, and
+      integrating with Bonsai, LXR and CVS.</para>
 
-    <section id="patchviewer_collapse">
-      <title>Collapsing and Expanding Sections of a Patch</title>
-      <para>To view only a certain set of files in a patch (for example, if a
-      patch is absolutely huge and you want to only review part of it at a
-      time), you can click the "(+)" and "(-)" links next to each file (to
-      expand it or collapse it). If you want to collapse all files or expand
-      all files, you can click the "Collapse All" and "Expand All" links at the
-      top of the page.</para>
-    </section>
+      <para>Patch viewer allows you to:</para>
 
-    <section id="patchviewer_link">
-      <title>Linking to a Section of a Patch</title>
-      <para>To link to a section of a patch (for example, if you want to be
-      able to give someone a URL to show them which part you are talking
-      about) you simply click the "Link Here" link on the section header. The
-      resulting URL can be copied and used in discussion. (Copy Link
-      Location in Mozilla works as well.)</para>
-    </section>
+      <simplelist>
+        <member>View patches in color, with side-by-side view rather than trying
+        to interpret the contents of the patch.</member>
+        <member>See the difference between two patches.</member>
+        <member>Get more context in a patch.</member>
+        <member>Collapse and expand sections of a patch for easy
+        reading.</member>
+        <member>Link to a particular section of a patch for discussion or
+        review</member>
+        <member>Go to Bonsai or LXR to see more context, blame, and
+        cross-references for the part of the patch you are looking at</member>
+        <member>Create a rawtext unified format diff out of any patch, no
+        matter what format it came from</member>
+      </simplelist>
 
-    <section id="patchviewer_bonsai_lxr">
-      <title>Going to Bonsai and LXR</title>
-      <para>To go to Bonsai to get blame for the lines you are interested in,
-      you can click the "Lines XX-YY" link on the section header you are
-      interested in. This works even if the patch is against an old
-      version of the file, since Bonsai stores all versions of the file.</para>
+      <section id="patchviewer_view">
+        <title>Viewing Patches in Patch Viewer</title>
+        <para>The main way to view a patch in patch viewer is to click on the
+        "Diff" link next to a patch in the Attachments list on a bug. You may
+        also do this within the edit window by clicking the "View Attachment As
+        Diff" button in the Edit Attachment screen.</para>
+      </section>
 
-      <para>To go to LXR, you click on the filename on the file header
-      (unfortunately, since LXR only does the most recent version, line
-      numbers are likely to rot).</para>
-    </section>
+      <section id="patchviewer_diff">
+        <title>Seeing the Difference Between Two Patches</title>
+        <para>To see the difference between two patches, you must first view the
+        newer patch in Patch Viewer.  Then select the older patch from the
+        dropdown at the top of the page ("Differences between [dropdown] and
+        this patch") and click the "Diff" button. This will show you what
+        is new or changed in the newer patch.</para>
+      </section>
 
-    <section id="patchviewer_unified_diff">
-      <title>Creating a Unified Diff</title>
-      <para>If the patch is not in a format that you like, you can turn it
-      into a unified diff format by clicking the "Raw Unified" link at the top
-      of the page.</para>
-    </section>
+      <section id="patchviewer_context">
+        <title>Getting More Context in a Patch</title>
+        <para>To get more context in a patch, you put a number in the textbox at
+        the top of Patch Viewer ("Patch / File / [textbox]") and hit enter.
+        This will give you that many lines of context before and after each
+        change. Alternatively, you can click on the "File" link there and it
+        will show each change in the full context of the file. This feature only
+        works against files that were diffed using "cvs diff".</para>
+      </section>
+
+      <section id="patchviewer_collapse">
+        <title>Collapsing and Expanding Sections of a Patch</title>
+        <para>To view only a certain set of files in a patch (for example, if a
+        patch is absolutely huge and you want to only review part of it at a
+        time), you can click the "(+)" and "(-)" links next to each file (to
+        expand it or collapse it). If you want to collapse all files or expand
+        all files, you can click the "Collapse All" and "Expand All" links at the
+        top of the page.</para>
+      </section>
+
+      <section id="patchviewer_link">
+        <title>Linking to a Section of a Patch</title>
+        <para>To link to a section of a patch (for example, if you want to be
+        able to give someone a URL to show them which part you are talking
+        about) you simply click the "Link Here" link on the section header. The
+        resulting URL can be copied and used in discussion.</para>
+      </section>
+
+      <section id="patchviewer_bonsai_lxr">
+        <title>Going to Bonsai and LXR</title>
+        <para>To go to Bonsai to get blame for the lines you are interested in,
+        you can click the "Lines XX-YY" link on the section header you are
+        interested in. This works even if the patch is against an old
+        version of the file, since Bonsai stores all versions of the file.</para>
+
+        <para>To go to LXR, you click on the filename on the file header
+        (unfortunately, since LXR only does the most recent version, line
+        numbers are likely to rot).</para>
+      </section>
 
+      <section id="patchviewer_unified_diff">
+        <title>Creating a Unified Diff</title>
+        <para>If the patch is not in a format that you like, you can turn it
+        into a unified diff format by clicking the "Raw Unified" link at the top
+        of the page.</para>
+      </section>
+    </section>
   </section>
 
   <section id="hintsandtips">
@@ -914,44 +944,6 @@
       </para>      
     </section>
     
-    <section id="attachments">
-      <title>Attachments</title>
-      
-      <para>
-      Use attachments, rather than comments, for large chunks of ASCII data,
-      such as trace, debugging output files, or log files. That way, it doesn't
-      bloat the bug for everyone who wants to read it, and cause people to
-      receive fat, useless mails.
-      </para>      
-
-      <para>Trim screenshots. There's no need to show the whole screen if
-      you are pointing out a single-pixel problem.
-      </para>
-      
-      <para>Don't attach simple test cases (e.g. one HTML file, one 
-      CSS file and an image) as a ZIP file. Instead, upload them in 
-      reverse order and edit the referring file so that they point to the
-      attached files. This way, the test case works immediately 
-      out of the bug.
-      </para>
-      <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> 
-
-      <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 id="dependencytree">
       <title>Dependency Tree</title>