*** empty log message ***
[emacs.git] / man / eudc.texi
blobb5ff83be14a5ded7e966c5d00399a92757d19bb6
1 \input texinfo.tex
2 @c %**start of header
3 @setfilename ../info/eudc
4 @settitle Emacs Unified Directory Client (EUDC) Manual
5 @afourpaper
6 @c %**end of header
8 @copying
9 This file documents EUDC v1.30b.
11 EUDC is the Emacs Unified Directory Client, a common interface to
12 directory servers using various protocols such as LDAP or the CCSO white
13 pages directory system (PH/QI)
15 Copyright 1998, 2000, 2001, 2002 Free Software Foundation, Inc.
17 @quotation
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.1 or
20 any later version published by the Free Software Foundation; with no
21 Invariant Sections, with the Front-Cover texts being ``A GNU
22 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
23 license is included in the section entitled ``GNU Free Documentation
24 License'' in the Emacs manual.
26 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
27 this GNU Manual, like GNU software.  Copies published by the Free
28 Software Foundation raise funds for GNU development.''
30 This document is part of a collection distributed under the GNU Free
31 Documentation License.  If you want to distribute this document
32 separately from the collection, you can do so by adding a copy of the
33 license to the document, as described in section 6 of the license.
34 @end quotation
35 @end copying
37 @dircategory Emacs
38 @direntry
39 * EUDC: (eudc).   An Emacs client for directory servers (LDAP, PH).
40 @end direntry
42 @footnotestyle end
44 @titlepage
45 @title{EUDC Manual}
46 @subtitle{The Emacs Unified Directory Client}
47 @author by Oscar Figueiredo
48 @code{1.30b}
50 @page
51 @vskip 0pt plus 1fill
52 @insertcopying
53 @end titlepage
55 @ifnottex
56 @node     Top, Overview, (dir), (dir)
57 @comment  node-name,  next,         previous, up
60 This manual documents EUDC v1.30b, the Emacs Unified Directory Client.
62 A common interface to directory servers using various protocols such as
63 LDAP or the CCSO white pages directory system (PH/QI)
65 @end ifnottex
67 @menu
68 * Overview::                    Summary of EUDC features
69 * Installation::                How to install EUDC
70 * Usage::                       The various usage possibilities explained
71 * Credits::                     Who's done what
72 * Command and Function Index::
73 * Variables Index::
74 @end menu
80 @node     Overview, Installation, Top, Top
81 @comment  node-name,   next,  previous,  up
82 @chapter Overview
84 EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user
85 interface to access directory servers using different directory
86 protocols.
88 Currently supported back-ends are:
90 @itemize @bullet
91 @item
92 LDAP, Lightweight Directory Access Protocol
93 @item
94 CCSO PH/QI
95 @item
96 BBDB, Big Brother's Insiduous Database
97 @end itemize
99 The main features of the EUDC interface are:
101 @itemize @bullet
102 @item
103 Queries using a customizable form
104 @item
105 Inline query expansion (for instance you can expand a name
106 to an email address in a mail message buffer using a server as an
107 address book)
108 @item
109 Multiple servers can be tried in turn until a match is found for an
110 inline query
111 @item
112 Fast minibuffer queries for email addresses and phone numbers
113 @item
114 Interface to BBDB to let you insert server records into your own BBDB database
115 (@pxref{Top,,BBDB,bbdb,BBDB Manual})
116 @end itemize
118 @menu
119 * LDAP::                        What is LDAP ?
120 * CCSO PH/QI::                  What is CCSO, PH, QI ?
121 * BBDB::                        What is BBDB ?
122 @end menu
126 @node LDAP, CCSO PH/QI, Overview, Overview
127 @comment  node-name,  next,  previous,  up
128 @section LDAP
130 LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication
131 protocol for directory applications defined in RFC 1777.
133 Quoted from RFC 1777:
135 @quotation
136 [LDAP] is designed to provide access to the X.500 Directory while not
137 incurring the resource requirements of the Directory Access Protocol
138 (DAP). This protocol is specifically targeted at simple management
139 applications and browser applications that provide simple read/write
140 interactive access to the X.500 Directory, and is intended to be a
141 complement to the DAP itself.
142 @end quotation
144 LDAP servers usually store (but are not limited to) information about
145 people such as their name, phone number, email address, office
146 location, etc@enddots{} More information about LDAP can be found at
147 @url{http://www.openldap.org/}
149 EUDC requires external support to access LDAP directory servers
150 (@pxref{LDAP Requirements})
153 @node CCSO PH/QI, BBDB, LDAP, Overview
154 @comment  node-name,  next,  previous,  up
155 @section CCSO PH/QI
157 The Central Computing Services Office (CCSO) of the University of
158 Illinois at Urbana Champaign (UIUC) created and freely distributes a
159 directory system that is currently in use in more than 300 organizations
160 around the world.  The system records information about people such as
161 their address, phone number, email, academic information or any other
162 details it was configured to.
164 The system consists of two parts: a database server traditionally called
165 @samp{qi} and a command-line client called @samp{ph}.
166 @url{ftp://uiarchive.cso.uiuc.edu/pub/packages/ph} is the main
167 distribution site.  @url{http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.}
168 provides a listing of the active @samp{qi} servers.
170 The original command-line @samp{ph} client that comes with the
171 @samp{ph/qi} distribution provides additional features like the
172 possibility to communicate with the server in login-mode which makes it
173 possible to change records in the database.  This is not implemented in
174 EUDC.
177 @node BBDB,  , CCSO PH/QI, Overview
178 @comment  node-name,  next,  previous,  up
179 @section BBDB
181 BBDB is the @dfn{Big Brother's Insiduous Database}, a package for Emacs
182 originally written by Jamie Zawinski which provides rolodex-like
183 database functionality featuring tight integration with the Emacs mail
184 and news readers.
186 It is often used as an enhanced email address book.
188 EUDC considers BBDB as a directory server back end just like LDAP or
189 PH/QI servers, though BBDB has no client/server protocol and thus always
190 resides locally on your machine.  The point in this is not to offer an
191 alternate way to query your BBDB database (BBDB itself provides much
192 more flexible ways to do that), but rather to offer an interface to your
193 local directory that is consistent with the interface to external
194 directories (LDAP, PH/QI).  This is particularly interesting when
195 performing queries on multiple servers.
197 EUDC also offers a means to insert results from directory queries into
198 your own local BBDB (@pxref{Creating BBDB Records})
200 @node Installation, Usage, Overview, Top
201 @comment  node-name,  next,  previous,  up
202 @chapter Installation
204 Add the following to your @file{.emacs} init file:
205 @lisp
206 (require 'eudc)
207 @end lisp
208 This will install EUDC at startup.
210 After installing EUDC you will find (the next time you launch Emacs) a
211 new @code{Directory Search} submenu in the @samp{Tools} menu that will
212 give you access to EUDC.
214 You may also find it useful to add the following to your @file{.emacs}
215 initialization file to add a shortcut for email address expansion in
216 email composition buffers (@pxref{Inline Query Expansion})
218 @lisp
219 (eval-after-load
220  "message"
221  '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
222 (eval-after-load
223  "sendmail"
224  '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
225 @end lisp
227 @menu
228 * LDAP Requirements::           EUDC needs external support for LDAP
229 @end menu
231 @node LDAP Requirements,  , Installation, Installation
232 @comment  node-name,  next,  previous,  up
233 @section LDAP Requirements
235 LDAP support is added by means of @file{ldap.el} which is part of Emacs.
236 @file{ldap.el} needs an external command line utility named
237 @file{ldapsearch} which is available as part of LDAP toolkits:
239 @itemize @bullet
240 @item
241 Open LDAP Libraries
242 (@url{http://www.openldap.org/})
243 @item
244 University of Michigan's LDAP Client software
245 (@url{http://www.umich.edu/~dirsvcs/ldap/})
246 @end itemize
249 @node Usage, Credits, Installation, Top
250 @comment  node-name,  next,  previous,  up
251 @chapter Usage
253 This chapter describes the usage of EUDC.  Most functions and
254 customization options are available through the @samp{Directory Search}
255 submenu of the @samp{Tools} submenu.
257 @menu
258 * Querying Servers::            How queries are performed and handled
259 * Query Form::                  How to use and customize the query form
260 * Display of Query Results::    Controlling how query results are presented
261 * Inline Query Expansion::      How to use and customize inline queries
262 * The Server Hotlist::          How to use and manage the server hotlist
263 * Multi-server Queries::        How to query multiple servers successively
264 * Creating BBDB Records::       How to insert query results into your BBDB
265 * Server/Protocol Locals::      Customizing on a per server/protocol basis
266 @end menu
269 @node Querying Servers, Query Form, Usage, Usage
270 @comment  node-name,  next,  previous,  up
271 @section Querying Servers
273 EUDC's basic functionality is to let you query a directory server and
274 return the results back to you.  There are several things you may want
275 to customize in this process.
278 @menu
279 * Selecting a Server::          The first thing to do
280 * Return Attributes::           Configuring what the server should return
281 * Duplicate Attributes::        What to do when records have duplicate attributes
282 @end menu
284 @node Selecting a Server, Return Attributes, Querying Servers, Querying Servers
285 @subsection Selecting a Server
287 Before doing any query you will need to set the directory server.  You
288 need to specify the name of the host machine running the server software
289 and the protocol to use. If you do not set the server in any fashion,
290 EUDC will ask you for one when you make your first query.
292 You can set the server by selecting one from your hotlist of servers
293 (@pxref{The Server Hotlist}) available in the @samp{Server} submenu or
294 by selecting @samp{New Server} in that same menu.
296 LDAP servers generally require some configuration before you can perform
297 queries on them.  In particular, the @dfn{search base} must be
298 configured.  If the server you select has no configured search base then
299 EUDC will propose you to configure it at this point.  A customization
300 buffer will be displayed where you can edit the search base and other
301 parameters for the server.
303 @defvar eudc-server
304 The name or IP address of the remote directory server. A TCP port number
305 may be specified by appending a colon and a number to the name of the
306 server. You will not need this unless your server runs on a port other
307 than the default (which depends on the protocol).
308 If the directory server resides on your own computer (which is the case
309 if you use the BBDB back end) then `localhost' is a reasonable value but
310 it will be ignored anyway.
311 @end defvar
313 @defvar eudc-protocol
314 The directory protocol to use to query the server.  Currently supported
315 protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}.
316 @end defvar
318 @deffn Command eudc-set-server
319 This command accessible from @samp{New Server} submenu lets you specify a
320 new directory server and protocol.
321 @end deffn
323 @node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers
324 @subsection Return Attributes
326 Directory servers may be configured to return a default set of
327 attributes for each record matching a query if the query specifies none.
328 The variable @code{eudc-default-return-attributes} controls the return
329 attributes you want to see, if different from the server defaults.
331 @defvar eudc-default-return-attributes
332 A list of the default attributes to extract from directory entries.  If
333 set to the symbol @code{all} then all available attributes are
334 returned. A value of @code{nil}, the default, means to return the
335 default attributes as configured in the server.
336 @end defvar
338 The server may return several matching records to a query. Some of the
339 records may however not contain all the attributes you requested. You can
340 discard those records.
342 @defopt eudc-strict-return-matches
343 If non-@code{nil}, entries that do not contain all the requested return
344 attributes are ignored.  Default is @code{t}.
345 @end defopt
347 @node Duplicate Attributes,  , Return Attributes, Querying Servers
348 @subsection Duplicate Attributes
350 Directory standards may authorize different instances of the same
351 attribute in a record. For instance the record of a person may contain
352 several email fields containing different email addresses. When using
353 a QI directory server this is difficult to distinguish from attributes
354 having multi-line values such as the postal address that may contain a
355 line for the street and another one for the zip code and city name. In
356 both cases, EUDC will consider the attribute duplicated.
358 EUDC has several methods to deal with duplicated attributes. The
359 available methods are:
361 @table @code
362 @item list
363 Makes a list with the different values of the duplicate attribute. The
364 record is returned with only one instance of the attribute with a list
365 of all the different values as a value. This is the default method that
366 is used to handle duplicate fields for which no other method has been
367 specified.
368 @item first
369 Discards all the duplicate values of the field keeping only the first
370 one.
371 @item concat
372 Concatenates the different values using a newline as a separator. The
373 record keeps only one instance of the field the value of which is a
374 single multi-line string.
375 @item duplicate
376 Duplicates the whole record into as many instances as there are different
377 values for the field. This is the default for the email field. Thus a
378 record containing 3 different email addresses is duplicated into three
379 different records each having a single email address. This is
380 particularly useful in combination with @code{select} as the method to
381 handle multiple matches in inline expansion queries (@pxref{Inline Query
382 Expansion}) because you are presented with the 3 addresses in a
383 selection buffer
384 @end table
386 Because a method may not be applicable to all fields, the variable
387 @code{eudc-duplicate-attribute-handling-method} lets you specify either a
388 default method for all fields or a method for each individual field.
390 @defvar eudc-duplicate-attribute-handling-method
391 A method to handle entries containing duplicate attributes.  This is
392 either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol
393 @var{method}.  The alist form of the variable associates a method to an
394 individual attribute name; the second form specifies a method applicable
395 to all attribute names. Available methods are: @code{list},
396 @code{first}, @code{concat}, and @code{duplicate} (see above).  The default is
397 @code{list}.
398 @end defvar
402 @node Query Form, Display of Query Results, Querying Servers, Usage
403 @comment  node-name,  next,  previous,  up
404 @section Query Form
406 The simplest way to query your directory server is to use the query
407 form. You display the query form with the @samp{Query with Form} menu
408 item or by invoking the command @kbd{M-x eudc-query-form}. The attribute
409 names presented in this form are defined by the
410 @code{eudc-query-form-attributes} variable (unless a non-@code{nil}
411 argument is supplied to @code{eudc-query-form}).
413 Since the different directory protocols to which EUDC interfaces may
414 use different names for equivalent attributes, EUDC defines its own set
415 of attribute names and a mapping between these names and their
416 protocol-specific equivalent through the variable
417 @code{eudc-protocol-attributes-translation-alist}.  Names currently
418 defined by EUDC are @code{name}, @code{firstname}, @code{email} and
419 @code{phone}.
421 @defvar eudc-query-form-attributes
422 @findex eudc-get-attribute-list
423 A list of attributes presented in the query form.  Attribute names in
424 this list should be either EUDC attribute names or valid attribute
425 names.  You can get a list of valid attribute names for the current
426 protocol with the @samp{List Valid Attribute Names} menu item or the
427 @kbd{M-x eudc-get-attribute-list} command.  Defaults to @code{name},
428 @code{email} and @code{phone}.
429 @end defvar
431 @deffn Command eudc-query-form get-fields-from-server
432 Display a form to query the directory server.  If given a non-@code{nil}
433 argument the function first queries the server for the existing fields
434 and displays a corresponding form.  Not all protocols may support a
435 non-@code{nil} argument here.
436 @end deffn
438 Since the names of the fields may not be explicit enough or adapted to
439 be directly displayed as prompt strings in the form, the variable
440 @code{eudc-user-attribute-names-alist} lets you define more explicit
441 names for directory attribute names.  This variable is ignored if
442 @code{eudc-use-raw-directory-names} is non-@code{nil}.
444 @defvar eudc-user-attribute-names-alist
445 This is an alist of user-defined names for the directory attributes used in
446 query/response forms. Prompt strings for attributes that are not in this
447 alist are derived by splitting the attribute name at underscores and
448 capitalizing the individual words.
449 @end defvar
451 @defvar eudc-use-raw-directory-names
452 If non-@code{nil}, use attributes names as defined in the directory.
453 Otherwise, directory query/response forms display the user attribute
454 names defined in @code{eudc-user-attribute-names-alist}.
455 @end defvar
457 @node Display of Query Results, Inline Query Expansion, Query Form, Usage
458 @comment  node-name,  next,  previous,  up
459 @section Display of Query Results
461 Upon successful completion of a form query, EUDC will display a buffer
462 containing the results of the query.
464 The fields that are returned for each record
465 are controlled by @code{eudc-default-return-attributes} (@pxref{Return
466 Attributes}).
468 The display of each individual field can be performed by an arbitrary
469 function which allows specific processing for binary values, such as
470 images or audio samples, as well as values with semantics, such as
471 URLs.
473 @defvar eudc-attribute-display-method-alist
474 An alist specifying methods to display attribute values.  Each member of
475 the list is of the form @code{(@var{name} . @var{func})} where
476 @var{name} is a lowercased string naming a directory attribute
477 (translated according to @code{eudc-user-attribute-names-alist} if
478 @code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a
479 function that will be passed the corresponding attribute values for
480 display.
481 @end defvar
483 This variable has protocol-local definitions (see @pxref{Server/Protocol
484 Locals}).  For instance, it is defined as follows for LDAP:
486 @lisp
487 (eudc-protocol-set 'eudc-attribute-display-method-alist
488                    '(("jpegphoto" . eudc-display-jpeg-inline)
489                      ("labeledurl" . eudc-display-url)
490                      ("audio" . eudc-display-sound)
491                      ("labeledurl" . eudc-display-url)
492                      ("url" . eudc-display-url))
493                    'ldap)
494 @end lisp
496 EUDC provides a set of built-in functions to display binary value types:
498 @defun eudc-display-generic-binary data
499 Display a button for unidentified binary @var{data}.
500 @end defun
502 @defun eudc-display-url url
503 Display URL and make it clickable.
504 @end defun
506 @defun eudc-display-sound data
507 Display a button to play the sound @var{data}.
508 @end defun
510 @defun eudc-display-jpeg-inline data
511 Display the JPEG @var{data} inline at point if possible.
512 @end defun
514 @defun eudc-display-jpeg-as-button data
515 Display a button for the JPEG @var{data}.
516 @end defun
518 Right-clicking on a binary value button pops up a contextual menu with
519 options to process the value.  Among these are saving the attribute
520 value to a file or sending it to an external viewer command.  External
521 viewers should expect the value on their standard input and should
522 display it or perform arbitrary processing on it.  Messages sent to
523 standard output are discarded.  External viewers are listed in the
524 variable @code{eudc-external-viewers} which you can customize.
526 @defvar eudc-external-viewers
527 This is a list of viewer program specifications.  Each specification is
528 a list whose first element is a string naming the viewer for unique
529 identification, the second element is the executable program which
530 should be invoked and the following elements are arguments that should
531 be passed to the program.
532 @end defvar
535 @node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage
536 @comment  node-name,  next,  previous,  up
537 @section Inline Query Expansion
539 Inline query expansion is a powerful method to get completion from your
540 directory server.  The most common usage is for expanding names to email
541 addresses in mail message buffers.  The expansion is performed by the
542 command @kbd{M-x eudc-expand-inline} which is available from the
543 @samp{Expand Inline Query} menu item but can also be conveniently
544 bound to a key shortcut (@pxref{Installation}).  The operation is
545 controlled by the variables @code{eudc-inline-expansion-format},
546 @code{eudc-inline-query-format},
547 @code{eudc-expanding-overwrites-query} and
548 @code{eudc-multiple-match-handling-method}.
550 If the query fails for a server, other servers may be tried successively
551 until one of them finds a match (@pxref{Multi-server Queries}).
553 @deffn Command eudc-expand-inline replace-p
554 Query the server and expand the query string before point.  The query
555 string consists of the buffer substring from the point back to the
556 preceding comma, colon or beginning of
557 line.  @code{eudc-inline-query-format} controls how individual words
558 are mapped onto directory attribute names.  After querying the server
559 for the given string, the expansion specified by
560 @code{eudc-inline-expansion-format} is inserted in the buffer at
561 point. If @var{replace-p} is @code{t} then this expansion replaces the
562 query string in the buffer.  If @code{eudc-expanding-overwrites-query}
563 is non-@code{nil} then the meaning of @var{replace-p} is negated.
564 @end deffn
566 @defvar eudc-inline-query-format
567 Format of an inline expansion query.
568 This is actually a list of @var{format}s.  A @var{format} is a list of
569 one or more EUDC attribute names.  A @var{format} applies if it contains
570 as many attributes as individual words in the inline query string.  If
571 several @var{format}s apply then they are tried in order until a match
572 is found.  If @code{nil} all the words will be mapped onto the default
573 server/protocol attribute name (generally @code{name}).
575 For instance, use the following
576 @lisp
577 (setq eudc-inline-query-format '((name)
578                                  (firstname)
579                                  (firstname name)))
580 @end lisp
581 @noindent
582 to indicate that single word expansion queries are to be considered as
583 surnames and if no match is found then they should be tried as first
584 names.  Inline queries consisting of two words are considered as
585 consisting of a first name followed by a surname.  If the query consists
586 of more than two words, then the first one is considered as the first
587 name and the remaining words are all considered as surname constituents.
589 @var{format}s are in fact not limited to EUDC attribute names, you can
590 use server or protocol specific names in them.  It may be safer if you
591 do so, to set the variable @code{eudc-inline-query-format} in a protocol
592 or server local fashion (see @pxref{Server/Protocol Locals}).
594 For instance you could use the following to match up to three words
595 against the @code{cn} attribute of LDAP servers:
596 @lisp
597 (eudc-protocol-set 'eudc-inline-query-format
598                    '((cn)
599                      (cn cn)
600                      (cn cn cn))
601                    'ldap)
602 @end lisp
603 @end defvar
605 @defvar eudc-inline-expansion-format
606 This variable lets you control exactly what is inserted into the buffer
607 upon an inline expansion request.  It is a list whose first element is a
608 string passed to @code{format}.  Remaining elements are symbols
609 corresponding to directory attribute names.  The corresponding attribute
610 values are passed as additional arguments to @code{format}.  Default is
611 @code{("%s" email)} but you may want to consider a value like @code{("%s
612 <%s>" name email)}
613 @end defvar
615 @defvar eudc-multiple-match-handling-method
616 This variable controls what to do when multiple entries match a query
617 for an inline expansion.  Possible values are:
618 @table @code
619 @item first
620 The first match is considered as being the only one, the others are
621 discarded.
622 @item select
623 A selection buffer pops up where you can choose a particular match.  This
624 is the default value of the variable.
625 @item all
626 The expansion uses all records successively
627 @item abort
628 An error is signaled.  The expansion aborts.
629 @end table
631 Default is @code{select}
632 @end defvar
636 @node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage
637 @comment  node-name,  next,  previous,  up
638 @section The Server Hotlist
640 EUDC lets you maintain a list of frequently used servers so that you
641 can easily switch from one to another.  This hotlist appears in the
642 @samp{Server} submenu.  You select a server in this list by clicking on
643 its name.  You can add the current server to the list with the command
644 @kbd{M-x eudc-bookmark-current-server}.  The list is contained in the variable
645 @code{eudc-server-hotlist} which is stored in and retrieved from the file
646 designated by @code{eudc-options-file}.  EUDC also provides a facility to
647 edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}).
649 The hotlist is also used to make queries on multiple servers
650 successively (@pxref{Multi-server Queries}).  The order in which the
651 servers are tried is the order they appear in the hotlist, therefore it
652 is important to sort the hotlist appropriately.
654 @deffn Command eudc-bookmark-server server
655 Add @var{server} to the hotlist of servers
656 @end deffn
658 @deffn Command eudc-bookmark-current-server
659 Add the current server to the hotlist of servers
660 @end deffn
662 @defvar eudc-options-file
663 The name of a file where EUDC stores its internal variables
664 (the hotlist and the current server).  EUDC will try to load
665 that file upon initialization so, if you choose a file name
666 different from the defaults @file{~/.eudc-options}, be sure to set this
667 variable to the appropriate value @emph{before} EUDC is itself
668 loaded.
669 @end defvar
671 @menu
672 * The Hotlist Edit Buffer::     An interactive hotlist editing facility
673 @end menu
675 @node The Hotlist Edit Buffer,  , The Server Hotlist, The Server Hotlist
676 @comment  node-name,  next,  previous,  up
677 @subsection The Hotlist Edit Buffer
679 The hotlist edit buffer offers a means to manage a list of frequently
680 used servers.  Commands are available in the context pop-up menu
681 generally bound to the right mouse button.  Those commands also have
682 equivalent key bindings.
684 @deffn Command eudc-hotlist-add-server
685 Bound to @kbd{a}.
686 Add a new server to the hotlist on the line after point
687 @end deffn
689 @deffn Command eudc-hotlist-delete-server
690 Bound to @kbd{d}.
691 Delete the server on the line point is on
692 @end deffn
694 @deffn Command eudc-hotlist-select-server
695 Bound to @kbd{s}.
696 Select the server the point is on as the current directory server for
697 the next queries
698 @end deffn
700 @deffn Command eudc-hotlist-transpose-servers
701 Bound to @kbd{t}.
702 Bubble up the server the point is on to the top of the list
703 @end deffn
705 @deffn Command eudc-hotlist-quit-edit
706 Bound to @kbd{q}.
707 Save the changes and quit the hotlist edit buffer.  Use @kbd{x} or
708 @kbd{M-x kill-buffer} to exit without saving.
709 @end deffn
712 @node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage
713 @comment  node-name,  next,  previous,  up
714 @section Multi-server Queries
716 When using inline query expansion (@pxref{Inline Query Expansion}), EUDC
717 can try to query successively a sequence of directory servers until one
718 of them successfully finds a match for the query.
720 @defvar eudc-inline-expansion-servers
721 This variable controls which servers are tried and in which order when
722 trying to perform an inline query.  Possible values are:
723 @table @code
724 @item current-server
725 Only the current directory server is tried
726 @item hotlist
727 The servers in the hotlist are tried in order until one finds a match
728 for the query or `eudc-max-servers-to-query' is reached
729 @item server-then-hotlist
730 The current server then the servers in the hotlist are tried in the
731 order they appear in the hotlist until one of them finds a match or
732 `eudc-max-servers-to-query' is reached.  This is the default.
733 @end table
734 @end defvar
736 @defvar eudc-max-servers-to-query
737 This variable indicates the maximum number of servers to query when
738 performing a multi-server query.  The default, @code{nil}, indicates
739 that all available servers should be tried.
740 @end defvar
744 @node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage
745 @comment  node-name,  next,  previous,  up
746 @section Creating BBDB Records
748 @findex eudc-insert-record-at-point-into-bbdb
749 @findex eudc-try-bbdb-insert
750 With EUDC, you can automatically create BBDB records
751 (@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a
752 directory server.  You do this by moving point to the appropriate
753 record in a query result display buffer and invoking the command
754 @kbd{M-x eudc-insert-record-at-point-into-bbdb} with the
755 keyboard binding @kbd{b}@footnote{This key binding does not actually
756 call @code{eudc-insert-record-at-point-into-bbdb} but uses
757 @code{eudc-try-bbdb-insert} instead.}, or with the menu.  EUDC
758 cannot update an existing BBDB record and will signal an error if you
759 try to insert a record matching an existing one.
761 @findex eudc-batch-export-records-to-bbdb
762 It is also possible to export to BBDB the whole batch of records
763 contained in the directory query result with the command
764 @kbd{M-x eudc-batch-export-records-to-bbdb}.
766 Because directory systems may not enforce a strict record format, local
767 server installations may use different attribute names and have
768 different ways to organize the information.  Furthermore BBDB has its own
769 record structure.  For these reasons converting a record from its
770 external directory format to the BBDB format is a highly customizable
771 process.
773 @defvar eudc-bbdb-conversion-alist
774 The value of this variable should be a symbol naming an alist defining a
775 mapping between BBDB field names onto directory attribute names records.
776 This is a protocol-local variable and is initialized upon protocol
777 switch (@pxref{Server/Protocol Locals}).  The alist is made of cells of the
778 form @code{(@var{bbdb-field} . @var{spec-or-list})}.
779 @var{bbdb-field} is the name of a field
780 that must be defined in your BBDB environment (standard field names are
781 @code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
782 and @code{notes}).
783 @var{spec-or-list} is either a single mapping specification or a list of
784 mapping specifications.  Lists of mapping specifications are valid for
785 the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
786 actually s-expressions which are evaluated as follows:
788 @table @asis
789 @item a string
790 evaluates to itself
791 @item a symbol
792 evaluates to the symbol value.  Symbols corresponding to directory
793 attribute names present in the record evaluate to the value of the field
794 in the record
795 @item a form
796 is evaluated as a function.  The argument list may contain attribute
797 names which evaluate to the corresponding values in the record.  The form
798 evaluation should return something appropriate for the particular
799 @var{bbdb-field} (see @code{bbdb-create-internal}).
800 @code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
801 convenience functions to parse phones and addresses.
802 @end table
803 @end defvar
805 The default value of the PH-specific value of that variable is
806 @code{eudc-ph-bbdb-conversion-alist}:
808 @lisp
809 ((name . name)
810  (net . email)
811  (address . (eudc-bbdbify-address address "Address"))
812  (phone . ((eudc-bbdbify-phone phone "Phone")
813            (eudc-bbdbify-phone office_phone "Office Phone"))))
814 @end lisp
816 This means that:
818 @itemize @bullet
819 @item
820 the @code{name} field of the BBDB record gets its value
821 from the @code{name} attribute of the directory record
822 @item
823 the @code{net} field of the BBDB record gets its value
824 from the @code{email} attribute of the directory record
825 @item
826 the @code{address} field of the BBDB record is obtained by parsing the
827 @code{address} attribute of the directory record with the function
828 @code{eudc-bbdbify-address}
829 @item
830 two @code{phone} fields are created (when possible) in the BBDB record.
831 The first one has @cite{Phone} for location and its value is obtained by
832 parsing the @code{phone} attribute of the PH/QI record with the function
833 @code{eudc-bbdbify-phone}.  The second one has @cite{Office Phone} for location
834 its value is obtained by parsing the @code{office_phone} attribute of the
835 PH/QI record with the function @code{eudc-bbdbify-phone}.
836 @end itemize
838 @defun eudc-bbdbify-phone phone location
839 This is a convenience function provided for use in
840 @code{eudc-bbdb-conversion-alist}.  It parses @var{phone} into a vector
841 compatible with @code{bbdb-create-internal}.  @var{phone} is either a string
842 supposedly containing a phone number or a list of such strings which are
843 concatenated. @var{location} is used as the phone location for BBDB.
844 @end defun
846 @defun eudc-bbdbify-address addr location
847 This is a convenience function provided for use in
848 @code{eudc-bbdb-conversion-alist}.  It parses @var{addr} into a vector
849 compatible with @code{bbdb-create-internal}.  @var{addr} should be an
850 address string of no more than four lines or a list of lines.  The last
851 line is searched for the zip code, city and state name.  @var{location}
852 is used as the phone location for BBDB.
853 @end defun
855 Note that only a subset of the attributes you selected with
856 @code{eudc-default-return-attributes} and that are actually displayed may
857 actually be inserted as part of the newly created BBDB record.
860 @node Server/Protocol Locals,  , Creating BBDB Records, Usage
861 @comment  node-name,  next,  previous,  up
862 @section Server/Protocol Locals
864 EUDC can be customized independently for each server or directory
865 protocol.  All variables can be given local bindings that are activated
866 when a particular server and/or protocol becomes active.  This is much
867 like buffer-local bindings but on a per server or per protocol basis.
869 @menu
870 * Manipulating local bindings::  Functions to set and query local bindings
871 @end menu
873 @node Manipulating local bindings,  , Server/Protocol Locals, Server/Protocol Locals
874 @comment  node-name,  next,  previous,  up
875 @subsection Manipulating local bindings
877 EUDC offers functions that let you set and query variables on a per
878 server or per protocol basis.
880 The following predicates allow you to test the existence of
881 server/protocol local bindings for a particular variable.
883 @defun eudc-server-local-variable-p var
884 Return non-@code{nil} if @var{var} has server-local bindings
885 @end defun
887 @defun eudc-protocol-local-variable-p var
888 Return non-@code{nil} if @var{var} has protocol-local bindings
889 @end defun
891 The following functions allow you to set the value of a variable with
892 various degrees of locality.
894 @defun eudc-default-set var val
895 Set the EUDC default value of @var{var} to @var{val}.
896 The current binding of @var{var} (if local to the current server or
897 protocol) is not changed.
898 @end defun
900 @defun eudc-protocol-set var val &optional protocol
901 Set the binding of @var{var} local to @var{protocol} to @var{val}.  If
902 omitted, @var{protocol} defaults to the current value of
903 @code{eudc-protocol}.  The current binding of @var{var} is changed only
904 if @var{protocol} is omitted.
905 @end defun
907 @defun eudc-server-set var val &optional server
908 Set the binding of @var{var} local to @var{server} to @var{val}.  If
909 omitted, @var{server} defaults to the current value of
910 @code{eudc-server}.  The current binding of @var{var} is changed only if
911 @var{server} is omitted.
912 @end defun
914 @defun eudc-set var val
915 Set the most local (server, protocol or default) binding of @var{var} to
916 @var{val}.  The current binding of @var{var} is also set to @var{val}.
917 @end defun
919 The following variables allow you to query the various bindings of a
920 variable (local or non-local).
922 @defun eudc-variable-default-value var
923 Return the default binding of @var{var} (outside of a particular server
924 or protocol local binding).
925 Return @code{unbound} if @var{var} has no EUDC default value.
926 @end defun
928 @defun eudc-variable-protocol-value var &optional protocol
929 Return the value of @var{var} local to @var{protocol}.  Return
930 @code{unbound} if @var{var} has no value local to @var{protocol}.
931 @var{protocol} defaults to @code{eudc-protocol}.
932 @end defun
934 @defun eudc-variable-server-value var [server]
935 Return the value of @var{var} local to @var{server}.
936 Return @code{unbound} if @var{var} has no value local to @var{server}.
937 @var{server} defaults to @code{eudc-server}.
938 @end defun
940 Changing a protocol-local or server-local value of a variable has no
941 effect on its current value.  The following command is used to
942 synchronize the current values of variables with their local values
943 given the current @code{eudc-server} and @code{eudc-protocol}:
945 @defun eudc-update-local-variables
946 Update all EUDC variables according to their local settings.
947 @end defun
951 @node Credits, Command and Function Index, Usage, Top
952 @comment  node-name,  next,  previous,  up
953 @chapter Credits
955 EUDC was written by Oscar Figueiredo based on @file{ph.el} by the
956 same author.
958 Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
959 in testing and proofreading the code and docs of @file{ph.el}.
961 @node Command and Function Index, Variables Index, Credits, Top
962 @comment  node-name,  next,  previous,  up
963 @unnumbered Command and Function Index
965 @printindex fn
967 @node Variables Index,  , Command and Function Index, Top
968 @comment  node-name,  next,  previous,  up
969 @unnumbered Variables Index
971 @printindex vr
973 @setchapternewpage odd
974 @contents
975 @bye
977 @ignore
978    arch-tag: 1b79460b-4ea1-441d-ab45-05ddd16ef241
979 @end ignore