diff options
| -rw-r--r-- | docs/xml/using.xml | 226 |
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>&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 "e;Big File"e;, 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 "e;Big File"e; 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>&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> |