]> code.delx.au - gnu-emacs-elpa/blobdiff - packages/debbugs/debbugs.texi
Clean up copyright notices.
[gnu-emacs-elpa] / packages / debbugs / debbugs.texi
index b0470f4431f51d3b8fa4669dbd1b8337904b3efc..9cbb3c2ba14f425f47c7a9529860bed48b88d6b0 100644 (file)
@@ -14,7 +14,7 @@ Copyright @copyright{} 2011 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
 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
+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.
 
 the license is included in the section entitled ``GNU Free Documentation
 License'' in the Emacs manual.
 
@@ -28,51 +28,64 @@ and modified without restriction.
 @end quotation
 @end copying
 
 @end quotation
 @end copying
 
+@titlepage
+@title Debbugs Programmer's Manual
+@author by Evgeny M. Zubok
+@page
+@insertcopying
+@end titlepage
+
+@contents
+
 @node Top
 @node Top
-@top Debbugs programmer's manual
+@top Debbugs Programmer's Manual
+
 Debbugs is a bugtracking system (BTS) that was initially written for
 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,
+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
 commenting, forwarding are performed via email by sending specially
-composed letters to the partucular mail addresses. However, searching
+composed letters to the particular mail addresses.  However, searching
 the bug reports, querying bug report status and viewing comments have
 the bug reports, querying bug report status and viewing comments have
-been web-based for a long time. To overcome this inconvinience the
+been web-based for a long time.  To overcome this inconvenience the
 Debbugs/SOAP service was introduced.
 
 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.
+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.
 
 @code{debbugs}, described in this document, is the Emacs library that
 
 @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.
+exposes to developers the available functions provided by the Debbugs
+server.  @code{debbugs} uses Emacs' SOAP client library for
+communication with the Debbugs server.  In tandem with Emacs' email
+facilities, @code{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 @code{debbugs}.
 * Configuration::               Configuring @code{debbugs}.
 * Requesting bug numbers::      How to request bug report numbers.
 
 @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.
+* 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.
 @end menu
 
 @node Installation
 @chapter Installation
 
 @subheading Installation on Emacs 24 or later
 @end menu
 
 @node Installation
 @chapter Installation
 
 @subheading Installation on Emacs 24 or later
-Install @code{debbugs} from ELPA repository.
+
+Install @code{debbugs} from the @ref{Packaging, ELPA repository, , elisp}.
 
 @subheading Installation on Emacs 22 and Emacs 23
 
 @subheading Installation on Emacs 22 and Emacs 23
+
 If you want to install @code{debbugs} on Emacs 22/23, you will need to
 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
+install the @code{soap-client} library first.  It can be downloaded from
+the @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}:
 project page}.
 
 Compile the library and add it into your @code{load-path}:
@@ -81,54 +94,57 @@ Compile the library and add it into your @code{load-path}:
 (add-to-list 'load-path "/path/to/emacs-soap-client/")
 @end 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}: 
+@code{debbugs} library can be downloaded from the
+@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
 
 @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
+
+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
 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
 @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.
