Skip to content
Snippets Groups Projects
eudc.texi 26.6 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
    *eudc::   A client for directory servers (LDAP, PH)
    @end direntry
    
    steveb's avatar
    new
    steveb committed
    
    
    steveb's avatar
    steveb committed
    This file documents EUDC v1.02
    
    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.02, the Emacs Unified Directory Client
    
    steveb's avatar
    new
    steveb committed
    96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717
    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