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