emacs/doc/misc/eudc.texi

\input texinfo.tex
@c %**start of header
@setfilename ../../info/eudc.info
@settitle Emacs Unified Directory Client (EUDC) Manual
@include docstyle.texi
@afourpaper
@syncodeindex fn cp
@syncodeindex vr cp
@c %**end of header

@copying
This file documents EUDC version 1.40.0.

EUDC is the Emacs Unified Directory Client, a common interface to
directory servers and contact information.

Copyright @copyright{} 1998, 2000--2024 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.''
@end quotation
@end copying

@dircategory Emacs network features
@direntry
* EUDC: (eudc).                 Emacs client for directory servers (LDAP, BBDB).
@end direntry

@footnotestyle end

@titlepage
@title EUDC Manual
@subtitle The Emacs Unified Directory Client
@author by Oscar Figueiredo
@code{1.40.0}

@page
@vskip 0pt plus 1fill
@insertcopying
@end titlepage

@contents

@ifnottex
@node     Top
@top Emacs Unified Directory Client

@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.
* Index::
@end menu





@node     Overview
@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
BBDB, Big Brother's Insidious Database
@item
macOS Contacts
@item
@code{ecomplete}, Emacs's electrical completion
@item
@code{mailabbrev}, Emacs's abbrev-expansion of mail aliases
@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 ?
* BBDB::                        What is BBDB ?
* macOS Contacts::              What is macOS Contacts ?
* ecomplete::                   What is @code{ecomplete} ?
* mailabbrev::                  What is @code{mailabbrev}?
@end menu



