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