summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorlpsolit%gmail.com <>2008-04-04 13:48:01 +0200
committerlpsolit%gmail.com <>2008-04-04 13:48:01 +0200
commit3e0378702e38aa3f21a5c38c0527d00cb68371d2 (patch)
tree19e951cf4e1543edc04f05dea9d9ecab4bc6bffc
parent8b11e35f0469291f2405300ed49c42bed27fd767 (diff)
downloadbugzilla-3e0378702e38aa3f21a5c38c0527d00cb68371d2.tar.gz
bugzilla-3e0378702e38aa3f21a5c38c0527d00cb68371d2.tar.xz
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
-rw-r--r--docs/en/xml/using.xml226
1 files changed, 109 insertions, 117 deletions
diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml
index da271519e..ee9616e2f 100644
--- a/docs/en/xml/using.xml
+++ b/docs/en/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>