From 0efff4c683729e4d4e9ee120ade3b1183d1043ee Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Wed, 20 Jul 2011 15:01:22 +0200 Subject: [PATCH] * debbugs.texi (top): Add a title page. (all): Correct some typos. --- packages/debbugs/ChangeLog | 5 + packages/debbugs/debbugs.texi | 304 ++++++++++++++++++++-------------- 2 files changed, 182 insertions(+), 127 deletions(-) diff --git a/packages/debbugs/ChangeLog b/packages/debbugs/ChangeLog index 1a8cfe57e..3f1063139 100644 --- a/packages/debbugs/ChangeLog +++ b/packages/debbugs/ChangeLog @@ -1,3 +1,8 @@ +2011-07-20 Michael Albinus + + * debbugs.texi (top): Add a title page. + (all): Correct some typos. + 2011-07-19 Lars Magne Ingebrigtsen * debbugs-gnu.el (debbugs-guess-current-id): New function. diff --git a/packages/debbugs/debbugs.texi b/packages/debbugs/debbugs.texi index b0470f443..92e33e24a 100644 --- a/packages/debbugs/debbugs.texi +++ b/packages/debbugs/debbugs.texi @@ -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 -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. @@ -28,51 +28,63 @@ and modified without restriction. @end quotation @end copying +@titlepage +@title Debbugs Programmer's Manual +@author by Evgeny M. Zubok +@page +@insertcopying +@end titlepage + +@contents + @node Top -@top Debbugs programmer's manual +@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, +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 partucular mail addresses. However, searching +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 +been web-based for a long time. To overcome this inconvenience 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. +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 -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. -* 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. @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 + 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}: @@ -81,54 +93,57 @@ Compile the library and add it into your @code{load-path}: (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 -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 + @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 -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 -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 -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 -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 -Example. Add new Debbugs port with name "foobars.net": +Example. Add a new Debbugs port with name "foobars.net": @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")) @@ -136,21 +151,22 @@ Example. Add new Debbugs port with name "foobars.net": @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 -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 -@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 +@var{query}. @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: @@ -159,22 +175,24 @@ 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 :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"}. -GNU port: -@code{"important"}, @code{"grave"}, @code{"normal"}, @code{"minor"}, +GNU port: +@code{"serious"}, @code{"important"}, @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. + +@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"}, @@ -187,25 +205,29 @@ Debian port: @code{"etch"}, @code{"etch-ignore"}, @code{"lenny"}, @code{"lenny-ignore"}. -GNU port: +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}) +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 -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 :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. +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. Get all bug reports that were initiated by me. @example (let ((debbugs-port "gnu.org")) @@ -218,7 +240,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. -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")) @@ -229,100 +251,126 @@ Example. Get the latest six bug report numbers from Debian BTS: @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 +@var{bug-numbers}. Every returned entry is an association list with the following attributes: @table @code -@item bug_num +@item id +@itemx 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 +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 +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. +The E-mail address of the 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. +Date of bug creation. Encoded as UNIX time. + @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 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 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. +The date the bug has been unarchived, if ever. Encoded as UNIX time. + @item found_versions -@item fixed_versions +@itemx 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. 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) - (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>") - (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>") - (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 -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")) @@ -337,12 +385,12 @@ Example. Return the originator of last submitted bug report: @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 -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 @@ -350,16 +398,16 @@ tracker. @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 -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. -Example. Get message numbers from bug report #456789 log from Debian +Example. Get message numbers from bug report #456789 log from Debian BTS: @example @@ -371,21 +419,21 @@ BTS: @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}. -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") - (messages (apply 'debbugs-get-bug-log + (messages (apply 'debbugs-get-bug-log (debbugs-newest-bugs 1)))) - (debbugs-get-message + (debbugs-get-message messages (car (debbugs-get-message-numbers messages)))) @end example @@ -393,30 +441,32 @@ BTS: @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 -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. + @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 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 file to store mbox. If -@var{filename} is @code{nil}, the downloaded mbox is inserted into the -current buffer. +@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 @code{debbugs-servers} variable is specified -(@pxref{Configuration}). +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 @bye -- 2.39.2