Merge branch 'master' into comment-cache
[emacs.git] / doc / misc / eudc.texi
blobb7b263d5194ba93689c851110b55bb43c905318c
1 \input texinfo.tex
2 @c %**start of header
3 @setfilename ../../info/eudc.info
4 @settitle Emacs Unified Directory Client (EUDC) Manual
5 @include docstyle.texi
6 @afourpaper
7 @syncodeindex fn cp
8 @syncodeindex vr cp
9 @c %**end of header
11 @copying
12 This file documents EUDC version 1.40.0.
14 EUDC is the Emacs Unified Directory Client, a common interface to
15 directory servers and contact information.
17 Copyright @copyright{} 1998, 2000--2017 Free Software Foundation, Inc.
19 @quotation
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.3 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
24 and with the Back-Cover Texts as in (a) below.  A copy of the license
25 is included in the section entitled ``GNU Free Documentation License''.
27 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
28 modify this GNU manual.''
29 @end quotation
30 @end copying
32 @dircategory Emacs network features
33 @direntry
34 * EUDC: (eudc).                 Emacs client for directory servers (LDAP, BBDB).
35 @end direntry
37 @footnotestyle end
39 @titlepage
40 @title EUDC Manual
41 @subtitle The Emacs Unified Directory Client
42 @author by Oscar Figueiredo
43 @code{1.40.0}
45 @page
46 @vskip 0pt plus 1fill
47 @insertcopying
48 @end titlepage
50 @contents
52 @ifnottex
53 @node     Top
54 @top Emacs Unified Directory Client
56 @insertcopying
57 @end ifnottex
59 @menu
60 * Overview::                    Summary of EUDC features
61 * Installation::                How to install EUDC
62 * Usage::                       The various usage possibilities explained
63 * Credits::                     Who's done what
64 * GNU Free Documentation License:: The license for this documentation.
65 * Index::
66 @end menu
72 @node     Overview
73 @chapter Overview
75 EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user
76 interface to access directory servers using different directory
77 protocols.
79 Currently supported back-ends are:
81 @itemize @bullet
82 @item
83 LDAP, Lightweight Directory Access Protocol
84 @item
85 BBDB, Big Brother's Insidious Database
86 @end itemize
88 The main features of the EUDC interface are:
90 @itemize @bullet
91 @item
92 Queries using a customizable form
93 @item
94 Inline query expansion (for instance you can expand a name
95 to an email address in a mail message buffer using a server as an
96 address book)
97 @item
98 Multiple servers can be tried in turn until a match is found for an
99 inline query
100 @item
101 Fast minibuffer queries for email addresses and phone numbers
102 @item
103 Interface to BBDB to let you insert server records into your own BBDB database
104 (@pxref{Top,,BBDB,bbdb,BBDB Manual})
105 @end itemize
107 @menu
108 * LDAP::                        What is LDAP ?
109 * BBDB::                        What is BBDB ?
110 @end menu
114 @node LDAP
115 @section LDAP
117 LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication
118 protocol for directory applications defined in RFC 1777.
120 Quoted from RFC 1777:
122 @quotation
123 [LDAP] is designed to provide access to the X.500 Directory while not
124 incurring the resource requirements of the Directory Access Protocol
125 (DAP). This protocol is specifically targeted at simple management
126 applications and browser applications that provide simple read/write
127 interactive access to the X.500 Directory, and is intended to be a
128 complement to the DAP itself.
129 @end quotation
131 LDAP servers usually store (but are not limited to) information about
132 people such as their name, phone number, email address, office
133 location, etc@enddots{} More information about LDAP can be found at
134 @url{http://www.openldap.org/}.
136 EUDC requires external support to access LDAP directory servers
137 (@pxref{LDAP Configuration})
140 @node BBDB
141 @section BBDB
143 BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs
144 originally written by Jamie Zawinski which provides rolodex-like
145 database functionality featuring tight integration with the Emacs mail
146 and news readers.
148 It is often used as an enhanced email address book.
150 EUDC considers BBDB as a directory server back end just like LDAP,
151 though BBDB has no client/server protocol and thus always resides
152 locally on your machine.  The point in this is not to offer an
153 alternate way to query your BBDB database (BBDB itself provides much
154 more flexible ways to do that), but rather to offer an interface to
155 your local directory that is consistent with the interface to external
156 LDAP directories.  This is particularly interesting when performing
157 queries on multiple servers.
159 EUDC also offers a means to insert results from directory queries into
160 your own local BBDB (@pxref{Creating BBDB Records})
162 @node Installation
163 @chapter Installation
165 Add the following to your @file{.emacs} init file:
166 @lisp
167 (require 'eudc)
168 @end lisp
169 This will install EUDC at startup.
171 After installing EUDC you will find (the next time you launch Emacs) a
172 new @code{Directory Search} submenu in the @samp{Tools} menu that will
173 give you access to EUDC.
175 You may also find it useful to add the following to your @file{.emacs}
176 initialization file to add a shortcut for email address expansion in
177 email composition buffers (@pxref{Inline Query Expansion})
179 @lisp
180 (with-eval-after-load "message"
181   (define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
182 (with-eval-after-load "sendmail"
183   (define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
184 @end lisp
186 @menu
187 * LDAP Configuration::           EUDC needs external support for LDAP
188 @end menu
190 @node LDAP Configuration
191 @section LDAP Configuration
193 LDAP support is added by means of @file{ldap.el}, which is part of
194 Emacs.  @file{ldap.el} needs an external program called
195 @command{ldapsearch}, available as part of OpenLDAP
196 (@url{http://www.openldap.org/}).  The configurations in this section
197 were tested with OpenLDAP 2.4.23.
199 Most servers use LDAP-over-SSL these days; the examples here reflect
200 that.  The other possibilities are:
202 @vindex ldap-host-parameters-alist
203 @vindex ldap-ldapsearch-args
204 @itemize @bullet
206 @item
207 Servers that do not require authentication or that do not encrypt
208 authentication traffic.
210 Include @code{auth simple} in @code{ldap-host-parameters-alist}, which
211 causes the @code{-x} option to be passed to @command{ldapsearch}.
213 @item
214 Servers that require SASL authentication.
216 Pass any required extra options to @command{ldapsearch} using
217 @code{ldap-ldapsearch-args}.
218 @end itemize
220 The following examples use a base of
221 @code{ou=people,dc=gnu,dc=org} and the host name
222 @code{ldap.gnu.org}, a server that supports LDAP-over-SSL (the
223 @code{ldaps} protocol, with default port @code{636}) and which
224 requires authentication by the user @code{emacsuser} with password
225 @code{s3cr3t}.
227 These configurations are meant to be self-contained; that is, each
228 provides everything required for sensible TAB-completion of email
229 fields.  BBDB lookups are attempted first; if a matching BBDB entry is
230 found then EUDC will not attempt any LDAP lookups.
232 Wildcard LDAP lookups are supported using the @code{*} character.  For
233 example, attempting to TAB-complete the following:
235 @example
236 To: * Smith
237 @end example
239 @noindent
240 will return all LDAP entries with surnames that begin with
241 @code{Smith}.  In every LDAP query it makes, EUDC implicitly appends
242 the wildcard character to the end of the last word.
244 @menu
245 * Emacs-only Configuration::    Configure with @file{.emacs}
246 * External Configuration::      Configure with @file{/etc/openldap/ldap.conf}
247 * Troubleshooting::             Debug @command{ldapsearch} failures
248 @end menu
250 @node Emacs-only Configuration
251 @subsection Emacs-only Configuration
253 Emacs can pass most required configuration options via the
254 @command{ldapsearch} command-line.  One exception is certificate
255 configuration for LDAP-over-SSL, which must be specified in
256 @file{/etc/openldap/ldap.conf}.  On systems that provide such
257 certificates as part of the @code{OpenLDAP} installation, this can be
258 as simple as one line:
260 @example
261 TLS_CACERTDIR /etc/openldap/certs
262 @end example
264 In @file{.emacs}, these expressions suffice to configure EUDC for
265 LDAP:
267 @vindex message-mode-map
268 @findex eudc-expand-inline
269 @vindex eudc-server-hotlist
270 @vindex ldap-host-parameters-alist
271 @lisp
272 (with-eval-after-load "message"
273   (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
274 (customize-set-variable 'eudc-server-hotlist
275                         '(("" . bbdb)
276                           ("ldaps://ldap.gnu.org" . ldap)))
277 (customize-set-variable 'ldap-host-parameters-alist
278                         '(("ldaps://ldap.gnu.org"
279                            base "ou=people,dc=gnu,dc=org"
280                            binddn "gnu\\emacsuser"
281                            passwd ldap-password-read)))
282 @end lisp
284 @findex ldap-password-read
285 @vindex passwd
286 @vindex password-cache
287 @vindex password-cache-expiry
288 @findex password-reset
289 Specifying the function @code{ldap-password-read} for @code{passwd}
290 will cause Emacs to prompt interactively for the password.  The
291 password will then be validated and cached, unless
292 @code{password-cache} is nil.  You can customize
293 @code{password-cache-expiry} to control the duration for which the
294 password is cached.  If you want to clear the cache, call
295 @code{password-reset}.
297 @node External Configuration
298 @subsection External Configuration
300 Your system may already be configured for a default LDAP server.  For
301 example, @file{/etc/openldap/ldap.conf} might contain:
303 @example
304 BASE ou=people,dc=gnu,dc=org
305 URI ldaps://ldap.gnu.org
306 TLS_CACERTDIR /etc/openldap/certs
307 @end example
309 @cindex bind distinguished name
310 @cindex binddn
311 Authentication requires a password, and a @dfn{bind distinguished name
312 (binddn)} representing the user, in this case,
313 @code{gnu\emacsuser}.  These can be specified in
314 @file{~/.authinfo.gpg} with the following line:
316 @example
317 machine ldaps://ldap.gnu.org binddn gnu\emacsuser password s3cr3t
318 @end example
320 Then in the @file{.emacs} init file, these expressions suffice to
321 configure EUDC for LDAP:
323 @vindex message-mode-map
324 @findex eudc-expand-inline
325 @vindex eudc-server-hotlist
326 @vindex ldap-host-parameters-alist
327 @lisp
328 (with-eval-after-load "message"
329   (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
330 (customize-set-variable 'eudc-server-hotlist
331                         '(("" . bbdb)
332                           ("ldaps://ldap.gnu.org" . ldap)))
333 (customize-set-variable 'ldap-host-parameters-alist
334                         '(("ldaps://ldap.gnu.org"
335                            auth-source t)))
336 @end lisp
338 For this example where we only care about one server, the server name
339 can be omitted in @file{~/.authinfo.gpg} and @file{.emacs}, in which
340 case @command{ldapsearch} defaults to the host name in
341 @file{/etc/openldap/ldap.conf}.
343 The @file{~/.authinfo.gpg} line becomes:
345 @example
346 binddn gnu\emacsuser password s3cr3t
347 @end example
349 @noindent
350 and the @file{.emacs} expressions become:
352 @vindex message-mode-map
353 @findex eudc-expand-inline
354 @vindex eudc-server-hotlist
355 @vindex ldap-host-parameters-alist
356 @lisp
357 (with-eval-after-load "message"
358   (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
359 (customize-set-variable 'eudc-server-hotlist
360                         '(("" . bbdb) ("" . ldap)))
361 (customize-set-variable 'ldap-host-parameters-alist
362                         '(("" auth-source t)))
363 @end lisp
365 @node Troubleshooting
366 @subsection Troubleshooting
368 If @command{ldapsearch} exits with an error, you'll see a message like
369 this in the @code{*Messages*} buffer (all on one line):
371 @example
372 ldap-search-internal: Failed ldapsearch invocation:
373    ldapsearch "-Hldaps://ldap.gnu.org" "-bou=people,dc=gnu,dc=org"
374    "-Dgnu\emacsuser" "-W" "-LL" "-tt" "(&(mail=name*))"
375    "givenname" "sn" "mail"
376 @end example
378 The @command{ldapsearch} command is formatted such that it can be
379 copied and pasted into a terminal.  Set the @command{ldapsearch} debug
380 level to 5 by appending @code{-d 5} to the command line.
382 @node Usage
383 @chapter Usage
385 This chapter describes the usage of EUDC@.  Most functions and
386 customization options are available through the @samp{Directory Search}
387 submenu of the @samp{Tools} submenu.
389 @menu
390 * Querying Servers::            How queries are performed and handled
391 * Query Form::                  How to use and customize the query form
392 * Display of Query Results::    Controlling how query results are presented
393 * Inline Query Expansion::      How to use and customize inline queries
394 * The Server Hotlist::          How to use and manage the server hotlist
395 * Multi-server Queries::        How to query multiple servers successively
396 * Creating BBDB Records::       How to insert query results into your BBDB
397 * Server/Protocol Locals::      Customizing on a per server/protocol basis
398 @end menu
401 @node Querying Servers
402 @section Querying Servers
404 EUDC's basic functionality is to let you query a directory server and
405 return the results back to you.  There are several things you may want
406 to customize in this process.
409 @menu
410 * Selecting a Server::          The first thing to do
411 * Return Attributes::           Configuring what the server should return
412 * Duplicate Attributes::        What to do when records have duplicate attributes
413 @end menu
415 @node Selecting a Server
416 @subsection Selecting a Server
418 Before doing any query you will need to set the directory server.  You
419 need to specify the name of the host machine running the server software
420 and the protocol to use. If you do not set the server in any fashion,
421 EUDC will ask you for one when you make your first query.
423 You can set the server by selecting one from your hotlist of servers
424 (@pxref{The Server Hotlist}) available in the @samp{Server} submenu or
425 by selecting @samp{New Server} in that same menu.
427 LDAP servers generally require some configuration before you can perform
428 queries on them.  In particular, the @dfn{search base} must be
429 configured.  If the server you select has no configured search base then
430 EUDC will propose you to configure it at this point.  A customization
431 buffer will be displayed where you can edit the search base and other
432 parameters for the server.
434 @defvar eudc-server
435 The name or IP address of the remote directory server. A TCP port number
436 may be specified by appending a colon and a number to the name of the
437 server. You will not need this unless your server runs on a port other
438 than the default (which depends on the protocol).
439 If the directory server resides on your own computer (which is the case
440 if you use the BBDB back end) then @samp{localhost} is a reasonable value but
441 it will be ignored anyway.
442 @end defvar
444 @defvar eudc-protocol
445 The directory protocol to use to query the server.  Currently supported
446 protocols in this version of EUDC are @code{ldap} and @code{bbdb}.
447 @end defvar
449 @deffn Command eudc-set-server
450 This command accessible from @samp{New Server} submenu lets you specify a
451 new directory server and protocol.
452 @end deffn
454 @node Return Attributes
455 @subsection Return Attributes
457 Directory servers may be configured to return a default set of
458 attributes for each record matching a query if the query specifies none.
459 The variable @code{eudc-default-return-attributes} controls the return
460 attributes you want to see, if different from the server defaults.
462 @defvar eudc-default-return-attributes
463 A list of the default attributes to extract from directory entries.  If
464 set to the symbol @code{all} then all available attributes are
465 returned. A value of @code{nil}, the default, means to return the
466 default attributes as configured in the server.
467 @end defvar
469 The server may return several matching records to a query. Some of the
470 records may however not contain all the attributes you requested. You can
471 discard those records.
473 @defopt eudc-strict-return-matches
474 If non-@code{nil}, entries that do not contain all the requested return
475 attributes are ignored.  Default is @code{t}.
476 @end defopt
478 @node Duplicate Attributes
479 @subsection Duplicate Attributes
481 Directory standards may authorize different instances of the same
482 attribute in a record. For instance the record of a person may contain
483 several email fields containing different email addresses, in which
484 case EUDC will consider the attribute duplicated.
486 EUDC has several methods to deal with duplicated attributes. The
487 available methods are:
489 @table @code
490 @item list
491 Makes a list with the different values of the duplicate attribute. The
492 record is returned with only one instance of the attribute with a list
493 of all the different values as a value. This is the default method that
494 is used to handle duplicate fields for which no other method has been
495 specified.
496 @item first
497 Discards all the duplicate values of the field keeping only the first
498 one.
499 @item concat
500 Concatenates the different values using a newline as a separator. The
501 record keeps only one instance of the field the value of which is a
502 single multi-line string.
503 @item duplicate
504 Duplicates the whole record into as many instances as there are different
505 values for the field. This is the default for the email field. Thus a
506 record containing 3 different email addresses is duplicated into three
507 different records each having a single email address. This is
508 particularly useful in combination with @code{select} as the method to
509 handle multiple matches in inline expansion queries (@pxref{Inline Query
510 Expansion}) because you are presented with the 3 addresses in a
511 selection buffer
512 @end table
514 Because a method may not be applicable to all fields, the variable
515 @code{eudc-duplicate-attribute-handling-method} lets you specify either a
516 default method for all fields or a method for each individual field.
518 @defvar eudc-duplicate-attribute-handling-method
519 A method to handle entries containing duplicate attributes.  This is
520 either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol
521 @var{method}.  The alist form of the variable associates a method to an
522 individual attribute name; the second form specifies a method applicable
523 to all attribute names. Available methods are: @code{list},
524 @code{first}, @code{concat}, and @code{duplicate} (see above).  The default is
525 @code{list}.
526 @end defvar
530 @node Query Form
531 @section Query Form
533 The simplest way to query your directory server is to use the query
534 form. You display the query form with the @samp{Query with Form} menu
535 item or by invoking the command @kbd{M-x eudc-query-form}. The attribute
536 names presented in this form are defined by the
537 @code{eudc-query-form-attributes} variable (unless a non-@code{nil}
538 argument is supplied to @code{eudc-query-form}).
540 Since the different directory protocols to which EUDC interfaces may
541 use different names for equivalent attributes, EUDC defines its own set
542 of attribute names and a mapping between these names and their
543 protocol-specific equivalent through the variable
544 @code{eudc-protocol-attributes-translation-alist}.  Names currently
545 defined by EUDC are @code{name}, @code{firstname}, @code{email} and
546 @code{phone}.
548 @defvar eudc-query-form-attributes
549 @findex eudc-get-attribute-list
550 A list of attributes presented in the query form.  Attribute names in
551 this list should be either EUDC attribute names or valid attribute
552 names.  You can get a list of valid attribute names for the current
553 protocol with the @samp{List Valid Attribute Names} menu item or the
554 @kbd{M-x eudc-get-attribute-list} command.  Defaults to @code{name},
555 @code{email} and @code{phone}.
556 @end defvar
558 @deffn Command eudc-query-form get-fields-from-server
559 Display a form to query the directory server.  If given a non-@code{nil}
560 argument the function first queries the server for the existing fields
561 and displays a corresponding form.  Not all protocols may support a
562 non-@code{nil} argument here.
563 @end deffn
565 Since the names of the fields may not be explicit enough or adapted to
566 be directly displayed as prompt strings in the form, the variable
567 @code{eudc-user-attribute-names-alist} lets you define more explicit
568 names for directory attribute names.  This variable is ignored if
569 @code{eudc-use-raw-directory-names} is non-@code{nil}.
571 @defvar eudc-user-attribute-names-alist
572 This is an alist of user-defined names for the directory attributes used in
573 query/response forms. Prompt strings for attributes that are not in this
574 alist are derived by splitting the attribute name at underscores and
575 capitalizing the individual words.
576 @end defvar
578 @defvar eudc-use-raw-directory-names
579 If non-@code{nil}, use attributes names as defined in the directory.
580 Otherwise, directory query/response forms display the user attribute
581 names defined in @code{eudc-user-attribute-names-alist}.
582 @end defvar
584 @node Display of Query Results
585 @section Display of Query Results
587 Upon successful completion of a form query, EUDC will display a buffer
588 containing the results of the query.
590 The fields that are returned for each record
591 are controlled by @code{eudc-default-return-attributes} (@pxref{Return
592 Attributes}).
594 The display of each individual field can be performed by an arbitrary
595 function which allows specific processing for binary values, such as
596 images or audio samples, as well as values with semantics, such as
597 URLs.
599 @defvar eudc-attribute-display-method-alist
600 An alist specifying methods to display attribute values.  Each member of
601 the list is of the form @code{(@var{name} . @var{func})} where
602 @var{name} is a lowercased string naming a directory attribute
603 (translated according to @code{eudc-user-attribute-names-alist} if
604 @code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a
605 function that will be passed the corresponding attribute values for
606 display.
607 @end defvar
609 This variable has protocol-local definitions (see @pxref{Server/Protocol
610 Locals}).  For instance, it is defined as follows for LDAP:
612 @lisp
613 (eudc-protocol-set 'eudc-attribute-display-method-alist
614                    '(("jpegphoto" . eudc-display-jpeg-inline)
615                      ("labeledurl" . eudc-display-url)
616                      ("audio" . eudc-display-sound)
617                      ("labeledurl" . eudc-display-url)
618                      ("url" . eudc-display-url))
619                    'ldap)
620 @end lisp
622 EUDC provides a set of built-in functions to display binary value types:
624 @defun eudc-display-generic-binary data
625 Display a button for unidentified binary @var{data}.
626 @end defun
628 @defun eudc-display-url url
629 Display URL and make it clickable.
630 @end defun
632 @defun eudc-display-sound data
633 Display a button to play the sound @var{data}.
634 @end defun
636 @defun eudc-display-jpeg-inline data
637 Display the JPEG @var{data} inline at point if possible.
638 @end defun
640 @defun eudc-display-jpeg-as-button data
641 Display a button for the JPEG @var{data}.
642 @end defun
644 Right-clicking on a binary value button pops up a contextual menu with
645 options to process the value.  Among these are saving the attribute
646 value to a file or sending it to an external viewer command.  External
647 viewers should expect the value on their standard input and should
648 display it or perform arbitrary processing on it.  Messages sent to
649 standard output are discarded.  External viewers are listed in the
650 variable @code{eudc-external-viewers} which you can customize.
652 @defvar eudc-external-viewers
653 This is a list of viewer program specifications.  Each specification is
654 a list whose first element is a string naming the viewer for unique
655 identification, the second element is the executable program which
656 should be invoked and the following elements are arguments that should
657 be passed to the program.
658 @end defvar
661 @node Inline Query Expansion
662 @section Inline Query Expansion
664 Inline query expansion is a powerful method to get completion from your
665 directory server.  The most common usage is for expanding names to email
666 addresses in mail message buffers.  The expansion is performed by the
667 command @kbd{M-x eudc-expand-inline} which is available from the
668 @samp{Expand Inline Query} menu item but can also be conveniently
669 bound to a key shortcut (@pxref{Installation}).  The operation is
670 controlled by the variables @code{eudc-inline-expansion-format},
671 @code{eudc-inline-query-format},
672 @code{eudc-expanding-overwrites-query} and
673 @code{eudc-multiple-match-handling-method}.
675 If the query fails for a server, other servers may be tried successively
676 until one of them finds a match (@pxref{Multi-server Queries}).
678 @deffn Command eudc-expand-inline replace-p
679 Query the server and expand the query string before point.  The query
680 string consists of the buffer substring from the point back to the
681 preceding comma, colon or beginning of
682 line.  @code{eudc-inline-query-format} controls how individual words
683 are mapped onto directory attribute names.  After querying the server
684 for the given string, the expansion specified by
685 @code{eudc-inline-expansion-format} is inserted in the buffer at
686 point. If @var{replace-p} is @code{t} then this expansion replaces the
687 query string in the buffer.  If @code{eudc-expanding-overwrites-query}
688 is non-@code{nil} then the meaning of @var{replace-p} is negated.
689 @end deffn
691 @defvar eudc-inline-query-format
692 Format of an inline expansion query.
693 This is actually a list of @var{format}s.  A @var{format} is a list of
694 one or more EUDC attribute names.  A @var{format} applies if it contains
695 as many attributes as individual words in the inline query string.  If
696 several @var{format}s apply then they are tried in order until a match
697 is found.  If @code{nil} all the words will be mapped onto the default
698 server/protocol attribute name (generally @code{name}).
700 For instance, use the following
701 @lisp
702 (setq eudc-inline-query-format '((name)
703                                  (firstname)
704                                  (firstname name)))
705 @end lisp
706 @noindent
707 to indicate that single word expansion queries are to be considered as
708 surnames and if no match is found then they should be tried as first
709 names.  Inline queries consisting of two words are considered as
710 consisting of a first name followed by a surname.  If the query consists
711 of more than two words, then the first one is considered as the first
712 name and the remaining words are all considered as surname constituents.
714 @var{format}s are in fact not limited to EUDC attribute names, you can
715 use server or protocol specific names in them.  It may be safer if you
716 do so, to set the variable @code{eudc-inline-query-format} in a protocol
717 or server local fashion (see @pxref{Server/Protocol Locals}).
719 For instance you could use the following to match up to three words
720 against the @code{cn} attribute of LDAP servers:
721 @lisp
722 (eudc-protocol-set 'eudc-inline-query-format
723                    '((cn)
724                      (cn cn)
725                      (cn cn cn))
726                    'ldap)
727 @end lisp
728 @end defvar
730 @defvar eudc-inline-expansion-format
731 This variable lets you control exactly what is inserted into the buffer
732 upon an inline expansion request.  It is a list whose first element is a
733 string passed to @code{format}.  Remaining elements are symbols
734 corresponding to directory attribute names.  The corresponding attribute
735 values are passed as additional arguments to @code{format}.  Default is
736 @code{("%s %s <%s>" firstname name email)}.
737 @end defvar
739 @defvar eudc-multiple-match-handling-method
740 This variable controls what to do when multiple entries match a query
741 for an inline expansion.  Possible values are:
742 @table @code
743 @item first
744 The first match is considered as being the only one, the others are
745 discarded.
746 @item select
747 A selection buffer pops up where you can choose a particular match.  This
748 is the default value of the variable.
749 @item all
750 The expansion uses all records successively
751 @item abort
752 An error is signaled.  The expansion aborts.
753 @end table
755 Default is @code{select}
756 @end defvar
760 @node The Server Hotlist
761 @section The Server Hotlist
763 EUDC lets you maintain a list of frequently used servers so that you
764 can easily switch from one to another.  This hotlist appears in the
765 @samp{Server} submenu.  You select a server in this list by clicking on
766 its name.  You can add the current server to the list with the command
767 @kbd{M-x eudc-bookmark-current-server}.  The list is contained in the variable
768 @code{eudc-server-hotlist} which is stored in and retrieved from the file
769 designated by @code{eudc-options-file}.  EUDC also provides a facility to
770 edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}).
772 The hotlist is also used to make queries on multiple servers
773 successively (@pxref{Multi-server Queries}).  The order in which the
774 servers are tried is the order they appear in the hotlist, therefore it
775 is important to sort the hotlist appropriately.
777 @deffn Command eudc-bookmark-server server
778 Add @var{server} to the hotlist of servers
779 @end deffn
781 @deffn Command eudc-bookmark-current-server
782 Add the current server to the hotlist of servers
783 @end deffn
785 @defvar eudc-options-file
786 The name of a file where EUDC stores its internal variables (the
787 hotlist and the current server).  EUDC will try to load that file upon
788 initialization so, if you choose a file name different from the
789 defaults @file{~/.emacs.d/eudc-options}, be sure to set this variable
790 to the appropriate value @emph{before} EUDC is itself loaded.
791 @end defvar
793 @menu
794 * The Hotlist Edit Buffer::     An interactive hotlist editing facility
795 @end menu
797 @node The Hotlist Edit Buffer
798 @subsection The Hotlist Edit Buffer
800 The hotlist edit buffer offers a means to manage a list of frequently
801 used servers.  Commands are available in the context pop-up menu
802 generally bound to the right mouse button.  Those commands also have
803 equivalent key bindings.
805 @deffn Command eudc-hotlist-add-server
806 Bound to @kbd{a}.
807 Add a new server to the hotlist on the line after point
808 @end deffn
810 @deffn Command eudc-hotlist-delete-server
811 Bound to @kbd{d}.
812 Delete the server on the line point is on
813 @end deffn
815 @deffn Command eudc-hotlist-select-server
816 Bound to @kbd{s}.
817 Select the server the point is on as the current directory server for
818 the next queries
819 @end deffn
821 @deffn Command eudc-hotlist-transpose-servers
822 Bound to @kbd{t}.
823 Bubble up the server the point is on to the top of the list
824 @end deffn
826 @deffn Command eudc-hotlist-quit-edit
827 Bound to @kbd{q}.
828 Save the changes and quit the hotlist edit buffer.  Use @kbd{x} or
829 @kbd{M-x kill-buffer} to exit without saving.
830 @end deffn
833 @node Multi-server Queries
834 @section Multi-server Queries
836 When using inline query expansion (@pxref{Inline Query Expansion}), EUDC
837 can try to query successively a sequence of directory servers until one
838 of them successfully finds a match for the query.
840 @defvar eudc-inline-expansion-servers
841 This variable controls which servers are tried and in which order when
842 trying to perform an inline query.  Possible values are:
843 @table @code
844 @item current-server
845 Only the current directory server is tried
846 @item hotlist
847 The servers in the hotlist are tried in order until one finds a match
848 for the query or @code{eudc-max-servers-to-query} is reached
849 @item server-then-hotlist
850 The current server then the servers in the hotlist are tried in the
851 order they appear in the hotlist until one of them finds a match or
852 @code{eudc-max-servers-to-query} is reached.  This is the default.
853 @end table
854 @end defvar
856 @defvar eudc-max-servers-to-query
857 This variable indicates the maximum number of servers to query when
858 performing a multi-server query.  The default, @code{nil}, indicates
859 that all available servers should be tried.
860 @end defvar
864 @node Creating BBDB Records
865 @section Creating BBDB Records
867 @findex eudc-insert-record-at-point-into-bbdb
868 @findex eudc-try-bbdb-insert
869 With EUDC, you can automatically create BBDB records
870 (@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a
871 directory server.  You do this by moving point to the appropriate
872 record in a query result display buffer and invoking the command
873 @kbd{M-x eudc-insert-record-at-point-into-bbdb} with the
874 keyboard binding @kbd{b}@footnote{This key binding does not actually
875 call @code{eudc-insert-record-at-point-into-bbdb} but uses
876 @code{eudc-try-bbdb-insert} instead.}, or with the menu.  EUDC
877 cannot update an existing BBDB record and will signal an error if you
878 try to insert a record matching an existing one.
880 @findex eudc-batch-export-records-to-bbdb
881 It is also possible to export to BBDB the whole batch of records
882 contained in the directory query result with the command
883 @kbd{M-x eudc-batch-export-records-to-bbdb}.
885 Because directory systems may not enforce a strict record format, local
886 server installations may use different attribute names and have
887 different ways to organize the information.  Furthermore BBDB has its own
888 record structure.  For these reasons converting a record from its
889 external directory format to the BBDB format is a highly customizable
890 process.
892 @defvar eudc-bbdb-conversion-alist
893 The value of this variable should be a symbol naming an alist defining a
894 mapping between BBDB field names onto directory attribute names records.
895 This is a protocol-local variable and is initialized upon protocol
896 switch (@pxref{Server/Protocol Locals}).  The alist is made of cells of the
897 form @code{(@var{bbdb-field} . @var{spec-or-list})}.
898 @var{bbdb-field} is the name of a field
899 that must be defined in your BBDB environment (standard field names are
900 @code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
901 and @code{notes}).
902 @var{spec-or-list} is either a single mapping specification or a list of
903 mapping specifications.  Lists of mapping specifications are valid for
904 the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
905 actually s-expressions which are evaluated as follows:
907 @table @asis
908 @item a string
909 evaluates to itself
910 @item a symbol
911 evaluates to the symbol value.  Symbols corresponding to directory
912 attribute names present in the record evaluate to the value of the field
913 in the record
914 @item a form
915 is evaluated as a function.  The argument list may contain attribute
916 names which evaluate to the corresponding values in the record.  The form
917 evaluation should return something appropriate for the particular
918 @var{bbdb-field} (see @code{bbdb-create-internal}).
919 @code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
920 convenience functions to parse phones and addresses.
921 @end table
922 @end defvar
924 @defun eudc-bbdbify-phone phone location
925 This is a convenience function provided for use in
926 @code{eudc-bbdb-conversion-alist}.  It parses @var{phone} into a vector
927 compatible with @code{bbdb-create-internal}.  @var{phone} is either a string
928 supposedly containing a phone number or a list of such strings which are
929 concatenated. @var{location} is used as the phone location for BBDB.
930 @end defun
932 @defun eudc-bbdbify-address addr location
933 This is a convenience function provided for use in
934 @code{eudc-bbdb-conversion-alist}.  It parses @var{addr} into a vector
935 compatible with @code{bbdb-create-internal}.  @var{addr} should be an
936 address string of no more than four lines or a list of lines.  The last
937 line is searched for the zip code, city and state name.  @var{location}
938 is used as the phone location for BBDB.
939 @end defun
941 Note that only a subset of the attributes you selected with
942 @code{eudc-default-return-attributes} and that are actually displayed may
943 actually be inserted as part of the newly created BBDB record.
946 @node Server/Protocol Locals
947 @section Server/Protocol Locals
949 EUDC can be customized independently for each server or directory
950 protocol.  All variables can be given local bindings that are activated
951 when a particular server and/or protocol becomes active.  This is much
952 like buffer-local bindings but on a per server or per protocol basis.
954 @menu
955 * Manipulating local bindings::  Functions to set and query local bindings
956 @end menu
958 @node Manipulating local bindings
959 @subsection Manipulating local bindings
961 EUDC offers functions that let you set and query variables on a per
962 server or per protocol basis.
964 The following predicates allow you to test the existence of
965 server/protocol local bindings for a particular variable.
967 @defun eudc-server-local-variable-p var
968 Return non-@code{nil} if @var{var} has server-local bindings
969 @end defun
971 @defun eudc-protocol-local-variable-p var
972 Return non-@code{nil} if @var{var} has protocol-local bindings
973 @end defun
975 The following functions allow you to set the value of a variable with
976 various degrees of locality.
978 @defun eudc-default-set var val
979 Set the EUDC default value of @var{var} to @var{val}.
980 The current binding of @var{var} (if local to the current server or
981 protocol) is not changed.
982 @end defun
984 @defun eudc-protocol-set var val &optional protocol
985 Set the binding of @var{var} local to @var{protocol} to @var{val}.  If
986 omitted, @var{protocol} defaults to the current value of
987 @code{eudc-protocol}.  The current binding of @var{var} is changed only
988 if @var{protocol} is omitted.
989 @end defun
991 @defun eudc-server-set var val &optional server
992 Set the binding of @var{var} local to @var{server} to @var{val}.  If
993 omitted, @var{server} defaults to the current value of
994 @code{eudc-server}.  The current binding of @var{var} is changed only if
995 @var{server} is omitted.
996 @end defun
998 @defun eudc-set var val
999 Set the most local (server, protocol or default) binding of @var{var} to
1000 @var{val}.  The current binding of @var{var} is also set to @var{val}.
1001 @end defun
1003 The following variables allow you to query the various bindings of a
1004 variable (local or non-local).
1006 @defun eudc-variable-default-value var
1007 Return the default binding of @var{var} (outside of a particular server
1008 or protocol local binding).
1009 Return @code{unbound} if @var{var} has no EUDC default value.
1010 @end defun
1012 @defun eudc-variable-protocol-value var &optional protocol
1013 Return the value of @var{var} local to @var{protocol}.  Return
1014 @code{unbound} if @var{var} has no value local to @var{protocol}.
1015 @var{protocol} defaults to @code{eudc-protocol}.
1016 @end defun
1018 @defun eudc-variable-server-value var [server]
1019 Return the value of @var{var} local to @var{server}.
1020 Return @code{unbound} if @var{var} has no value local to @var{server}.
1021 @var{server} defaults to @code{eudc-server}.
1022 @end defun
1024 Changing a protocol-local or server-local value of a variable has no
1025 effect on its current value.  The following command is used to
1026 synchronize the current values of variables with their local values
1027 given the current @code{eudc-server} and @code{eudc-protocol}:
1029 @defun eudc-update-local-variables
1030 Update all EUDC variables according to their local settings.
1031 @end defun
1035 @node Credits
1036 @chapter Credits
1038 EUDC was written by Oscar Figueiredo based on @file{ph.el} by the
1039 same author.
1041 Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
1042 in testing and proofreading the code and docs of @file{ph.el}.
1044 @node GNU Free Documentation License
1045 @appendix GNU Free Documentation License
1046 @include doclicense.texi
1048 @node Index
1049 @unnumbered Index
1051 @printindex cp
1053 @bye