@node LDAP
@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{https://www.openldap.org/}.

EUDC requires external support to access LDAP directory servers
(@pxref{LDAP Configuration})


@node BBDB
@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,
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
LDAP directories.  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 macOS Contacts
@section macOS Contacts

This EUDC back end considers macOS Contacts as a directory server just
like LDAP, though the macOS Contacts application always runs locally
on your machine.  The Contacts application was previously called
Address Book; the EUDC macOS Contacts back end also works on those
older versions.


@node ecomplete
@section @code{ecomplete}

@code{ecomplete} is Emacs's ``electric completion'', and it is part of
Emacs.  It stores all information in an @file{ecompleterc} file, whose
location, and name can be configured via the variable
@code{ecomplete-database-file} (which see).  The format of the file
is:

@display
((TYPE_1 ITEM_1 ITEM_2 ...)
 (TYPE_2 ITEM_N+1 ITEM_N+2 ...)
 ...)
@end display

That is, it is an alist map where the key is the type of match (so
that you can have one list of things for ``mail'', and one for, say,
``mastodon'').  In each of these sections you then have a list where
each item is of the form:

@display
(KEY TIMES-USED LAST-TIME-USED STRING)
@end display

When performing a query, the result will be all items where the search
term matches all, or part of STRING.

When EUDC performs queries with @code{ecomplete}, the name of each
attribute making up the query is used as the type in which the lookup
is performed.  The mapping from EUDC attribute names to
@code{ecomplete} type names is performed according to the variable
@code{eudc-ecomplete-attributes-translation-alist} (which see).


@node mailabbrev
@section @code{mailabbrev}

@code{mailabbrev} is Emacs's ``abbrev-expansion of mail aliases'', and
it is part of Emacs.  It stores all information in a @file{mailrc}
file, whose location, and name can be configured via the variable
@code{mail-personal-alias-file} (which see).  The @file{mailrc} file
has the same format as the @command{mail} and @command{mailx} commands
use for their startup configuration file.  @code{mailabbrev} processes
@samp{alias}, and @samp{source} statements in the @file{mailrc} file.
@samp{alias} statements can define simple aliases and distribution
lists, and can be nested in that the alias expansion can contain
references to other alias definitions.  Forward references, that is
references to aliases before they are actually defined, are possible,
too.

Originally, @code{mailabbrev} was designed to be used with
@code{abbrev-mode}.  The @code{mailabbrev} EUDC backend does not use
@code{abbrev-mode}, but queries @code{mailabbrev} for alias entries
only, and returns these as EUDC results.  All entries where the alias
name exactly equals either the @code{email}, @code{name}, or
@code{firstname} attribute value in the EUDC query, will be returned
as matches.  When a @file{mailrc} alias defines a distribution list,
that is it expands to more than one email address, the EUDC result
will contain a single entry, which will contain an email attribute
only, whose value will be a comma-separated list of RFC 5322 formatted
recipient specifications.


@node Installation
@chapter Installation

EUDC is built-in to Emacs, and its main functions are autoloaded.

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
(with-eval-after-load "message"
  (define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-try-all))
(with-eval-after-load "sendmail"
  (define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-try-all))
@end lisp

@menu
* LDAP Configuration::           EUDC needs external support for LDAP
* macOS Contacts Configuration:: Enable the macOS Contacts backend
* ecomplete Configuration::      Enable the ecomplete backend
* mailabbrev Configuration::     Enable the mailabbrev backend
@end menu

@node LDAP Configuration
@section LDAP Configuration

LDAP support is added by means of @file{ldap.el}, which is part of
Emacs.  @file{ldap.el} needs an external program called
@command{ldapsearch}, available as part of OpenLDAP
(@url{https://www.openldap.org/}).  The configurations in this section
were tested with OpenLDAP 2.4.23.

Most servers use LDAP-over-SSL these days; the examples here reflect
that.  The other possibilities are:

@vindex ldap-host-parameters-alist
@vindex ldap-ldapsearch-args
@itemize @bullet

@item
Servers that do not require authentication or that do not encrypt
authentication traffic.

Include @code{auth simple} in @code{ldap-host-parameters-alist}, which
causes the @code{-x} option to be passed to @command{ldapsearch}.

@item
Servers that require SASL authentication.

Pass any required extra options to @command{ldapsearch} using
@code{ldap-ldapsearch-args}.
@end itemize

The following examples use a base of
@code{ou=people,dc=gnu,dc=org} and the host name
@code{ldap.gnu.org}, a server that supports LDAP-over-SSL (the
@code{ldaps} protocol, with default port @code{636}) and which
requires authentication by the user @code{emacsuser} with password
@code{s3cr3t}.

These configurations are meant to be self-contained; that is, each
provides everything required for sensible TAB-completion of email
fields.  BBDB lookups are attempted first; if a matching BBDB entry is
found then EUDC will not attempt any LDAP lookups.

Wildcard LDAP lookups are supported using the @code{*} character.  For
example, attempting to TAB-complete the following:

@example
To: * Smith
@end example

@noindent
will return all LDAP entries with surnames that begin with
@code{Smith}.  In every LDAP query it makes, EUDC implicitly appends
the wildcard character to the end of the last word, except if the word
corresponds to an attribute which is a member of
@code{eudc-ldap-no-wildcard-attributes}.

@menu
* Emacs-only Configuration::    Configure with @file{.emacs}
* External Configuration::      Configure with @file{/etc/openldap/ldap.conf}
* Troubleshooting::             Debug @command{ldapsearch} failures
@end menu

@node Emacs-only Configuration
@subsection Emacs-only Configuration

Emacs can pass most required configuration options via the
@command{ldapsearch} command-line.  One exception is certificate
configuration for LDAP-over-SSL, which must be specified in
@file{/etc/openldap/ldap.conf}.  On systems that provide such
certificates as part of the @code{OpenLDAP} installation, this can be
as simple as one line:

@example
TLS_CACERTDIR /etc/openldap/certs
@end example

In @file{.emacs}, these expressions suffice to configure EUDC for
LDAP:

@vindex message-mode-map
@findex eudc-expand-inline
@findex eudc-expand-try-all
@vindex eudc-server-hotlist
@vindex ldap-host-parameters-alist
@lisp
(with-eval-after-load "message"
  (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all))
(setopt eudc-server-hotlist
        '(("" . bbdb)
          ("ldaps://ldap.gnu.org" . ldap)))
(setopt ldap-host-parameters-alist
        '(("ldaps://ldap.gnu.org"
                  base "ou=people,dc=gnu,dc=org"
                  binddn "gnu\\emacsuser"
                  passwd ldap-password-read)))
