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