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