Re: Moving files from lisp/gnus/ to lisp/net/?

[Simon Josefsson <jas@extundo.com>]

Richard Stallman <rms@gnu.org> writes:

> I would think that the current definition of read-passwd fits the
> first criterion but not the second.  The new definition, depending on
> password.el, I think doesn't fit either one; it may as well be
> autoloaded from the new file.

I agree, thanks for explaining.  I have installed an updated node on
the password cache interface, in lispref/minibuf.texi.  Complete text
below.  I'm not a native speaker, so please review and improve it.

20.9 Reading a Password
=======================

To read a password to pass to another program, you can use the function
`read-passwd'.

   Passwords are sometimes needed several times throughout an Emacs
session.  Then it can be useful to avoid having to ask for a password
more than once.  Passwords are entered into the password cache using
the function `password-cache-add'.  To read a password, possibly
retrieving the password from the cache without querying the user, you
can use the function `password-read'.  The two calls can be combined
into the function `password-read-and-add' that read a password and
store it in the cache.

   Typically users do not use the same password for all services.  The
password cache mechanism use a `key' string to differentiate among the
passwords.  The `key' string is typically a fixed string chosen to be
related to what the password is used for.  For example, a password used
when connecting to a IMAP mail server called `mail.example.org', could
use a `key' string of `imap:mail.example.org'.  You can use any string,
as long as it is reasonably unique.

   Passwords in the cache typically expire after a while (controlled by
the variable `password-cache-expiry'), but you can force removal of a
password using the function `password-cache-remove'.  This is useful
when there is a problem with the password, to avoid using the same
incorrect password from the cache in the future.

 -- Function: read-passwd prompt &optional confirm default
     This function reads a password, prompting with PROMPT.  It does
     not echo the password as the user types it; instead, it echoes `.'
     for each character in the password.

     The optional argument CONFIRM, if non-`nil', says to read the
     password twice and insist it must be the same both times.  If it
     isn't the same, the user has to type it over and over until the
     last two times match.

     The optional argument DEFAULT specifies the default password to
     return if the user enters empty input.  If DEFAULT is `nil', then
     `read-passwd' returns the null string in that case.

 -- Function: password-read prompt key
     Read a password from the user, using `read-passwd', prompting with
     PROMPT.  If a password has been stored in the password cache,
     using `password-cache-add' on the same KEY, it is returned
     directly, without querying the user.

 -- Function: password-cache-add key password
     Add a password to the password cache, indexed under the given KEY.
     The password is later retrieved using `password-read' called with
     the same KEY.

 -- Function: password-cache-remove key
     Remove a password from the cache, indexed under the given KEY.

 -- Function: password-read-and-add prompt &optional key
     Read a password, prompting with PROMPT, and possibly add it to the
     cache, indexed using the KEY string.  This is one-call interface
     to `password-read' and `password-cache-add'.

 -- Variable: password-cache-expiry
     This variable specify for how many seconds passwords are retained
     in the password cache before they are expired.  For high security,
     use a low value (below a minute).  For more lax security, use a
     setting of `14400' corresponding to half a work day (4 hours).

 -- Variable: password-cache
     This variable toggle whether or not the password cache is used at
     all.  The default is non-`nil', i.e., to use the cache.