branch: master
commit 0d8297cf1b0ec4bd909bba273c5e21c8c1e87852
Author: Michael Albinus <michael.albi...@gmx.de>
Commit: Michael Albinus <michael.albi...@gmx.de>
Documentation enhancement for debbugs
* packages/debbugs/debbugs-gnu.el (debbugs-gnu-patches): Do not show closed
bugs.
(debbugs-gnu-send-control-message): Add "easy".
* packages/debbugs/debbugs-ug.texi (Control Messages): Add "easy".
Describe, how to remove tags.
* packages/debbugs/debbugs.el (debbugs-get-status)
(debbugs-search-est): Fix docstring.
* packages/debbugs/debbugs.texi (Requesting bug numbers):
Add missing tags.
(Requesting bugs statuses): Describe `cache_time' attribute.
(Searching bugs): New chapter.
---
packages/debbugs/debbugs-gnu.el | 3 +-
packages/debbugs/debbugs-ug.info | 20 ++--
packages/debbugs/debbugs-ug.texi | 8 +-
packages/debbugs/debbugs.el | 24 +++--
packages/debbugs/debbugs.info | 222 +++++++++++++++++++++++++++++++++-----
packages/debbugs/debbugs.texi | 212 ++++++++++++++++++++++++++++++++----
6 files changed, 428 insertions(+), 61 deletions(-)
diff --git a/packages/debbugs/debbugs-gnu.el b/packages/debbugs/debbugs-gnu.el
index 98e7360..0dd79ed 100644
--- a/packages/debbugs/debbugs-gnu.el
+++ b/packages/debbugs/debbugs-gnu.el
@@ -534,6 +534,7 @@ marked as \"client-side filter\"."
(defun debbugs-gnu-patches ()
"List the bug reports that have been marked as containing a patch."
(interactive)
+ (setq debbugs-gnu-current-suppress t)
(debbugs-gnu nil debbugs-gnu-default-packages nil nil "patch"))
;;;###autoload
@@ -1382,7 +1383,7 @@ removed instead."
"reassign"
"retitle"
"patch" "wontfix" "moreinfo" "unreproducible" "fixed" "notabug"
- "pending" "help" "security" "confirmed"
+ "pending" "help" "security" "confirmed" "easy"
"usertag")
nil t)
current-prefix-arg))
diff --git a/packages/debbugs/debbugs-ug.info b/packages/debbugs/debbugs-ug.info
index b4a768c..1204e4f 100644
--- a/packages/debbugs/debbugs-ug.info
+++ b/packages/debbugs/debbugs-ug.info
@@ -441,6 +441,7 @@ The strings show the exact format of the control messages.
the bugs belongs to the '"emacs"' package.
'confirmed'
+'easy'
'fixed'
'help'
'moreinfo'
@@ -450,10 +451,15 @@ The strings show the exact format of the control messages.
'security'
'unreproducible'
'wontfix'
- "tags 12345 confirmed|fixed|help|moreinfo|notabug"
+ "tags 12345 confirmed|easy|fixed|help|moreinfo|notabug"
"tags 12345 patch|pending|security|unreproducible|wontfix"
+ If the command invoking the control message has been prefixed
+ with 'C-u', the respective tag is removed from the bug, like
+
+ "tags 12345 -confirmed"
+
'done'
'donenotabug'
'doneunreproducible'
@@ -609,7 +615,7 @@ Variable Index
* debbugs-gnu-default-severities: Retrieving Bugs. (line 63)
* debbugs-gnu-default-suppress-bugs: Retrieving Bugs. (line 44)
* debbugs-gnu-mail-backend: Tabulated Lists. (line 79)
-* debbugs-gnu-send-mail-function: Control Messages. (line 108)
+* debbugs-gnu-send-mail-function: Control Messages. (line 114)
* debbugs-gnu-suppress-closed: Tabulated Lists. (line 76)
* debbugs-gnu-trunk-directory: Applying Patches. (line 18)
* debbugs-org-severity-priority: TODO Items. (line 10)
@@ -656,10 +662,10 @@ Node: Presenting Bugs10806
Node: Tabulated Lists11382
Node: TODO Items15057
Node: Control Messages16113
-Node: Applying Patches18979
-Node: Minor Mode20342
-Node: Command Index21290
-Node: Variable Index22079
-Node: Key Index23082
+Node: Applying Patches19155
+Node: Minor Mode20518
+Node: Command Index21466
+Node: Variable Index22255
+Node: Key Index23258
End Tag Table
diff --git a/packages/debbugs/debbugs-ug.texi b/packages/debbugs/debbugs-ug.texi
index 6d06ae7..26704ef 100644
--- a/packages/debbugs/debbugs-ug.texi
+++ b/packages/debbugs/debbugs-ug.texi
@@ -505,6 +505,7 @@ The second argument, the Emacs version, is read
interactively if the
bugs belongs to the @code{"emacs"} package.
@item confirmed
+@itemx easy
@itemx fixed
@itemx help
@itemx moreinfo
@@ -514,10 +515,15 @@ bugs belongs to the @code{"emacs"} package.
@itemx security
@itemx unreproducible
@itemx wontfix
-"tags 12345 confirmed|fixed|help|moreinfo|notabug"
+"tags 12345 confirmed|easy|fixed|help|moreinfo|notabug"
"tags 12345 patch|pending|security|unreproducible|wontfix"
+If the command invoking the control message has been prefixed with
+@kbd{C-u}, the respective tag is removed from the bug, like
+
+"tags 12345 -confirmed"
+
@item done
@itemx donenotabug
@itemx doneunreproducible
diff --git a/packages/debbugs/debbugs.el b/packages/debbugs/debbugs.el
index d31f355..fbca0af 100644
--- a/packages/debbugs/debbugs.el
+++ b/packages/debbugs/debbugs.el
@@ -317,8 +317,9 @@ Every returned entry is an association list with the
following attributes:
\"normal\", \"minor\" or \"wishlist\".
`tags': The status of the bug report, a list of strings. This
- can be \"fixed\", \"notabug\", \"wontfix\", \"unreproducible\",
- \"moreinfo\" or \"patch\".
+ can be \"confirmed\", \"fixed\", \"pending\", \"notabug\",
+ \"wontfix\", \"unreproducible\", \"moreinfo\", \"security\" or
+ \"patch\".
`pending': The string \"pending\", \"forwarded\", \"fixed\" or \"done\".
@@ -363,12 +364,16 @@ Every returned entry is an association list with the
following attributes:
`summary': Arbitrary text.
+ `cache_time': This is not an attribute located at the debbugs
+ server, but an internal value of the debbugs.el package itself.
+
Example:
\(debbugs-get-status 10)
=> ;; Attributes with empty values are not shown
- \(\(\(bug_num . 10)
+ \(\(\(cache_time . 1469716026.4981334)
+ \(bug_num . 10)
\(source . \"unknown\")
\(date . 1203606305.0)
\(msgid . \"<87zltuz7eh....@freemail.hu>\")
@@ -575,7 +580,7 @@ Every message is an association list with the following
attributes:
"Return the result of a full text search according to QUERY.
QUERY is a sequence of lists of keyword-value pairs where the
-values are strings or numbers, i.e. :KEYWORD \"VALUE\" [:KEYWORD
+values are strings or numbers, i.e. :KEYWORD VALUE [:KEYWORD
VALUE]*
Every sublist of the QUERY forms a hyperestraier condition. A
@@ -595,11 +600,14 @@ The following conditions are possible:
:skip and :max are optional. They specify, how many hits are
skipped, and how many maximal hits are returned. This can be
used for paged results. Per default, :skip is 0 and all
- possible hits are returned.
+ possible hits are returned according to the default maximum of
+ the debbugs server. There is also an absolute maximum how many
+ hits are returned by the debbugs server, which cannot be
+ overwritten my any larger :max number.
There must be exactly one such condition.
-\[ATTRIBUTE VALUE+ :operation OPERATION :order ORDER\]
+\[ATTRIBUTE VALUE+ :operator OPERATOR :order ORDER\]
ATTRIBUTE is one of the following keywords:
@@ -643,8 +651,8 @@ The following conditions are possible:
\"NUMBT\" \(is between the two numbers). In the last case,
there must be two values for ATTRIBUTE.
- If an operator is leaded by \"!\", the meaning is inverted. If
- a string operator is leaded by \"I\", the case of the value is
+ If an operator is led by \"!\", the meaning is inverted. If a
+ string operator is led by \"I\", the case of the value is
ignored.
The optional :order can be specified only in one condition. It
diff --git a/packages/debbugs/debbugs.info b/packages/debbugs/debbugs.info
index 7763609..18c5ada 100644
--- a/packages/debbugs/debbugs.info
+++ b/packages/debbugs/debbugs.info
@@ -64,6 +64,7 @@ projects is described in *note Debbugs User Guide:
(debbugs-ug)Top.
* Configuration:: Configuring 'debbugs'.
* Requesting bug numbers:: How to request bug report numbers.
* Requesting bugs statuses:: How to request the status of bug reports.
+* Searching bugs:: How to search for bugs.
* Requesting messages:: How to get messages from bug reports.
* Requesting user tags:: How to request tags set by users.
@@ -215,13 +216,15 @@ Debbugs server the list of bug numbers that match a
user's query.
'"confirmed"', '"ipv6"', '"lfs"', '"fixed-in-experimental"',
'"fixed-upstream"', '"l10n"', '"etch"', '"etch-ignore"',
'"lenny"', '"lenny-ignore"', '"squeeze"',
- '"squeeze-ignore"', '"wheezy"', '"wheezy-ignore"'. The
+ '"squeeze-ignore"', '"wheezy"', '"wheezy-ignore"',
+ '"jessie"', '"jessie-ignore"', '"stretch"',
+ '"stretch-ignore"', '"buster"', '"buster-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
+ '"help"', '"security"', '"confirmed"', '"easy"'. See
<http://debbugs.gnu.org/Developer.html#tags> for the actual
list of tags.
@@ -285,10 +288,11 @@ Debbugs server the list of bug numbers that match a
user's query.
(let ((debbugs-port "debian.org"))
(debbugs-newest-bugs 6))
+
=> (633152 633153 633154 633155 633156 633157)
-File: debbugs.info, Node: Requesting bugs statuses, Next: Requesting
messages, Prev: Requesting bug numbers, Up: Top
+File: debbugs.info, Node: Requesting bugs statuses, Next: Searching bugs,
Prev: Requesting bug numbers, Up: Top
4 Requesting bugs statuses
**************************
@@ -386,23 +390,28 @@ and various aspects of relationship with other bug
reports.
'summary'
Arbitrary text.
+ 'cache_time'
+ This is not an attribute located at the debbugs server, but
+ an internal value of the debbugs.el package itself.
+
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....@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)))
+
+ => (((cache_time . 1469716026.4981334)
+ (source . "unknown") (found_versions) (done) (blocks)
+ (date . 1203606305.0) (fixed) (fixed_versions) (mergedwith)
+ (found) (unarchived) (blockedby) (keywords) (summary)
+ (msgid . "<87zltuz7eh....@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.
@@ -416,12 +425,171 @@ and various aspects of relationship with other bug
reports.
(debbugs-get-attribute
(car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
'originator))
+
=> "Jack Daniels <j...@daniels.com>"
-File: debbugs.info, Node: Requesting messages, Next: Requesting user tags,
Prev: Requesting bugs statuses, Up: Top
+File: debbugs.info, Node: Searching bugs, Next: Requesting messages, Prev:
Requesting bugs statuses, Up: Top
+
+5 Searching bugs
+****************
+
+The Debbugs servers include an hyperestraier search engine, which
+allows to search inside the bug database. This is enabled only for
+the GNU port of the BTS, and aslo only the GNU port offers a
+Debbugs/SOAP interface for access.
+
+ -- Function: debbugs-search-est &rest query
+ Return the result of a full text search according to QUERY.
+
+ QUERY is a sequence of lists of keyword-value pairs where the
+ values are strings or numbers, i.e. :KEYWORD VALUE [:KEYWORD
+ VALUE]*
+
+ Every sublist of the QUERY forms a hyperestraier condition. A
+ detailed description of hyperestraier conditions can be found at
+ <http://fallabs.com/hyperestraier/uguide-en.html#searchcond>.
+
+ The following conditions are possible:
+
+ (:phrase SEARCH-PHRASE :skip NUMBER :max NUMBER)
+
+ The string SEARCH-PHRASE forms the search on the database.
+ It contains 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. The phrase keyword and value
+ can also be omitted, this is useful in combination with
+ other conditions.
+
+ ':skip' and ':max' are optional. They specify, how many
+ hits are skipped, and how many maximal hits are returned.
+ This can be used for paged results. Per default, :skip is 0
+ and all possible hits are returned according to the default
+ maximum of the debbugs server. There is also an absolute
+ maximum how many hits are returned by the debbugs server,
+ which cannot be overwritten my any larger ':max' number.
+
+ There must be exactly one such condition.
+
+ (ATTRIBUTE VALUE+ :operator OPERATOR :order ORDER)
+
+ ATTRIBUTE is one of the following keywords:
+
+ ':subject'
+ ':@title'
+ The subject of a message or the title of the bug, a
+ string.
+
+ ':date'
+ ':@cdate'
+ The submission date of the bug or the modification date
+ of a message, a number.
+
+ ':@author'
+ The email address of the author of a message belonging
+ to this bug, a string. It may be different than the
+ email of the person submitting the bug. The special
+ email address '"me"' is used as pattern, replaced with
+ 'user-mail-address'.
+
+ ':package'
+ The value is the name of the package a bug belongs to,
+ like '"emacs"', '"coreutils"', '"gnus"', or '"tramp"'.
+
+ ':tags'
+ An arbitrary string the bug is annotated with.
+
+ ':severity'
+ This is the severity of the bug. The exact set of
+ allowed values depends on the Debbugs port. Examples
+ are '"normal"', '"minor"', '"wishlist"' etc.
+
+ ':operator' defines the comparison operator to be applied to
+ ATTRIBUTE. For string attributes this could be '"STREQ"'
+ (is equal to the string), '"STRNE"' (is not equal to the
+ string), '"STRINC"' (includes the string), '"STRBW"' (begins
+ with the string), '"STREW"' (ends with the string),
+ '"STRAND"' (includes all tokens in the string), '"STROR"'
+ (includes at least one token in the string), '"STROREQ"' (is
+ equal to at least one token in the string) or '"STRRX"'
+ (matches regular expressions of the string). For operators
+ with tokens, several values for ATTRIBUTE shall be used.
+
+ Numbers can be compared by the operators '"NUMEQ"' (is equal
+ to the number), '"NUMNE"' (is not equal to the number),
+ '"NUMGT"' (is greater than the number), '"NUMGE"' (is
+ greater than or equal to the number), '"NUMLT"' (is less
+ than the number), '"NUMLE"' (is less than or equal to the
+ number) or '"NUMBT"' (is between the two numbers). In the
+ last case, there must be two values for ATTRIBUTE.
+
+ If an operator is led by '"!"', the meaning is inverted. If
+ a string operator is led by '"I"', the case of the value is
+ ignored.
+
+ The optional ':order' can be specified only in one
+ condition. It means, that ATTRIBUTE is used for sorting the
+ results. The following order operators exist: '"STRA"'
+ (ascending by string), '"STRD"' (descending by string),
+ '"NUMA"' (ascending by number) or '"NUMD"' (descending by
+ number).
+
+ A special case is an ':order', where there is no
+ corresponding attribute value and no operator. In this
+ case, ATTRIBUTE is not used for the search.
+
+ The result of the QUERY is a list of association lists with
+ the same attributes as in the conditions. Additional
+ attributes are
+
+ 'id'
+ The bug number.
+
+ 'msg_num'
+ The number of the message inside the bug log.
+
+ 'snippet'
+ The surrounding text found by the search. For the
+ syntax of the snippet, consult the hyperestraier user
+ guide.
+
+ Example. Get two messages containing words "armstrong" and
+ "debbugs" from GNU BTS. Skip the first 10 hits:
-5 Requesting messages
+ (let ((debbugs-port "gnu.org"))
+ (debbugs-search-est
+ '(:phrase "armstrong AND debbugs" :skip 10 :max 2)
+ '(:severity "normal" :operator "STRINC")
+ '(:date :order "NUMA")))
+
+ => ((("msg_num" . 21)
+ ("date" . 1229208302)
+ ("@author" . "Glenn Morris <*****@gnu.org>")
+ ("@title" . "Re: bug#1567: Mailing an archived bug")
+ ("id" . 1567)
+ ("severity" . "normal")
+ ("@cdate" . "Wed, 17 Dec 2008 14:34:50 -0500")
+ ("snippet" . "...")
+ ("subject" . "Mailing an archived bug")
+ ("package" . "debbugs.gnu.org"))
+ ...)
+
+ Example. Show all messages for package "emacs" on GNU BTS
+ between 2011-08-21 and 2011-08-31.
+
+ (let ((debbugs-port "gnu.org"))
+ (debbugs-search-est
+ '(:max 500)
+ '(:package "emacs" :operator "STREQ")
+ `(:@cdate
+ ,(floor (float-time (encode-time 0 0 0 21 8 2011)))
+ ,(floor (float-time (encode-time 0 0 0 31 8 2011)))
+ :operator "NUMBT")))
+
+
+File: debbugs.info, Node: Requesting messages, Next: Requesting user tags,
Prev: Searching bugs, Up: Top
+
+6 Requesting messages
*********************
-- Function: debbugs-get-bug-log bug-number
@@ -449,6 +617,7 @@ File: debbugs.info, Node: Requesting messages, Next:
Requesting user tags, Pr
(let ((debbugs-port "debian.org"))
(debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
+
=> (5 10 12)
-- Function: debbugs-get-message messages message-number
@@ -500,7 +669,7 @@ File: debbugs.info, Node: Requesting messages, Next:
Requesting user tags, Pr
File: debbugs.info, Node: Requesting user tags, Prev: Requesting messages,
Up: Top
-6 Requesting user tags
+7 Requesting user tags
**********************
A user tag is a string, a user has assigned to one or several bugs.
@@ -535,6 +704,7 @@ also package names as user identification.
(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
@@ -542,17 +712,19 @@ also package names as user identification.
(let ((debbugs-port "gnu.org"))
(debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
+
=> (807 1223 5637)
Tag Table:
Node: Top1094
-Node: Installation3179
-Node: Configuration4278
-Node: Requesting bug numbers6629
-Node: Requesting bugs statuses11883
-Node: Requesting messages15955
-Node: Requesting user tags18970
+Node: Installation3235
+Node: Configuration4334
+Node: Requesting bug numbers6685
+Node: Requesting bugs statuses12065
+Node: Searching bugs16357
+Node: Requesting messages23003
+Node: Requesting user tags26009
End Tag Table
diff --git a/packages/debbugs/debbugs.texi b/packages/debbugs/debbugs.texi
index d71d866..d09dd06 100644
--- a/packages/debbugs/debbugs.texi
+++ b/packages/debbugs/debbugs.texi
@@ -73,6 +73,7 @@ is described in @ref{Top, Debbugs User Guide, , debbugs-ug}.
* Configuration:: Configuring @code{debbugs}.
* Requesting bug numbers:: How to request bug report numbers.
* Requesting bugs statuses:: How to request the status of bug reports.
+* Searching bugs:: How to search for bugs.
* Requesting messages:: How to get messages from bug reports.
* Requesting user tags:: How to request tags set by users.
@end menu
@@ -223,16 +224,19 @@ Debian port: @code{"patch"}, @code{"wontfix"},
@code{"moreinfo"},
@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{"fixed-in-experimental"}, @code{"fixed-upstream"},
+@code{"l10n"}, @code{"etch"}, @code{"etch-ignore"}, @code{"lenny"},
@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}.
+@code{"wheezy"}, @code{"wheezy-ignore"}, @code{"jessie"},
+@code{"jessie-ignore"}, @code{"stretch"}, @code{"stretch-ignore"},
+@code{"buster"}, @code{"buster-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
+@code{"pending"}, @code{"help"}, @code{"security"},
+@code{"confirmed"}, @code{"easy"}. See
+@url{http://debbugs.gnu.org/Developer.html#tags} for the actual list
of tags.
@item :owner
@@ -296,6 +300,7 @@ 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
@@ -393,6 +398,10 @@ A list of package names.
@item summary
Arbitrary text.
+
+@item cache_time
+This is not an attribute located at the debbugs server, but an
+internal value of the debbugs.el package itself.
@end table
Example. Get the status of bug number #10 from GNU BTS:
@@ -400,19 +409,20 @@ 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")
- (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)))
+
+@result{} (((cache_time . 1469716026.4981334)
+ (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
@@ -429,10 +439,171 @@ Example. Return the originator of the last submitted
bug report:
(debbugs-get-attribute
(car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
'originator))
+
@result{} "Jack Daniels <jack@@daniels.com>"
@end example
@end defun
+@node Searching bugs
+@chapter Searching bugs
+
+The Debbugs servers include an hyperestraier search engine, which
+allows to search inside the bug database. This is enabled only for
+the GNU port of the BTS, and aslo only the GNU port offers a
+Debbugs/SOAP interface for access.
+
+@defun debbugs-search-est &rest query
+Return the result of a full text search according to @var{query}.
+
+@var{query} is a sequence of lists of keyword-value pairs where the
+values are strings or numbers, i.e.@: @var{:keyword} @var{value}
+[@var{:keyword} @var{value}]*
+
+Every sublist of the @var{query} forms a hyperestraier condition. A
+detailed description of hyperestraier conditions can be found at
+@url{http://fallabs.com/hyperestraier/uguide-en.html#searchcond}.
+
+The following conditions are possible:
+
+@itemize @w{}
+@item (:phrase @var{search-phrase} :skip @var{number} :max @var{number})
+
+The string @var{search-phrase} forms the search on the database. It
+contains 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. The phrase keyword and value can also be omitted, this is
+useful in combination with other conditions.
+
+@code{:skip} and @code{:max} are optional. They specify, how many
+hits are skipped, and how many maximal hits are returned. This can be
+used for paged results. Per default, :skip is 0 and all possible hits
+are returned according to the default maximum of the debbugs server.
+There is also an absolute maximum how many hits are returned by the
+debbugs server, which cannot be overwritten my any larger @code{:max}
+number.
+
+There must be exactly one such condition.
+
+@item (@var{attribute} @var{value}+ :operator @var{operator} :order
@var{order})
+
+@var{attribute} is one of the following keywords:
+
+@table @code
+@item :subject
+@itemx :@@title
+The subject of a message or the title of the bug, a string.
+
+@item :date
+@itemx :@@cdate
+The submission date of the bug or the modification date of a message,
+a number.
+
+@item :@@author
+The email address of the author of a message belonging to this bug, a
+string. It may be different than the email of the person submitting
+the bug. The special email address @code{"me"} is used as pattern,
+replaced with @code{user-mail-address}.
+
+@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 :tags
+An arbitrary string the bug is annotated with.
+
+@item :severity
+This is the severity of the bug. The exact set of allowed values
+depends on the Debbugs port. Examples are @code{"normal"},
+@code{"minor"}, @code{"wishlist"} etc.
+@end table
+
+@code{:operator} defines the comparison operator to be applied to
+@var{attribute}. For string attributes this could be @code{"STREQ"}
+(is equal to the string), @code{"STRNE"} (is not equal to the string),
+@code{"STRINC"} (includes the string), @code{"STRBW"} (begins with the
+string), @code{"STREW"} (ends with the string), @code{"STRAND"}
+(includes all tokens in the string), @code{"STROR"} (includes at least
+one token in the string), @code{"STROREQ"} (is equal to at least one
+token in the string) or @code{"STRRX"} (matches regular expressions of
+the string). For operators with tokens, several values for
+@var{attribute} shall be used.
+
+Numbers can be compared by the operators @code{"NUMEQ"} (is equal to
+the number), @code{"NUMNE"} (is not equal to the number),
+@code{"NUMGT"} (is greater than the number), @code{"NUMGE"} (is
+greater than or equal to the number), @code{"NUMLT"} (is less than the
+number), @code{"NUMLE"} (is less than or equal to the number) or
+@code{"NUMBT"} (is between the two numbers). In the last case, there
+must be two values for @var{attribute}.
+
+If an operator is led by @code{"!"}, the meaning is inverted. If a
+string operator is led by @code{"I"}, the case of the value is
+ignored.
+
+The optional @code{:order} can be specified only in one condition. It
+means, that @var{attribute} is used for sorting the results. The
+following order operators exist: @code{"STRA"} (ascending by string),
+@code{"STRD"} (descending by string), @code{"NUMA"} (ascending by
+number) or @code{"NUMD"} (descending by number).
+
+A special case is an @code{:order}, where there is no corresponding
+attribute value and no operator. In this case, @var{attribute} is
+not used for the search.
+
+The result of the @var{query} is a list of association lists with the
+same attributes as in the conditions. Additional attributes are
+
+@table @code
+@item id
+The bug number.
+
+@item msg_num
+The number of the message inside the bug log.
+
+@item snippet
+The surrounding text found by the search. For the syntax of the
+snippet, consult the hyperestraier user guide.
+@end table
+@end itemize
+
+Example. Get two messages containing words "armstrong" and "debbugs"
+from GNU BTS. Skip the first 10 hits:
+
+@example
+(let ((debbugs-port "gnu.org"))
+ (debbugs-search-est
+ '(:phrase "armstrong AND debbugs" :skip 10 :max 2)
+ '(:severity "normal" :operator "STRINC")
+ '(:date :order "NUMA")))
+
+@result{} ((("msg_num" . 21)
+ ("date" . 1229208302)
+ ("@@author" . "Glenn Morris <*****@@gnu.org>")
+ ("@@title" . "Re: bug#1567: Mailing an archived bug")
+ ("id" . 1567)
+ ("severity" . "normal")
+ ("@@cdate" . "Wed, 17 Dec 2008 14:34:50 -0500")
+ ("snippet" . "@dots{}")
+ ("subject" . "Mailing an archived bug")
+ ("package" . "debbugs.gnu.org"))
+ @dots{})
+@end example
+
+Example. Show all messages for package "emacs" on GNU BTS between
+2011-08-21 and 2011-08-31.
+
+@example
+(let ((debbugs-port "gnu.org"))
+ (debbugs-search-est
+ '(:max 500)
+ '(:package "emacs" :operator "STREQ")
+ `(:@@cdate
+ ,(floor (float-time (encode-time 0 0 0 21 8 2011)))
+ ,(floor (float-time (encode-time 0 0 0 31 8 2011)))
+ :operator "NUMBT")))
+@end example
+@end defun
+
@node Requesting messages
@chapter Requesting messages
@@ -465,6 +636,7 @@ BTS:
@example
(let ((debbugs-port "debian.org"))
(debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
+
@result{} (5 10 12)
@end example
@end defun
@@ -559,6 +731,7 @@ Example. Get all user tags for the package @code{"emacs"}:
@example
(let ((debbugs-port "gnu.org"))
(debbugs-get-usertag :user "emacs"))
+
@result{} ("www" "solaris" "ls-lisp" "cygwin")
@end example
@@ -568,6 +741,7 @@ Get all bugs tagged by package @code{"emacs"} with
@code{"www"} or
@example
(let ((debbugs-port "gnu.org"))
(debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
+
@result{} (807 1223 5637)
@end example
@end defun