+@uref{http://debbugs.gnu.org}.  So if you intend to use one of these
+ports, you don't need to configure @code{debbugs}.  If you want to
+interact with a Debbugs port other than those listed, you have to
+configure @code{debbugs} by adding a new server specifier to the
+@code{debbugs-servers} variable.  The actual port can be selected by
+the @code{debbugs-port} variable.
 
 @defvar debbugs-servers
 
 @defvar debbugs-servers
-List of Debbugs server specifiers. Each entry is a list that contains a
+List of Debbugs server specifiers.  Each entry is a list that contains a
 string identifying the port name and the server parameters in
 string identifying the port name and the server parameters in
-keyword-value form. The list initially contains two predefined and
+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
 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.
+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.
+
 @item :bugreport-url
 @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.
+The URL of the server script (@code{bugreport.cgi} in the default
+Debbugs installation) that provides the access to mboxes with messages
+from bug reports.
 @end table
 
 @end table
 
-Example. Add new Debbugs port with name "foobars.net":
+Example.  Add a new Debbugs port with name "foobars.net":
 
 @example
 
 @example
-(add-to-list 
- 'debbugs-servers 
+(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"))
  '("foobars.net"
    :wsdl "http://bugs.foobars.net/cgi/soap.cgi?WSDL"
    :bugreport-url "http://bugs.foobars.net/cgi/bugreport.cgi"))
@@ -136,22 +152,30 @@ Example. Add new Debbugs port with name "foobars.net":
 @end defvar
 
 @defvar debbugs-port
 @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.
+This variable holds the name of the currently used port.  The value of
+the variable corresponds to the Debbugs server to be accessed, either
+@code{"gnu.org"} or @code{"debian.org"}, or a user defined port name.
 @end defvar
 
 @node Requesting bug numbers
 @chapter Requesting bug numbers
 @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.
+
+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.
 
 @defun debbugs-get-bugs &rest query
 This function returns a list of bug numbers that match the
 
 @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.
+@var{query}. @var{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 @var{query} is an intersection of results of all
+subqueries.
 
 Valid keywords are:
 
 
 Valid keywords are:
 
@@ -159,25 +183,29 @@ Valid keywords are:
 @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 :package
 The value is the name of the package a bug belongs to, like @code{"emacs"},
 @code{"coreutils"}, @code{"gnus"}, or @code{"tramp"}.
+
+@item :src
+This is used to retrieve bugs that belong to source with given name.
+
 @item :severity
 @item :severity
-This is the severity of the bug. The exact set of available severities
-depends on policy of particular Debbugs port:
+This is the severity of the bug.  The exact set of available severities
+depends on the policy of a particular Debbugs port:
 
 Debian port:
 @code{"critical"}, @code{"grave"}, @code{"serious"},
 @code{"important"}, @code{"normal"}, @code{"minor"}, @code{"wishlist"},
 and @code{"fixed"}.
 
 
 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"},
+GNU port:
+@code{"serious"}, @code{"important"}, @code{"normal"}, @code{"minor"},
 @code{"wishlist"}.
 @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"},
+@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
+the 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{"unreproducible"}, @code{"fixed"}, @code{"potato"},
 @code{"woody"}, @code{"sid"}, @code{"help"}, @code{"security"},
 @code{"upstream"}, @code{"pending"}, @code{"sarge"},
@@ -185,32 +213,65 @@ Debian port:
 @code{"confirmed"}, @code{"ipv6"}, @code{"lfs"},
 @code{"fixed-in-experimental"}, @code{"fixed-upstream"}, @code{"l10n"},
 @code{"etch"}, @code{"etch-ignore"}, @code{"lenny"},
 @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"}.
+@code{"lenny-ignore"}, @code{"squeeze"}, @code{"squeeze-ignore"},
+@code{"wheezy"}, @code{"wheezy-ignore"}. The actual list of tags can be
+found on @uref{http://www.debian.org/Bugs/Developer#tags}.
+
+GNU port: @code{"fixed"}, @code{"notabug"}, @code{"wontfix"},
+@code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"},
+@code{"pending"}, @code{"help"}, @code{"security"}, @code{"confirmed"}.
+See @url{http://debbugs.gnu.org/Developer.html#tags} for the actual list
+of tags.
 
 
-GNU port: 
-@code{"fixed"}, @code{"notabug"}, @code{"wontfix"},
-@code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"}.
 @item :owner
 @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})
+This is used to identify bugs by the owner's email address.  The
+special email address @code{"me"} is used as pattern, replaced with
+the variable @code{user-mail-address} (@pxref{(elisp)User
+Identification}).
+
 @item :submitter
 @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}.
+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 the variable @code{user-mail-address}.
+
+@item :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
+@code{"me"} is used as pattern, replaced with @code{user-mail-address}.
+
+@item :correspondent
+This allows to find bug reports where the person with the given email
+address has participated.  The special email address @code{"me"} is used
+as pattern, replaced with @code{user-mail-address}.
+
+@item :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
+@code{affects} in bug's status.  The returned bugs do not necessary
+belong to this package.
+
+@item :status
+Status of bug.  Valid values are @code{"done"}, @code{"forwarded"} and
+@code{"open"}.
+
 @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
 @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.
+@code{"both"}.  If this keyword is not given in the query,
+@code{:archive "0"} is assumed by default.
 @end table
 
 @end table
 
-Example. Get all bug reports that were initiated by me.
+Example.  Get all opened and forwarded release critical bugs for the
+packages which are maintained by @code{"me"} and which have a patch:
 
 @example
 
 @example
-(let ((debbugs-port "gnu.org"))
-  (debbugs-get-bugs :submitter "me" :archive "both"))
-@result{} (5516 5551 5645 7259)
+(let ((debbugs-port "debian.org"))
+  (debbugs-get-bugs :maint "me" :tag "patch"
+                    :severity "critical"
+                    :status "open"
+                    :severity "grave"
+                    :status "forwarded"
+                    :severity "serious"))
 @end example
 @end defun
 
 @end example
 @end defun
 
@@ -218,7 +279,7 @@ Example. Get all bug reports that were initiated by me.
 This function returns a list of bug numbers, according to @var{amount}
 (a number) of latest bugs.
 
 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.  Get the latest six bug report numbers from Debian BTS:
 
 @example
 (let ((debbugs-port "debian.org"))
 
 @example
 (let ((debbugs-port "debian.org"))
@@ -229,100 +290,126 @@ Example. Get the latest six bug report numbers from Debian BTS:
 
 @node Requesting bugs statuses
 @chapter Requesting bugs statuses
 
 @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
 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
+@var{bug-numbers}.  Every returned entry is an association list with the
 following attributes:
 
 @table @code
 following attributes:
 
 @table @code
-@item bug_num
+@item id
+@itemx bug_num
 The bug number.
 The bug number.
+
 @item package
 A list of package names the bug belongs to.
 @item package
 A list of package names the bug belongs to.
+
 @item severity
 @item severity
-The severity of the bug report. Possible values are the same as for
+The severity of the bug report.  Possible values are the same as for
 @code{:severity} in @code{debbugs-get-bugs} (@pxref{Requesting bug
 numbers}).
 @code{:severity} in @code{debbugs-get-bugs} (@pxref{Requesting bug
 numbers}).
+
 @item tags
 @item tags
-The status of the bug report, a list of strings. Possible values are the
+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}).
 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 pending
 The string @code{"pending"}, @code{"forwarded"} or @code{"done"}.
+
 @item subject
 Subject/Title of the bugreport.
 @item subject
 Subject/Title of the bugreport.
+
 @item originator
 @item originator
-The E-mail address of bug report submitter.
+The E-mail address of the bug report submitter.
+
 @item mergedwith
 A list of bug numbers this bug was merged with.
 @item mergedwith
 A list of bug numbers this bug was merged with.
+
 @item source
 Source package name of the bug report.
 @item source
 Source package name of the bug report.
+
 @item date
 @item date
-Date of bug creation. Encoded as UNIX time.
+Date of bug creation.  Encoded as UNIX time.
+
 @item log_modified
 @item log_modified
-@item last_modified
-Date of last update. Encoded as UNIX time.
+@itemx last_modified
+Date of last update.  Encoded as UNIX time.
+
 @item found_date
 @item found_date
-@item fixed_date
-Date of bug report / bug fix (empty for now). Encoded as UNIX time.
+@itemx 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 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 archived
 @code{t} if the bug is archived, @code{nil} otherwise.
+
 @item unarchived
 @item unarchived
-The date the bug has been unarchived, if ever. Encoded as UNIX time.
+The date the bug has been unarchived, if ever.  Encoded as UNIX time.
+
 @item found_versions
 @item found_versions
-@item fixed_versions
+@itemx fixed_versions
 List of version strings.
 List of version strings.
+
 @item forwarded
 A URL or an E-mail address.
 @item forwarded
 A URL or an E-mail address.
+
 @item blocks
 A list of bug numbers this bug blocks.
 @item blocks
 A list of bug numbers this bug blocks.
+
 @item blockedby
 A list of bug numbers this bug is blocked by.
 @item blockedby
 A list of bug numbers this bug is blocked by.
+
 @item msgid
 The message id of the initial bug report.
 @item msgid
 The message id of the initial bug report.
+
 @item owner
 Who is responsible for fixing.
 @item owner
 Who is responsible for fixing.
+
 @item location
 Always the string @code{"db-h"} or @code{"archive"}.
 @item location
 Always the string @code{"db-h"} or @code{"archive"}.
+
 @item affects
 A list of package names.
 @item affects
 A list of package names.
+
 @item summary
 Arbitrary text.
 @end table
 
 @item summary
 Arbitrary text.
 @end table
 
-Example. Get status of bug number #10 from GNU BTS:
+Example.  Get the 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)
 
 @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") 
