[elpa] externals/debbugs c9989ec 133/311: New manual debbugs-ug.texi

[Stefan Monnier]

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