@end lisp

@findex ldap-password-read
@vindex passwd
@vindex password-cache
@vindex password-cache-expiry
@findex password-reset
Specifying the function @code{ldap-password-read} for @code{passwd}
will cause Emacs to prompt interactively for the password.  The
password will then be validated and cached, unless
@code{password-cache} is @code{nil}.  You can customize
@code{password-cache-expiry} to control the duration for which the
password is cached.  If you want to clear the cache, call
@code{password-reset}.

@node External Configuration
@subsection External Configuration

Your system may already be configured for a default LDAP server.  For
example, @file{/etc/openldap/ldap.conf} might contain:

@example
BASE ou=people,dc=gnu,dc=org
URI ldaps://ldap.gnu.org
TLS_CACERTDIR /etc/openldap/certs
@end example

@cindex bind distinguished name
@cindex binddn
Authentication requires a password, and a @dfn{bind distinguished name
(binddn)} representing the user, in this case,
@code{gnu\emacsuser}.  These can be specified in
@file{~/.authinfo.gpg} with the following line:

@example
machine ldaps://ldap.gnu.org binddn gnu\emacsuser password s3cr3t
@end example

Then in the @file{.emacs} init file, these expressions suffice to
configure EUDC for LDAP:

@vindex message-mode-map
@findex eudc-expand-inline
@findex eudc-expand-try-all
@vindex eudc-server-hotlist
@vindex ldap-host-parameters-alist
@lisp
(with-eval-after-load "message"
  (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all))
(setopt eudc-server-hotlist
        '(("" . bbdb)
          ("ldaps://ldap.gnu.org" . ldap)))
(setopt ldap-host-parameters-alist
        '(("ldaps://ldap.gnu.org"
                  auth-source t)))
@end lisp

For this example where we only care about one server, the server name
can be omitted in @file{~/.authinfo.gpg} and @file{.emacs}, in which
case @command{ldapsearch} defaults to the host name in
@file{/etc/openldap/ldap.conf}.

The @file{~/.authinfo.gpg} line becomes:

@example
binddn gnu\emacsuser password s3cr3t
@end example

@noindent
and the @file{.emacs} expressions become:

@vindex message-mode-map
@findex eudc-expand-inline
@findex eudc-expand-try-all
@vindex eudc-server-hotlist
@vindex ldap-host-parameters-alist
@lisp
(with-eval-after-load "message"
  (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all))