+  (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>")
   (owner . "Magnus Henoch <*****@@freemail.hu>")
-  (log_modified . 1310061242.0) (location . "db-h") 
-  (subject . "url-gw should support HTTP CONNECT proxies") 
+  (log_modified . 1310061242.0) (location . "db-h")
+  (subject . "url-gw should support HTTP CONNECT proxies")
   (originator . "Magnus Henoch <*****@@freemail.hu>")
   (originator . "Magnus Henoch <*****@@freemail.hu>")
-  (last_modified . 1310061242.0) (pending . "pending") (affects) 
-  (archived) (tags) (fixed_date) (package "emacs") (found_date) 
+  (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
   (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}.
+General accessor that returns the value of key @var{attribute}.
+@var{bug-or-message} must be a list element returned by either
+@code{debbugs-get-status} or @code{debbugs-get-bug-log}
+(@pxref{Requesting messages}).
 
 
-Example. Return the originator of last submitted bug report:
+Example.  Return the originator of the last submitted bug report:
 
 @example
 (let ((debbags-port "gnu.org"))
 
 @example
 (let ((debbags-port "gnu.org"))
@@ -337,12 +424,12 @@ Example. Return the originator of last submitted bug report:
 @chapter Requesting messages
 
 @defun debbugs-get-bug-log bug-number
 @chapter Requesting messages
 
 @defun debbugs-get-bug-log bug-number
-Returns a list of messages related to @var{bug-number}. Every message is
+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
 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,
+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
 newer messages have a higher number.
 @item header
 The header lines from the E-mail messages, as arrived at the bug
@@ -350,16 +437,16 @@ tracker.
 @item body
 The message body.
 @item attachments
 @item body
 The message body.
 @item attachments
-A list of possible attachments, or @code{nil}. Not implemented yet server
+A list of possible attachments, or @code{nil}.  Not implemented yet server
 side.
 @end table
 @end defun
 
 @defun debbugs-get-message-numbers messages
 side.
 @end table
 @end defun
 
 @defun debbugs-get-message-numbers messages
-Returns the message numbers of @var{messages}. @var{messages} must be
+Returns the message numbers of @var{messages}.  @var{messages} must be
 the result of a @code{debbugs-get-bug-log} call.
 
 the result of a @code{debbugs-get-bug-log} call.
 
-Example. Get message numbers from bug report #456789 log from Debian
+Example.  Get message numbers from bug report #456789 log from Debian
 BTS:
 
 @example
 BTS:
 
 @example
@@ -371,21 +458,21 @@ BTS:
 
 @defun debbugs-get-message messages message-number
 Returns the message @var{message-number} of
 
 @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{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}.
 
 @var{message-number}, the function returns @code{nil}.
 
-Example: Return the first message of last submitted bug report to Debian
-BTS:
+Example: Return the first message of the last submitted bug report to
+GNU BTS:
 
 @example
 (let* ((debbugs-port "gnu.org")
 
 @example
 (let* ((debbugs-port "gnu.org")
-       (messages (apply 'debbugs-get-bug-log 
+       (messages (apply 'debbugs-get-bug-log
                        (debbugs-newest-bugs 1))))
                        (debbugs-newest-bugs 1))))
-  (debbugs-get-message 
+  (debbugs-get-message
    messages
    (car (debbugs-get-message-numbers messages))))
 @end example
    messages
    (car (debbugs-get-message-numbers messages))))
 @end example
@@ -393,30 +480,83 @@ BTS:
 
 @defun debbugs-get-mbox bug-number mbox-type &optional filename
 Download mbox with all messages from bug report
 
 @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
+@var{bug-number}.  @var{mbox-type} specifies a type of mbox and can be
 one of the following symbols:
 
 @table @code
 @item mboxfolder
 one of the following symbols:
 
 @table @code
 @item mboxfolder
-Download mbox folder, i. e. mbox with messages as they arrived at
+Download mbox folder, i.e. mbox with messages as they arrived at the
 Debbugs server.
 Debbugs server.
+
 @item mboxmaint
 @item mboxmaint
-Download maintainer's mbox, i. e. mbox with messages as they are
-resended from Debbugs server.
+Download maintainer's mbox, i.e. mbox with messages as they are resent
+from the Debbugs server.
+
 @item mboxstat
 @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.
+@itemx mboxstatus
+Download status mbox.  The use of either symbol depends on the actual
+Debbugs server configuration.  For @code{"gnu.org"}, use the former;
+for @code{"debian.org} - the latter.
+@end table
+
+@var{filename}, if non-@code{nil}, is the name of the 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 the @code{debbugs-servers} variable is
+specified (@pxref{Configuration}).
+@end defun
+
+@node Requesting user tags
+@chapter 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 @code{"gnu.org"}
+uses also package names as user identification.
+
+@defun debbugs-get-usertag &rest query
+Return a list of bug numbers which match @var{query}.
+
+@var{query} is a sequence of keyword-value pairs where the values are
+strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']*
+
+Valid keywords are:
+
+@table @code
+@item :user
+The value is the name of the package a bug belongs to, like
+@code{"emacs"}, @code{"coreutils"}, or @code{"tramp"}.  It can also be
+an email address of a user who has applied a user tag.  The special
+email address @code{"me"} is used as pattern, replaced with
+@code{user-mail-address}.  There must be at least one such entry; it
+is recommended to have exactly one.
+
+@item :tag
+A string applied as user tag.  Often, it is a subproduct
+identification, like @code{"cedet"} or @code{"tramp"} for the package
+@code{"emacs"}.
 @end table
 
 @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.
+If there is no @code{:tag} entry, no bug numbers will be returned but
+a list of existing user tags for @code{:user}.
+
+Example.  Get all user tags for the package @code{"emacs"}:
 
 
-Note that mbox downloading will work only if the @code{:bugreport-url}
-field of @code{debbugs-servers} variable is specified
-(@pxref{Configuration}).
+@example
+(let ((debbugs-port "gnu.org"))
+  (debbugs-get-usertag :user "emacs"))
+@result{} ("www" "solaris" "ls-lisp" "cygwin")
+@end example
+
+Get all bugs tagged by package @code{"emacs"} with @code{"www"} or
+@code{"cygwin"})):
+
+@example
+(let ((debbugs-port "gnu.org"))
+  (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
+@result{} (807 1223 5637)
+@end example
 @end defun
 
 @bye
 @end defun
 
 @bye