Merge changes made in Gnus trunk.

auth.texi (Help for developers): Update docs to explain that the :save-function will only run the first time.
auth-source.el (auth-source-format-prompt): Always convert the value to a string to avoid evaluating non-string arguments.
 (auth-source-netrc-create): Offer default properly, not as initial content in `read-string'.
 (auth-source-netrc-saver): Use a cache keyed by file name and MD5 hash of line to determine if we've been run before.  If so, don't run again, but print a trivial message to indicate the cache was hit instead.

2 files changed, 16 insertions, 1 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 1a1ca1d6296..db3a944c160 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2011-03-12  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * auth.texi (Help for developers): Update docs to explain that the
+        :save-function will only run the first time.
+
 2011-03-12  Glenn Morris  <rgm@gnu.org>
 
         * Makefile.in (emacs-faq.html): Fix some more cross-refs.
diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 85a3f098131..a16da92343e 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -289,11 +289,21 @@ Later, after a successful login, @code{nnimal.el} calls the
    (funcall (nth 2 credentials)))
 @end example
 
-Which will work whether the @code{:save-function} was provided or not.
+This will work whether the @code{:save-function} was provided or not.
 @code{:save-function} will be provided only when a new entry was
 created, so this effectively says ``after a successful login, save the
 authentication information we just used, if it was newly created.''
 
+After the first time it's called, the @code{:save-function} will not
+run again (but it will log something if you have set
+@code{auth-source-debug} to @code{'trivia}).  This is so it won't ask
+the same question again, which is annoying.  This is so it won't ask
+the same question again, which is annoying.  This is so it won't ask
+the same question again, which is annoying.
+
+So the responsibility of the API user that specified @code{:create t}
+is to call the @code{:save-function} if it's provided.
+
 @defun auth-source-delete SPEC
 
 TODO: how to include docstring?