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