X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=auth-ja.texi;h=6649c957b793888e2fe72055d992c4af0a0f2f00;hb=4615db659aafbe231326087128238f2e5b698934;hp=75fd016e8fb724b6535c99faa93859ca4e0d86a5;hpb=d270018a82c7168ff6064534e8e7032a41ce87f4;p=elisp%2Fgnus-doc-ja.git

diff --git a/auth-ja.texi b/auth-ja.texi
index 75fd016..6649c95 100644
--- a/auth-ja.texi
+++ b/auth-ja.texi
@@ -10,7 +10,7 @@
 @copying
 このファイルは Emacs auth-source ライブラリーを説明します。
 
-Copyright @copyright{} 2008-2011 Free Software Foundation, Inc.
+Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -104,8 +104,8 @@ Auth-source ライブラリーは単なるユーザー名やパスワード (いわゆる秘密
 
 同様に auth-source ライブラリーは多くの貯蔵バックエンド、現在は伝統的
 な ``netrc'' バクエンド (この文書の後の方にあります) またはシークレット
-サービス API をサポートします。これは EIEIO に基づいたバクエンドで行なわ
-れ、もし必要ならあなた独自のものを書くことができます。
+サービス API をサポートします。これは EIEIO に基づいたバックエンドで行な
+われ、もし必要ならあなた独自のものを書くことができます。
 
 @node Help for users
 @chapter 利用者のためのヘルプ
@@ -141,16 +141,16 @@ password @var{mypassword}
 わないでください}。さもないとひどい目に会うでしょう。
 
 ``Netrc'' ファイルは通常 @code{.authinfo} または @code{.netrc} と呼ばれ
-ます。今では @code{.authinfo} の方が普及しているようなので、後でわかるよ
-うに auth-source ライブラリーはそれをディフォルトにすることによって、こ
-の混乱を助長しています。
+ます。今では @code{.authinfo} の方が普及しているようですが、後でわかるよ
+うに 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 ライブラリー
@@ -173,7 +173,7 @@ password @var{mypassword}
 ;;; ほぼ等価だが、より短い (後述の fallback についての記述を参照)。
 (setq auth-sources '((:source "~/.authinfo.gpg")))
 ;;; さらに短い @emph{ディフォルト}:
-(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo"))
+(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
 ;;; シークレット API の @var{Login} コレクションを使う
 ;;; (@pxref{Secret Service API})
 (setq auth-sources '("secrets:Login"))
@@ -200,8 +200,8 @@ password @var{mypassword}
 は GnuPG で暗号化されたファイルです (@pxref{GnuPG and EasyPG Assistant
 Configuration})。
 
-もしその読み込みに失敗すると、暗号化されていない netrc ファイ
-ル @code{~/.authinfo} が使われます。
+もしその読み込みに失敗すると、暗号化されていない netrc ファイルであ
+る @code{~/.authinfo}、続いて @code{~/.netrc} が使われます。
 
 代表的な netrc 行の例は、ポートが無いものです。
 
@@ -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 を含める?