# HG changeset patch # User Glenn Morris # Date 1189053370 0 # Node ID 6b43164de1e9f73bc21afc69aefd601d6e4c1447 # Parent a7bcf165720dea749bc74e08bd5c84226a0fbc1b Move to ../doc/emacs/, misc/ diff -r a7bcf165720d -r 6b43164de1e9 man/eudc.texi --- a/man/eudc.texi Thu Sep 06 04:36:05 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,985 +0,0 @@ -\input texinfo.tex -@c %**start of header -@setfilename ../info/eudc -@settitle Emacs Unified Directory Client (EUDC) Manual -@afourpaper -@c %**end of header - -@copying -This file documents EUDC v1.30b. - -EUDC is the Emacs Unified Directory Client, a common interface to -directory servers using various protocols such as LDAP or the CCSO white -pages directory system (PH/QI) - -Copyright @copyright{} 1998, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify -this GNU Manual, like GNU software. Copies published by the Free -Software Foundation raise funds for GNU development.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs -@direntry -* EUDC: (eudc). An Emacs client for directory servers (LDAP, PH). -@end direntry - -@footnotestyle end - -@titlepage -@title{EUDC Manual} -@subtitle{The Emacs Unified Directory Client} -@author by Oscar Figueiredo -@code{1.30b} - -@page -@vskip 0pt plus 1fill -@insertcopying -@end titlepage - -@ifnottex -@node Top, Overview, (dir), (dir) -@comment node-name, next, previous, up - - -This manual documents EUDC v1.30b, the Emacs Unified Directory Client. - -A common interface to directory servers using various protocols such as -LDAP or the CCSO white pages directory system (PH/QI) - -@end ifnottex - -@menu -* Overview:: Summary of EUDC features -* Installation:: How to install EUDC -* Usage:: The various usage possibilities explained -* Credits:: Who's done what -* GNU Free Documentation License:: The license for this documentation. -* Command and Function Index:: -* Variables Index:: -@end menu - - - - - -@node Overview, Installation, Top, Top -@comment node-name, next, previous, up -@chapter Overview - -EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user -interface to access directory servers using different directory -protocols. - -Currently supported back-ends are: - -@itemize @bullet -@item -LDAP, Lightweight Directory Access Protocol -@item -CCSO PH/QI -@item -BBDB, Big Brother's Insidious Database -@end itemize - -The main features of the EUDC interface are: - -@itemize @bullet -@item -Queries using a customizable form -@item -Inline query expansion (for instance you can expand a name -to an email address in a mail message buffer using a server as an -address book) -@item -Multiple servers can be tried in turn until a match is found for an -inline query -@item -Fast minibuffer queries for email addresses and phone numbers -@item -Interface to BBDB to let you insert server records into your own BBDB database -(@pxref{Top,,BBDB,bbdb,BBDB Manual}) -@end itemize - -@menu -* LDAP:: What is LDAP ? -* CCSO PH/QI:: What is CCSO, PH, QI ? -* BBDB:: What is BBDB ? -@end menu - - - -@node LDAP, CCSO PH/QI, Overview, Overview -@comment node-name, next, previous, up -@section LDAP - -LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication -protocol for directory applications defined in RFC 1777. - -Quoted from RFC 1777: - -@quotation -[LDAP] is designed to provide access to the X.500 Directory while not -incurring the resource requirements of the Directory Access Protocol -(DAP). This protocol is specifically targeted at simple management -applications and browser applications that provide simple read/write -interactive access to the X.500 Directory, and is intended to be a -complement to the DAP itself. -@end quotation - -LDAP servers usually store (but are not limited to) information about -people such as their name, phone number, email address, office -location, etc@enddots{} More information about LDAP can be found at -@url{http://www.openldap.org/} - -EUDC requires external support to access LDAP directory servers -(@pxref{LDAP Requirements}) - - -@node CCSO PH/QI, BBDB, LDAP, Overview -@comment node-name, next, previous, up -@section CCSO PH/QI - -The Central Computing Services Office (CCSO) of the University of -Illinois at Urbana Champaign (UIUC) created and freely distributes a -directory system that is currently in use in more than 300 organizations -around the world. The system records information about people such as -their address, phone number, email, academic information or any other -details it was configured to. - -The system consists of two parts: a database server traditionally called -@samp{qi} and a command-line client called @samp{ph}. -@url{ftp://uiarchive.cso.uiuc.edu/pub/packages/ph} is the main -distribution site. @url{http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.} -provides a listing of the active @samp{qi} servers. - -The original command-line @samp{ph} client that comes with the -@samp{ph/qi} distribution provides additional features like the -possibility to communicate with the server in login-mode which makes it -possible to change records in the database. This is not implemented in -EUDC. - - -@node BBDB, , CCSO PH/QI, Overview -@comment node-name, next, previous, up -@section BBDB - -BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs -originally written by Jamie Zawinski which provides rolodex-like -database functionality featuring tight integration with the Emacs mail -and news readers. - -It is often used as an enhanced email address book. - -EUDC considers BBDB as a directory server back end just like LDAP or -PH/QI servers, though BBDB has no client/server protocol and thus always -resides locally on your machine. The point in this is not to offer an -alternate way to query your BBDB database (BBDB itself provides much -more flexible ways to do that), but rather to offer an interface to your -local directory that is consistent with the interface to external -directories (LDAP, PH/QI). This is particularly interesting when -performing queries on multiple servers. - -EUDC also offers a means to insert results from directory queries into -your own local BBDB (@pxref{Creating BBDB Records}) - -@node Installation, Usage, Overview, Top -@comment node-name, next, previous, up -@chapter Installation - -Add the following to your @file{.emacs} init file: -@lisp -(require 'eudc) -@end lisp -This will install EUDC at startup. - -After installing EUDC you will find (the next time you launch Emacs) a -new @code{Directory Search} submenu in the @samp{Tools} menu that will -give you access to EUDC. - -You may also find it useful to add the following to your @file{.emacs} -initialization file to add a shortcut for email address expansion in -email composition buffers (@pxref{Inline Query Expansion}) - -@lisp -(eval-after-load - "message" - '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) -(eval-after-load - "sendmail" - '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) -@end lisp - -@menu -* LDAP Requirements:: EUDC needs external support for LDAP -@end menu - -@node LDAP Requirements, , Installation, Installation -@comment node-name, next, previous, up -@section LDAP Requirements - -LDAP support is added by means of @file{ldap.el} which is part of Emacs. -@file{ldap.el} needs an external command line utility named -@file{ldapsearch} which is available as part of LDAP toolkits: - -@itemize @bullet -@item -Open LDAP Libraries -(@url{http://www.openldap.org/}) -@item -University of Michigan's LDAP Client software -(@url{http://www.umich.edu/~dirsvcs/ldap/}) -@end itemize - - -@node Usage, Credits, Installation, Top -@comment node-name, next, previous, up -@chapter Usage - -This chapter describes the usage of EUDC. Most functions and -customization options are available through the @samp{Directory Search} -submenu of the @samp{Tools} submenu. - -@menu -* Querying Servers:: How queries are performed and handled -* Query Form:: How to use and customize the query form -* Display of Query Results:: Controlling how query results are presented -* Inline Query Expansion:: How to use and customize inline queries -* The Server Hotlist:: How to use and manage the server hotlist -* Multi-server Queries:: How to query multiple servers successively -* Creating BBDB Records:: How to insert query results into your BBDB -* Server/Protocol Locals:: Customizing on a per server/protocol basis -@end menu - - -@node Querying Servers, Query Form, Usage, Usage -@comment node-name, next, previous, up -@section Querying Servers - -EUDC's basic functionality is to let you query a directory server and -return the results back to you. There are several things you may want -to customize in this process. - - -@menu -* Selecting a Server:: The first thing to do -* Return Attributes:: Configuring what the server should return -* Duplicate Attributes:: What to do when records have duplicate attributes -@end menu - -@node Selecting a Server, Return Attributes, Querying Servers, Querying Servers -@subsection Selecting a Server - -Before doing any query you will need to set the directory server. You -need to specify the name of the host machine running the server software -and the protocol to use. If you do not set the server in any fashion, -EUDC will ask you for one when you make your first query. - -You can set the server by selecting one from your hotlist of servers -(@pxref{The Server Hotlist}) available in the @samp{Server} submenu or -by selecting @samp{New Server} in that same menu. - -LDAP servers generally require some configuration before you can perform -queries on them. In particular, the @dfn{search base} must be -configured. If the server you select has no configured search base then -EUDC will propose you to configure it at this point. A customization -buffer will be displayed where you can edit the search base and other -parameters for the server. - -@defvar eudc-server -The name or IP address of the remote directory server. A TCP port number -may be specified by appending a colon and a number to the name of the -server. You will not need this unless your server runs on a port other -than the default (which depends on the protocol). -If the directory server resides on your own computer (which is the case -if you use the BBDB back end) then `localhost' is a reasonable value but -it will be ignored anyway. -@end defvar - -@defvar eudc-protocol -The directory protocol to use to query the server. Currently supported -protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}. -@end defvar - -@deffn Command eudc-set-server -This command accessible from @samp{New Server} submenu lets you specify a -new directory server and protocol. -@end deffn - -@node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers -@subsection Return Attributes - -Directory servers may be configured to return a default set of -attributes for each record matching a query if the query specifies none. -The variable @code{eudc-default-return-attributes} controls the return -attributes you want to see, if different from the server defaults. - -@defvar eudc-default-return-attributes -A list of the default attributes to extract from directory entries. If -set to the symbol @code{all} then all available attributes are -returned. A value of @code{nil}, the default, means to return the -default attributes as configured in the server. -@end defvar - -The server may return several matching records to a query. Some of the -records may however not contain all the attributes you requested. You can -discard those records. - -@defopt eudc-strict-return-matches -If non-@code{nil}, entries that do not contain all the requested return -attributes are ignored. Default is @code{t}. -@end defopt - -@node Duplicate Attributes, , Return Attributes, Querying Servers -@subsection Duplicate Attributes - -Directory standards may authorize different instances of the same -attribute in a record. For instance the record of a person may contain -several email fields containing different email addresses. When using -a QI directory server this is difficult to distinguish from attributes -having multi-line values such as the postal address that may contain a -line for the street and another one for the zip code and city name. In -both cases, EUDC will consider the attribute duplicated. - -EUDC has several methods to deal with duplicated attributes. The -available methods are: - -@table @code -@item list -Makes a list with the different values of the duplicate attribute. The -record is returned with only one instance of the attribute with a list -of all the different values as a value. This is the default method that -is used to handle duplicate fields for which no other method has been -specified. -@item first -Discards all the duplicate values of the field keeping only the first -one. -@item concat -Concatenates the different values using a newline as a separator. The -record keeps only one instance of the field the value of which is a -single multi-line string. -@item duplicate -Duplicates the whole record into as many instances as there are different -values for the field. This is the default for the email field. Thus a -record containing 3 different email addresses is duplicated into three -different records each having a single email address. This is -particularly useful in combination with @code{select} as the method to -handle multiple matches in inline expansion queries (@pxref{Inline Query -Expansion}) because you are presented with the 3 addresses in a -selection buffer -@end table - -Because a method may not be applicable to all fields, the variable -@code{eudc-duplicate-attribute-handling-method} lets you specify either a -default method for all fields or a method for each individual field. - -@defvar eudc-duplicate-attribute-handling-method -A method to handle entries containing duplicate attributes. This is -either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol -@var{method}. The alist form of the variable associates a method to an -individual attribute name; the second form specifies a method applicable -to all attribute names. Available methods are: @code{list}, -@code{first}, @code{concat}, and @code{duplicate} (see above). The default is -@code{list}. -@end defvar - - - -@node Query Form, Display of Query Results, Querying Servers, Usage -@comment node-name, next, previous, up -@section Query Form - -The simplest way to query your directory server is to use the query -form. You display the query form with the @samp{Query with Form} menu -item or by invoking the command @kbd{M-x eudc-query-form}. The attribute -names presented in this form are defined by the -@code{eudc-query-form-attributes} variable (unless a non-@code{nil} -argument is supplied to @code{eudc-query-form}). - -Since the different directory protocols to which EUDC interfaces may -use different names for equivalent attributes, EUDC defines its own set -of attribute names and a mapping between these names and their -protocol-specific equivalent through the variable -@code{eudc-protocol-attributes-translation-alist}. Names currently -defined by EUDC are @code{name}, @code{firstname}, @code{email} and -@code{phone}. - -@defvar eudc-query-form-attributes -@findex eudc-get-attribute-list -A list of attributes presented in the query form. Attribute names in -this list should be either EUDC attribute names or valid attribute -names. You can get a list of valid attribute names for the current -protocol with the @samp{List Valid Attribute Names} menu item or the -@kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name}, -@code{email} and @code{phone}. -@end defvar - -@deffn Command eudc-query-form get-fields-from-server -Display a form to query the directory server. If given a non-@code{nil} -argument the function first queries the server for the existing fields -and displays a corresponding form. Not all protocols may support a -non-@code{nil} argument here. -@end deffn - -Since the names of the fields may not be explicit enough or adapted to -be directly displayed as prompt strings in the form, the variable -@code{eudc-user-attribute-names-alist} lets you define more explicit -names for directory attribute names. This variable is ignored if -@code{eudc-use-raw-directory-names} is non-@code{nil}. - -@defvar eudc-user-attribute-names-alist -This is an alist of user-defined names for the directory attributes used in -query/response forms. Prompt strings for attributes that are not in this -alist are derived by splitting the attribute name at underscores and -capitalizing the individual words. -@end defvar - -@defvar eudc-use-raw-directory-names -If non-@code{nil}, use attributes names as defined in the directory. -Otherwise, directory query/response forms display the user attribute -names defined in @code{eudc-user-attribute-names-alist}. -@end defvar - -@node Display of Query Results, Inline Query Expansion, Query Form, Usage -@comment node-name, next, previous, up -@section Display of Query Results - -Upon successful completion of a form query, EUDC will display a buffer -containing the results of the query. - -The fields that are returned for each record -are controlled by @code{eudc-default-return-attributes} (@pxref{Return -Attributes}). - -The display of each individual field can be performed by an arbitrary -function which allows specific processing for binary values, such as -images or audio samples, as well as values with semantics, such as -URLs. - -@defvar eudc-attribute-display-method-alist -An alist specifying methods to display attribute values. Each member of -the list is of the form @code{(@var{name} . @var{func})} where -@var{name} is a lowercased string naming a directory attribute -(translated according to @code{eudc-user-attribute-names-alist} if -@code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a -function that will be passed the corresponding attribute values for -display. -@end defvar - -This variable has protocol-local definitions (see @pxref{Server/Protocol -Locals}). For instance, it is defined as follows for LDAP: - -@lisp -(eudc-protocol-set 'eudc-attribute-display-method-alist - '(("jpegphoto" . eudc-display-jpeg-inline) - ("labeledurl" . eudc-display-url) - ("audio" . eudc-display-sound) - ("labeledurl" . eudc-display-url) - ("url" . eudc-display-url)) - 'ldap) -@end lisp - -EUDC provides a set of built-in functions to display binary value types: - -@defun eudc-display-generic-binary data -Display a button for unidentified binary @var{data}. -@end defun - -@defun eudc-display-url url -Display URL and make it clickable. -@end defun - -@defun eudc-display-sound data -Display a button to play the sound @var{data}. -@end defun - -@defun eudc-display-jpeg-inline data -Display the JPEG @var{data} inline at point if possible. -@end defun - -@defun eudc-display-jpeg-as-button data -Display a button for the JPEG @var{data}. -@end defun - -Right-clicking on a binary value button pops up a contextual menu with -options to process the value. Among these are saving the attribute -value to a file or sending it to an external viewer command. External -viewers should expect the value on their standard input and should -display it or perform arbitrary processing on it. Messages sent to -standard output are discarded. External viewers are listed in the -variable @code{eudc-external-viewers} which you can customize. - -@defvar eudc-external-viewers -This is a list of viewer program specifications. Each specification is -a list whose first element is a string naming the viewer for unique -identification, the second element is the executable program which -should be invoked and the following elements are arguments that should -be passed to the program. -@end defvar - - -@node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage -@comment node-name, next, previous, up -@section Inline Query Expansion - -Inline query expansion is a powerful method to get completion from your -directory server. The most common usage is for expanding names to email -addresses in mail message buffers. The expansion is performed by the -command @kbd{M-x eudc-expand-inline} which is available from the -@samp{Expand Inline Query} menu item but can also be conveniently -bound to a key shortcut (@pxref{Installation}). The operation is -controlled by the variables @code{eudc-inline-expansion-format}, -@code{eudc-inline-query-format}, -@code{eudc-expanding-overwrites-query} and -@code{eudc-multiple-match-handling-method}. - -If the query fails for a server, other servers may be tried successively -until one of them finds a match (@pxref{Multi-server Queries}). - -@deffn Command eudc-expand-inline replace-p -Query the server and expand the query string before point. The query -string consists of the buffer substring from the point back to the -preceding comma, colon or beginning of -line. @code{eudc-inline-query-format} controls how individual words -are mapped onto directory attribute names. After querying the server -for the given string, the expansion specified by -@code{eudc-inline-expansion-format} is inserted in the buffer at -point. If @var{replace-p} is @code{t} then this expansion replaces the -query string in the buffer. If @code{eudc-expanding-overwrites-query} -is non-@code{nil} then the meaning of @var{replace-p} is negated. -@end deffn - -@defvar eudc-inline-query-format -Format of an inline expansion query. -This is actually a list of @var{format}s. A @var{format} is a list of -one or more EUDC attribute names. A @var{format} applies if it contains -as many attributes as individual words in the inline query string. If -several @var{format}s apply then they are tried in order until a match -is found. If @code{nil} all the words will be mapped onto the default -server/protocol attribute name (generally @code{name}). - -For instance, use the following -@lisp -(setq eudc-inline-query-format '((name) - (firstname) - (firstname name))) -@end lisp -@noindent -to indicate that single word expansion queries are to be considered as -surnames and if no match is found then they should be tried as first -names. Inline queries consisting of two words are considered as -consisting of a first name followed by a surname. If the query consists -of more than two words, then the first one is considered as the first -name and the remaining words are all considered as surname constituents. - -@var{format}s are in fact not limited to EUDC attribute names, you can -use server or protocol specific names in them. It may be safer if you -do so, to set the variable @code{eudc-inline-query-format} in a protocol -or server local fashion (see @pxref{Server/Protocol Locals}). - -For instance you could use the following to match up to three words -against the @code{cn} attribute of LDAP servers: -@lisp -(eudc-protocol-set 'eudc-inline-query-format - '((cn) - (cn cn) - (cn cn cn)) - 'ldap) -@end lisp -@end defvar - -@defvar eudc-inline-expansion-format -This variable lets you control exactly what is inserted into the buffer -upon an inline expansion request. It is a list whose first element is a -string passed to @code{format}. Remaining elements are symbols -corresponding to directory attribute names. The corresponding attribute -values are passed as additional arguments to @code{format}. Default is -@code{("%s" email)} but you may want to consider a value like @code{("%s -<%s>" name email)} -@end defvar - -@defvar eudc-multiple-match-handling-method -This variable controls what to do when multiple entries match a query -for an inline expansion. Possible values are: -@table @code -@item first -The first match is considered as being the only one, the others are -discarded. -@item select -A selection buffer pops up where you can choose a particular match. This -is the default value of the variable. -@item all -The expansion uses all records successively -@item abort -An error is signaled. The expansion aborts. -@end table - -Default is @code{select} -@end defvar - - - -@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage -@comment node-name, next, previous, up -@section The Server Hotlist - -EUDC lets you maintain a list of frequently used servers so that you -can easily switch from one to another. This hotlist appears in the -@samp{Server} submenu. You select a server in this list by clicking on -its name. You can add the current server to the list with the command -@kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable -@code{eudc-server-hotlist} which is stored in and retrieved from the file -designated by @code{eudc-options-file}. EUDC also provides a facility to -edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}). - -The hotlist is also used to make queries on multiple servers -successively (@pxref{Multi-server Queries}). The order in which the -servers are tried is the order they appear in the hotlist, therefore it -is important to sort the hotlist appropriately. - -@deffn Command eudc-bookmark-server server -Add @var{server} to the hotlist of servers -@end deffn - -@deffn Command eudc-bookmark-current-server -Add the current server to the hotlist of servers -@end deffn - -@defvar eudc-options-file -The name of a file where EUDC stores its internal variables -(the hotlist and the current server). EUDC will try to load -that file upon initialization so, if you choose a file name -different from the defaults @file{~/.eudc-options}, be sure to set this -variable to the appropriate value @emph{before} EUDC is itself -loaded. -@end defvar - -@menu -* The Hotlist Edit Buffer:: An interactive hotlist editing facility -@end menu - -@node The Hotlist Edit Buffer, , The Server Hotlist, The Server Hotlist -@comment node-name, next, previous, up -@subsection The Hotlist Edit Buffer - -The hotlist edit buffer offers a means to manage a list of frequently -used servers. Commands are available in the context pop-up menu -generally bound to the right mouse button. Those commands also have -equivalent key bindings. - -@deffn Command eudc-hotlist-add-server -Bound to @kbd{a}. -Add a new server to the hotlist on the line after point -@end deffn - -@deffn Command eudc-hotlist-delete-server -Bound to @kbd{d}. -Delete the server on the line point is on -@end deffn - -@deffn Command eudc-hotlist-select-server -Bound to @kbd{s}. -Select the server the point is on as the current directory server for -the next queries -@end deffn - -@deffn Command eudc-hotlist-transpose-servers -Bound to @kbd{t}. -Bubble up the server the point is on to the top of the list -@end deffn - -@deffn Command eudc-hotlist-quit-edit -Bound to @kbd{q}. -Save the changes and quit the hotlist edit buffer. Use @kbd{x} or -@kbd{M-x kill-buffer} to exit without saving. -@end deffn - - -@node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage -@comment node-name, next, previous, up -@section Multi-server Queries - -When using inline query expansion (@pxref{Inline Query Expansion}), EUDC -can try to query successively a sequence of directory servers until one -of them successfully finds a match for the query. - -@defvar eudc-inline-expansion-servers -This variable controls which servers are tried and in which order when -trying to perform an inline query. Possible values are: -@table @code -@item current-server -Only the current directory server is tried -@item hotlist -The servers in the hotlist are tried in order until one finds a match -for the query or `eudc-max-servers-to-query' is reached -@item server-then-hotlist -The current server then the servers in the hotlist are tried in the -order they appear in the hotlist until one of them finds a match or -`eudc-max-servers-to-query' is reached. This is the default. -@end table -@end defvar - -@defvar eudc-max-servers-to-query -This variable indicates the maximum number of servers to query when -performing a multi-server query. The default, @code{nil}, indicates -that all available servers should be tried. -@end defvar - - - -@node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage -@comment node-name, next, previous, up -@section Creating BBDB Records - -@findex eudc-insert-record-at-point-into-bbdb -@findex eudc-try-bbdb-insert -With EUDC, you can automatically create BBDB records -(@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a -directory server. You do this by moving point to the appropriate -record in a query result display buffer and invoking the command -@kbd{M-x eudc-insert-record-at-point-into-bbdb} with the -keyboard binding @kbd{b}@footnote{This key binding does not actually -call @code{eudc-insert-record-at-point-into-bbdb} but uses -@code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC -cannot update an existing BBDB record and will signal an error if you -try to insert a record matching an existing one. - -@findex eudc-batch-export-records-to-bbdb -It is also possible to export to BBDB the whole batch of records -contained in the directory query result with the command -@kbd{M-x eudc-batch-export-records-to-bbdb}. - -Because directory systems may not enforce a strict record format, local -server installations may use different attribute names and have -different ways to organize the information. Furthermore BBDB has its own -record structure. For these reasons converting a record from its -external directory format to the BBDB format is a highly customizable -process. - -@defvar eudc-bbdb-conversion-alist -The value of this variable should be a symbol naming an alist defining a -mapping between BBDB field names onto directory attribute names records. -This is a protocol-local variable and is initialized upon protocol -switch (@pxref{Server/Protocol Locals}). The alist is made of cells of the -form @code{(@var{bbdb-field} . @var{spec-or-list})}. -@var{bbdb-field} is the name of a field -that must be defined in your BBDB environment (standard field names are -@code{name}, @code{company}, @code{net}, @code{phone}, @code{address} -and @code{notes}). -@var{spec-or-list} is either a single mapping specification or a list of -mapping specifications. Lists of mapping specifications are valid for -the @code{phone} and @code{address} BBDB fields only. @var{spec}s are -actually s-expressions which are evaluated as follows: - -@table @asis -@item a string -evaluates to itself -@item a symbol -evaluates to the symbol value. Symbols corresponding to directory -attribute names present in the record evaluate to the value of the field -in the record -@item a form -is evaluated as a function. The argument list may contain attribute -names which evaluate to the corresponding values in the record. The form -evaluation should return something appropriate for the particular -@var{bbdb-field} (see @code{bbdb-create-internal}). -@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as -convenience functions to parse phones and addresses. -@end table -@end defvar - -The default value of the PH-specific value of that variable is -@code{eudc-ph-bbdb-conversion-alist}: - -@lisp -((name . name) - (net . email) - (address . (eudc-bbdbify-address address "Address")) - (phone . ((eudc-bbdbify-phone phone "Phone") - (eudc-bbdbify-phone office_phone "Office Phone")))) -@end lisp - -This means that: - -@itemize @bullet -@item -the @code{name} field of the BBDB record gets its value -from the @code{name} attribute of the directory record -@item -the @code{net} field of the BBDB record gets its value -from the @code{email} attribute of the directory record -@item -the @code{address} field of the BBDB record is obtained by parsing the -@code{address} attribute of the directory record with the function -@code{eudc-bbdbify-address} -@item -two @code{phone} fields are created (when possible) in the BBDB record. -The first one has @cite{Phone} for location and its value is obtained by -parsing the @code{phone} attribute of the PH/QI record with the function -@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location -its value is obtained by parsing the @code{office_phone} attribute of the -PH/QI record with the function @code{eudc-bbdbify-phone}. -@end itemize - -@defun eudc-bbdbify-phone phone location -This is a convenience function provided for use in -@code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector -compatible with @code{bbdb-create-internal}. @var{phone} is either a string -supposedly containing a phone number or a list of such strings which are -concatenated. @var{location} is used as the phone location for BBDB. -@end defun - -@defun eudc-bbdbify-address addr location -This is a convenience function provided for use in -@code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector -compatible with @code{bbdb-create-internal}. @var{addr} should be an -address string of no more than four lines or a list of lines. The last -line is searched for the zip code, city and state name. @var{location} -is used as the phone location for BBDB. -@end defun - -Note that only a subset of the attributes you selected with -@code{eudc-default-return-attributes} and that are actually displayed may -actually be inserted as part of the newly created BBDB record. - - -@node Server/Protocol Locals, , Creating BBDB Records, Usage -@comment node-name, next, previous, up -@section Server/Protocol Locals - -EUDC can be customized independently for each server or directory -protocol. All variables can be given local bindings that are activated -when a particular server and/or protocol becomes active. This is much -like buffer-local bindings but on a per server or per protocol basis. - -@menu -* Manipulating local bindings:: Functions to set and query local bindings -@end menu - -@node Manipulating local bindings, , Server/Protocol Locals, Server/Protocol Locals -@comment node-name, next, previous, up -@subsection Manipulating local bindings - -EUDC offers functions that let you set and query variables on a per -server or per protocol basis. - -The following predicates allow you to test the existence of -server/protocol local bindings for a particular variable. - -@defun eudc-server-local-variable-p var -Return non-@code{nil} if @var{var} has server-local bindings -@end defun - -@defun eudc-protocol-local-variable-p var -Return non-@code{nil} if @var{var} has protocol-local bindings -@end defun - -The following functions allow you to set the value of a variable with -various degrees of locality. - -@defun eudc-default-set var val -Set the EUDC default value of @var{var} to @var{val}. -The current binding of @var{var} (if local to the current server or -protocol) is not changed. -@end defun - -@defun eudc-protocol-set var val &optional protocol -Set the binding of @var{var} local to @var{protocol} to @var{val}. If -omitted, @var{protocol} defaults to the current value of -@code{eudc-protocol}. The current binding of @var{var} is changed only -if @var{protocol} is omitted. -@end defun - -@defun eudc-server-set var val &optional server -Set the binding of @var{var} local to @var{server} to @var{val}. If -omitted, @var{server} defaults to the current value of -@code{eudc-server}. The current binding of @var{var} is changed only if -@var{server} is omitted. -@end defun - -@defun eudc-set var val -Set the most local (server, protocol or default) binding of @var{var} to -@var{val}. The current binding of @var{var} is also set to @var{val}. -@end defun - -The following variables allow you to query the various bindings of a -variable (local or non-local). - -@defun eudc-variable-default-value var -Return the default binding of @var{var} (outside of a particular server -or protocol local binding). -Return @code{unbound} if @var{var} has no EUDC default value. -@end defun - -@defun eudc-variable-protocol-value var &optional protocol -Return the value of @var{var} local to @var{protocol}. Return -@code{unbound} if @var{var} has no value local to @var{protocol}. -@var{protocol} defaults to @code{eudc-protocol}. -@end defun - -@defun eudc-variable-server-value var [server] -Return the value of @var{var} local to @var{server}. -Return @code{unbound} if @var{var} has no value local to @var{server}. -@var{server} defaults to @code{eudc-server}. -@end defun - -Changing a protocol-local or server-local value of a variable has no -effect on its current value. The following command is used to -synchronize the current values of variables with their local values -given the current @code{eudc-server} and @code{eudc-protocol}: - -@defun eudc-update-local-variables -Update all EUDC variables according to their local settings. -@end defun - - - -@node Credits, GNU Free Documentation License, Usage, Top -@comment node-name, next, previous, up -@chapter Credits - -EUDC was written by Oscar Figueiredo based on @file{ph.el} by the -same author. - -Thanks to Soren Dayton for his suggestions, his enthusiasm and his help -in testing and proofreading the code and docs of @file{ph.el}. - -@node GNU Free Documentation License, Command and Function Index, Credits, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Command and Function Index, Variables Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Command and Function Index - -@printindex fn - -@node Variables Index, , Command and Function Index, Top -@comment node-name, next, previous, up -@unnumbered Variables Index - -@printindex vr - -@setchapternewpage odd -@contents -@bye - -@ignore - arch-tag: 1b79460b-4ea1-441d-ab45-05ddd16ef241 -@end ignore