[Emacs-diffs] master c098424: Clean up LDAP Configuration section of EUDC manual

[Thomas Fitzsimmons]

branch: master
commit c0984249eb65641a0876594183c80fd8e6b37962
Author: Thomas Fitzsimmons <address@hidden>
Commit: Thomas Fitzsimmons <address@hidden>

    Clean up LDAP Configuration section of EUDC manual
    
    * doc/misc/eudc.texi: Combine indices.
    (LDAP Configuration): Use command markup.  Add index entries.
    Change formatting.  Wrap long lines.  Add noindent markup.
---
 doc/misc/eudc.texi |   70 +++++++++++++++++++++++++++++++--------------------
 1 files changed, 42 insertions(+), 28 deletions(-)

diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
index 9757c82..76a25c1 100644
--- a/doc/misc/eudc.texi
+++ b/doc/misc/eudc.texi
@@ -4,6 +4,8 @@
 @settitle Emacs Unified Directory Client (EUDC) Manual
 @afourpaper
 @documentencoding UTF-8
address@hidden fn cp
address@hidden vr cp
 @c %**end of header
 
 @copying
@@ -61,8 +63,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.
-* Command and Function Index::
-* Variables Index::
+* Index::
 @end menu
 
 
@@ -220,15 +221,15 @@ email composition buffers (@pxref{Inline Query Expansion})
 @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
address@hidden, available as part of OpenLDAP
+Emacs.  @file{ldap.el} needs an external program called
address@hidden, available as part of OpenLDAP
 (@url{http://www.openldap.org/}).  The configurations in this section
 were tested with OpenLDAP 2.4.23.
 
 The following examples use a base of
 @code{ou=people,dc=example,dc=com} and the host name
address@hidden, a server that supports LDAP-over-SSL
-(the @code{ldaps} protocol, with default port @code{636}) and which
address@hidden, a server that supports LDAP-over-SSL (the
address@hidden protocol, with default port @code{636}) and which
 requires authentication by the user @code{emacsuser} with password
 @code{s3cr3t}.
 
@@ -244,14 +245,21 @@ example, attempting to TAB-complete the following:
 To: * Smith
 @end example
 
address@hidden
 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.
 
address@hidden
+* Emacs-only Configuration::    Configure with @file{.emacs}
+* External Configuration::      Configure with @file{/etc/openldap/ldap.conf}
address@hidden menu
+
address@hidden Emacs-only Configuration
 @subsection Emacs-only Configuration
 
 Emacs can pass most required configuration options via the
address@hidden command-line.  One exception is certificate
address@hidden 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
@@ -269,14 +277,19 @@ LDAP:
   '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
 (customize-set-variable 'eudc-server-hotlist
                         '(("" . bbdb)
-                          ("ldaps://directory.example.com" . ldap)))
+                          ("ldaps://ldaps.gnu.org" . ldap)))
 (customize-set-variable 'ldap-host-parameters-alist
-                        '(("ldaps://directory.example.com"
+                        '(("ldaps://ldaps.gnu.org"
                            base "ou=people,dc=example,dc=com"
                            binddn "example\\emacsuser"
                            passwd ldap-password-read)))
 @end lisp
 
address@hidden ldap-password-read
address@hidden passwd
address@hidden password-cache
address@hidden password-cache-expiry
address@hidden 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
@@ -285,6 +298,7 @@ password will then be validated and cached, unless
 password is cached.  If you want to clear the cache, call
 @code{password-reset}.
 
address@hidden External Configuration
 @subsection External Configuration
 
 Your system may already be configured for a default LDAP server.  For
@@ -292,17 +306,19 @@ example, @file{/etc/openldap/ldap.conf} might contain:
 
 @example
 BASE ou=people,dc=example,dc=com
-URI ldaps://directory.example.com
+URI ldaps://ldaps.gnu.org
 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:
address@hidden bind distinguished name
address@hidden binddn
+Authentication requires a password, and a @dfn{bind distinguished name
+(binddn)} representing the user, in this case,
address@hidden  These can be specified in
address@hidden/.authinfo.gpg} with the following line:
 
 @example
-machine ldaps://directory.example.com binddn example\emacsuser password s3cr3t
+machine ldaps://ldaps.gnu.org binddn example\emacsuser password s3cr3t
 @end example
 
 Then in the @file{.emacs} init file, these expressions suffice to
@@ -313,15 +329,15 @@ configure EUDC for LDAP:
   '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
 (customize-set-variable 'eudc-server-hotlist
                         '(("" . bbdb)
-                          ("ldaps://directory.example.com" . ldap)))
+                          ("ldaps://ldaps.gnu.org" . ldap)))
 (customize-set-variable 'ldap-host-parameters-alist
-                        '(("ldaps://directory.example.com"
+                        '(("ldaps://ldaps.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
-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:
@@ -330,13 +346,16 @@ The @file{~/.authinfo.gpg} line becomes:
 binddn example\emacsuser password s3cr3t
 @end example
 
address@hidden
 and the @file{.emacs} expressions become:
 
 @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
 
 @node Usage
@@ -1043,14 +1062,9 @@ in testing and proofreading the code and docs of 
@file{ph.el}.
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
address@hidden Command and Function Index
address@hidden Command and Function Index
-
address@hidden fn
-
address@hidden Variables Index
address@hidden Variables Index
address@hidden Index
address@hidden Index
 
address@hidden vr
address@hidden cp
 
 @bye