[elpa] master de5e933 1/3: New manual debbugs-ug.texi

[Michael Albinus]

branch: master
commit de5e933706472f50f678c55a4509db34d713956a
Author: Michael Albinus <address@hidden>
Commit: Michael Albinus <address@hidden>

    New manual debbugs-ug.texi
---
 packages/debbugs/debbugs-ug.texi |  550 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 550 insertions(+), 0 deletions(-)

diff --git a/packages/debbugs/debbugs-ug.texi b/packages/debbugs/debbugs-ug.texi
new file mode 100644
index 0000000..453487c
--- /dev/null
+++ b/packages/debbugs/debbugs-ug.texi
@@ -0,0 +1,550 @@
+\input texinfo
address@hidden debbugs-ug.info
address@hidden Debbugs User Guide
+
address@hidden Emacs
address@hidden
+* Debbugs UG: (debbugs-ug).  Debbugs User Interface in Emacs.
address@hidden direntry
+
address@hidden
+Copyright @copyright{} 2015 Free Software Foundation, Inc.
+
address@hidden
+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.
address@hidden quotation
address@hidden copying
+
address@hidden
address@hidden Debbugs User Guide
address@hidden by Michael Albinus
address@hidden
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden Top
address@hidden 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}).
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Retrieving Bugs
address@hidden 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
address@hidden"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
address@hidden or @code{debbugs-org-bugs} are applicable.
+
+
address@hidden  {Command} debbugs-gnu severities &optional packages archivedp 
suppress tags
address@hidden {Command} debbugs-org severities &optional packages archivedp 
suppress tags
+
+These commands retrieve bug reports from the GNU Debbugs server.
address@hidden 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.
+
address@hidden debbugs-gnu-all-severities
address@hidden is a list of strings which filter for the severities
+of the bugs to be retrieved.  Valid severities are @code{"serious"},
address@hidden"important"}, @code{"normal"}, @code{"minor"} and
address@hidden"wishlist"} (see also the constant
address@hidden).  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.
+
address@hidden debbugs-gnu-all-packages
address@hidden, 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
address@hidden
+
address@hidden, if address@hidden, extends the result also on
+archived bugs on the GNU Debbugs server.
+
address@hidden shall also distinct between @code{nil} and
address@hidden  When address@hidden, closed bugs are suppressed from
+the results.
+
+When @var{severities} contains the severity @code{"tagged"},
address@hidden 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.
+
address@hidden debbugs-gnu-default-severities
address@hidden debbugs-gnu-default-packages
+Default values for interactive use could be configured in the customer
+options @code{debbugs-gnu-default-severities} and
address@hidden
+
address@hidden 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.
+
address@hidden for the presentation of the results.
+
address@hidden deffn
+
+
address@hidden  {Command} debbugs-gnu-bugs &rest bugs
address@hidden {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.
+
address@hidden for the presentation of the results.
+
address@hidden deffn
+
+
address@hidden Searching Bugs
address@hidden Searching in the Debbugs Database.
+
+The GNU Debbugs server allows full text search in the database.  It
+uses a
address@hidden://fallabs.com/hyperestraier/uguide-en.html#searchcond,
+HyperEstraier based search address@hidden has been added to the
+Debbugs/SOAP backend of the GNU Debbugs server only.}.
+
address@hidden  {Command} debbugs-gnu-search
address@hidden {Command} debbugs-org-search
+
+These both commands are completely interactive.  They ask for a
address@hidden"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"address@hidden 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
+
address@hidden @samp
address@hidden severity
+A comma-separated list of bug severities, @xref{Retrieving Bugs}.
+
address@hidden package
+A comma-separated list of defined software packages on the GNU Debbugs
+server, @xref{Retrieving Bugs}.
+
address@hidden tags
+A comma-separated list of defined user tags.
+
address@hidden submitter
+The address of the bug submitter.
+
address@hidden date
+A time period the bug has been in which the bug has been submitted or
+modified.
+
address@hidden subject
+Word(s) the subject of the bug report contains.
+
address@hidden status
+The status of the bug report.  Valid values are "done", "forwarded"
+and "open".
address@hidden 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
+
address@hidden @samp
address@hidden archive
+Whether archived bugs shall be searched (no value to be entered).
+
address@hidden src
+Bugs which belong to a given source, if that attribute has set.
+
address@hidden tag
+An arbitrary string the bug is annotated with.  Usually, this is the
+same as the status mentioned above.
+
address@hidden  owner
address@hidden maint
address@hidden correspondent
+The email address of the bug's owner, maintainer, or correspondent
+(somebody who has participated in bug messages).
+
address@hidden  log_modified
address@hidden last_modified
address@hidden found_date
address@hidden fixed_date
+The date of the last update, or the date of the bug report / bug fix.
+
address@hidden unarchived
+The date the bug has been unarchived, if ever.
+
address@hidden done
+The email address of the worker who has closed the bug (if done).
+
address@hidden forwarded
+A URL or an email address.
+
address@hidden msgid
+The message id of the initial bug report.
+
address@hidden summary
+The summary of the bug report.
address@hidden 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.
address@hidden deffn
+
+
address@hidden Layout
address@hidden 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}.
+
address@hidden
+* Tabulated Lists::             Tabulated Lists.
+* TODO Items::                  TODO Items.
+* Control Messages::            Control Messages.
address@hidden menu
+
address@hidden Tabulated Lists
address@hidden 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),
address@hidden (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
address@hidden  This enables the following key strokes:
+
address@hidden address@hidden@key{mouse-2}}} {Some very very very long long 
text Some very very very long long text Some very very very long long text}
+
address@hidden
address@hidden @address@hidden
address@hidden@key{RET}}
address@hidden @address@hidden
address@hidden@key{mouse-1}}
address@hidden @address@hidden
address@hidden@key{mouse-2}} @tab
address@hidden @*
+Open a GNUS ephemeral group for that address@hidden (@pxref{xxx}).
+
address@hidden @item
address@hidden @kbd{d}
address@hidden @tab
address@hidden @*
+Show all bug attributes.
+
address@hidden @item
address@hidden @kindex @kbd{/}
address@hidden @kbd{/} @tab
address@hidden @code{debbugs-gnu-narrow-to-status}
+
address@hidden @item
address@hidden @kindex @kbd{w}
address@hidden @kbd{w} @tab
address@hidden @code{debbugs-gnu-widen}
+
address@hidden
address@hidden @kbd{g}
address@hidden @tab
address@hidden @*
+Reload all bugs from the GNU Debbugs server.
+
address@hidden
address@hidden @kbd{B}
address@hidden @tab
address@hidden
address@hidden
address@hidden @kbd{b}
address@hidden @tab
address@hidden @*
+Show all bug reports which are blocking / blocked by this bug.
+
address@hidden
address@hidden @kbd{s}
address@hidden @tab
address@hidden @*
+Toggle sorting order of bugs.
+
address@hidden
address@hidden @kbd{t}
address@hidden @tab
address@hidden @*
+Toggle local tag of bugs.
+
address@hidden
address@hidden @kbd{x}
address@hidden @tab
address@hidden @*
+Toggle showing of closed bugs.
+
address@hidden
address@hidden @kbd{C}
address@hidden @tab
address@hidden @*
+Send a control message for this bug, @ref{Control Messages}.
+
address@hidden multitable
+
+
address@hidden TODO Items
address@hidden 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
address@hidden
+
+The bug report buffers have enabled the minor
address@hidden  This enables the following key strokes:
+
address@hidden address@hidden # C}} {Some very very very long long text Some 
very very very long long text Some very very very long long text}
+
address@hidden
address@hidden @address@hidden
address@hidden@key{TAB}} @tab
address@hidden @*
+Outline the bug report attributes in @code{org-mode}.
+
address@hidden
address@hidden @kbd{C-c # d}
address@hidden # d} @tab
address@hidden @*
+Show all bug attributes.
+
address@hidden
address@hidden @kbd{C-c # t}
address@hidden # t} @tab
address@hidden @*
+Toggle local tag of bugs.
+
address@hidden
address@hidden @kbd{C-c # C}
address@hidden # C} @tab
address@hidden @*
+Send a control message for this bug, @ref{Control Messages}.
+
address@hidden multitable
+
+When the bug attributes are shown by @code{org-cycle}, there is a link
address@hidden which opens a GNUS ephemeral group for that address@hidden 
(@pxref{xxx}).
+
+
address@hidden Control Messages
address@hidden Control Messages
+
+Debbugs control messages are sent by email to the GNU Debbugs control
+server.  Their format is described in
address@hidden://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.
+
address@hidden @samp
address@hidden block
address@hidden unblock
+"block|unblock 12345 by 54321"
+
+The second bug number is read interactively.  It could be also a list
+of comma-separated bug numbers.
+
address@hidden close
+"close 12345 25.1"
+
+The second argument, the Emacs version, is read interactively.
+
address@hidden confirmed
address@hidden fixed
address@hidden help
address@hidden moreinfo
address@hidden notabug
address@hidden patch
address@hidden pending
address@hidden security
address@hidden unreproducible
address@hidden wontfix
+"tags 12345 confirmed|fixed|help|moreinfo|notabug"
+
+"tags 12345 patch|pending|security|unreproducible|wontfix"
+
address@hidden done
address@hidden donenotabug
address@hidden doneunreproducible
address@hidden donewontfix
+"tags 12345 fixed|notabug|unreproducible|wontfix" @*
+"close 12345 25.1"
+
+The second argument in the close message, the Emacs version, is read
+interactively.
+
address@hidden forcemerge
address@hidden merge
+"forcemerge|merge 12345 54321"
+
+The second bug number is read interactively.
+
address@hidden important
address@hidden minor
address@hidden normal
address@hidden serious
address@hidden wishlist
+"severity 12345 important|minor|normal|serious|wishlist"
+
address@hidden invalid
+"tags 12345 notabug" @*
+"tags 12345 wontfix" @*
+"close 12345"
+
address@hidden noowner
+"noowner 12345"
+
address@hidden owner
+"owner 12345 !"
+
address@hidden reassign
+"reassign 12345 @var{package}"
+
+The package name on the GNU Debbugs server is read interactively.
+
address@hidden reopen
+"reopen 12345"
+
address@hidden unarchive
+"unarchive 12345"
+
address@hidden unmerge
+"unmerge 12345"
+
address@hidden 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.
address@hidden table
+
+
address@hidden Command Index
address@hidden Command Index
address@hidden fn
+
+
address@hidden Variable Index
address@hidden Variable Index
address@hidden vr
+
+
address@hidden Key Index
address@hidden Key Index
address@hidden ky
+
address@hidden