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