comparison man/eudc.texi @ 49600:23a1cea22d13

Trailing whitespace deleted.

49599:5ade352e8d1c

* Overview::                    Summary of EUDC features
* Installation::                How to install EUDC
* Usage::                       The various usage possibilities explained
* Credits::                     Who's done what
* Command and Function Index::
* Variables Index::             
@end menu

@comment  node-name,   next,  previous,  up
@chapter Overview

EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user
interface to access directory servers using different directory
protocols. 

Currently supported back-ends are:

@itemize @bullet
@item

@end itemize

The main features of the EUDC interface are:

@itemize @bullet
@item 
Queries using a customizable form
@item
Inline query expansion (for instance you can expand a name
to an email address in a mail message buffer using a server as an
address book)

You may also find it useful to add the following to your @file{.emacs}
initialization file to add a shortcut for email address expansion in
email composition buffers (@pxref{Inline Query Expansion})

@lisp
(eval-after-load 
 "message"
 '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
(eval-after-load 
 "sendmail"
 '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
@end lisp

@menu

This chapter describes the usage of EUDC.  Most functions and
customization options are available through the @samp{Directory Search}
submenu of the @samp{Tools} submenu.

@menu
* Querying Servers::            How queries are performed and handled 
* Query Form::                  How to use and customize the query form
* Display of Query Results::    Controlling how query results are presented
* Inline Query Expansion::      How to use and customize inline queries
* The Server Hotlist::          How to use and manage the server hotlist
* Multi-server Queries::        How to query multiple servers successively

Upon successful completion of a form query, EUDC will display a buffer
containing the results of the query.

The fields that are returned for each record
are controlled by @code{eudc-default-return-attributes} (@pxref{Return
Attributes}).  

The display of each individual field can be performed by an arbitrary
function which allows specific processing for binary values, such as
images or audio samples, as well as values with semantics, such as
URLs.

This variable has protocol-local definitions (see @pxref{Server/Protocol
Locals}).  For instance, it is defined as follows for LDAP:

@lisp
(eudc-protocol-set 'eudc-attribute-display-method-alist 
                   '(("jpegphoto" . eudc-display-jpeg-inline)
                     ("labeledurl" . eudc-display-url)
                     ("audio" . eudc-display-sound)
                     ("labeledurl" . eudc-display-url)
                     ("url" . eudc-display-url)) 
                   'ldap)
@end lisp

EUDC provides a set of built-in functions to display binary value types:

controlled by the variables @code{eudc-inline-expansion-format},
@code{eudc-inline-query-format},
@code{eudc-expanding-overwrites-query} and
@code{eudc-multiple-match-handling-method}.

If the query fails for a server, other servers may be tried successively 
until one of them finds a match (@pxref{Multi-server Queries}).

@deffn Command eudc-expand-inline replace-p
Query the server and expand the query string before point.  The query
string consists of the buffer substring from the point back to the

query string in the buffer.  If @code{eudc-expanding-overwrites-query}
is non-@code{nil} then the meaning of @var{replace-p} is negated.
@end deffn

@defvar eudc-inline-query-format
Format of an inline expansion query.  
This is actually a list of @var{format}s.  A @var{format} is a list of
one or more EUDC attribute names.  A @var{format} applies if it contains
as many attributes as individual words in the inline query string.  If
several @var{format}s apply then they are tried in order until a match
is found.  If @code{nil} all the words will be mapped onto the default
server/protocol attribute name (generally @code{name}).

For instance, use the following 
@lisp
(setq eudc-inline-query-format '((name)
                                 (firstname)
                                 (firstname name)))
@end lisp
@noindent
to indicate that single word expansion queries are to be considered as
surnames and if no match is found then they should be tried as first
names.  Inline queries consisting of two words are considered as
consisting of a first name followed by a surname.  If the query consists 
of more than two words, then the first one is considered as the first
name and the remaining words are all considered as surname constituents.

@var{format}s are in fact not limited to EUDC attribute names, you can
use server or protocol specific names in them.  It may be safer if you

@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.

@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage
@comment  node-name,  next,  previous,  up
@section The Server Hotlist

EUDC lets you maintain a list of frequently used servers so that you 
can easily switch from one to another.  This hotlist appears in the
@samp{Server} submenu.  You select a server in this list by clicking on
its name.  You can add the current server to the list with the command
@kbd{M-x eudc-bookmark-current-server}.  The list is contained in the variable
@code{eudc-server-hotlist} which is stored in and retrieved from the file

Add the current server to the hotlist of servers
@end deffn

@defvar eudc-options-file
The name of a file where EUDC stores its internal variables
(the hotlist and the current server).  EUDC will try to load 
that file upon initialization so, if you choose a file name
different from the defaults @file{~/.eudc-options}, be sure to set this
variable to the appropriate value @emph{before} EUDC is itself
loaded.
@end defvar

@defvar eudc-bbdb-conversion-alist
The value of this variable should be a symbol naming an alist defining a
mapping between BBDB field names onto directory attribute names records.
This is a protocol-local variable and is initialized upon protocol
switch (@pxref{Server/Protocol Locals}).  The alist is made of cells of the
form @code{(@var{bbdb-field} . @var{spec-or-list})}. 
@var{bbdb-field} is the name of a field
that must be defined in your BBDB environment (standard field names are
@code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
and @code{notes}). 
@var{spec-or-list} is either a single mapping specification or a list of
mapping specifications.  Lists of mapping specifications are valid for
the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
actually s-expressions which are evaluated as follows:

@table @asis
@item a string 
evaluates to itself
@item a symbol
evaluates to the symbol value.  Symbols corresponding to directory
attribute names present in the record evaluate to the value of the field
in the record
@item a form
is evaluated as a function.  The argument list may contain attribute 
names which evaluate to the corresponding values in the record.  The form
evaluation should return something appropriate for the particular
@var{bbdb-field} (see @code{bbdb-create-internal}).
@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
convenience functions to parse phones and addresses.

@end 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

@code{unbound} if @var{var} has no value local to @var{protocol}.
@var{protocol} defaults to @code{eudc-protocol}.
@end defun

@defun eudc-variable-server-value var [server]
Return the value of @var{var} local to @var{server}.  
Return @code{unbound} if @var{var} has no value local to @var{server}.
@var{server} defaults to @code{eudc-server}.
@end defun

Changing a protocol-local or server-local value of a variable has no

@node Credits, Command and Function Index, Usage, Top
@comment  node-name,  next,  previous,  up
@chapter Credits

EUDC was written by Oscar Figueiredo based on @file{ph.el} by the 
same author.

Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
in testing and proofreading the code and docs of @file{ph.el}.

49600:23a1cea22d13

* Overview::                    Summary of EUDC features
* Installation::                How to install EUDC
* Usage::                       The various usage possibilities explained
* Credits::                     Who's done what
* Command and Function Index::
* Variables Index::
@end menu

@comment  node-name,   next,  previous,  up
@chapter Overview

EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user
interface to access directory servers using different directory
protocols.

Currently supported back-ends are:

@itemize @bullet
@item

@end itemize

The main features of the EUDC interface are:

@itemize @bullet
@item
Queries using a customizable form
@item
Inline query expansion (for instance you can expand a name
to an email address in a mail message buffer using a server as an
address book)

You may also find it useful to add the following to your @file{.emacs}
initialization file to add a shortcut for email address expansion in
email composition buffers (@pxref{Inline Query Expansion})

@lisp
(eval-after-load
 "message"
 '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
(eval-after-load
 "sendmail"
 '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
@end lisp

@menu

This chapter describes the usage of EUDC.  Most functions and
customization options are available through the @samp{Directory Search}
submenu of the @samp{Tools} submenu.

@menu
* Querying Servers::            How queries are performed and handled
* Query Form::                  How to use and customize the query form
* Display of Query Results::    Controlling how query results are presented
* Inline Query Expansion::      How to use and customize inline queries
* The Server Hotlist::          How to use and manage the server hotlist
* Multi-server Queries::        How to query multiple servers successively

Upon successful completion of a form query, EUDC will display a buffer
containing the results of the query.

The fields that are returned for each record
are controlled by @code{eudc-default-return-attributes} (@pxref{Return
Attributes}).

The display of each individual field can be performed by an arbitrary
function which allows specific processing for binary values, such as
images or audio samples, as well as values with semantics, such as
URLs.

This variable has protocol-local definitions (see @pxref{Server/Protocol
Locals}).  For instance, it is defined as follows for LDAP:

@lisp
(eudc-protocol-set 'eudc-attribute-display-method-alist
                   '(("jpegphoto" . eudc-display-jpeg-inline)
                     ("labeledurl" . eudc-display-url)
                     ("audio" . eudc-display-sound)
                     ("labeledurl" . eudc-display-url)
                     ("url" . eudc-display-url))
                   'ldap)
@end lisp

EUDC provides a set of built-in functions to display binary value types:

controlled by the variables @code{eudc-inline-expansion-format},
@code{eudc-inline-query-format},
@code{eudc-expanding-overwrites-query} and
@code{eudc-multiple-match-handling-method}.

If the query fails for a server, other servers may be tried successively
until one of them finds a match (@pxref{Multi-server Queries}).

@deffn Command eudc-expand-inline replace-p
Query the server and expand the query string before point.  The query
string consists of the buffer substring from the point back to the

query string in the buffer.  If @code{eudc-expanding-overwrites-query}
is non-@code{nil} then the meaning of @var{replace-p} is negated.
@end deffn

@defvar eudc-inline-query-format
Format of an inline expansion query.
This is actually a list of @var{format}s.  A @var{format} is a list of
one or more EUDC attribute names.  A @var{format} applies if it contains
as many attributes as individual words in the inline query string.  If
several @var{format}s apply then they are tried in order until a match
is found.  If @code{nil} all the words will be mapped onto the default
server/protocol attribute name (generally @code{name}).

For instance, use the following
@lisp
(setq eudc-inline-query-format '((name)
                                 (firstname)
                                 (firstname name)))
@end lisp
@noindent
to indicate that single word expansion queries are to be considered as
surnames and if no match is found then they should be tried as first
names.  Inline queries consisting of two words are considered as
consisting of a first name followed by a surname.  If the query consists
of more than two words, then the first one is considered as the first
name and the remaining words are all considered as surname constituents.

@var{format}s are in fact not limited to EUDC attribute names, you can
use server or protocol specific names in them.  It may be safer if you

@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.

@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage
@comment  node-name,  next,  previous,  up
@section The Server Hotlist

EUDC lets you maintain a list of frequently used servers so that you
can easily switch from one to another.  This hotlist appears in the
@samp{Server} submenu.  You select a server in this list by clicking on
its name.  You can add the current server to the list with the command
@kbd{M-x eudc-bookmark-current-server}.  The list is contained in the variable
@code{eudc-server-hotlist} which is stored in and retrieved from the file

Add the current server to the hotlist of servers
@end deffn

@defvar eudc-options-file
The name of a file where EUDC stores its internal variables
(the hotlist and the current server).  EUDC will try to load
that file upon initialization so, if you choose a file name
different from the defaults @file{~/.eudc-options}, be sure to set this
variable to the appropriate value @emph{before} EUDC is itself
loaded.
@end defvar

@defvar eudc-bbdb-conversion-alist
The value of this variable should be a symbol naming an alist defining a
mapping between BBDB field names onto directory attribute names records.
This is a protocol-local variable and is initialized upon protocol
switch (@pxref{Server/Protocol Locals}).  The alist is made of cells of the
form @code{(@var{bbdb-field} . @var{spec-or-list})}.
@var{bbdb-field} is the name of a field
that must be defined in your BBDB environment (standard field names are
@code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
and @code{notes}).
@var{spec-or-list} is either a single mapping specification or a list of
mapping specifications.  Lists of mapping specifications are valid for
the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
actually s-expressions which are evaluated as follows:

@table @asis
@item a string
evaluates to itself
@item a symbol
evaluates to the symbol value.  Symbols corresponding to directory
attribute names present in the record evaluate to the value of the field
in the record
@item a form
is evaluated as a function.  The argument list may contain attribute
names which evaluate to the corresponding values in the record.  The form
evaluation should return something appropriate for the particular
@var{bbdb-field} (see @code{bbdb-create-internal}).
@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
convenience functions to parse phones and addresses.

@end 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

@code{unbound} if @var{var} has no value local to @var{protocol}.
@var{protocol} defaults to @code{eudc-protocol}.
@end defun

@defun eudc-variable-server-value var [server]
Return the value of @var{var} local to @var{server}.
Return @code{unbound} if @var{var} has no value local to @var{server}.
@var{server} defaults to @code{eudc-server}.
@end defun

Changing a protocol-local or server-local value of a variable has no

@node Credits, Command and Function Index, Usage, Top
@comment  node-name,  next,  previous,  up
@chapter Credits

EUDC was written by Oscar Figueiredo based on @file{ph.el} by the
same author.

Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
in testing and proofreading the code and docs of @file{ph.el}.