GNU bug report logs - #16322
24.3; [PATCH] Streamline EUDC LDAP configuration

Previous Next

Full log

Message #17 received at 16322 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Thomas Fitzsimmons <fitzsim <at> fitzsim.org>
Cc: 16322 <at> debbugs.gnu.org
Subject: Re: bug#16322: Acknowledgement (24.3;
 [PATCH] Streamline EUDC LDAP configuration)
Date: Thu, 13 Nov 2014 22:16:07 +0200

> From: Thomas Fitzsimmons <fitzsim <at> fitzsim.org>
> Cc: 16322 <at> debbugs.gnu.org
> Date: Thu, 13 Nov 2014 12:11:59 -0500
> 
> * eudc.texi (LDAP Configuration): Rename from LDAP Requirements
> and provide configuration examples.

A few comments about this part:

> +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

Command names are better given the @command markup (here and elsewhere
in the patch).

> +@subsection Emacs-only Configuration

Please don't use sectioning commands without a corresponding @node.
Having subsections that aren't nodes makes those subsections harder to
find.

> +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
> +@code{password-cache} is nil.  You can customize
> +@code{password-cache-expiry} to control the duration for which the
> +password is cached.  If you want to clear the cache, call
> +@code{password-reset}.

Each variable or function you describe should have a corresponding
@findex or @vindex entry right before the description.

> +To authenticate, the @dfn{bind distinguished name (binddn)} is

When you introduce a new term using @dfn, please provide a @cindex
entry for that term.

> +@example
> +machine ldaps://directory.example.com binddn example\emacsuser password s3cr3t
> +@end example

This line is too long, and since lines in @example are never broken by
the typesetter, it will overflow the right margin.  Break it into 2 or
more lines, and indicate in the text that this is one long line, to
avoid confusion.

> +@example
> +binddn example\emacsuser password s3cr3t
> +@end example
> +
> +and the @file{.emacs} expressions become:

You need @noindent before the last line, otherwise it will be
indented, as it starts a new paragraph.

> +@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)))
> +@end lisp

I think these lines are also too long, consider breaking them.

Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.