Fix copyright years by hand

[gnu-emacs] / doc / misc / eudc.texi

diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
index 9757c82fe7eb7b0c725c4b843c5bc3499afff54d..da63975c2e5e0689e5daab47188067f4f1f7b492 100644 (file)
--- a/doc/misc/eudc.texi
+++ b/doc/misc/eudc.texi
@@ -2,18 +2,19 @@
 @c %**start of header
 @setfilename ../../info/eudc.info
 @settitle Emacs Unified Directory Client (EUDC) Manual
 @c %**start of header
 @setfilename ../../info/eudc.info
 @settitle Emacs Unified Directory Client (EUDC) Manual

+@include docstyle.texi

 @afourpaper
 @afourpaper

-@documentencoding UTF-8
+@syncodeindex fn cp
+@syncodeindex vr cp

 @c %**end of header
 
 @copying
 @c %**end of header
 
 @copying

-This file documents EUDC v1.30b.
+This file documents EUDC version 1.40.0.

 
 EUDC is the Emacs Unified Directory Client, a common interface to
 
 EUDC is the Emacs Unified Directory Client, a common interface to

-directory servers using various protocols such as LDAP or the CCSO white
-pages directory system (PH/QI)
+directory servers and contact information.

 
 

-Copyright @copyright{} 1998, 2000--2015 Free Software Foundation, Inc.
+Copyright @copyright{} 1998, 2000--2016 Free Software Foundation, Inc.

 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document


@@ -30,7 +31,7 @@ modify this GNU manual.''
 
 @dircategory Emacs network features
 @direntry
 
 @dircategory Emacs network features
 @direntry

-* EUDC: (eudc).                 Emacs client for directory servers (LDAP, PH).
+* EUDC: (eudc).                 Emacs client for directory servers (LDAP, BBDB).

 @end direntry
 
 @footnotestyle end
 @end direntry
 
 @footnotestyle end


@@ -39,7 +40,7 @@ modify this GNU manual.''
 @title EUDC Manual
 @subtitle The Emacs Unified Directory Client
 @author by Oscar Figueiredo
 @title EUDC Manual
 @subtitle The Emacs Unified Directory Client
 @author by Oscar Figueiredo

-@code{1.30b}
+@code{1.40.0}

 
 @page
 @vskip 0pt plus 1fill
 
 @page
 @vskip 0pt plus 1fill


@@ -61,8 +62,7 @@ modify this GNU manual.''
 * Usage::                       The various usage possibilities explained
 * Credits::                     Who's done what
 * GNU Free Documentation License:: The license for this documentation.
 * Usage::                       The various usage possibilities explained
 * Credits::                     Who's done what
 * GNU Free Documentation License:: The license for this documentation.

-* Command and Function Index::
-* Variables Index::
+* Index::

 @end menu
 
 
 @end menu
 
 


@@ -82,8 +82,6 @@ Currently supported back-ends are:
 @item
 LDAP, Lightweight Directory Access Protocol
 @item
 @item
 LDAP, Lightweight Directory Access Protocol
 @item

-CCSO PH/QI
-@item

 BBDB, Big Brother's Insidious Database
 @end itemize
 
 BBDB, Big Brother's Insidious Database
 @end itemize
 


@@ -108,7 +106,6 @@ Interface to BBDB to let you insert server records into your own BBDB database
 
 @menu
 * LDAP::                        What is LDAP ?
 
 @menu
 * LDAP::                        What is LDAP ?

-* CCSO PH/QI::                  What is CCSO, PH, QI ?

 * BBDB::                        What is BBDB ?
 @end menu
 
 * BBDB::                        What is BBDB ?
 @end menu
 


@@ -140,30 +137,6 @@ EUDC requires external support to access LDAP directory servers
 (@pxref{LDAP Configuration})
 
 
 (@pxref{LDAP Configuration})
 
 

