[elpa] externals/debbugs 37245ae 067/311: * debbugs.texi (top): Add a title page.

[Stefan Monnier]

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

    * debbugs.texi (top): Add a title page.
    (all): Correct some typos.
---
 ChangeLog    |   5 +
 debbugs.texi | 304 ++++++++++++++++++++++++++++++++++-------------------------
 2 files changed, 182 insertions(+), 127 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1a8cfe5..3f10631 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2011-07-20  Michael Albinus  <michael.albinus@gmx.de>
+
+       * debbugs.texi (top): Add a title page.
+       (all): Correct some typos.
+
 2011-07-19  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
        * debbugs-gnu.el (debbugs-guess-current-id): New function.
diff --git a/debbugs.texi b/debbugs.texi
index b0470f4..92e33e2 100644
--- a/debbugs.texi
+++ b/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