Synch with No Gnus (201103091437).

diff --git a/auth-ja.texi b/auth-ja.texi
index e0cd820..d973608 100644 (file)
--- a/auth-ja.texi
+++ b/auth-ja.texi
@@ -145,12 +145,12 @@ password @var{mypassword}
 \e$B$&$K\e(B auth-source \e$B%i%$%V%i%j!<$O$=$l$i$NN>J}$r<u$1F~$l$k$?$a$K!"$3$N:.Mp\e(B
 \e$B$r=uD9$7$F$$$^$9!#\e(B
 
-\e$B$b$78!:w$GLdBj$,$"$k$N$J$i\e(B @code{auth-source-debug} \e$B$r\e(B @code{t} \e$B$K@_Dj$7\e(B
-\e$B$F!"%i%$%V%i%j!<$,$I$N%[%9%H!"%]!<%H$*$h$S%f!<%6!<$r%A%'%C%/$7$F$$$k$+\e(B
-\e$B$r\e(B @code{*Messages*} \e$B%P%C%U%!!<$G8+$F$/$@$5$$!#F1MM$KB>$N$I$s$JLdBj$K$D\e(B
-\e$B$$$F$b!"2?$,%A%'%C%/$5$l$F$$$k$+$rD4$Y$k$N$,!"$"$J$?$NBh0lJb$G$9!#BhFs$N\e(B
-\e$B%9%F%C%W$O$b$A$m$s$=$l$K$D$$$F$N\e(B blog \e$B$r=q$$$F!"%3%a%s%H$G2sEz$rBT$D$3$H\e(B
-\e$B$G$9!#\e(B
+\e$B$b$78!:w$GLdBj$,$"$k$N$J$i\e(B @code{auth-source-debug} \e$B$r\e(B @code{trivia} \e$B$K\e(B
+\e$B@_Dj$7$F!"%i%$%V%i%j!<$,$I$N%[%9%H!"%]!<%H$*$h$S%f!<%6!<$r%A%'%C%/$7$F$$\e(B
+\e$B$k$+$r\e(B @code{*Messages*} \e$B%P%C%U%!!<$G8+$F$/$@$5$$!#F1MM$KB>$N$I$s$JLdBj\e(B
+\e$B$K$D$$$F$b!"2?$,%A%'%C%/$5$l$F$$$k$+$rD4$Y$k$N$,!"$"$J$?$NBh0lJb$G$9!#Bh\e(B
+\e$BFs$N%9%F%C%W$O$b$A$m$s$=$l$K$D$$$F$N\e(B blog \e$B$r=q$$$F!"%3%a%s%H$G2sEz$rBT$D\e(B
+\e$B$3$H$G$9!#\e(B
 
 \e$BJQ?t\e(B @code{auth-sources} \e$B$r%+%9%?%^%$%:$9$k$3$H$,$G$-$^$9!#$b$78E$$%P!<\e(B
 \e$B%8%g%s$N\e(B Emacs \e$B$r;H$C$F$$$k$+!"2?$+$NM}M3$N$?$a$K\e(B auth-source \e$B%i%$%V%i%j!<\e(B
@@ -248,6 +248,15 @@ TODO: \e$B$I$&F/$/$+$r0lHLE*$K!"\e(Bsecrets.el \e$B$O$I$&$d$k$+!"$$$/$D$+$NNc!#\e(B
 @node Help for developers
 @chapter \e$B3+H/<T$N$?$a$N%X%k%W\e(B
 
+auth-source \e$B%i%$%V%i%j!<$O!"2?$i$+$NF0:n$r9T$J$C$?7k2L$N5-O?$r:N$k$3$H$,\e(B
+\e$B$G$-$^$9!#\e(B
+
+@defvar auth-source-debug
+\e$B$3$NJQ?t$r\e(B @code{trivia} \e$B$K$9$k$H!"\e(B@code{*Messages*} \e$B%P%C%U%!!<$X$N$?$/\e(B
+\e$B$5$s$N=PNO$r8+$k$3$H$,$G$-$^$9!#$"$k$$$O$3$l$K\e(B @code{message} \e$B$K;w$?4X?t\e(B
+\e$B$r@_Dj$7$F!"$"$J$?FH<+$N$d$jJ}$G5-O?$r:N$k$3$H$b$G$-$^$9!#\e(B
+@end defvar
+
 auth-source \e$B%i%$%V%i%j!<$K$O!"30It$G;H$&$?$a$N4X?t$O>/$7$7$+$"$j$^$;$s!#\e(B
 
 @defun auth-source-search SPEC
@@ -256,6 +265,53 @@ TODO: \e$B$I$&$d$C$F\e(B docstring \e$B$r4^$a$k\e(B?
 
 @end defun
 
+@c TRANSLATEME
+Let's take a look at an example of using @code{auth-source-search}
+from Gnus' @code{nnimap.el}.
+
+@example
+(defun nnimap-credentials (address ports)
+  (let* ((auth-source-creation-prompts
+          '((user  . "IMAP user at %h: ")
+            (secret . "IMAP password for %u@@%h: ")))
+         (found (nth 0 (auth-source-search :max 1
+                                           :host address
+                                           :port ports
+                                           :require '(:user :secret)
+                                           :create t))))
+    (if found
+        (list (plist-get found :user)
+              (let ((secret (plist-get found :secret)))
+                (if (functionp secret)
+                    (funcall secret)
+                  secret))
+              (plist-get found :save-function))
+      nil)))
+@end example
+
+This call requires the user and password (secret) to be in the
+results.  It also requests that an entry be created if it doesn't
+exist already.  While the created entry is being assembled, the shown
+prompts will be used to interact with the user.  The caller can also
+pass data in @code{auth-source-creation-defaults} to supply defaults
+for any of the prompts.
+
+Note that the password needs to be evaluated if it's a function.  It's
+wrapped in a function to provide some security.
+
+Later, after a successful login, @code{nnimal.el} calls the
+@code{:save-function} like so:
+
+@example
+(when (functionp (nth 2 credentials))
+   (funcall (nth 2 credentials)))
+@end example
+
+Which 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.''
+
 @defun auth-source-delete SPEC
 
 TODO: \e$B$I$&$d$C$F\e(B docstring \e$B$r4^$a$k\e(B?