X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=auth-ja.texi;h=195ff07c878c34a679f749cdc8b76ababc0ff0e0;hb=94910cf84358f48804af90b747fd21d9a5f5cc5f;hp=e0cd82010cc33cc11fb08087266847454239f527;hpb=65aee2b5da8b9618b7221640f59a6d1ed0e7995e;p=elisp%2Fgnus-doc-ja.git

diff --git a/auth-ja.texi b/auth-ja.texi
index e0cd820..195ff07 100644
--- a/auth-ja.texi
+++ b/auth-ja.texi
@@ -145,12 +145,12 @@ password @var{mypassword}
 うに auth-source ライブラリーはそれらの両方を受け入れるために、この混乱
 を助長しています。
 
-もし検索で問題があるのなら @code{auth-source-debug} を @code{t} に設定し
-て、ライブラリーがどのホスト、ポートおよびユーザーをチェックしているか
-を @code{*Messages*} バッファーで見てください。同様に他のどんな問題につ
-いても、何がチェックされているかを調べるのが、あなたの第一歩です。第二の
-ステップはもちろんそれについての blog を書いて、コメントで回答を待つこと
-です。
+もし検索で問題があるのなら @code{auth-source-debug} を @code{trivia} に
+設定して、ライブラリーがどのホスト、ポートおよびユーザーをチェックしてい
+るかを @code{*Messages*} バッファーで見てください。同様に他のどんな問題
+についても、何がチェックされているかを調べるのが、あなたの第一歩です。第
+二のステップはもちろんそれについての blog を書いて、コメントで回答を待つ
+ことです。
 
 変数 @code{auth-sources} をカスタマイズすることができます。もし古いバー
 ジョンの Emacs を使っているか、何かの理由のために auth-source ライブラリー
@@ -248,6 +248,15 @@ TODO: どう働くかを一般的に、secrets.el はどうやるか、いくつかの例。
 @node Help for developers
 @chapter 開発者のためのヘルプ
 
+auth-source ライブラリーは、何らかの動作を行なった結果の記録を採ることが
+できます。
+
+@defvar auth-source-debug
+この変数を @code{trivia} にすると、@code{*Messages*} バッファーへのたく
+さんの出力を見ることができます。あるいはこれに @code{message} に似た関数
+を設定して、あなた独自のやり方で記録を採ることもできます。
+@end defvar
+
 auth-source ライブラリーには、外部で使うための関数は少ししかありません。
 
 @defun auth-source-search SPEC
@@ -256,6 +265,61 @@ TODO: どうやって docstring を含める?
 
 @end defun
 
+では Gnus の @code{nnimap.el} から @code{auth-source-search} を使う例を
+見てみましょう。
+
+@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
+
+@c 以下の訳文の質が悪いのは原文の出来の酷さのため。
+この呼び出しはその結果にユーザー名とパスワード (式中の @code{secret}) が
+含まれることを求めています。さらに、もしその項目がまだ無かったら作る必要
+もあります。その項目を作る際にユーザーとやり取りする場合は、式中にある質
+問文が使われます。この呼び出しは、ユーザーへの質問文のディフォルト値のた
+めに @code{auth-source-creation-defaults} にあるデータを渡すこともできま
+す。
+
+パスワードがもし関数だったら、それは評価される必要があることに注意してく
+ださい。ある程度の安全対策として、それは関数で包まれています。
+
+その後ログインに成功したら @code{nnimap.el} は次のよう
+に @code{:save-function} を呼びます:
+
+@example
+(when (functionp (nth 2 credentials))
+   (funcall (nth 2 credentials)))
+@end example
+
+これは @code{:save-function} の有無に関わらす動作するでしょう。
+@code{:save-function}は新しい項目が作られたときだけ提供されるので、これ
+は実際に「ログイン成功後」なのです。そして我々がちょうど使っていた認証情
+報 (ただしこれが新た作られたものであるのなら) をセーブします。
+
+最初にそれが呼ばれた後、@code{:save-function} が再度走ることはありません
+(しかしもし @code{auth-source-debug} を @code{'trivia} に設定してあるな
+らば、そのことを多少記録します。これすなわち、それは鬱陶しい同じ質問が繰
+り返されることはないということです。
+
+したがって @code{:create t} を設定した API ユーザーの責任は、もし存在す
+るならば @code{:save-function} を呼ぶことです。
+
 @defun auth-source-delete SPEC
 
 TODO: どうやって docstring を含める?