mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-13 09:32:47 +00:00
961 lines
36 KiB
Plaintext
961 lines
36 KiB
Plaintext
\input texinfo.tex
|
|
@c %**start of header
|
|
@setfilename ../../info/eudc
|
|
@settitle Emacs Unified Directory Client (EUDC) Manual
|
|
@afourpaper
|
|
@c %**end of header
|
|
|
|
@copying
|
|
This file documents EUDC v1.30b.
|
|
|
|
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-2012 Free Software Foundation, Inc.
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
|
|
and with the Back-Cover Texts as in (a) below. A copy of the license
|
|
is included in the section entitled ``GNU Free Documentation License''.
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
|
|
modify this GNU manual. Buying copies from the FSF supports it in
|
|
developing GNU and promoting software freedom.''
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Emacs network features
|
|
@direntry
|
|
* EUDC: (eudc). Emacs client for directory servers (LDAP, PH).
|
|
@end direntry
|
|
|
|
@footnotestyle end
|
|
|
|
@titlepage
|
|
@title{EUDC Manual}
|
|
@subtitle{The Emacs Unified Directory Client}
|
|
@author by Oscar Figueiredo
|
|
@code{1.30b}
|
|
|
|
@page
|
|
@vskip 0pt plus 1fill
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top, Overview, (dir), (dir)
|
|
@top Emacs Unified Directory Client
|
|
@comment node-name, next, previous, up
|
|
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Overview:: Summary of EUDC features
|
|
* Installation:: How to install EUDC
|
|
* Usage:: The various usage possibilities explained
|
|
* Credits:: Who's done what
|
|
* GNU Free Documentation License:: The license for this documentation.
|
|
* Command and Function Index::
|
|
* Variables Index::
|
|
@end menu
|
|
|
|
|
|
|
|
|
|
|
|
@node Overview, Installation, Top, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Overview
|
|
|
|
EUDC, the @dfn{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 Insidious 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, @dfn{the 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 created and freely distributed a
|
|
directory system that was used by many organizations in the 1990s.
|
|
The system records information about people such as their address,
|
|
phone number, email, academic information or any other details it was
|
|
configured to. Nowadays this system is not widely used.
|
|
|
|
The system consists of two parts: a database server traditionally called
|
|
@samp{qi} and a command-line client called @samp{ph}. As of 2010, the
|
|
code can still be downloaded from @url{http://www-dev.cites.uiuc.edu/ph/}.
|
|
|
|
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 @dfn{Big Brother's Insidious 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 back end 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}, available as part of Open LDAP
|
|
(@url{http://www.openldap.org/}).
|
|
|
|
|
|
@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 successively
|
|
* 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 back end) 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{New 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 of elements @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}, and @code{duplicate} (see above). The default is
|
|
@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
|
|
@findex eudc-get-attribute-list
|
|
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, such as
|
|
images or audio samples, as well as values with semantics, such as
|
|
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-@code{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{Expand Inline Query} menu item 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
|
|
@noindent
|
|
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
|
|
|
|
Default is @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 key bindings.
|
|
|
|
@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
|
|
|
|
@findex eudc-insert-record-at-point-into-bbdb
|
|
@findex eudc-try-bbdb-insert
|
|
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 key binding 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.
|
|
|
|
@findex eudc-batch-export-records-to-bbdb
|
|
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 locality.
|
|
|
|
@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, GNU Free Documentation License, 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 GNU Free Documentation License, Command and Function Index, Credits, Top
|
|
@appendix GNU Free Documentation License
|
|
@include doclicense.texi
|
|
|
|
@node Command and Function Index, Variables Index, GNU Free Documentation License, Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Command and Function Index
|
|
|
|
@printindex fn
|
|
|
|
@node Variables Index, , Command and Function Index, Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Variables Index
|
|
|
|
@printindex vr
|
|
|
|
@bye
|