From: Michael Albinus Date: Wed, 1 Apr 2015 11:56:54 +0000 (+0200) Subject: New manual debbugs-ug.texi X-Git-Url: https://code.delx.au/gnu-emacs-elpa/commitdiff_plain/de5e933706472f50f678c55a4509db34d713956a New manual debbugs-ug.texi --- diff --git a/packages/debbugs/debbugs-ug.texi b/packages/debbugs/debbugs-ug.texi new file mode 100644 index 000000000..453487cbd --- /dev/null +++ b/packages/debbugs/debbugs-ug.texi @@ -0,0 +1,550 @@ +\input texinfo +@setfilename debbugs-ug.info +@settitle Debbugs User Guide + +@dircategory Emacs +@direntry +* Debbugs UG: (debbugs-ug). Debbugs User Interface in Emacs. +@end direntry + +@copying +Copyright @copyright{} 2015 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover, or Back-Cover Texts. A copy of +the license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. + +All Emacs Lisp code contained in this document may be used, distributed, +and modified without restriction. +@end quotation +@end copying + +@titlepage +@title Debbugs User Guide +@author by Michael Albinus +@page +@insertcopying +@end titlepage + +@contents + +@node Top +@top Debbugs User Guide + +Debbugs is a bugtracking system (BTS) that was initially written for +the Debian project but actually used also by the GNU project. The +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. + +Based on the Debbugs/SOAP service, frontends are written which offer +handling of bugs inside Emacs. These frontends are restricted to the +GNU Debbugs server. Bugs are presented either as tabulated list +(@code{debbugs-gnu}) or as @code{org-mode} TODO list +(@code{debbugs-org}, @pxref{Top, , Org Mode, org}). As backend they +use the @code{debbugs} Emacs library (@pxref{Top, , Debbugs +Programmer's Manual, debbugs}). + +@menu +* Retrieving Bugs:: How to retrieve bugs. +* Searching Bugs:: How to search in the debbugs database. +* Layout:: How to results are presented. + +* Command Index:: Debbugs commands. +* Variable Index:: User options and variables. +* Key Index:: Keyboard strokes on bug report buffers. +@end menu + +@node Retrieving Bugs +@chapter Retrieving Bugs + +Bugs are retrieved by the @code{debbugs-gnu} or @code{debbugs-org} +commands. In their simple version, they retrieve just bugs for the +@code{"emacs"} package on the GNU Debbugs server, filtered by bug +severities. Further filtering is possible when the commands are +called with a prefix. + +When the bug numbers to be retrieved are known, the commands +@code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} are applicable. + + +@deffn {Command} debbugs-gnu severities &optional packages archivedp suppress tags +@deffnx {Command} debbugs-org severities &optional packages archivedp suppress tags + +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. + +@vindex debbugs-gnu-all-severities +@var{severities} is a list of strings which filter for the severities +of the bugs to be retrieved. Valid severities are @code{"serious"}, +@code{"important"}, @code{"normal"}, @code{"minor"} and +@code{"wishlist"} (see also the constant +@code{debbugs-gnu-all-severities}). If the list is empty, there is no +filtering with respect to severities. The keyword @code{"tagged"}, +which is also possible, is not a severity in the GNU Debbugs server +but allows to restrict the result to bugs with a given user tag. + +@vindex debbugs-gnu-all-packages +@var{packages}, also a list of strings, point to the defined software +packages on the GNU Debbugs server which shall be taken into account. +The existing package names are compiled into the constant +@code{debbugs-gnu-all-packages}. + +@var{archivedp}, if non-@code{nil}, extends the result also on +archived bugs on the GNU Debbugs server. + +@var{suppress} shall also distinct between @code{nil} and +non-@code{nil}. When non-@code{nil}, closed bugs are suppressed from +the results. + +When @var{severities} contains the severity @code{"tagged"}, +@var{tags} is consulted in order to restrict the result on bugs which +are tagged with one of the strings of the list @var{tags}. This list +can also be empty; in this case locally tagged bugs are included into +the results. + +Called interactively, the commands require just the @var{severities} +and the @var{tags} (if @var{severities} includes @code{"tagged"}). In +order to provide the other arguments interactively, the commands must +be called with a prefix, like @kbd{C-u M-x debbugs-gnu}. In the +minibuffer, lists must be entered comma-separated. + +@vindex debbugs-gnu-default-severities +@vindex debbugs-gnu-default-packages +Default values for interactive use could be configured in the customer +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 + + +@deffn {Command} debbugs-gnu-bugs &rest bugs +@deffnx {Command} debbugs-org-bugs &rest bugs + +The commands @code{debbugs-gnu-bugs} and @code{debbugs-org-bugs} show +bugs specified by their bug number. Interactively, the bug numbers +must be entered as comma-separated list. + +@ref{Layout} for the presentation of the results. + +@end deffn + + +@node Searching Bugs +@chapter Searching in the Debbugs Database. + +The GNU Debbugs server allows full text search in the database. It +uses a +@uref{http://fallabs.com/hyperestraier/uguide-en.html#searchcond, +HyperEstraier based search engine}@footnote{This has been added to the +Debbugs/SOAP backend of the GNU Debbugs server only.}. + +@deffn {Command} debbugs-gnu-search +@deffnx {Command} debbugs-org-search + +These both commands are completely interactive. They ask for a +@code{"search phrase"} for the full text search. It is just a string +which contains the words to be searched for, combined by operators +like AND, ANDNOT and OR. If there is no operator between the words, +AND is used by default. + +Wild card searches are also supported. It can be used for forward +match search and backward match search. For example, "[BW] euro" +matches words which begin with "euro". "[EW] shere" matches words +which end with "sphere". Moreover, regular expressions are also +supported. For example, "[RX] ^inter.*al$" matches words which begin +with "inter" and end with "al".@footnote{Simplified forms, as +described in the Hyperestraier User Guide, are not supported.} + +While the words to be searched for are case insensitive, the operators +must be specified case sensitive. + +While the search for the phrase is performed only in the bodies of the +messages belonging to a bug report, it is also possible to +discriminate the search to further bug attributes. The commands ask +for such key-value pairs, until an empty key is returned. Possible +attributes are + +@table @samp +@item severity +A comma-separated list of bug severities, @xref{Retrieving Bugs}. + +@item package +A comma-separated list of defined software packages on the GNU Debbugs +server, @xref{Retrieving Bugs}. + +@item tags +A comma-separated list of defined user tags. + +@item submitter +The address of the bug submitter. + +@item date +A time period the bug has been in which the bug has been submitted or +modified. + +@item subject +Word(s) the subject of the bug report contains. + +@item status +The status of the bug report. Valid values are "done", "forwarded" +and "open". +@end table + +It is also possible to apply these commands with an empty search +phrase. In this case, the GNU Debbugs server is searched only for +bugs which fulfill the given attributes. The attributes to be applied +are the same as already described, plus + +@table @samp +@item archive +Whether archived bugs shall be searched (no value to be entered). + +@item src +Bugs which belong to a given source, if that attribute has set. + +@item tag +An arbitrary string the bug is annotated with. Usually, this is the +same as the status mentioned above. + +@item owner +@itemx maint +@itemx correspondent +The email address of the bug's owner, maintainer, or correspondent +(somebody who has participated in bug messages). + +@item log_modified +@itemx last_modified +@itemx found_date +@itemx fixed_date +The date of the last update, or the date of the bug report / bug fix. + +@item unarchived +The date the bug has been unarchived, if ever. + +@item done +The email address of the worker who has closed the bug (if done). + +@item forwarded +A URL or an email address. + +@item msgid +The message id of the initial bug report. + +@item summary +The summary of the bug report. +@end table + +Not all of these attributes could be queried on the GNU Debbugs server +via the Debbugs/SOAP backend. In this case, the results of a query +are discriminated on the client side, which is indicated by the string +"(client-side filter)" in the minibuffer after the attribute name. +@end deffn + + +@node Layout +@chapter Layout + +The commands described in the previous chapters generate (a) report +buffer(s) applicable for navigation. @code{debbugs-gnu-*} return a +tabulated list, and @code{debbugs-org-*} return a list of TODO items +in @code{org-mode}. + +@menu +* Tabulated Lists:: Tabulated Lists. +* TODO Items:: TODO Items. +* 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. + +Different foreground colours present further information on the bug +report. If the bug number uses a red colour +(@code{debbugs-gnu-tagged}), the bug has been tagged locally. The +same face is used to mark bugs in the submitter or title column, when +the bug has been reported / is maintained by the user. + +The bug state could appear in different colours: red +(@code{debbugs-gnu-new}, nobody has answered yet to this bug), +ForestGreen (@code{debbugs-gnu-handled}, the bug has been modified +recently), MidnightBlue (@code{debbugs-gnu-pending}, the bug is +pending), orange (@code{debbugs-gnu-stale}, the bug has not been +touched for a while), and DarkGrey (@code{debbugs-gnu-done}, the bug +is closed). + +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} + +@item +@kindex @kbd{@key{RET}} +@kbd{@key{RET}} +@kindex @kbd{@key{mouse-1}} +@kbd{@key{mouse-1}} +@kindex @kbd{@key{mouse-2}} +@kbd{@key{mouse-2}} @tab +@code{debbugs-gnu-select-report} @* +Open a GNUS ephemeral group for that bug.@c (@pxref{xxx}). + +@* @item +@kindex @kbd{d} +@kbd{d} @tab +@code{debbugs-gnu-display-status} @* +Show all bug attributes. + +@c @item +@c @kindex @kbd{/} +@c @kbd{/} @tab +@c @code{debbugs-gnu-narrow-to-status} + +@c @item +@c @kindex @kbd{w} +@c @kbd{w} @tab +@c @code{debbugs-gnu-widen} + +@item +@kindex @kbd{g} +@kbd{g} @tab +@code{debbugs-gnu-rescan} @* +Reload all bugs from the GNU Debbugs server. + +@item +@kindex @kbd{B} +@kbd{B} @tab +@code{debbugs-gnu-show-blocking-reports} +@item +@kindex @kbd{b} +@kbd{b} @tab +@code{debbugs-gnu-show-blocked-by-reports} @* +Show all bug reports which are blocking / blocked by this bug. + +@item +@kindex @kbd{s} +@kbd{s} @tab +@code{debbugs-gnu-toggle-sort} @* +Toggle sorting order of bugs. + +@item +@kindex @kbd{t} +@kbd{t} @tab +@code{debbugs-gnu-toggle-tag} @* +Toggle local tag of bugs. + +@item +@kindex @kbd{x} +@kbd{x} @tab +@code{debbugs-gnu-toggle-suppress} @* +Toggle showing of closed bugs. + +@item +@kindex @kbd{C} +@kbd{C} @tab +@code{debbugs-gnu-send-control-message} @* +Send a control message for this bug, @ref{Control Messages}. + +@end multitable + + +@node TODO Items +@section TODO Items + +TODO items are offered as usual in @code{org-mode}. The bug +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: + +@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} + +@item +@kindex @kbd{@key{TAB}} +@kbd{@key{TAB}} @tab +@code{org-cycle} @* +Outline the bug report attributes in @code{org-mode}. + +@item +@kindex @kbd{C-c # d} +@kbd{C-c # d} @tab +@code{debbugs-gnu-display-status} @* +Show all bug attributes. + +@item +@kindex @kbd{C-c # t} +@kbd{C-c # t} @tab +@code{debbugs-gnu-toggle-tag} @* +Toggle local tag of bugs. + +@item +@kindex @kbd{C-c # C} +@kbd{C-c # C} @tab +@code{debbugs-gnu-send-control-message} @* +Send a control message for this bug, @ref{Control Messages}. + +@end multitable + +When the bug attributes are shown by @code{org-cycle}, there is a link +@code{Messages} which opens a GNUS ephemeral group for that bug.@c (@pxref{xxx}). + + +@node Control Messages +@section Control Messages + +Debbugs control messages are sent by email to the GNU Debbugs control +server. Their format is described in +@uref{http://debbugs.gnu.org/server-control.html}. + +A control message can be initiated in the tabulated list of bugs, in +the list of org TODO items, or in the GNUS ephemeral group opened for +the messages belonging to a given bug. In the minibuffer, the +following control messages can be requested (assuming that 12345 is +the bug the control message is intended for). The strings show the +exact format of the control messages. + +@table @samp +@item block +@itemx unblock +"block|unblock 12345 by 54321" + +The second bug number is read interactively. It could be also a list +of comma-separated bug numbers. + +@item close +"close 12345 25.1" + +The second argument, the Emacs version, is read interactively. + +@item confirmed +@itemx fixed +@itemx help +@itemx moreinfo +@itemx notabug +@itemx patch +@itemx pending +@itemx security +@itemx unreproducible +@itemx wontfix +"tags 12345 confirmed|fixed|help|moreinfo|notabug" + +"tags 12345 patch|pending|security|unreproducible|wontfix" + +@item done +@itemx donenotabug +@itemx doneunreproducible +@itemx donewontfix +"tags 12345 fixed|notabug|unreproducible|wontfix" @* +"close 12345 25.1" + +The second argument in the close message, the Emacs version, is read +interactively. + +@item forcemerge +@itemx merge +"forcemerge|merge 12345 54321" + +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" @* +"close 12345" + +@item noowner +"noowner 12345" + +@item owner +"owner 12345 !" + +@item reassign +"reassign 12345 @var{package}" + +The package name on the GNU Debbugs server is read interactively. + +@item reopen +"reopen 12345" + +@item unarchive +"unarchive 12345" + +@item unmerge +"unmerge 12345" + +@item usertag +"user @var{username}" @* +"usertag 12345 @var{tag}" + +The username, read interactively, is either a package name or an email +address. The tag to be set is also read interactively. +@end table + + +@node Command Index +@unnumbered Command Index +@printindex fn + + +@node Variable Index +@unnumbered Variable Index +@printindex vr + + +@node Key Index +@unnumbered Key Index +@printindex ky + +@bye