[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/debbugs c9989ec 133/311: New manual debbugs-ug.texi
From: |
Stefan Monnier |
Subject: |
[elpa] externals/debbugs c9989ec 133/311: New manual debbugs-ug.texi |
Date: |
Sun, 29 Nov 2020 18:41:56 -0500 (EST) |
branch: externals/debbugs
commit c9989ec993ba0086f8a4b88a85a31258bc9163ec
Author: Michael Albinus <michael.albinus@gmx.de>
Commit: Michael Albinus <michael.albinus@gmx.de>
New manual debbugs-ug.texi
---
debbugs-ug.texi | 550 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 550 insertions(+)
diff --git a/debbugs-ug.texi b/debbugs-ug.texi
new file mode 100644
index 0000000..453487c
--- /dev/null
+++ b/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
- [elpa] externals/debbugs d710aff 114/311: * debbugs-org.el (debbugs-org-show-reports): Add a minor mode header line., (continued)
- [elpa] externals/debbugs d710aff 114/311: * debbugs-org.el (debbugs-org-show-reports): Add a minor mode header line., Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 99fd49a 115/311: * debbugs-gnu.el (debbugs-gnu): Handle SUPPRESS properly., Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs e7d2d81 118/311: * debbugs-org.el (debbugs-org-ids): Declare it buffer-local., Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 9b62ae8 119/311: * debbugs-org.el (debbugs-org-show-next-reports): Use `org-sbe' if available., Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs c0648d6 121/311: * README: Fix command invocation., Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 394f5ff 122/311: * debbugs/debbugs-gnu.el (debbugs-gnu-default-packages): Remove w32, ns., Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 2e43897 127/311: Also suppress all locally tagged bug reports, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs cfb0bdb 128/311: Really allow narrowing to subject fields, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 3cf7c83 129/311: Make an empty `/' command display all the bugs, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs a0b4b2e 131/311: Require compile before using variables from that package, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs c9989ec 133/311: New manual debbugs-ug.texi,
Stefan Monnier <=
- [elpa] externals/debbugs 9ba8dcc 139/311: Minor improvements to debbugs-reference.el, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 8de636e 140/311: Rename debbugs-reference.el to debbugs-browse.el, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 4c9f22b 148/311: Command to list blocking reports, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs f4bc079 151/311: * debbugs-gnu.el (debbugs-gnu-narrow-to-status): Make narrowing to the severity work., Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 6d52539 143/311: Support reading debbugs email exchange with Rmail, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 02fa6d4 144/311: Version: bump to 0.8 in debbugs files, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 23786a1 146/311: * debbugs-gnu.el (debbugs-gnu-select-report): Don't bug out on the, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs ea69942 155/311: Allow patching from non-MIME articles, Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 78ad396 157/311: Further tweaks to the patch fixer-upper (for a/erc.el), Stefan Monnier, 2020/11/29
- [elpa] externals/debbugs 20cf154 160/311: Retrieve bugs asynchronously, Stefan Monnier, 2020/11/29