(setopt eudc-server-hotlist
        '(("" . bbdb) ("" . ldap)))
(setopt ldap-host-parameters-alist
        '(("" auth-source t)))
@end lisp

@node Troubleshooting
@subsection Troubleshooting

If @command{ldapsearch} exits with an error, you'll see a message like
this in the @code{*Messages*} buffer (all on one line):

@example
ldap-search-internal: Failed ldapsearch invocation:
   ldapsearch "-Hldaps://ldap.gnu.org" "-bou=people,dc=gnu,dc=org"
   "-Dgnu\emacsuser" "-W" "-LL" "-tt" "(&(mail=name*))"
   "givenname" "sn" "mail"
@end example

The @command{ldapsearch} command is formatted such that it can be
copied and pasted into a terminal.  Set the @command{ldapsearch} debug
level to 5 by appending @code{-d 5} to the command line.


@node macOS Contacts Configuration
@section macOS Contacts Configuration

macOS Contacts support is added by means of @file{eudcb-mab.el}, or
@file{eudcb-macos-contacts.el} which are part of Emacs.

To enable a macOS Contacts backend, first @code{require} the
respective library to load it, and then set the @code{eudc-server} to
localhost in your init file:
@lisp
(require 'eudcb-macos-contacts)
(eudc-macos-contacts-set-server "localhost")
@end lisp

@file{eudcb-macos-contacts.el} uses the public scripting interfaces
offered by the Contacts app via the macOS Open Scripting Architecture
(OSA).  To accomplish this, @file{eudcb-macos-contacts.el} uses an
external command line utility named osascript, which is included with
all macOS versions since 10.0 (which was released 2001).
@file{eudcb-macos-contacts.el} is hence recommended for all new
configurations.

@file{eudcb-mab.el} reverse engineers the format of the database file
using the external command-line utility named contacts, which needs to
be installed separately.  While this may promise some performance
advantages, it comes at the cost of using an undocumented interface.
Hence, users of @file{eudcb-mab.el} are recommended to double check
the compatibility of @file{eudcb-mab.el} and the required, external
command-line utility before upgrading to a new version of macOS.
@file{eudcb-mab.el} is retained for backwards compatibility with
existing configurations, and may be removed in a future release.


@node ecomplete Configuration
@section @code{ecomplete} Configuration

@code{ecomplete} is Emacs's ``electrical completion'', and is part of
Emacs.  To use it, you will need to set up a database file
(@pxref{ecomplete}) first.

It will be autoloaded on demand.

You can also enable multi-server queries as described in
@pxref{Multi-server Queries}.


@node mailabbrev Configuration
@section @code{mailabbrev} Configuration

@code{mailabbrev} is Emacs's ``abbrev-expansion of mail aliases'', and
it is part of Emacs.  To use it, you will need to set up a database file
(@pxref{mailabbrev}) first.

It will be autoloaded on demand.

You can also enable multi-server queries as described in
@pxref{Multi-server Queries}.


@node Usage
@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
@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
@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 @samp{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{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
@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
@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, in which
case 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
@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
@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 (@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
@section Inline Query Expansion
@subsection Inline Query Expansion Using a Key Binding

Inline query expansion is a powerful method to get completion from
your directory servers.  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-try-all} which is
available from the @samp{Expand Inline Query Trying All Servers} 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}), or all servers can be tried and all matches returned.

@deffn Command eudc-expand-try-all try-all-servers-p
Query some or all servers 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 or
servers for the given string, the expansion specified by
@code{eudc-inline-expansion-format} is inserted in the buffer at
point.  If multiple matches are available, a selection window is
displayed.  If @var{try-all-servers-p} is non-@code{nil} then all
servers are queried.
@end deffn

@deffn Command eudc-expand-inline save-query-as-kill-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 multiple matches are available, a selection window is
displayed.  If @var{save-query-as-kill-p} is @code{t} then the query
string is saved to the kill ring.  If
@code{eudc-expansion-save-query-as-kill} is non-@code{nil} then the
meaning of @var{save-query-as-kill-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 (@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 can be set to @code{nil},
to a function, or to a list.  Default is @code{nil}.

When the value is a list, the 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}.

When the value is @code{nil}, the expansion result will be formatted
according to @url{https://datatracker.ietf.org/doc/html/rfc5322, RFC
5322}.  The @var{phrase} part will be formatted as ``firstname name'',
quoting the result if necessary.  No @var{comment} part will be added
in this case.  This will produce any of the default formats
@center @var{address}
@center @var{first} @code{<}@var{address}@code{>}
@center @var{last} @code{<}@var{address}@code{>}
@center @var{first} @var{last} @code{<}@var{address}@code{>}
depending on whether a first and/or last name are returned by the
query, or not.

When the value is a function, the expansion result will be formatted
according to @url{https://datatracker.ietf.org/doc/html/rfc5322, RFC
5322}, and the referenced function is called to format the
@var{phrase}, and @var{comment} parts, respectively.  The formatted
@var{phrase} part will be quoted if necessary.  Thus one can produce
any of the formats:
@center @var{address}
@center @var{phrase} @code{<}@var{address}@code{>}
@center @var{address} @code{(}@var{comment}@code{)}
@center @var{phrase} @code{<}@var{address}@code{>} @code{(}@var{comment}@code{)}

Email address specifications, as are generated by inline expansion,
need to comply with RFC 5322 in order to be useful in email
messages. When an invalid address specification is present in an email
message header, the message is likely to be rejected by a receiving
MTA.  It is hence recommended to switch old configurations, which use
a list value, to the new @code{nil}, or function value type since it
ensures that the inserted address specifications will be in line with
@url{https://datatracker.ietf.org/doc/html/rfc5322, RFC 5322}.  At
minimum, and to achieve the same semantics as with the old list
default value, this variable should now be set to @code{nil}:
@lisp
(customize-set-variable 'eudc-inline-expansion-format nil)
@end lisp

A function value can for example be used to get @emph{``last, first
<address>''} instead of the default @emph{``first last <address>''}:
@lisp
(defun my-phrase-last-comma-first (search-res-alist)
  (let* (phrase
	 (my-attrs (eudc-translate-attribute-list '(firstname name)))
	 (first-name (cdr (assq (nth 0 my-attrs) search-res-alist)))
	 (last-name (cdr (assq (nth 1 my-attrs) search-res-alist)))
         (comment nil))
    (setq phrase (concat last-name ", " first-name))
    (cons phrase comment)))

(customize-set-variable 'eudc-inline-expansion-format
                        #'my-phrase-last-comma-first)
@end lisp
To set the @var{comment} part, too, instead of @code{nil} as in this
example, also provide a string as the @code{cdr} of the @code{cons}
being returned.  Do not include any double quotes in the @var{phrase}
part, as they are added automatically if needed.  Neither include
parentheses in the @var{comment} part as they, too, are added
automatically.
@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

@subsection Inline Query Expansion Using completion-at-point

In addition to providing a dedicated EUDC function for binding to a
key shortcut (@pxref{Inline Query Expansion}), EUDC also provides a
function to contribute search results to the Emacs in-buffer
completion system available via the function
@code{completion-at-point} (@pxref{Identifier
Inquiries,,,maintaining}) in @code{message-mode} buffers
(@pxref{Top,Message,, message, Message}).  When using this mechanism,
queries are made in the multi-server query mode of operation
(@pxref{Multi-server Queries}).

When a buffer in @code{message-mode} is created, EUDC's inline
expansion function is automatically added to the variable
@code{completion-at-point-functions}.  As a result, whenever
@code{completion-at-point} is invoked in a @code{message-mode} buffer,
EUDC will be queried for email addresses matching the words before
point.  Since this will be useful only when editing specific message
header fields that require specifying one or more email addresses, an
additional check is performed whether point is actually in one of
those header fields.  Thus, any matching email addresses will be
offered for completion in suitable message header fields only, and not
in other places, like for example the body of the message.


@node The Server Hotlist
@section The Server Hotlist

EUDC lets you maintain a list of frequently used servers so that you
can easily switch from one to another.  Most users should configure
the hotlist via Customize, and store the configuration in the main
Emacs initialization file.  Configuring it dynamically can be
confusing, particularly if the hotlist settings are saved to
@code{eudc-options-file} automatically.  @code{eudc-options-file} is
historical and support for it is still maintained, but new EUDC users
should set @code{eudc-ignore-options-file} to @code{t}.

However, this hotlist also 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}, or normal Emacs
initialization if @code{eudc-ignore-options-file} is non-@code{nil}.
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-ignore-options-file
If non-@code{nil}, EUDC ignores @code{eudc-options-file} and warns or
issues an error when an attempt is made to use it.  Most users should
set this, and keep their EUDC configuration in the main Emacs
initialization file instead.  The separate @file{eudc-options} file
has created confusion for users in the past.
@end defvar

@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
default @file{~/.emacs.d/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
@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
@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 @code{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
@code{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
@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

@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
@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
@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
@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
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index
@unnumbered Index

@printindex cp

@bye