[elpa] externals/debbugs 5129bba 063/311: * debbugs.texi: New file.

[Stefan Monnier]

branch: externals/debbugs
commit 5129bba3464ff8519cf39f97bef916c080824bf0
Author: Michael Albinus <michael.albinus@gmx.de>
Commit: Michael Albinus <michael.albinus@gmx.de>

    * debbugs.texi: New file.
---
 ChangeLog    |   5 +
 debbugs.texi | 422 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 427 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 48666e9..84981a8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2011-07-17  Evgeny M. Zubok <zoubok@mail.ru>
+
+       * debbugs.texi: New file.
+
 2011-07-17  Michael Albinus  <michael.albinus@gmx.de>
 
        * debbugs-gnu.el (debbugs-gnu-get-bugs): It is sufficient to have
@@ -248,6 +252,7 @@
        (debbugs-done, debbugs-emacs, debbugs-mode-map, debbugs-mode)
        (debbugs-select-report, debbugs-summary-mode-map)
        (debbugs-summary-mode, debbugs-send-control-message): Move to ...
+
        * debbugs-gnu.el: New file.
 
 2011-07-02  Lars Magne Ingebrigtsen  <larsi@gnus.org>
diff --git a/debbugs.texi b/debbugs.texi
new file mode 100644
index 0000000..b0470f4
--- /dev/null
+++ b/debbugs.texi
@@ -0,0 +1,422 @@
+\input texinfo
+@setfilename debbugs.info
+@settitle Debbugs programmer's manual
+
+@dircategory Emacs
+@direntry
+* Debbugs: (debbugs).  A library for communication with Debbugs.
+@end direntry
+
+@copying
+Copyright @copyright{} 2011 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
+
+@node Top
+@top Debbugs programmer's manual
+Debbugs is a bugtracking system (BTS) that was initially written for
+Debian project but actually used also by 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 partucular 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 inconvinience the
+Debbugs/SOAP service was introduced.
+
+Debbugs/SOAP service provides the means for developer to write client
+application that can send the queries with certain search criteria to
+Debbugs server and retrieve a set of bug reports that match them. The
+developer may also ask Debbugs server for additional information about
+every bug report (e. g. subject, date, originator, tags and etc.) and
+get all comments and attachments.
+
+@code{debbugs}, described in this document, is the Emacs library that
+exposes to developer the available functions provided by Debbugs
+server. @code{debbugs} uses Emacs SOAP client library for communication
+with Debbugs server. In tandem with Emacs email facilities,
+@code{debbugs} provides a solution for building application that
+interacts with Debbugs BTS directly from Emacs without addressing
+Debbugs' web interface.
+
+@menu
+* Installation::                Getting and installing @code{debbugs}.
+* Configuration::               Configuring @code{debbugs}.
+* Requesting bug numbers::      How to request bug report numbers.
+* Requesting bugs statuses::    How to request status of bug report.
+* Requesting messages::         How to get messages from bug report.
+@end menu
+
+@node Installation
+@chapter Installation
+
+@subheading Installation on Emacs 24 or later
+Install @code{debbugs} from ELPA repository.
+
+@subheading Installation on Emacs 22 and Emacs 23
+If you want to install @code{debbugs} on Emacs 22/23, you will need to
+install @code{soap-client} library first. It can be downloaded from
+@uref{http://code.google.com/p/emacs-soap-client/, Emacs SOAP client
+project page}.
+
+Compile the library and add it into your @code{load-path}:
+
+@example
+(add-to-list 'load-path "/path/to/emacs-soap-client/")
+@end example
+
+@code{debbugs} library can be downloaded from
+@uref{http://elpa.gnu.org/packages/, ELPA repository}. Compile it and
+set the @code{load-path}: 
+
+@example
+(add-to-list 'load-path "/path/to/debbugs/")
+@end example
+
+@subheading Installation on Emacs 21
+We have not tried yet to install @code{debbugs} on Emacs 21. We would
+definitely say that the installation will require even more additional
+libraries than needed for installation on Emacs 22/23.
+
+@node Configuration
+@chapter Configuration
+@code{debbugs} is already configured to work with two main ports of
+Debbugs BTS: @uref{http://bugs.debian.org} and
+@uref{http://debbugs.gnu.org}. So if you intend to use these ports, you
+don't need to configure @code{debbugs}. If you want to interact with
+Debbugs port other than those listed, you have to configure
+@code{debbugs} by adding a new server specifier to
+@code{debbugs-servers} variable. The actual port can be selected by
+@code{debbugs-port} variable.
+
+@defvar debbugs-servers
+List of Debbugs server specifiers. Each entry is a list that contains a
+string identifying the port name and the server parameters in
+keyword-value form. The list initially contains two predefined and
+configured Debbugs servers: @code{"gnu.org"} and @code{"debian.org"}.
+
+Valid keywords are:
+
+@table @code
+@item :wsdl
+Location of WSDL. The value is a string with URL that should return the
+WSDL specification of Debbugs/SOAP service. This keyword is intended for
+future use and currently is ignored.
+@item :bugreport-url
+URL of the server script (@code{bugreport.cgi} in default Debbugs
+installation) that provides the access to mboxes with messages from bug
+reports.
+@end table
+
+Example. Add new Debbugs port with name "foobars.net":
+
+@example
+(add-to-list 
+ 'debbugs-servers 
+ '("foobars.net"
+   :wsdl "http://bugs.foobars.net/cgi/soap.cgi?WSDL";
+   :bugreport-url "http://bugs.foobars.net/cgi/bugreport.cgi";))
+@end example
+@end defvar
+
+@defvar debbugs-port
+This variable holds the name of currently used port. Value of the
+variable corresponds to the Debbugs server to be accessed, either
+"gnu.org", or "debian.org", or user defined port name.
+@end defvar
+
+@node Requesting bug numbers
+@chapter Requesting bug numbers
+In Debbugs BTS, the bug number is the unique identifier of bug
+report. The functions described in this section return from Debbugs
+server the list of bug numbers that match user's query.
+
+@defun debbugs-get-bugs &rest query
+This function returns a list of bug numbers that match the
+@var{query}. The @var{query} is a key-value pair sequence, where the key
+is a keyword (symbol) and the value is a string. All queries are
+logically concatenated via AND.
+
+Valid keywords are:
+
+@table @code
+@item :package
+The value is the name of the package a bug belongs to, like @code{"emacs"},
+@code{"coreutils"}, @code{"gnus"}, or @code{"tramp"}.
+@item :severity
+This is the severity of the bug. The exact set of available severities
+depends on policy of particular Debbugs port:
+
+Debian port:
+@code{"critical"}, @code{"grave"}, @code{"serious"},
+@code{"important"}, @code{"normal"}, @code{"minor"}, @code{"wishlist"},
+and @code{"fixed"}.
+
+GNU port: 
+@code{"important"}, @code{"grave"}, @code{"normal"}, @code{"minor"},
+@code{"wishlist"}.
+@item :tag 
+An arbitrary string the bug is annotated with. Usually, this is used to
+mark the status of the bug. The list of possible tags depends on Debbugs
+port.
+
+Debian port:
+@code{"patch"}, @code{"wontfix"}, @code{"moreinfo"},
+@code{"unreproducible"}, @code{"fixed"}, @code{"potato"},
+@code{"woody"}, @code{"sid"}, @code{"help"}, @code{"security"},
+@code{"upstream"}, @code{"pending"}, @code{"sarge"},
+@code{"sarge-ignore"}, @code{"experimental"}, @code{"d-i"},
+@code{"confirmed"}, @code{"ipv6"}, @code{"lfs"},
+@code{"fixed-in-experimental"}, @code{"fixed-upstream"}, @code{"l10n"},
+@code{"etch"}, @code{"etch-ignore"}, @code{"lenny"},
+@code{"lenny-ignore"}.
+
+GNU port: 
+@code{"fixed"}, @code{"notabug"}, @code{"wontfix"},
+@code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"}.
+@item :owner
+This is used to identify bugs by the owner's email address. The special
+email address @code{"me"} is used as pattern, replaced with variable
+@code{user-mail-address} (@pxref{(elisp)User Identification})
+@item :submitter
+With this keyword it is possible to filter bugs by the submitter's email
+address. The special email address @code{"me"} is used as pattern,
+replaced with variable @code{user-mail-address}.
+@item :archive
+A keyword to filter for bugs which are already archived, or not.  Valid
+values are @code{"0"} (not archived), @code{"1"} (archived) or
+@code{"both"}. If this keyword is not given in the query, @code{:archive
+"0"} is assumed by default.
+@end table
+
+Example. Get all bug reports that were initiated by me.
+
+@example
+(let ((debbugs-port "gnu.org"))
+  (debbugs-get-bugs :submitter "me" :archive "both"))
+@result{} (5516 5551 5645 7259)
+@end example
+@end defun
+
+@defun debbugs-newest-bugs amount
+This function returns a list of bug numbers, according to @var{amount}
+(a number) of latest bugs.
+
+Example. Get the latest six bug report numbers from Debian BTS:
+
+@example
+(let ((debbugs-port "debian.org"))
+  (debbugs-newest-bugs 6))
+@result{} (633152 633153 633154 633155 633156 633157)
+@end example
+@end defun
+
+@node Requesting bugs statuses
+@chapter Requesting bugs statuses
+Bug status is a collection of fields that holds the information about
+the state and importance of the bug report, about originator, owner and
+various aspects of relationship with other bug reports.
+
+@defun debbugs-get-status &rest bug-numbers
+Return a list of status entries for the bug reports identified by
+@var{bug-numbers}. Every returned entry is an association list with the
+following attributes:
+
+@table @code
+@item bug_num
+The bug number.
+@item package
+A list of package names the bug belongs to.
+@item severity
+The severity of the bug report. Possible values are the same as for
+@code{:severity} in @code{debbugs-get-bugs} (@pxref{Requesting bug
+numbers}).
+@item tags
+The status of the bug report, a list of strings. Possible values are the
+same as for @code{:tags} in @code{debbugs-get-bugs} (@pxref{Requesting
+bug numbers}).
+@item pending
+The string @code{"pending"}, @code{"forwarded"} or @code{"done"}.
+@item subject
+Subject/Title of the bugreport.
+@item originator
+The E-mail address of bug report submitter.
+@item mergedwith
+A list of bug numbers this bug was merged with.
+@item source
+Source package name of the bug report.
+@item date
+Date of bug creation. Encoded as UNIX time.
+@item log_modified
+@item last_modified
+Date of last update. Encoded as UNIX time.
+@item found_date
+@item fixed_date
+Date of bug report / bug fix (empty for now). Encoded as UNIX time.
+@item done
+The E-mail address of the worker who has closed the bug (if done).
+@item archived
+@code{t} if the bug is archived, @code{nil} otherwise.
+@item unarchived
+The date the bug has been unarchived, if ever. Encoded as UNIX time.
+@item found_versions
+@item fixed_versions
+List of version strings.
+@item forwarded
+A URL or an E-mail address.
+@item blocks
+A list of bug numbers this bug blocks.
+@item blockedby
+A list of bug numbers this bug is blocked by.
+@item msgid
+The message id of the initial bug report.
+@item owner
+Who is responsible for fixing.
+@item location
+Always the string @code{"db-h"} or @code{"archive"}.
+@item affects
+A list of package names.
+@item summary
+Arbitrary text.
+@end table
+
+Example. Get status of bug number #10 from GNU BTS:
+
+@example
+(let ((debbugs-port "gnu.org"))
+  (debbugs-get-status 10))
+@result{}
+(((source . "unknown") (found_versions) (done) (blocks)
+  (date . 1203606305.0) (fixed) (fixed_versions) (mergedwith) 
+  (found) (unarchived) (blockedby) (keywords) (summary) 
+  (msgid . "<87zltuz7eh.fsf@@freemail.hu>") (id . 10) 
+  (forwarded) (severity . "wishlist") 
+  (owner . "Magnus Henoch <*****@@freemail.hu>")
+  (log_modified . 1310061242.0) (location . "db-h") 
+  (subject . "url-gw should support HTTP CONNECT proxies") 
+  (originator . "Magnus Henoch <*****@@freemail.hu>")
+  (last_modified . 1310061242.0) (pending . "pending") (affects) 
+  (archived) (tags) (fixed_date) (package "emacs") (found_date) 
+  (bug_num . 10)))
+@end example
+@end defun
+
+@defun debbugs-get-attribute bug-or-message attribute
+General accessor that returns the value of key
+@var{attribute}. @var{bug-or-message} must be list element returned by
+either @code{debbugs-get-status} or @code{debbugs-get-bug-log}.
+
+Example. Return the originator of last submitted bug report:
+
+@example
+(let ((debbags-port "gnu.org"))
+  (debbugs-get-attribute
+   (car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
+   'originator))
+@result{} "Jack Daniels <jack@@daniels.com>"
+@end example
+@end defun
+
+@node Requesting messages
+@chapter Requesting messages
+
+@defun debbugs-get-bug-log bug-number
+Returns a list of messages related to @var{bug-number}. Every message is
+an association list with the following attributes:
+
+@table @code
+@item msg_num
+The number of the message inside the bug log. The numbers are ascending,
+newer messages have a higher number.
+@item header
+The header lines from the E-mail messages, as arrived at the bug
+tracker.
+@item body
+The message body.
+@item attachments
+A list of possible attachments, or @code{nil}. Not implemented yet server
+side.
+@end table
+@end defun
+
+@defun debbugs-get-message-numbers messages
+Returns the message numbers of @var{messages}. @var{messages} must be
+the result of a @code{debbugs-get-bug-log} call.
+
+Example. Get message numbers from bug report #456789 log from Debian
+BTS:
+
+@example
+(let ((debbugs-port "debian.org"))
+   (debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
+@result{} (5 10 12)
+@end example
+@end defun
+
+@defun debbugs-get-message messages message-number
+Returns the message @var{message-number} of
+@var{messages}. @var{messages} must be the result of a
+@code{debbugs-get-bug-log} call. The returned message is a list of
+strings. The first element are the header lines of the message, the
+second element is the body of the message. Further elements of the list,
+if any, are attachments of the message. If there is no message with
+@var{message-number}, the function returns @code{nil}.
+
+Example: Return the first message of last submitted bug report to Debian
+BTS:
+
+@example
+(let* ((debbugs-port "gnu.org")
+       (messages (apply 'debbugs-get-bug-log 
+                       (debbugs-newest-bugs 1))))
+  (debbugs-get-message 
+   messages
+   (car (debbugs-get-message-numbers messages))))
+@end example
+@end defun
+
+@defun debbugs-get-mbox bug-number mbox-type &optional filename
+Download mbox with all messages from bug report
+@var{bug-number}. @var{mbox-type} specifies a type of mbox and can be
+one of the following symbols:
+
+@table @code
+@item mboxfolder
+Download mbox folder, i. e. mbox with messages as they arrived at
+Debbugs server.
+@item mboxmaint
+Download maintainer's mbox, i. e. mbox with messages as they are
+resended from Debbugs server.
+@item mboxstat
+@item mboxstatus
+Download status mbox. The use of either symbol depends on actual Debbugs
+server configuration. For gnu.org, use the former; for debian.org - the
+latter.
+@end table
+
+@var{filename}, if non-@code{nil}, is the name of file to store mbox. If
+@var{filename} is @code{nil}, the downloaded mbox is inserted into the
+current buffer.
+
+Note that mbox downloading will work only if the @code{:bugreport-url}
+field of @code{debbugs-servers} variable is specified
+(@pxref{Configuration}).
+@end defun
+
+@bye