-@node CCSO PH/QI
-@section CCSO PH/QI
-
-The Central Computing Services Office (CCSO) of the University of
-Illinois at Urbana Champaign created and freely distributed a
-directory system that was used by many organizations in the 1990s.
-The system records information about people such as their address,
-phone number, email, academic information or any other details it was
-configured to.  Nowadays this system is not widely used.
-
-The system consists of two parts: a database server traditionally called
-@samp{qi} and a command-line client called @samp{ph}.
-@ignore
-Until 2010, the code could be downloaded from
-@url{http://www-dev.cites.uiuc.edu/ph/}.
-@end ignore
-
-The original command-line @samp{ph} client that came with the
-@samp{ph/qi} distribution provided additional features that are
-not implemented in EUDC, like the possibility to communicate with the
-server in login-mode, which made it possible to change records in the
-database.
-
-

 @node BBDB
 @section BBDB
 
 @node BBDB
 @section BBDB
 


@@ -174,14 +147,14 @@ and news readers.
 
 It is often used as an enhanced email address book.
 
 
 It is often used as an enhanced email address book.
 

-EUDC considers BBDB as a directory server back end just like LDAP or
-PH/QI servers, though BBDB has no client/server protocol and thus always
-resides locally on your machine.  The point in this is not to offer an
+EUDC considers BBDB as a directory server back end just like LDAP,
+though BBDB has no client/server protocol and thus always resides
+locally on your machine.  The point in this is not to offer an

 alternate way to query your BBDB database (BBDB itself provides much
 alternate way to query your BBDB database (BBDB itself provides much

-more flexible ways to do that), but rather to offer an interface to your
-local directory that is consistent with the interface to external
-directories (LDAP, PH/QI).  This is particularly interesting when
-performing queries on multiple servers.
+more flexible ways to do that), but rather to offer an interface to
+your local directory that is consistent with the interface to external
+LDAP directories.  This is particularly interesting when performing
+queries on multiple servers.

 
 EUDC also offers a means to insert results from directory queries into
 your own local BBDB (@pxref{Creating BBDB Records})
 
 EUDC also offers a means to insert results from directory queries into
 your own local BBDB (@pxref{Creating BBDB Records})


@@ -220,15 +193,36 @@ email composition buffers (@pxref{Inline Query Expansion})
 @section LDAP Configuration
 
 LDAP support is added by means of @file{ldap.el}, which is part of
 @section LDAP Configuration
 
 LDAP support is added by means of @file{ldap.el}, which is part of

-Emacs.  @file{ldap.el} needs an external command line utility named
-@file{ldapsearch}, available as part of OpenLDAP
+Emacs.  @file{ldap.el} needs an external program called
+@command{ldapsearch}, available as part of OpenLDAP

 (@url{http://www.openldap.org/}).  The configurations in this section
 were tested with OpenLDAP 2.4.23.
 
 (@url{http://www.openldap.org/}).  The configurations in this section
 were tested with OpenLDAP 2.4.23.
 

+Most servers use LDAP-over-SSL these days; the examples here reflect
+that.  The other possibilities are:
+
+@vindex ldap-host-parameters-alist
+@vindex ldap-ldapsearch-args
+@itemize @bullet
+
+@item
+Servers that do not require authentication or that do not encrypt
+authentication traffic.
+
+Include @code{auth simple} in @code{ldap-host-parameters-alist}, which
+causes the @code{-x} option to be passed to @command{ldapsearch}.
+
+@item
+Servers that require SASL authentication.
+
+Pass any required extra options to @command{ldapsearch} using
+@code{ldap-ldapsearch-args}.
+@end itemize
+

 The following examples use a base of
 The following examples use a base of

-@code{ou=people,dc=example,dc=com} and the host name
-@code{directory.example.com}, a server that supports LDAP-over-SSL
-(the @code{ldaps} protocol, with default port @code{636}) and which
+@code{ou=people,dc=gnu,dc=org} and the host name
+@code{ldap.gnu.org}, a server that supports LDAP-over-SSL (the
+@code{ldaps} protocol, with default port @code{636}) and which

 requires authentication by the user @code{emacsuser} with password
 @code{s3cr3t}.
 
 requires authentication by the user @code{emacsuser} with password
 @code{s3cr3t}.
 


@@ -244,14 +238,22 @@ example, attempting to TAB-complete the following:
 To: * Smith
 @end example
 
 To: * Smith
 @end example
 

+@noindent

 will return all LDAP entries with surnames that begin with
 @code{Smith}.  In every LDAP query it makes, EUDC implicitly appends
 the wildcard character to the end of the last word.
 
 will return all LDAP entries with surnames that begin with
 @code{Smith}.  In every LDAP query it makes, EUDC implicitly appends
 the wildcard character to the end of the last word.
 

+@menu
+* Emacs-only Configuration::    Configure with @file{.emacs}
+* External Configuration::      Configure with @file{/etc/openldap/ldap.conf}
+* Troubleshooting::             Debug @command{ldapsearch} failures
+@end menu
+
+@node Emacs-only Configuration

 @subsection Emacs-only Configuration
 
 Emacs can pass most required configuration options via the
 @subsection Emacs-only Configuration
 
 Emacs can pass most required configuration options via the

-@file{ldapsearch} command-line.  One exception is certificate
+@command{ldapsearch} command-line.  One exception is certificate

 configuration for LDAP-over-SSL, which must be specified in
 @file{/etc/openldap/ldap.conf}.  On systems that provide such
 certificates as part of the @code{OpenLDAP} installation, this can be
 configuration for LDAP-over-SSL, which must be specified in
 @file{/etc/openldap/ldap.conf}.  On systems that provide such
 certificates as part of the @code{OpenLDAP} installation, this can be


@@ -264,19 +266,28 @@ TLS_CACERTDIR /etc/openldap/certs
 In @file{.emacs}, these expressions suffice to configure EUDC for
 LDAP:
 
 In @file{.emacs}, these expressions suffice to configure EUDC for
 LDAP:
 

+@vindex message-mode-map
+@findex eudc-expand-inline
+@vindex eudc-server-hotlist
+@vindex ldap-host-parameters-alist

 @lisp
 (eval-after-load "message"
   '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
 (customize-set-variable 'eudc-server-hotlist
                         '(("" . bbdb)
 @lisp
 (eval-after-load "message"
   '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
 (customize-set-variable 'eudc-server-hotlist
                         '(("" . bbdb)

-                          ("ldaps://directory.example.com" . ldap)))
+                          ("ldaps://ldap.gnu.org" . ldap)))

 (customize-set-variable 'ldap-host-parameters-alist
 (customize-set-variable 'ldap-host-parameters-alist

-                        '(("ldaps://directory.example.com"
-                           base "ou=people,dc=example,dc=com"
-                           binddn "example\\emacsuser"
+                        '(("ldaps://ldap.gnu.org"
+                           base "ou=people,dc=gnu,dc=org"
+                           binddn "gnu\\emacsuser"

                            passwd ldap-password-read)))
 @end lisp
 
                            passwd ldap-password-read)))
 @end lisp
 

+@findex ldap-password-read
+@vindex passwd
+@vindex password-cache
+@vindex password-cache-expiry
+@findex password-reset

 Specifying the function @code{ldap-password-read} for @code{passwd}
 will cause Emacs to prompt interactively for the password.  The
 password will then be validated and cached, unless
 Specifying the function @code{ldap-password-read} for @code{passwd}
 will cause Emacs to prompt interactively for the password.  The
 password will then be validated and cached, unless


@@ -285,60 +296,91 @@ password will then be validated and cached, unless
 password is cached.  If you want to clear the cache, call
 @code{password-reset}.
 
 password is cached.  If you want to clear the cache, call
 @code{password-reset}.
 

+@node External Configuration

 @subsection External Configuration
 
 Your system may already be configured for a default LDAP server.  For
 example, @file{/etc/openldap/ldap.conf} might contain:
 
 @example
 @subsection External Configuration
 
 Your system may already be configured for a default LDAP server.  For
 example, @file{/etc/openldap/ldap.conf} might contain:
 
 @example

-BASE ou=people,dc=example,dc=com
-URI ldaps://directory.example.com
+BASE ou=people,dc=gnu,dc=org
+URI ldaps://ldap.gnu.org

 TLS_CACERTDIR /etc/openldap/certs
 @end example
 
 TLS_CACERTDIR /etc/openldap/certs
 @end example
 

-To authenticate, the @dfn{bind distinguished name (binddn)} is
-required, in this case, @code{example\emacsuser}, along with the
-password.  These can be specified in @file{~/.authinfo.gpg} with the
-following line:
+@cindex bind distinguished name
+@cindex binddn
+Authentication requires a password, and a @dfn{bind distinguished name
+(binddn)} representing the user, in this case,
+@code{gnu\emacsuser}.  These can be specified in
+@file{~/.authinfo.gpg} with the following line:

 
 @example
 
 @example

-machine ldaps://directory.example.com binddn example\emacsuser password s3cr3t
+machine ldaps://ldap.gnu.org binddn gnu\emacsuser password s3cr3t

 @end example
 
 Then in the @file{.emacs} init file, these expressions suffice to
 configure EUDC for LDAP:
 
 @end example
 
 Then in the @file{.emacs} init file, these expressions suffice to
 configure EUDC for LDAP:
 

+@vindex message-mode-map
+@findex eudc-expand-inline
+@vindex eudc-server-hotlist
+@vindex ldap-host-parameters-alist

 @lisp
 (eval-after-load "message"
   '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
 (customize-set-variable 'eudc-server-hotlist
                         '(("" . bbdb)
 @lisp
 (eval-after-load "message"
   '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
 (customize-set-variable 'eudc-server-hotlist
                         '(("" . bbdb)

-                          ("ldaps://directory.example.com" . ldap)))
+                          ("ldaps://ldap.gnu.org" . ldap)))

 (customize-set-variable 'ldap-host-parameters-alist
 (customize-set-variable 'ldap-host-parameters-alist

-                        '(("ldaps://directory.example.com"
+                        '(("ldaps://ldap.gnu.org"

                            auth-source t)))
 @end lisp
 
 For this example where we only care about one server, the server name
 can be omitted in @file{~/.authinfo.gpg} and @file{.emacs}, in which
                            auth-source t)))
 @end lisp
 
 For this example where we only care about one server, the server name
 can be omitted in @file{~/.authinfo.gpg} and @file{.emacs}, in which

