Skip to content
Snippets Groups Projects
eudc.texi 27.7 KiB
Newer Older
  • Learn to ignore specific revisions
  • steveb's avatar
    new
    steveb committed
    \input texinfo.tex
    @c %**start of header
    @setfilename eudc.info
    
    steveb's avatar
    steveb committed
    @settitle Emacs Unified Directory Client (EUDC) Manual
    
    steveb's avatar
    new
    steveb committed
    @iftex
    @afourpaper
    @end iftex
    @c %**end of header
    
    @footnotestyle end
    
    @ifinfo
    
    steveb's avatar
    steveb committed
    @direntry
    
    steveb's avatar
    steveb committed
    * EUDC::   A client for directory servers (LDAP, PH)
    
    steveb's avatar
    steveb committed
    @end direntry
    
    steveb's avatar
    new
    steveb committed
    
    
    steveb's avatar
    steveb committed
    This file documents EUDC v1.06
    
    steveb's avatar
    new
    steveb committed
    
    
    steveb's avatar
    steveb committed
    EUDC is part of XEmacs.
    
    EUDC is the Emacs Unified Directory Client, a common interface
    
    steveb's avatar
    new
    steveb committed
    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
    
    steveb's avatar
    steveb committed
    @title{EUDC Manual}
    
    steveb's avatar
    new
    steveb committed
    @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
    
    
    
    steveb's avatar
    steveb committed
    This manual documents EUDC v1.06, the Emacs Unified Directory Client.
    
    steveb's avatar
    steveb committed
    
    
    steveb's avatar
    new
    steveb committed
    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:
    
    steveb's avatar
    steveb committed
    
    
    steveb's avatar
    new
    steveb committed
    @itemize @bullet
    @item
    LDAP, Lightweight Directory Access Protocol
    @item
    CCSO PH/QI
    @end itemize
    
    
    steveb's avatar
    steveb committed
    The main features of the EUDC interface are:
    
    steveb's avatar
    new
    steveb committed
    
    @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}
    
    steveb's avatar
    steveb committed
    menu that will give you access to EUDC.
    
    steveb's avatar
    new
    steveb committed
    
    
    steveb's avatar
    steveb committed
    You may find also useful to add the following to your individual
    
    steveb's avatar
    new
    steveb committed
    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:
    
    steveb's avatar
    steveb committed
    ldap} 
    
    steveb's avatar
    new
    steveb committed
    
    LDAP support is automatically compiled in when you build XEmacs provided
    appropriate LDAP libraries are installed on your system.  As of this
    
    steveb's avatar
    steveb committed
    writing you can use either (URLs are subject to change):
    
    steveb's avatar
    new
    steveb committed
    
    @itemize @bullet
    @item
    
    steveb's avatar
    steveb committed
    University of Michigan's LDAP Client software
    
    steveb's avatar
    new
    steveb committed
    (@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
    
    steveb's avatar
    steveb committed
    both cases, EUDC will consider the attribute be duplicated.
    
    steveb's avatar
    new
    steveb committed
    
    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
    
    steveb's avatar
    steveb committed
    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
    
    steveb's avatar
    new
    steveb committed
    @code{eudc-protocol-attributes-translation-alist}.  Names currently
    
    steveb's avatar
    steveb committed
    defined by EUDC are @samp{name}, @samp{firstname}, @samp{email} and
    @samp{phone}.
    
    steveb's avatar
    new
    steveb committed
    
    @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
    
    steveb's avatar
    steveb committed
    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.  All protocols may not support a
    non-@code{nil} argument here.
    
    steveb's avatar
    new
    steveb committed
    @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
    
    steveb's avatar
    steveb committed
    designated by @code{eudc-options-file}.  EUDC also provides a facility to
    edit the hotlist interactively (@pxref{The Hotlist Edit Buffer})
    
    steveb's avatar
    new
    steveb committed
    
    @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
    
    
    steveb's avatar
    steveb committed
    @menu
    * The Hotlist Edit Buffer::  An interactive hotlist editing facility
    @end menu
    
    @node The Hotlist Edit Buffer
    @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 keybindings.
    
    @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
    @code{kill-buffer} to exit without saving.
    @end deffn
    
    
    steveb's avatar
    new
    steveb committed
    
    
    @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
    
    steveb's avatar
    steveb committed
    An alist defining the mapping from BBDB to LDAP attribute names.
    
    steveb's avatar
    new
    steveb committed
    (@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
    
    steveb's avatar
    steveb committed
    An alist defining the mapping from BBDB to PH/QI attribute names.
    
    steveb's avatar
    new
    steveb committed
    (@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