@end direntry
@copying
-Copyright @copyright{} 2015 Free Software Foundation, Inc.
+Copyright @copyright{} 2015-2016 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@contents
+
@node Top
@top Debbugs User Guide
main distinctive feature of Debbugs is that it's mostly email-based.
All actions on bug reports: opening, closing, changing the status,
commenting, forwarding are performed via email by sending specially
-composed letters to the particular mail addresses. However, searching
-the bug reports, querying bug report status and viewing comments have
-been web-based for a long time. To overcome this inconvenience the
-Debbugs/SOAP service was introduced.
+composed letters to the particular email addresses. However,
+searching the bug reports, querying bug report status and viewing
+comments have been web-based for a long time. To overcome this
+inconvenience the Debbugs/SOAP service was introduced.
Based on the Debbugs/SOAP service, frontends are written which offer
handling of bugs inside Emacs. These frontends are restricted to the
* Key Index:: Keyboard strokes on bug report buffers.
@end menu
+
@node Retrieving Bugs
@chapter Retrieving Bugs
These commands retrieve bug reports from the GNU Debbugs server.
@code{debbugs-gnu} returns a tabulated list, and @code{debbugs-org}
-returns a list of TODO items in @code{org-mode}. If there were more
-than @code{debbugs-gnu-default-hits-per-page} bug results from the
-query, there are widgets (@code{debbugs-gnu}) or links
-(@code{debbugs-org}) in the result buffer for retrieving the other
-results.
+returns a list of TODO items in @code{org-mode}. In order not to
+stress the GNU Debbugs server, the bugs are retrieved in chunks of 500
+bugs. However, the bug report buffer shows all retrieved bugs then,
+in reverse bug number order.
@vindex debbugs-gnu-all-severities
@var{severities} is a list of strings which filter for the severities
@var{archivedp}, if non-@code{nil}, extends the result also on
archived bugs on the GNU Debbugs server.
+@vindex debbugs-gnu-default-suppress-bugs
@var{suppress} shall also distinct between @code{nil} and
non-@code{nil}. When non-@code{nil}, closed bugs are suppressed from
-the results.
+being retrieved from the Debbugs server. Which bugs are regarded as
+suppressed is configured in the customer option
+@code{debbugs-gnu-suppress-bugs}. Per default, bugs marked as
+@code{"done"} are suppressed from being retrieved.
When @var{severities} contains the severity @code{"tagged"},
@var{tags} is consulted in order to restrict the result on bugs which
options @code{debbugs-gnu-default-severities} and
@code{debbugs-gnu-default-packages}.
-@vindex debbugs-gnu-default-hits-per-page
-When the result would exceed more than 500 bugs, the user is asked how
-many bugs to retrieve at once. This value can be configured in the
-customer option @code{debbugs-gnu-default-hits-per-page}. However, it
-is not recommended to exceeds the default value.
-
@ref{Layout} for the presentation of the results.
@end deffn
A comma-separated list of defined user tags.
@item submitter
-The address of the bug submitter.
+The email address of the bug submitter.
@item date
A time period the bug has been in which the bug has been submitted or
* Control Messages:: Control Messages.
@end menu
+
@node Tabulated Lists
@section Tabulated Lists
A tabulated list of bug reports consist of four columns for every bug
entry: @code{Id} (the bug number), @code{State} (some bug attributes),
@code{Submitter} (the name of the bug submitter), and @code{Title}
-(the bug subject). Per default the bugs are sorted by @code{Id}; this
-could be changed by clicking in the headline.
-
-Per bug retrieval only up to 500
-(@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
-presented in a buffer. If there shall be presented more bugs, widgets
-are placed on the top and bottom of the buffer for navigation to
-further report buffers.
+(the bug subject). Per default the bugs are sorted descending by
+@code{Id}; this could be changed by clicking in the headline.
Different foreground colours present further information on the bug
report. If the bug number uses a red colour
The bug report buffers have enabled the minor
@code{debbugs-gnu-mode}. This enables the following key strokes:
-@multitable {@kbd{@key{mouse-2}}} {Some very very very long long text Some very very very long long text Some very very very long long text}
+@multitable @columnfractions .20 .80
@item
@kindex @kbd{@key{RET}}
-@kbd{@key{RET}}
+@kbd{@key{RET}} @*
@kindex @kbd{@key{mouse-1}}
-@kbd{@key{mouse-1}}
+@kbd{@key{mouse-1}} @*
@kindex @kbd{@key{mouse-2}}
@kbd{@key{mouse-2}} @tab
@code{debbugs-gnu-select-report} @*
@code{debbugs-gnu-display-status} @*
Show all bug attributes.
-@c @item
-@c @kindex @kbd{/}
-@c @kbd{/} @tab
-@c @code{debbugs-gnu-narrow-to-status}
+@item
+@kindex @kbd{/}
+@kbd{/} @tab
+@code{debbugs-gnu-narrow-to-status} @*
+Narrow the list of bugs to the bugs that match the given regex in
+@code{State}, @code{Submitter} or @code{Title}.
-@c @item
-@c @kindex @kbd{w}
-@c @kbd{w} @tab
-@c @code{debbugs-gnu-widen}
+@item
+@kindex @kbd{R}
+@kbd{R} @tab
+@code{debbugs-gnu-show-all-blocking-reports} @*
+Narrow the list of bug reports to the ones that are blocking the
+current release.
+
+@item
+@kindex @kbd{w}
+@kbd{w} @tab
+@code{debbugs-gnu-widen} @*
+Restore the full list again after narrowing.
@item
@kindex @kbd{g}
@kbd{g} @tab
@code{debbugs-gnu-rescan} @*
-Reload all bugs from the GNU Debbugs server.
+Reload all bugs. With a prefix argument @kbd{C-u}, the bug status
+cache is disabled, and all bug reports are retrieved from the GNU
+Debbugs server.
@item
@kindex @kbd{B}
-@kbd{B} @tab
-@code{debbugs-gnu-show-blocking-reports}
-@item
+@kbd{B} @*
@kindex @kbd{b}
@kbd{b} @tab
+@code{debbugs-gnu-show-blocking-reports} @*
@code{debbugs-gnu-show-blocked-by-reports} @*
Show all bug reports which are blocking / blocked by this bug.
value is @code{rmail}, the command will present an Rmail folder
instead.
+
@node TODO Items
@section TODO Items
attributes are mapped onto properties of these items. They can be
shown by the usual navigation in @code{org-mode}.
-Per bug retrieval only up to 500
-(@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
-presented in a buffer. At the end of the buffer there is a link,
-which allows to append the next 500 bugs to the list.
-
Bug severities are mapped onto org severities, see
@code{debbugs-org-severity-priority}.
The bug report buffers have enabled the minor
-@code{debbugs-gnu-mode}. This enables the following key strokes:
+@code{debbugs-org-mode}. This enables the following key strokes:
@multitable {@kbd{C-c # C}} {Some very very very long long text Some very very very long long text Some very very very long long text}
The second bug number is read interactively.
-@item important
-@itemx minor
-@item normal
-@itemx serious
-@item wishlist
-"severity 12345 important|minor|normal|serious|wishlist"
-
@item invalid
"tags 12345 notabug" @*
"tags 12345 wontfix" @*
@item reopen
"reopen 12345"
+@item retitle
+"retitle 12345 @var{title}"
+
+The new bug title is read interactively.
+
+@item serious
+@itemx important
+@itemx normal
+@itemx minor
+@itemx wishlist
+"severity 12345 serious|important|normal|minor|wishlist"
+
@item unarchive
"unarchive 12345"