-case @file{ldapsearch} defaults to the host name in
+case @command{ldapsearch} defaults to the host name in

 @file{/etc/openldap/ldap.conf}.
 
 The @file{~/.authinfo.gpg} line becomes:
 
 @example
 @file{/etc/openldap/ldap.conf}.
 
 The @file{~/.authinfo.gpg} line becomes:
 
 @example

-binddn example\emacsuser password s3cr3t
+binddn gnu\emacsuser password s3cr3t

 @end example
 
 @end example
 

+@noindent

 and the @file{.emacs} expressions become:
 
 and the @file{.emacs} expressions become:
 

+@vindex message-mode-map
+@findex eudc-expand-inline
+@vindex eudc-server-hotlist
+@vindex ldap-host-parameters-alist

 @lisp
 (eval-after-load "message"
   '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
 @lisp
 (eval-after-load "message"
   '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))

-(customize-set-variable 'eudc-server-hotlist '(("" . bbdb) ("" . ldap)))
-(customize-set-variable 'ldap-host-parameters-alist '(("" auth-source t)))
+(customize-set-variable 'eudc-server-hotlist
+                        '(("" . bbdb) ("" . ldap)))
+(customize-set-variable 'ldap-host-parameters-alist
+                        '(("" auth-source t)))

 @end lisp
 
 @end lisp
 

+@node Troubleshooting
+@subsection Troubleshooting
+
+If @command{ldapsearch} exits with an error, you'll see a message like
+this in the @code{*Messages*} buffer (all on one line):
+
+@example
+ldap-search-internal: Failed ldapsearch invocation:
+   ldapsearch "-Hldaps://ldap.gnu.org" "-bou=people,dc=gnu,dc=org"
+   "-Dgnu\emacsuser" "-W" "-LL" "-tt" "(&(mail=name*))"
+   "givenname" "sn" "mail"
+@end example
+
+The @command{ldapsearch} command is formatted such that it can be
+copied and pasted into a terminal.  Set the @command{ldapsearch} debug
+level to 5 by appending @code{-d 5} to the command line.
+

 @node Usage
 @chapter Usage
 
 @node Usage
 @chapter Usage
 


@@ -397,13 +439,13 @@ may be specified by appending a colon and a number to the name of the
 server. You will not need this unless your server runs on a port other
 than the default (which depends on the protocol).
 If the directory server resides on your own computer (which is the case
 server. You will not need this unless your server runs on a port other
 than the default (which depends on the protocol).
 If the directory server resides on your own computer (which is the case

-if you use the BBDB back end) then `localhost' is a reasonable value but
+if you use the BBDB back end) then @samp{localhost} is a reasonable value but

 it will be ignored anyway.
 @end defvar
 
 @defvar eudc-protocol
 The directory protocol to use to query the server.  Currently supported
 it will be ignored anyway.
 @end defvar
 
 @defvar eudc-protocol
 The directory protocol to use to query the server.  Currently supported

-protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}.
+protocols in this version of EUDC are @code{ldap} and @code{bbdb}.

 @end defvar
 
 @deffn Command eudc-set-server
 @end defvar
 
 @deffn Command eudc-set-server


@@ -440,11 +482,8 @@ attributes are ignored.  Default is @code{t}.
 
 Directory standards may authorize different instances of the same
 attribute in a record. For instance the record of a person may contain
 
 Directory standards may authorize different instances of the same
 attribute in a record. For instance the record of a person may contain

-several email fields containing different email addresses. When using
-a QI directory server this is difficult to distinguish from attributes
-having multi-line values such as the postal address that may contain a
-line for the street and another one for the zip code and city name. In
-both cases, EUDC will consider the attribute duplicated.
+several email fields containing different email addresses, in which
+case EUDC will consider the attribute duplicated.

 
 EUDC has several methods to deal with duplicated attributes. The
 available methods are:
 
 EUDC has several methods to deal with duplicated attributes. The
 available methods are:


@@ -810,11 +849,11 @@ trying to perform an inline query.  Possible values are:
 Only the current directory server is tried
 @item hotlist
 The servers in the hotlist are tried in order until one finds a match
 Only the current directory server is tried
 @item hotlist
 The servers in the hotlist are tried in order until one finds a match

-for the query or `eudc-max-servers-to-query' is reached
+for the query or @code{eudc-max-servers-to-query} is reached

 @item server-then-hotlist
 The current server then the servers in the hotlist are tried in the
 order they appear in the hotlist until one of them finds a match or
 @item server-then-hotlist
 The current server then the servers in the hotlist are tried in the
 order they appear in the hotlist until one of them finds a match or

-`eudc-max-servers-to-query' is reached.  This is the default.
+@code{eudc-max-servers-to-query} is reached.  This is the default.

 @end table
 @end defvar
 
 @end table
 @end defvar
 


@@ -886,39 +925,6 @@ convenience functions to parse phones and addresses.
 @end table
 @end defvar
 
 @end table
 @end defvar
 

-The default value of the PH-specific value of that variable is
-@code{eudc-ph-bbdb-conversion-alist}:
-
-@lisp
-((name . name)
- (net . email)
- (address . (eudc-bbdbify-address address "Address"))
- (phone . ((eudc-bbdbify-phone phone "Phone")
-           (eudc-bbdbify-phone office_phone "Office Phone"))))
-@end lisp
-
-This means that:
-
-@itemize @bullet
-@item
-the @code{name} field of the BBDB record gets its value
-from the @code{name} attribute of the directory record
-@item
-the @code{net} field of the BBDB record gets its value
-from the @code{email} attribute of the directory record
-@item
-the @code{address} field of the BBDB record is obtained by parsing the
-@code{address} attribute of the directory record with the function
-@code{eudc-bbdbify-address}
-@item
-two @code{phone} fields are created (when possible) in the BBDB record.
-The first one has @cite{Phone} for location and its value is obtained by
-parsing the @code{phone} attribute of the PH/QI record with the function
-@code{eudc-bbdbify-phone}.  The second one has @cite{Office Phone} for location
-its value is obtained by parsing the @code{office_phone} attribute of the
-PH/QI record with the function @code{eudc-bbdbify-phone}.
-@end itemize
-

 @defun eudc-bbdbify-phone phone location
 This is a convenience function provided for use in
 @code{eudc-bbdb-conversion-alist}.  It parses @var{phone} into a vector
 @defun eudc-bbdbify-phone phone location
 This is a convenience function provided for use in
 @code{eudc-bbdb-conversion-alist}.  It parses @var{phone} into a vector


@@ -1043,14 +1049,9 @@ in testing and proofreading the code and docs of @file{ph.el}.
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
 @appendix GNU Free Documentation License
 @include doclicense.texi
 

-@node Command and Function Index
-@unnumbered Command and Function Index
-
-@printindex fn
-
-@node Variables Index
-@unnumbered Variables Index
+@node Index
+@unnumbered Index

 
 

-@printindex vr
+@printindex cp

 
 @bye
 
 @bye