--- /dev/null
+This is debbugs.info, produced by makeinfo version 5.0 from
+debbugs.texi.
+
+Copyright (C) 2011-2015 Free Software Foundation, Inc.
+
+ 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.
+INFO-DIR-SECTION Emacs
+START-INFO-DIR-ENTRY
+* Debbugs: (debbugs). A library for communication with Debbugs.
+END-INFO-DIR-ENTRY
+
+\1f
+File: debbugs.info, Node: Top, Next: Installation, Up: (dir)
+
+Debbugs Programmer's Manual
+***************************
+
+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.
+
+ The Debbugs/SOAP service provides the means for developers to write
+client applications that can send the queries with certain search
+criteria to the Debbugs server and retrieve a set of bug reports that
+match them. The developer may also ask the Debbugs server for
+additional information about every bug report (e.g. subject, date,
+originator, tags and etc.) and get all comments and attachments.
+
+ 'debbugs', described in this document, is the Emacs library that
+exposes to developers the available functions provided by the Debbugs
+server. 'debbugs' uses Emacs' SOAP client library for communication
+with the Debbugs server. In tandem with Emacs' email facilities,
+'debbugs' provides a solution for building applications that interact
+with the Debbugs BTS directly from Emacs without addressing Debbugs' web
+interface.
+
+* Menu:
+
+* Installation:: Getting and installing 'debbugs'.
+* Configuration:: Configuring 'debbugs'.
+* Requesting bug numbers:: How to request bug report numbers.
+* Requesting bugs statuses:: How to request the status of bug reports.
+* Requesting messages:: How to get messages from bug reports.
+* Requesting user tags:: How to request tags set by users.
+
+\1f
+File: debbugs.info, Node: Installation, Next: Configuration, Prev: Top, Up: Top
+
+1 Installation
+**************
+
+Installation on Emacs 24 or later
+---------------------------------
+
+Install 'debbugs' from the *note ELPA repository: (elisp)Packaging.
+
+Installation on Emacs 22 and Emacs 23
+-------------------------------------
+
+If you want to install 'debbugs' on Emacs 22/23, you will need to
+install the 'soap-client' library first. It can be downloaded from the
+Emacs SOAP client project page
+(http://code.google.com/p/emacs-soap-client/).
+
+ Compile the library and add it into your 'load-path':
+
+ (add-to-list 'load-path "/path/to/emacs-soap-client/")
+
+ 'debbugs' library can be downloaded from the ELPA repository
+(http://elpa.gnu.org/packages/). Compile it and set the 'load-path':
+
+ (add-to-list 'load-path "/path/to/debbugs/")
+
+Installation on Emacs 21
+------------------------
+
+We have not tried yet to install '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.
+
+\1f
+File: debbugs.info, Node: Configuration, Next: Requesting bug numbers, Prev: Installation, Up: Top
+
+2 Configuration
+***************
+
+'debbugs' is already configured to work with two main ports of Debbugs
+BTS: <http://bugs.debian.org> and <http://debbugs.gnu.org>. So if you
+intend to use one of these ports, you don't need to configure 'debbugs'.
+If you want to interact with a Debbugs port other than those listed, you
+have to configure 'debbugs' by adding a new server specifier to the
+'debbugs-servers' variable. The actual port can be selected by the
+'debbugs-port' variable.
+
+ -- Variable: 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: '"gnu.org"' and
+ '"debian.org"'.
+
+ Valid keywords are:
+
+ ':wsdl'
+ Location of WSDL. The value is a string with the URL that
+ should return the WSDL specification of the Debbugs/SOAP
+ service. This keyword is intended for future use, it is
+ ignored currently.
+
+ ':bugreport-url'
+ The URL of the server script ('bugreport.cgi' in the default
+ Debbugs installation) that provides the access to mboxes with
+ messages from bug reports.
+
+ Example. Add a new Debbugs port with name "foobars.net":
+
+ (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"))
+
+ -- Variable: debbugs-port
+ This variable holds the name of the currently used port. The value
+ of the variable corresponds to the Debbugs server to be accessed,
+ either '"gnu.org"' or '"debian.org"', or a user defined port name.
+
+\1f
+File: debbugs.info, Node: Requesting bug numbers, Next: Requesting bugs statuses, Prev: Configuration, Up: Top
+
+3 Requesting bug numbers
+************************
+
+In Debbugs BTS, the bug number is the unique identifier of a bug report.
+The functions described in this section return from the Debbugs server
+the list of bug numbers that match a user's query.
+
+ -- Function: debbugs-get-bugs &rest query
+ This function returns a list of bug numbers that match the QUERY.
+ QUERY is a sequence of keyword-value pairs where the values are
+ strings, i.e. :KEYWORD "VALUE" [:KEYWORD "VALUE"]*
+
+ The keyword-value pair is a subquery. The keywords are allowed to
+ have multiple occurrence within the query at any place. The
+ subqueries with the same keyword form the logical subquery, which
+ returns the union of bugs of every subquery it contains.
+
+ The result of the QUERY is an intersection of results of all
+ subqueries.
+
+ Valid keywords are:
+
+ ':package'
+ The value is the name of the package a bug belongs to, like
+ '"emacs"', '"coreutils"', '"gnus"', or '"tramp"'.
+
+ ':src'
+ This is used to retrieve bugs that belong to source with given
+ name.
+
+ ':severity'
+ This is the severity of the bug. The exact set of available
+ severities depends on the policy of a particular Debbugs port:
+
+ Debian port: '"critical"', '"grave"', '"serious"',
+ '"important"', '"normal"', '"minor"', '"wishlist"', and
+ '"fixed"'.
+
+ GNU port: '"serious"', '"important"', '"normal"', '"minor"',
+ '"wishlist"'.
+
+ ':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 the Debbugs port.
+
+ Debian port: '"patch"', '"wontfix"', '"moreinfo"',
+ '"unreproducible"', '"fixed"', '"potato"', '"woody"', '"sid"',
+ '"help"', '"security"', '"upstream"', '"pending"', '"sarge"',
+ '"sarge-ignore"', '"experimental"', '"d-i"', '"confirmed"',
+ '"ipv6"', '"lfs"', '"fixed-in-experimental"',
+ '"fixed-upstream"', '"l10n"', '"etch"', '"etch-ignore"',
+ '"lenny"', '"lenny-ignore"', '"squeeze"', '"squeeze-ignore"',
+ '"wheezy"', '"wheezy-ignore"'. The actual list of tags can be
+ found on <http://www.debian.org/Bugs/Developer#tags>.
+
+ GNU port: '"fixed"', '"notabug"', '"wontfix"',
+ '"unreproducible"', '"moreinfo"', '"patch"', '"pending"',
+ '"help"', '"security"', '"confirmed"'. See
+ <http://debbugs.gnu.org/Developer.html#tags> for the actual
+ list of tags.
+
+ ':owner'
+ This is used to identify bugs by the owner's email address.
+ The special email address '"me"' is used as pattern, replaced
+ with the variable 'user-mail-address' (*note (elisp)User
+ Identification::).
+
+ ':submitter'
+ With this keyword it is possible to filter bugs by the
+ submitter's email address. The special email address '"me"'
+ is used as pattern, replaced with the variable
+ 'user-mail-address'.
+
+ ':maint'
+ This is used to find bugs of the packages which are maintained
+ by the person with the given email address. The special email
+ address '"me"' is used as pattern, replaced with
+ 'user-mail-address'.
+
+ ':correspondent'
+ This allows to find bug reports where the person with the
+ given email address has participated. The special email
+ address '"me"' is used as pattern, replaced with
+ 'user-mail-address'.
+
+ ':affects'
+ With this keyword it is possible to find bugs which affect the
+ package with the given name. The bugs are chosen by the value
+ of field 'affects' in bug's status. The returned bugs do not
+ necessary belong to this package.
+
+ ':status'
+ Status of bug. Valid values are '"done"', '"forwarded"' and
+ '"open"'.
+
+ ':archive'
+ A keyword to filter for bugs which are already archived, or
+ not. Valid values are '"0"' (not archived), '"1"' (archived)
+ or '"both"'. If this keyword is not given in the query,
+ ':archive "0"' is assumed by default.
+
+ Example. Get all opened and forwarded release critical bugs for
+ the packages which are maintained by '"me"' and which have a patch:
+
+ (let ((debbugs-port "debian.org"))
+ (debbugs-get-bugs :maint "me" :tag "patch"
+ :severity "critical"
+ :status "open"
+ :severity "grave"
+ :status "forwarded"
+ :severity "serious"))
+
+ -- Function: debbugs-newest-bugs amount
+ This function returns a list of bug numbers, according to AMOUNT (a
+ number) of latest bugs.
+
+ Example. Get the latest six bug report numbers from Debian BTS:
+
+ (let ((debbugs-port "debian.org"))
+ (debbugs-newest-bugs 6))
+ => (633152 633153 633154 633155 633156 633157)
+
+\1f
+File: debbugs.info, Node: Requesting bugs statuses, Next: Requesting messages, Prev: Requesting bug numbers, Up: Top
+
+4 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.
+
+ -- Function: debbugs-get-status &rest bug-numbers
+ Return a list of status entries for the bug reports identified by
+ BUG-NUMBERS. Every returned entry is an association list with the
+ following attributes:
+
+ 'id'
+ 'bug_num'
+ The bug number.
+
+ 'package'
+ A list of package names the bug belongs to.
+
+ 'severity'
+ The severity of the bug report. Possible values are the same
+ as for ':severity' in 'debbugs-get-bugs' (*note Requesting bug
+ numbers::).
+
+ 'tags'
+ The status of the bug report, a list of strings. Possible
+ values are the same as for ':tags' in 'debbugs-get-bugs'
+ (*note Requesting bug numbers::).
+
+ 'pending'
+ The string '"pending"', '"forwarded"' or '"done"'.
+
+ 'subject'
+ Subject/Title of the bugreport.
+
+ 'originator'
+ The E-mail address of the bug report submitter.
+
+ 'mergedwith'
+ A list of bug numbers this bug was merged with.
+
+ 'source'
+ Source package name of the bug report.
+
+ 'date'
+ Date of bug creation. Encoded as UNIX time.
+
+ 'log_modified'
+ 'last_modified'
+ Date of last update. Encoded as UNIX time.
+
+ 'found_date'
+ 'fixed_date'
+ Date of bug report / bug fix (empty for now). Encoded as UNIX
+ time.
+
+ 'done'
+ The E-mail address of the worker who has closed the bug (if
+ done).
+
+ 'archived'
+ 't' if the bug is archived, 'nil' otherwise.
+
+ 'unarchived'
+ The date the bug has been unarchived, if ever. Encoded as
+ UNIX time.
+
+ 'found_versions'
+ 'fixed_versions'
+ List of version strings.
+
+ 'forwarded'
+ A URL or an E-mail address.
+
+ 'blocks'
+ A list of bug numbers this bug blocks.
+
+ 'blockedby'
+ A list of bug numbers this bug is blocked by.
+
+ 'msgid'
+ The message id of the initial bug report.
+
+ 'owner'
+ Who is responsible for fixing.
+
+ 'location'
+ Always the string '"db-h"' or '"archive"'.
+
+ 'affects'
+ A list of package names.
+
+ 'summary'
+ Arbitrary text.
+
+ Example. Get the status of bug number #10 from GNU BTS:
+
+ (let ((debbugs-port "gnu.org"))
+ (debbugs-get-status 10))
+ =>
+ (((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)))
+
+ -- Function: debbugs-get-attribute bug-or-message attribute
+ General accessor that returns the value of key ATTRIBUTE.
+ BUG-OR-MESSAGE must be a list element returned by either
+ 'debbugs-get-status' or 'debbugs-get-bug-log' (*note Requesting
+ messages::).
+
+ Example. Return the originator of the last submitted bug report:
+
+ (let ((debbags-port "gnu.org"))
+ (debbugs-get-attribute
+ (car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
+ 'originator))
+ => "Jack Daniels <jack@daniels.com>"
+
+\1f
+File: debbugs.info, Node: Requesting messages, Next: Requesting user tags, Prev: Requesting bugs statuses, Up: Top
+
+5 Requesting messages
+*********************
+
+ -- Function: debbugs-get-bug-log bug-number
+ Returns a list of messages related to BUG-NUMBER. Every message is
+ an association list with the following attributes:
+
+ 'msg_num'
+ The number of the message inside the bug log. The numbers are
+ ascending, newer messages have a higher number.
+ 'header'
+ The header lines from the E-mail messages, as arrived at the
+ bug tracker.
+ 'body'
+ The message body.
+ 'attachments'
+ A list of possible attachments, or 'nil'. Not implemented yet
+ server side.
+
+ -- Function: debbugs-get-message-numbers messages
+ Returns the message numbers of MESSAGES. MESSAGES must be the
+ result of a 'debbugs-get-bug-log' call.
+
+ Example. Get message numbers from bug report #456789 log from
+ Debian BTS:
+
+ (let ((debbugs-port "debian.org"))
+ (debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
+ => (5 10 12)
+
+ -- Function: debbugs-get-message messages message-number
+ Returns the message MESSAGE-NUMBER of MESSAGES. MESSAGES must be
+ the result of a '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 MESSAGE-NUMBER, the function
+ returns 'nil'.
+
+ Example: Return the first message of the last submitted bug report
+ to GNU BTS:
+
+ (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))))
+
+ -- Function: debbugs-get-mbox bug-number mbox-type &optional filename
+ Download mbox with all messages from bug report BUG-NUMBER.
+ MBOX-TYPE specifies a type of mbox and can be one of the following
+ symbols:
+
+ 'mboxfolder'
+ Download mbox folder, i.e. mbox with messages as they arrived
+ at the Debbugs server.
+
+ 'mboxmaint'
+ Download maintainer's mbox, i.e. mbox with messages as they
+ are resent from the Debbugs server.
+
+ 'mboxstat'
+ 'mboxstatus'
+ Download status mbox. The use of either symbol depends on the
+ actual Debbugs server configuration. For '"gnu.org"', use the
+ former; for '"debian.org' - the latter.
+
+ FILENAME, if non-'nil', is the name of the file to store mbox. If
+ FILENAME is 'nil', the downloaded mbox is inserted into the current
+ buffer.
+
+ Note, that mbox downloading will work only if the ':bugreport-url'
+ field of the 'debbugs-servers' variable is specified (*note
+ Configuration::).
+
+\1f
+File: debbugs.info, Node: Requesting user tags, Prev: Requesting messages, Up: Top
+
+6 Requesting user tags
+**********************
+
+A user tag is a string, a user has assigned to one or several bugs. The
+user is identified by an email address. The port '"gnu.org"' uses also
+package names as user identification.
+
+ -- Function: debbugs-get-usertag &rest query
+ Return a list of bug numbers which match QUERY.
+
+ QUERY is a sequence of keyword-value pairs where the values are
+ strings, i.e. :KEYWORD "VALUE" [:KEYWORD "VALUE"]*
+
+ Valid keywords are:
+
+ ':user'
+ The value is the name of the package a bug belongs to, like
+ '"emacs"', '"coreutils"', or '"tramp"'. It can also be an
+ email address of a user who has applied a user tag. The
+ special email address '"me"' is used as pattern, replaced with
+ 'user-mail-address'. There must be at least one such entry;
+ it is recommended to have exactly one.
+
+ ':tag'
+ A string applied as user tag. Often, it is a subproduct
+ identification, like '"cedet"' or '"tramp"' for the package
+ '"emacs"'.
+
+ If there is no ':tag' entry, no bug numbers will be returned but a
+ list of existing user tags for ':user'.
+
+ Example. Get all user tags for the package '"emacs"':
+
+ (let ((debbugs-port "gnu.org"))
+ (debbugs-get-usertag :user "emacs"))
+ => ("www" "solaris" "ls-lisp" "cygwin")
+
+ Get all bugs tagged by package '"emacs"' with '"www"' or
+ '"cygwin"')):
+
+ (let ((debbugs-port "gnu.org"))
+ (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
+ => (807 1223 5637)
+
+
+\1f
+Tag Table:
+Node: Top\7f1089
+Node: Installation\7f3042
+Node: Configuration\7f4141
+Node: Requesting bug numbers\7f6047
+Node: Requesting bugs statuses\7f11275
+Node: Requesting messages\7f15326
+Node: Requesting user tags\7f18342
+\1f
+End Tag Table