Mercurial > emacs

changeset 27316:6e868e0bc324

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*** empty log message ***
author Gerd Moellmann <gerd@gnu.org>
date Thu, 13 Jan 2000 12:07:39 +0000
parents e17a1c6d3d69
children afeb81bc23e6
files info/dir man/eudc.texi src/ChangeLog
diffstat 3 files changed, 999 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/info/dir	Thu Jan 13 12:06:44 2000 +0000
+++ b/info/dir	Thu Jan 13 12:07:39 2000 +0000
@@ -32,6 +32,7 @@
 			  and Java code.
 * Ada mode: (ada-mode). The GNU Emacs mode editing Ada.
 * IDLWAVE: (idlwave).	Major mode and shell for IDL and WAVE/CL files.
+* EUDC: (eudc).		Emacs Unified Directory Client.
 
 Editors
 * Autotype: (autotype). Convenient features for text that you enter frequently
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/eudc.texi	Thu Jan 13 12:07:39 2000 +0000
@@ -0,0 +1,998 @@
+\input texinfo.tex
+@c %**start of header
+@setfilename ../info/eudc
+@settitle Emacs Unified Directory Client (EUDC) Manual
+@iftex
+@afourpaper
+@end iftex
+@c %**end of header
+
+@footnotestyle end
+
+@ifinfo
+@direntry
+* EUDC::   A client for directory servers (LDAP, PH)
+@end direntry
+
+This file documents EUDC v1.30b
+
+EUDC is part of Emacs.
+
+EUDC is the Emacs Unified Directory Client, a common interface to
+directory servers using various protocols such as LDAP or the CCSO white
+pages directory system (PH/QI)
+
+Copyright @copyright{} 1998, 2000 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+     
+@ignore
+Permission is granted to process this file through TeX
+and print the results, provided the printed document
+carries a copying permission notice identical to this
+one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified
+versions of this manual under the conditions for
+verbatim copying and the terms of the ``GNU General
+Public License'', and provided that the entire
+resulting derived work is distributed under the terms
+of a permission notice identical to this one.
+     
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title{EUDC Manual}
+@subtitle{The Emacs Unified Directory Client}
+@author by Oscar Figueiredo
+@code{1.30b}
+
+@page
+@vskip 0pt plus 1fill
+     Copyright @copyright{} 1998, 2000 Free Software Foundation, Inc.
+
+     Permission is granted to make and distribute verbatim
+     copies of this manual provided the copyright notice and
+     this permission notice are preserved on all copies.
+     
+     @ignore
+     Permission is granted to process this file through TeX
+     and print the results, provided the printed document
+     carries a copying permission notice identical to this
+     one except for the removal of this paragraph (this
+     paragraph not being relevant to the printed manual).
+     
+     @end ignore
+
+     Permission is granted to copy and distribute modified
+     versions of this manual under the conditions for
+     verbatim copying and the terms of the ``GNU General 
+     Public License'', and provided that the entire
+     resulting derived work is distributed under the terms
+     of a permission notice identical to this one.
+     
+     Permission is granted to copy and distribute
+     translations of this manual into another language,
+     under the above conditions for modified versions,
+     except that this permission notice may be stated in a
+     translation approved by the Free Software Foundation.
+@end titlepage
+
+@ifinfo
+@node     Top, Overview, (dir), (dir)
+@comment  node-name,  next,         previous, up
+
+
+This manual documents EUDC v1.30b, the Emacs Unified Directory Client.
+
+A common interface to directory servers using various protocols such as
+LDAP or the CCSO white pages directory system (PH/QI)
+
+@end ifinfo
+
+@menu
+* Overview::                    Summary of EUDC features
+* Installation::                How to install EUDC
+* Usage::                       The various usage possibilities explained
+* Credits::                     Who's done what
+* Variables Index::             
+@end menu
+
+
+
+
+
+@node     Overview, Installation, Top, Top
+@comment  node-name,   next,  previous,  up
+@chapter Overview
+
+EUDC, the Emacs Unified Directory Client, provides a common user
+interface to access directory servers using different directory
+protocols. 
+
+Currently supported back-ends are:
+
+@itemize @bullet
+@item
+LDAP, Lightweight Directory Access Protocol
+@item
+CCSO PH/QI
+@item
+BBDB, Big Brother's Insiduous Database
+@end itemize
+
+The main features of the EUDC interface are:
+
+@itemize @bullet
+@item 
+Queries using a customizable form
+@item
+Inline query expansion (for instance you can expand a name
+to an email address in a mail message buffer using a server as an
+address book)
+@item
+Multiple servers can be tried in turn until a match is found for an
+inline query
+@item
+Fast minibuffer queries for email addresses and phone numbers
+@item
+Interface to BBDB to let you insert server records into your own BBDB database
+(@pxref{Top,,BBDB,bbdb,BBDB Manual})
+@end itemize
+
+@menu
+* LDAP::                        What is LDAP ?
+* CCSO PH/QI::                  What is CCSO, PH, QI ?
+* BBDB::                        What is BBDB ?
+@end menu
+
+
+
+@node LDAP, CCSO PH/QI, Overview, Overview
+@comment  node-name,  next,  previous,  up
+@section LDAP
+
+LDAP, Lightweight Directory Access Protocol, is a communication
+protocol for directory applications defined in RFC 1777.
+
+Quoted from RFC 1777:
+
+@quotation
+[LDAP] is designed to provide access to the X.500 Directory while not
+incurring the resource requirements of the Directory Access Protocol
+(DAP). This protocol is specifically targeted at simple management
+applications and browser applications that provide simple read/write
+interactive access to the X.500 Directory, and is intended to be a
+complement to the DAP itself.
+@end quotation
+
+LDAP servers usually store (but are not limited to) information about
+people such as their name, phone number, email address, office
+location, etc@enddots{} More information about LDAP can be found at
+@url{http://www.openldap.org/}
+
+EUDC requires external support to access LDAP directory servers
+(@pxref{LDAP Requirements})
+
+
+@node CCSO PH/QI, BBDB, LDAP, Overview
+@comment  node-name,  next,  previous,  up
+@section CCSO PH/QI
+
+The Central Computing Services Office (CCSO) of the University of
+Illinois at Urbana Champaign (UIUC) created and freely distributes a
+directory system that is currently in use in more than 300 organizations
+around the world.  The system records information about people such as
+their address, phone number, email, academic information or any other
+details it was configured to.
+
+The system consists of two parts: a database server traditionally called
+@samp{qi} and a command-line client called @samp{ph}.
+@url{ftp://uiarchive.cso.uiuc.edu/pub/packages/ph} is the main
+distribution site.  @url{http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.}
+provides a listing of the active @samp{qi} servers.
+
+The original command-line @samp{ph} client that comes with the
+@samp{ph/qi} distribution provides additional features like the
+possibility to communicate with the server in login-mode which makes it
+possible to change records in the database.  This is not implemented in
+EUDC.
+
+
+@node BBDB,  , CCSO PH/QI, Overview
+@comment  node-name,  next,  previous,  up
+@section BBDB
+
+BBDB is the Big Brother's Insiduous Database, a package for Emacs
+originally written by Jamie Zawinski which provides rolodex-like
+database functionality featuring tight integration with the Emacs mail
+and news readers.
+
+It is often used as an enhanced email address book.
+
+EUDC considers BBDB as a directory server backend just like LDAP or
+PH/QI servers though BBDB has no client/server protocol and thus always
+resides locally on your machine.  The point in this is not to offer an
+alternate way to query your BBDB database (BBDB itself provides much
+more flexible ways to do that) but rather to offer an interface to your
+local directory that is consistent with the interface to external
+directories (LDAP, PH/QI).  This is particularly interesting when
+performing queries on multiple servers.
+
+EUDC also offers a means to insert results from directory queries into
+your own local BBDB (@pxref{Creating BBDB Records})
+
+@node Installation, Usage, Overview, Top
+@comment  node-name,  next,  previous,  up
+@chapter Installation
+
+Add the following to your @file{.emacs} init file:
+@lisp
+(require 'eudc)
+@end lisp
+This will install EUDC at startup.
+
+After installing EUDC you will find (the next time you launch Emacs) a
+new @code{Directory Search} submenu in the @samp{Tools} menu that will
+give you access to EUDC.
+
+You may also find it useful to add the following to your @file{.emacs}
+initialization file to add a shortcut for email address expansion in
+email composition buffers (@pxref{Inline Query Expansion})
+
+@lisp
+(eval-after-load 
+ "message"
+ '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
+(eval-after-load 
+ "sendmail"
+ '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
+@end lisp
+
+@menu
+* LDAP Requirements::           EUDC needs external support for LDAP
+@end menu
+
+@node LDAP Requirements,  , Installation, Installation
+@comment  node-name,  next,  previous,  up
+@section LDAP Requirements
+
+LDAP support is added by means of @file{ldap.el} which is part of Emacs.
+@file{ldap.el} needs an external command line utility named
+@file{ldapsearch} which is available as part of LDAP toolkits.  above.
+
+@itemize @bullet
+@item
+Open LDAP Libraries
+(@url{http://www.openldap.org/})
+@item
+University of Michigan's LDAP Client software
+(@url{http://www.umich.edu/~dirsvcs/ldap/})
+@end itemize
+
+
+@node Usage, Credits, Installation, Top
+@comment  node-name,  next,  previous,  up
+@chapter Usage
+
+This chapter describes the usage of EUDC.  Most functions and
+customization options are available through the @samp{Directory Search}
+submenu of the @samp{Tools} submenu.
+
+@menu
+* Querying Servers::            How queries are performed and handled 
+* Query Form::                  How to use and customize the query form
+* Display of Query Results::    Controlling how query results are presented
+* Inline Query Expansion::      How to use and customize inline queries
+* The Server Hotlist::          How to use and manage the server hotlist
+* Multi-server Queries::        How to query multiple servers sucessively
+* Creating BBDB Records::       How to insert query results into your BBDB
+* Server/Protocol Locals::      Customizing on a per server/protocol basis
+@end menu
+
+
+@node Querying Servers, Query Form, Usage, Usage
+@comment  node-name,  next,  previous,  up
+@section Querying Servers
+
+EUDC's basic functionality is to let you query a directory server and
+return the results back to you.  There are several things you may want
+to customize in this process.
+
+
+@menu
+* Selecting a Server::          The first thing to do
+* Return Attributes::           Configuring what the server should return
+* Duplicate Attributes::        What to do when records have duplicate attributes
+@end menu
+
+@node Selecting a Server, Return Attributes, Querying Servers, Querying Servers
+@subsection Selecting a Server
+
+Before doing any query you will need to set the directory server.  You
+need to specify the name of the host machine running the server software
+and the protocol to use. If you do not set the server in any fashion,
+EUDC will ask you for one when you make your first query.
+
+You can set the server by selecting one from your hotlist of servers
+(@pxref{The Server Hotlist}) available in the @samp{Server} submenu or
+by selecting @samp{New Server} in that same menu.
+
+LDAP servers generally require some configuration before you can perform
+queries on them.  In particular, the @dfn{search base} must be
+configured.  If the server you select has no configured search base then
+EUDC will propose you to configure it at this point.  A customization
+buffer will be displayed where you can edit the search base and other
+parameters for the server.
+
+@defvar eudc-server
+The name or IP address of the remote directory server. A TCP port number
+may be specified by appending a colon and a number to the name of the
+server. You will not need this unless your server runs on a port other
+than the default (which depends on the protocol).
+If the directory server resides on your own computer (which is the case
+if you use the BBDB backend) then `localhost' is a reasonable value but
+it will be ignored anyway.
+@end defvar
+
+@defvar eudc-protocol
+The directory protocol to use to query the server.  Currently supported
+protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}.
+@end defvar
+
+@deffn Command eudc-set-server
+This command accessible from @samp{Server} submenu lets you specify a
+new directory server and protocol.
+@end deffn
+
+@node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers
+@subsection Return Attributes
+
+Directory servers may be configured to return a default set of
+attributes for each record matching a query if the query specifies none.
+The variable @code{eudc-default-return-attributes} controls the return
+attributes you want to see, if different from the server defaults.
+
+@defvar eudc-default-return-attributes
+A list of the default attributes to extract from directory entries.  If
+set to the symbol @code{all} then all available attributes are
+returned. A value of @code{nil}, the default, means to return the
+default attributes as configured in the server.
+@end defvar
+
+The server may return several matching records to a query. Some of the
+records may however not contain all the attributes you requested. You can
+discard those records.
+
+@defopt eudc-strict-return-matches
+If non-@code{nil}, entries that do not contain all the requested return
+attributes are ignored.  Default is @code{t}.
+@end defopt
+
+@node Duplicate Attributes,  , Return Attributes, Querying Servers
+@subsection Duplicate Attributes
+
+Directory standards may authorize different instances of the same
+attribute in a record. For instance the record of a person may contain
+several email fields containing different email addresses. When using
+a QI directory server this is difficult to distinguish from attributes
+having multi-line values such as the postal address that may contain a
+line for the street and another one for the zip code and city name. In
+both cases, EUDC will consider the attribute duplicated.
+
+EUDC has several methods to deal with duplicated attributes. The
+available methods are:
+
+@table @code
+@item list
+Makes a list with the different values of the duplicate attribute. The
+record is returned with only one instance of the attribute with a list
+of all the different values as a value. This is the default method that
+is used to handle duplicate fields for which no other method has been
+specified.
+@item first
+Discards all the duplicate values of the field keeping only the first
+one.
+@item concat
+Concatenates the different values using a newline as a separator. The
+record keeps only one instance of the field the value of which is a
+single multi-line string.
+@item duplicate
+Duplicates the whole record into as many instances as there are different
+values for the field. This is the default for the email field. Thus a
+record containing 3 different email addresses is duplicated into three
+different records each having a single email address. This is
+particularly useful in combination with @code{select} as the method to
+handle multiple matches in inline expansion queries (@pxref{Inline Query
+Expansion}) because you are presented with the 3 addresses in a
+selection buffer
+@end table
+
+Because a method may not be applicable to all fields, the variable
+@code{eudc-duplicate-attribute-handling-method} lets you specify either a
+default method for all fields or a method for each individual field.
+
+@defvar eudc-duplicate-attribute-handling-method
+A method to handle entries containing duplicate attributes.  This is
+either an alist @code{(@var{attr} . @var{method})} or a symbol
+@var{method}.  The alist form of the variable associates a method to an
+individual attribute name, the second form specifies a method applicable
+to all attribute names. Available methods are: @code{list},
+@code{first}, @code{concat}, @code{duplicate} (see above).  Defaults to
+@code{list}.
+@end defvar
+
+
+
+@node Query Form, Display of Query Results, Querying Servers, Usage
+@comment  node-name,  next,  previous,  up
+@section Query Form
+
+The simplest way to query your directory server is to use the query
+form. You display the query form with the @samp{Query with Form} menu
+item or by invoking the command @kbd{M-x eudc-query-form}. The attribute
+names presented in this form are defined by the
+@code{eudc-query-form-attributes} variable (unless a non-@code{nil}
+argument is supplied to @code{eudc-query-form}).
+
+Since the different directory protocols to which EUDC interfaces may
+use different names for equivalent attributes, EUDC defines its own set
+of attribute names and a mapping between these names and their
+protocol-specific equivalent through the variable
+@code{eudc-protocol-attributes-translation-alist}.  Names currently
+defined by EUDC are @code{name}, @code{firstname}, @code{email} and
+@code{phone}.
+
+@defvar eudc-query-form-attributes
+A list of attributes presented in the query form.  Attribute names in
+this list should be either EUDC attribute names or valid attribute
+names.  You can get a list of valid attribute names for the current
+protocol with the @samp{List Valid Attribute Names} menu item or the
+@kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name},
+@code{email} and @code{phone}.
+@end defvar
+
+@deffn Command eudc-query-form get-fields-from-server
+Display a form to query the directory server.  If given a non-@code{nil}
+argument the function first queries the server for the existing fields
+and displays a corresponding form.  Not all protocols may support a
+non-@code{nil} argument here.
+@end deffn
+
+Since the names of the fields may not be explicit enough or adapted to
+be directly displayed as prompt strings in the form, the variable
+@code{eudc-user-attribute-names-alist} lets you define more explicit
+names for directory attribute names.  This variable is ignored if
+@code{eudc-use-raw-directory-names} is non-@code{nil}.
+
+@defvar eudc-user-attribute-names-alist
+This is an alist of user-defined names for the directory attributes used in
+query/response forms. Prompt strings for attributes that are not in this
+alist are derived by splitting the attribute name at underscores and
+capitalizing the individual words.
+@end defvar
+
+@defvar eudc-use-raw-directory-names
+If non-@code{nil}, use attributes names as defined in the directory.
+Otherwise, directory query/response forms display the user attribute
+names defined in @code{eudc-user-attribute-names-alist}.
+@end defvar
+
+@node Display of Query Results, Inline Query Expansion, Query Form, Usage
+@comment  node-name,  next,  previous,  up
+@section Display of Query Results
+
+Upon successful completion of a form query, EUDC will display a buffer
+containing the results of the query.
+
+The fields that are returned for each record
+are controlled by @code{eudc-default-return-attributes} (@pxref{Return
+Attributes}).  
+
+The display of each individual field can be performed by an arbitrary
+function which allows specific processing for binary values like images
+or audio samples as well as values with computer semantics like URLs.
+
+@defvar eudc-attribute-display-method-alist
+An alist specifying methods to display attribute values.  Each member of
+the list is of the form @code{(@var{name} . @var{func})} where
+@var{name} is a lowercased string naming a directory attribute
+(translated according to @code{eudc-user-attribute-names-alist} if
+@code{eudc-use-raw-directory-names} is non-nil) and @var{func} a
+function that will be passed the corresponding attribute values for
+display.
+@end defvar
+
+This variable has protocol-local definitions (see @pxref{Server/Protocol
+Locals}).  For instance, it is defined as follows for LDAP:
+
+@lisp
+(eudc-protocol-set 'eudc-attribute-display-method-alist 
+                   '(("jpegphoto" . eudc-display-jpeg-inline)
+                     ("labeledurl" . eudc-display-url)
+                     ("audio" . eudc-display-sound)
+                     ("labeledurl" . eudc-display-url)
+                     ("url" . eudc-display-url)) 
+                   'ldap)
+@end lisp
+
+EUDC provides a set of built-in functions to display binary value types:
+
+@defun eudc-display-generic-binary data
+Display a button for unidentified binary @var{data}.
+@end defun
+
+@defun eudc-display-url url
+Display URL and make it clickable.
+@end defun
+
+@defun eudc-display-sound data
+Display a button to play the sound @var{data}.
+@end defun
+
+@defun eudc-display-jpeg-inline data
+Display the JPEG @var{data} inline at point if possible.
+@end defun
+
+@defun eudc-display-jpeg-as-button data
+Display a button for the JPEG @var{data}.
+@end defun
+
+Right-clicking on a binary value button pops up a contextual menu with
+options to process the value.  Among these are saving the attribute
+value to a file or sending it to an external viewer command.  External
+viewers should expect the value on their standard input and should
+display it or perform arbitrary processing on it.  Messages sent to
+standard output are discarded.  External viewers are listed in the
+variable @code{eudc-external-viewers} which you can customize.
+
+@defvar eudc-external-viewers
+This is a list of viewer program specifications.  Each specification is
+a list whose first element is a string naming the viewer for unique
+identification, the second element is the executable program which
+should be invoked and the following elements are arguments that should
+be passed to the program.
+@end defvar
+
+
+@node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage
+@comment  node-name,  next,  previous,  up
+@section Inline Query Expansion
+
+Inline query expansion is a powerful method to get completion from your
+directory server. The most common usage is for expanding names to email
+addresses in mail message buffers. The expansion is performed by the
+command @kbd{M-x eudc-expand-inline} which is available from the
+@samp{Directory Search} menu but can also be conveniently bound to a key
+shortcut (@pxref{Installation})  The operation is controlled by the
+variables @code{eudc-inline-expansion-format},
+@code{eudc-inline-query-format},
+@code{eudc-expanding-overwrites-query} and
+@code{eudc-multiple-match-handling-method}.
+
+If the query fails for a server, other servers may be tried successively 
+until one of them finds a match (@pxref{Multi-server Queries}).
+
+@deffn Command eudc-expand-inline replace-p
+Query the server and expand the query string before point.  The query
+string consists of the buffer substring from the point back to the
+preceding comma, colon or beginning of
+line. @code{eudc-inline-query-format} controls how individual words
+are mapped onto directory attribute names.  After querying the server
+for the given string, the expansion specified by
+@code{eudc-inline-expansion-format} is inserted in the buffer at
+point. If @var{replace-p} is @code{t} then this expansion replaces the
+query string in the buffer.  If @code{eudc-expanding-overwrites-query}
+is non-@code{nil} then the meaning of @var{replace-p} is negated.
+@end deffn
+
+@defvar eudc-inline-query-format
+Format of an inline expansion query.  
+This is actually a list of @var{format}s.  A @var{format} is a list of
+one or more EUDC attribute names.  A @var{format} applies if it contains
+as many attributes as individual words in the inline query string.  If
+several @var{format}s apply then they are tried in order until a match
+is found.  If @code{nil} all the words will be mapped onto the default
+server/protocol attribute name (generally @code{name}).
+
+For instance, use the following 
+@lisp
+(setq eudc-inline-query-format '((name)
+                                 (firstname)
+                                 (firstname name)))
+@end lisp
+to indicate that single word expansion queries are to be considered as
+surnames and if no match is found then they should be tried as first
+names.  Inline queries consisting of two words are considered as
+consisting of a first name followed by a surname.  If the query consists 
+of more than two words, then the first one is considered as the first
+name and the remaining words are all considered as surname constituents.
+
+@var{format}s are in fact not limited to EUDC attribute names, you can
+use server or protocol specific names in them.  It may be safer if you
+do so, to set the variable @code{eudc-inline-query-format} in a protocol
+or server local fashion (see @pxref{Server/Protocol Locals}).
+
+For instance you could use the following to match up to three words
+against the @code{cn} attribute of LDAP servers:
+@lisp
+(eudc-protocol-set 'eudc-inline-query-format
+                   '((cn)
+                     (cn cn)
+                     (cn cn cn))
+                   'ldap)
+@end lisp
+@end defvar
+
+@defvar eudc-inline-expansion-format
+This variable lets you control exactly what is inserted into the buffer
+upon an inline expansion request. It is a list whose first element is a
+string passed to @code{format}. Remaining elements are symbols
+corresponding to directory attribute names.  The corresponding attribute
+values are passed as additional arguments to @code{format}. Default is
+@code{("%s" email)} but you may want to consider a value like @code{("%s
+<%s>" name email)}
+@end defvar
+
+@defvar eudc-multiple-match-handling-method
+This variable controls what to do when multiple entries match a query
+for an inline expansion.  Possible values are:
+@table @code
+@item first
+The first match is considered as being the only one, the others are
+discarded.
+@item select
+A selection buffer pops up where you can choose a particular match. This 
+is the default value of the variable.
+@item all
+The expansion uses all records successively
+@item abort
+An error is signaled. The expansion aborts.
+@end table
+
+
+Defaults to @code{select}
+@end defvar
+
+
+
+@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage
+@comment  node-name,  next,  previous,  up
+@section The Server Hotlist
+
+EUDC lets you maintain a list of frequently used servers so that you 
+can easily switch from one to another. This hotlist appears in the
+@samp{Server} submenu. You select a server in this list by clicking on
+its name. You can add the current server to the list with the command
+@kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable
+@code{eudc-server-hotlist} which is stored in and retrieved from the file
+designated by @code{eudc-options-file}.  EUDC also provides a facility to
+edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}).
+
+The hotlist is also used to make queries on multiple servers
+successively (@pxref{Multi-server Queries}). The order in which the
+servers are tried is the order they appear in the hotlist, therefore it
+is important to sort the hotlist appropriately.
+
+@deffn Command eudc-bookmark-server server
+Add @var{server} to the hotlist of servers
+@end deffn
+
+@deffn Command eudc-bookmark-current-server
+Add the current server to the hotlist of servers
+@end deffn
+
+@defvar eudc-options-file
+The name of a file where EUDC stores its internal variables
+(the hotlist and the current server). EUDC will try to load 
+that file upon initialization so, if you choose a file name
+different from the defaults @file{~/.eudc-options}, be sure to set this
+variable to the appropriate value @emph{before} EUDC is itself
+loaded.
+@end defvar
+
+@menu
+* The Hotlist Edit Buffer::     An interactive hotlist editing facility
+@end menu
+
+@node The Hotlist Edit Buffer,  , The Server Hotlist, The Server Hotlist
+@comment  node-name,  next,  previous,  up
+@subsection The Hotlist Edit Buffer
+
+The hotlist edit buffer offers a means to manage a list of frequently
+used servers.  Commands are available in the context pop-up menu
+generally bound to the right mouse button.  Those commands also have
+equivalent keybindings.
+
+@deffn Command eudc-hotlist-add-server
+Bound to @kbd{a}.
+Add a new server to the hotlist on the line after point
+@end deffn
+
+@deffn Command eudc-hotlist-delete-server
+Bound to @kbd{d}.
+Delete the server on the line point is on
+@end deffn
+
+@deffn Command eudc-hotlist-select-server
+Bound to @kbd{s}.
+Select the server the point is on as the current directory server for
+the next queries
+@end deffn
+
+@deffn Command eudc-hotlist-transpose-servers
+Bound to @kbd{t}.
+Bubble up the server the point is on to the top of the list
+@end deffn
+
+@deffn Command eudc-hotlist-quit-edit
+Bound to @kbd{q}.
+Save the changes and quit the hotlist edit buffer.  Use @kbd{x} or
+@kbd{M-x kill-buffer} to exit without saving.
+@end deffn
+
+
+@node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage
+@comment  node-name,  next,  previous,  up
+@section Multi-server Queries
+
+When using inline query expansion (@pxref{Inline Query Expansion}), EUDC
+can try to query successively a sequence of directory servers until one
+of them successfully finds a match for the query.
+
+@defvar eudc-inline-expansion-servers
+This variable controls which servers are tried and in which order when
+trying to perform an inline query. Possible values are:
+@table @code
+@item current-server
+Only the current directory server is tried
+@item hotlist
+The servers in the hotlist are tried in order until one finds a match
+for the query or `eudc-max-servers-to-query' is reached
+@item server-then-hotlist
+The current server then the servers in the hotlist are tried in the
+order they appear in the hotlist until one of them finds a match or
+`eudc-max-servers-to-query' is reached.  This is the default.
+@end table
+@end defvar
+
+@defvar eudc-max-servers-to-query
+This variable indicates the maximum number of servers to query when
+performing a multi-server query. The default, @code{nil}, indicates
+that all available servers should be tried.
+@end defvar
+
+
+
+@node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage
+@comment  node-name,  next,  previous,  up
+@section Creating BBDB Records
+
+With EUDC, you can automatically create BBDB records
+(@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a
+directory server. You do this by moving point to the appropriate
+record in a query result display buffer and invoking the command
+@kbd{M-x eudc-insert-record-at-point-into-bbdb} with the
+keyboard binding @kbd{b} @footnote{This keybinding does not actually
+call @code{eudc-insert-record-at-point-into-bbdb} but uses
+@code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC
+cannot update an existing BBDB record and will signal an error if you
+try to insert a record matching an existing one.
+
+It is also possible to export to BBDB the whole batch of records
+contained in the directory query result with the command
+@kbd{M-x eudc-batch-export-records-to-bbdb}.
+
+Because directory systems may not enforce a strict record format, local
+server installations may use different attribute names and have
+different ways to organize the information. Furthermore BBDB has its own
+record structure. For these reasons converting a record from its
+external directory format to the BBDB format is a highly customizable
+process.
+
+@defvar eudc-bbdb-conversion-alist
+The value of this variable should be a symbol naming an alist defining a
+mapping between BBDB field names onto directory attribute names records.
+This is a protocol-local variable and is initialized upon protocol
+switch (@pxref{Server/Protocol Locals})  The alist is made of cells of the
+form @code{(@var{bbdb-field} . @var{spec-or-list})}. 
+@var{bbdb-field} is the name of a field
+that must be defined in your BBDB environment (standard field names are
+@code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
+and @code{notes}). 
+@var{spec-or-list} is either a single mapping specification or a list of
+mapping specifications. Lists of mapping specifications are valid for
+the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
+actually s-expressions which are evaluated as follows:
+
+@table @asis
+@item a string 
+evaluates to itself
+@item a symbol
+evaluates to the symbol value. Symbols corresponding to directory
+attribute names present in the record evaluate to the value of the field
+in the record
+@item a form
+is evaluated as a function. The argument list may contain attribute 
+names which evaluate to the corresponding values in the record. The form
+evaluation should return something appropriate for the particular
+@var{bbdb-field} (see @code{bbdb-create-internal}).
+@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
+convenience functions to parse phones and addresses.
+@end table
+@end defvar
+
+The default value of the PH-specific value of that variable is
+@code{eudc-ph-bbdb-conversion-alist}:
+
+@lisp
+((name . name)
+ (net . email)
+ (address . (eudc-bbdbify-address address "Address"))
+ (phone . ((eudc-bbdbify-phone phone "Phone")
+           (eudc-bbdbify-phone office_phone "Office Phone"))))
+@end lisp
+
+This means that:
+
+@itemize @bullet
+@item 
+the @code{name} field of the BBDB record gets its value
+from the @code{name} attribute of the directory record
+@item
+the @code{net} field of the BBDB record gets its value
+from the @code{email} attribute of the directory record
+@item
+the @code{address} field of the BBDB record is obtained by parsing the
+@code{address} attribute of the directory record with the function
+@code{eudc-bbdbify-address}
+@item
+two @code{phone} fields are created (when possible) in the BBDB record.
+The first one has @cite{Phone} for location and its value is obtained by
+parsing the @code{phone} attribute of the PH/QI record with the function
+@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location
+its value is obtained by parsing the @code{office_phone} attribute of the
+PH/QI record with the function @code{eudc-bbdbify-phone}.
+@end itemize
+
+@defun eudc-bbdbify-phone phone location
+This is a convenience function provided for use in
+@code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector
+compatible with @code{bbdb-create-internal}. @var{phone} is either a string
+supposedly containing a phone number or a list of such strings which are
+concatenated. @var{location} is used as the phone location for BBDB.
+@end defun
+
+@defun eudc-bbdbify-address addr location
+This is a convenience function provided for use in
+@code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector
+compatible with @code{bbdb-create-internal}. @var{addr} should be an
+address string of no more than four lines or a list of lines. The last
+line is searched for the zip code, city and state name. @var{location}
+is used as the phone location for BBDB.
+@end defun
+
+Note that only a subset of the attributes you selected with
+@code{eudc-default-return-attributes} and that are actually displayed may
+actually be inserted as part of the newly created BBDB record.
+
+
+@node Server/Protocol Locals,  , Creating BBDB Records, Usage
+@comment  node-name,  next,  previous,  up
+@section Server/Protocol Locals
+
+EUDC can be customized independently for each server or directory
+protocol.  All variables can be given local bindings that are activated
+when a particular server and/or protocol becomes active. This is much
+like buffer-local bindings but on a per server or per protocol basis.
+
+@menu
+* Manipulating local bindings::  Functions to set and query local bindings
+@end menu
+
+@node Manipulating local bindings,  , Server/Protocol Locals, Server/Protocol Locals
+@comment  node-name,  next,  previous,  up
+@subsection Manipulating local bindings
+
+EUDC offers functions that let you set and query variables on a per
+server or per protocol basis.
+
+The following predicates allow you to test the existence of
+server/protocol local bindings for a particular variable.
+
+@defun eudc-server-local-variable-p var
+Return non-@code{nil} if @var{var} has server-local bindings
+@end defun
+
+@defun eudc-protocol-local-variable-p var
+Return non-@code{nil} if @var{var} has protocol-local bindings
+@end defun
+
+The following functions allow you to set the value of a variable with
+various degrees of localness.
+
+@defun eudc-default-set var val
+Set the EUDC default value of @var{var} to @var{val}.
+The current binding of @var{var} (if local to the current server or
+protocol) is not changed.
+@end defun
+
+@defun eudc-protocol-set var val &optional protocol
+Set the binding of @var{var} local to @var{protocol} to @var{val}.  If
+omitted, @var{protocol} defaults to the current value of
+@code{eudc-protocol}.  The current binding of @var{var} is changed only
+if @var{protocol} is omitted.
+@end defun
+
+@defun eudc-server-set var val &optional server
+Set the binding of @var{var} local to @var{server} to @var{val}.  If
+omitted, @var{server} defaults to the current value of
+@code{eudc-server}.  The current binding of @var{var} is changed only if
+@var{server} is omitted.
+@end defun
+
+@defun eudc-set var val
+Set the most local (server, protocol or default) binding of @var{var} to
+@var{val}.  The current binding of @var{var} is also set to @var{val}.
+@end defun
+
+The following variables allow you to query the various bindings of a
+variable (local or non-local).
+
+@defun eudc-variable-default-value var
+Return the default binding of @var{var} (outside of a particular server
+or protocol local binding).
+Return @code{unbound} if @var{var} has no EUDC default value.
+@end defun
+
+@defun eudc-variable-protocol-value var &optional protocol
+Return the value of @var{var} local to @var{protocol}.  Return
+@code{unbound} if @var{var} has no value local to @var{protocol}.
+@var{protocol} defaults to @code{eudc-protocol}.
+@end defun
+
+@defun eudc-variable-server-value var [server]
+Return the value of @var{var} local to @var{server}.  
+Return @code{unbound} if @var{var} has no value local to @var{server}.
+@var{server} defaults to @code{eudc-server}.
+@end defun
+
+
+Changing a protocol-local or server-local value of a variable has no
+effect on its current value.  The following command is used to
+synchronize the current values of variables with their local values
+given the current @code{eudc-server} and @code{eudc-protocol}:
+
+@defun eudc-update-local-variables
+Update all EUDC variables according to their local settings.
+@end defun
+
+
+
+@node Credits, Variables Index, Usage, Top
+@comment  node-name,  next,  previous,  up
+@chapter Credits
+
+EUDC was written by Oscar Figueiredo based on @file{ph.el} by the 
+same author.
+
+Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
+in testing and proofreading the code and docs of @file{ph.el}.
+
+@node Variables Index,  , Credits, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Variables Index
+
+@printindex vr
+
+@contents
+@bye
Binary file src/ChangeLog has changed