# HG changeset patch # User steveb # Date 891773269 0 # Sun Apr 05 10:47:49 1998 +0000 # Node ID c6c8b91eb545ff112523470a21625e187276923e # Parent d3fa3e348f4b6529d67d227b968509171d603a2e new diff --git a/eudc.texi b/eudc.texi new file mode 100644 --- /dev/null +++ b/eudc.texi @@ -0,0 +1,714 @@ +\input texinfo.tex +@c %**start of header +@setfilename eudc.info +@settitle eudc.el Manual +@iftex +@afourpaper +@end iftex +@c %**end of header + +@footnotestyle end + +@ifinfo +This file documents eudc.el v1.02 + +eudc.el is part of XEmacs. + +eudc.el is is the Emacs Unified Directory Client, a common interface +interface to directory servers using various protocols such as LDAP or +the CCSO white pages directory system (PH/QI) + +Copyright @copyright{} 1998 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim +copies of this manual provided the copyright notice and +this permission notice are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX +and print the results, provided the printed document +carries a copying permission notice identical to this +one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified +versions of this manual under the conditions for +verbatim copying and the terms of the ``GNU General +Public License'', and provided that the entire +resulting derived work is distributed under the terms +of a permission notice identical to this one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. +@end ifinfo + +@titlepage +@title{eudc Manual} +@subtitle{The Emacs Unified Directory Client} +@author by Oscar Figueiredo +@code{1.0} + +@page +@vskip 0pt plus 1fill + Copyright @copyright{} 1998 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim + copies of this manual provided the copyright notice and + this permission notice are preserved on all copies. + + @ignore + Permission is granted to process this file through TeX + and print the results, provided the printed document + carries a copying permission notice identical to this + one except for the removal of this paragraph (this + paragraph not being relevant to the printed manual). + + @end ignore + + Permission is granted to copy and distribute modified + versions of this manual under the conditions for + verbatim copying and the terms of the ``GNU General + Public License'', and provided that the entire + resulting derived work is distributed under the terms + of a permission notice identical to this one. + + Permission is granted to copy and distribute + translations of this manual into another language, + under the above conditions for modified versions, + except that this permission notice may be stated in a + translation approved by the Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, Overview, (dir), (dir) +@comment node-name, next, previous, up + + +This manual documents eudc v1.02, the Emacs Unified Directory Client + +A common interface interface to directory servers using various +protocols such as LDAP or the CCSO white pages directory system (PH/QI) + +@end ifinfo + +@menu +* Overview:: Summary of eudc features +* Installation:: How to install eudc +* Usage:: The various usage possibilities explained +* Credits:: Who's done what +* Variables Index:: +@end menu + + + + + +@node Overview, Installation, Top, Top +@comment node-name, next, previous, up +@chapter Overview + +EUDC, the Emacs Unified Directory Client, provides a common user +interface to access directory servers using different directory +protocols. + +Currently supported protocols are: +@itemize @bullet +@item +LDAP, Lightweight Directory Access Protocol +@item +CCSO PH/QI +@end itemize + +EUDC provides a client interface to directory servers running one +of these protocols. Its main features are: + +@itemize @bullet +@item +Queries using a customizable form +@item +Inline query expansion (for instance you can expand a name +to an e-mail address in a mail message buffer using a server as an +address book) +@item +Fast minibuffer queries for e-mail 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 ? +@end menu + + + +@node LDAP, CCSO PH/QI, Overview, Overview +@comment node-name, next, previous, up +@section LDAP + +LDAP, Lightweight Directory Access Protocol, is a communication +protocol for directory applications defined in RFC 1777. + +Quoted from RFC 1777: + + [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. + +LDAP servers usually store (but are not limited to) information about +people such as their name, phone number, e-mail address, office +location, etc@enddots{} More information about LDAP can be found at +@url{http://www.umich.edu/~dirsvcs/ldap/} + +EUDC requires external support to access LDAP directory servers +(@pxref{LDAP Requirements}) + + +@node CCSO PH/QI, , 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, e-mail, academic information or any other +details it was configured to. + +The system consists of two parts: a database server traditionally called +@code{qi} and a command-line client called +EUDC. @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 QI servers in activity. + +The original command-line @code{ph} client that comes with the +@code{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 Installation, Usage, Overview, Top +@comment node-name, next, previous, up +@chapter Installation + +EUDC is distributed as an XEmacs package. Follow the rules for +the installation of XEmacs packages. + +After installing EUDC as a package you will find (the next time +you launch XEmacs) a new @code{Directory} submenu in the @code{Tools} +menu that will let you access EUDC. + +You may find useful to add the following to your individual +initialization file to add a shortcut for e-mail address expansion in +e-mail 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 + "mail" + '(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 + +EUDC requires LDAP support to be compiled in XEmacs to access +LDAP servers. If LDAP support has not been compiled in your XEmacs +executable you will get that error message: @samp{Cannot open load file: +ldap-internal} + +LDAP support is automatically compiled in when you build XEmacs provided +appropriate LDAP libraries are installed on your system. As of this +writing you can use either: + +@itemize @bullet +@item +University of Michingan's LDAP Client software +(@url{http://www.umich.edu/~dirsvcs/ldap/}) +@item +Netscape's LDAP SDK (@url{http://developer.netscape.com/one/directory/}) +@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 @code{Directory} +sub-menu of the @code{Tools} sub-menu. + +@menu +* Querying Servers:: How queries are performed and handled +* Query Form:: How to use and customize the query form +* Inline Query Expansion:: How to use and customize inline queries +* The Server Hotlist:: How to use and manage the server hotlist +* Creating BBDB Records:: How to insert query results into your BBDB +* Protocol Locals:: Protocol specific customizations +@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. + +@defvar eudc-server +The name or IP address of the 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). +@end defvar + +@defvar eudc-protocol +The directory protocol to use to query the server. Currently supported +protocols in this version of EUDC are @samp{ph} and @samp{ldap}. +@end defvar + +@deffn Command eudc-set-server +This command accessible from @samp{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. @code{nil} +returns the default attributes as configured in the server. Default is +@code{nil} +@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 +chose to 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 e-mail fields containing different e-mail 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 considers the attribute be 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 @code{\n} 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 e-mail field. Thus a +record containing 3 different e-mail addresses is duplicated into three +different records each having a single e-mail 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 (@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}, +@code{duplicate} (see above). Defaults to @code{list}. +@end defvar + + + +@node Query Form, Inline Query Expansion, 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 @code{Query with Form} menu +item or by invoking the command @kbd{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 +have 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 @samp{name}, @samp{email} and @samp{phone}. + +@defvar eudc-query-form-attributes +A list of attributes presented in the query form. Attribut 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 @code{List Valid Attribute Names} menu item or the +@kbd{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 CCSO PH/QI Nameserver. +If given a non-nil argument the function first queries the server +for the existing fields and displays a corresponding form. +@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 user-defined names for 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 + +Upon successful completion the command 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}) + +@node Inline Query Expansion, The Server Hotlist, Query Form, 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 e-mail +addresses in mail message buffers. The expansion is performed by the +command @code{eudc-expand-inline} which is available from the +@samp{Directory} menu 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-list}, +@code{eudc-expanding-overwrites-query} and +@code{eudc-multiple-match-handling-method} + +@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-list} 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-list +Format of an inline expansion query. This list specifies how individual +words in the inline query string are associated to directory attribute +names. If @code{nil} all the words will be mapped onto the server +default attribute name (generally @code{name}). Default is @code{nil}. +@end defvar + +@defvar eudc-inline-expansion-format +This variable lets you control what is exactly 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 directory attribute names, corresponding attribute values +are passed as additional arguments to 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 + + +Defaults to @code{select} +@end defvar + + + +@node The Server Hotlist, Creating BBDB Records, 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 +@code{Server} sub-menu. You select a server in this list by clicking on +its name. You can add the current server to the list with the command +@code{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}. + +@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 +(currently only the hotlist is stored there). 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 + +There is currently no way to remove a server from the list other than +editing directly the @code{eudc-options-file}. + + +@node Creating BBDB Records, Protocol Locals, The Server Hotlist, Usage +@comment node-name, next, previous, up +@section Creating BBDB Records + +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 the point to the appropriate +record in a query result display buffer and invoking the command +@code{eudc-insert-record-at-point-into-bbdb} with the corresponding +keyboard binding, @kbd{b} @footnote{This keybinding 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. + +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{Protocol Locals}) The alist is made of cells of the +form @code{(}@var{bbdb-field} . @var{spec-or-list}@code{)}. +@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 "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 "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 @var{phone} @var{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 @var{addr} @var{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 Protocol Locals, , Creating BBDB Records, Usage +@comment node-name, next, previous, up +@section Protocol Locals + +EUDC can be customized independently for each directory protocol. Each +time you switch to another protocol, EUDC initializes some variables +with their protocol specific values. + +@menu +* LDAP Locals:: LDAP Local Variables +* PH Locals:: PH/QI Local Variables +@end menu + +@node LDAP Locals, PH Locals, Protocol Locals, Protocol Locals +@comment node-name, next, previous, up +@subsection LDAP Locals + +@defvar eudc-ldap-bbdb-conversion-alist +An alist defining the mapping from BBDB to LDAP atribute names. +(@pxref{Creating BBDB Records}) +@end defvar + +@node PH Locals, , LDAP Locals, Protocol Locals +@comment node-name, next, previous, up +@subsection PH Locals + +@defvar eudc-ph-bbdb-conversion-alist +An alist defining the mapping from BBDB to PH/QI atribute names. +(@pxref{Creating BBDB Records}) +@end defvar + + + +@node Credits, Variables Index, Usage, Top +@comment node-name, next, previous, up +@chapter Credits + +EUDC was written by Oscar Figueiredo based on @code{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 @code{ph.el}. + +@node Variables Index, , Credits, Top +@comment node-name, next, previous, up +@unnumbered Variables Index + +@printindex vr + +@contents +@bye