fixed and clean up.

1 files changed, 63 insertions, 29 deletions

diff --git a/fml/doc/ja/tutorial/module/IO.sgml b/fml/doc/ja/tutorial/module/IO.sgml
index 47d8306f..518df072 100644
--- a/fml/doc/ja/tutorial/module/IO.sgml
+++ b/fml/doc/ja/tutorial/module/IO.sgml
@@ -1,5 +1,5 @@
 <!--
-   $FML: IO.sgml,v 1.5 2005/06/25 15:11:35 fukachan Exp $
+   $FML: IO.sgml,v 1.6 2008/08/19 03:16:57 fukachan Exp $
 -->
 
 <chapter id="module.io.adapter">
@@ -14,6 +14,14 @@
 	</title>
 
 <para>
+&fml8; のメンバーリストはファイル、
+Unix のグループ、
+RDBMS (リレーショナルデータベースシステム)、
+LDAP など、さまざまな形式で管理できます。
+もちろん、デフォルトはファイルです。
+</para>
+
+<para>
 &fml8; でのメンバーリストの読み書き、例えばアドレスの登録/削除は
 IO::Adapter という抽象クラスを通じて行ないます。ようは Unix で 
 vfs/vnode インターフェイスを導入した時のような感じですね。
@@ -28,7 +36,7 @@ $io->close;
 </para>
 
 <para>
-$map は「map:識別子」となります。
+$map は「map:識別子」形式です。
 現在のところ $map は次のようなものが使えます。
 file: は省略可能です。
 <screen>
@@ -50,8 +58,18 @@ ldap:id は LDAP への通信を可能とします。
 </para>
 
 <para>
-RDBMS などは別の名前空間で定義することにしています。
+設定ファイル中では、(なにかとまぎらわしいので)、
+RDBMS と LDAP を別の名前空間で定義する仕様です。
 たとえば MySQL は config.cf の mysql:id で指定されたパラメータを用います。
+<screen>
+[mysql:id]
+
+sql_database                                      = fml
+
+sql_password                                      = uja
+
+... 略 ...
+</screen>
 このパラメータは new IO::Adapter を実行する際に、
 指定する必要があります(後述)。
 </para>
@@ -84,7 +102,6 @@ touch()
 
 find(REGEXP, $args)
 </screen>
-です。
 </para>
 
 <para>
@@ -99,7 +116,7 @@ REGEXP は正規表現ですが、たいていはメールアドレスです。
 </para>
 
 <para>
-最低限のメソッド群の定義は実際に実装してみる実験を通じて選ばれました。
+メソッド群の定義は、実際に実装し、実験運用を通じて選ばれました。
 その際、ファイルの IO よりは、SQL との IO を想定しつつ、
 メソッドの組を考えています。
 そのため、&fml4; のファイルを前提にした処理とくらべると、
@@ -116,13 +133,16 @@ REGEXP は正規表現ですが、たいていはメールアドレスです。
 	</title>
 
 <para>
-get_next_key() のように引数なしか STR を引数にして STR を返り値にする
-ものが多いです。これはファイルの一覧を見るとか、特定のアドレスに対する
-何かの値を取り寄せるとかいう操作がよく使われるためです。
+メソッドの型は、
+get_next_key() のように引数なしか STR を引数にし STR を返り値にしています。
+これは、
+ファイルの一覧を見るとか、
+特定のアドレスに対する何かの値を取り寄せる、
+といった操作がよく使われるためです。
 </para>
 
 <para>
-しかし、特定のアドレスに対する値が組になっているものがあります。
+しかし、特定のアドレスに対する値が組になっている返り値もあります。
 これは
 <screen>
 KEY_STR => [
@@ -132,8 +152,9 @@ KEY_STR => [
 ]
 </screen>
 のようなデータ構造が返ってくることを期待する場合です。
-&fml4; の actives はメールアドレスに対していくつかのオプションの値を記
-述するので、こういったデータ構造と考えられます。
+たとえば &fml4; の actives 
+はメールアドレスに対していくつかのオプションの値を記述するので、
+こういったデータ構造と考えられます。
 <screen> 
 例
 
@@ -148,8 +169,9 @@ rudo@nuinui.net => [
 </para>
 
 <para>
-まとめると引数は「ない」か「STR」なので STR とひとまとめにしても良いで
-しょう。一方、返り値は STR か ARRAY_REF になります。
+まとめると引数は「ない」か「STR」(正規表現も文字列の一種)なので 
+STR とひとまとめにしても良いでしょう。
+一方、返り値は STR か ARRAY_REF になります。
 <screen>
 引数    返り値
 ---------------------------------------
@@ -232,9 +254,10 @@ NIS/YP から group にあたるものを引っ張ってくるところだけが異なります。
 	</title>
 
 <para>
-保守性をあげるためには、一箇所に設定をまとめておきたい。つまり、一つの 
-cf ファイルにいろいろ書けるようにしておきたい。たとえば &fml8; の
-場合、config.cf の中だけに SQL の設定を書いておきたいわけです。
+保守性をあげるためには、一箇所に設定をまとめておきたい。
+つまり、一つの cf ファイルにいろいろ書けるようにしておきたい。
+たとえば &fml8; の場合、
+config.cf の中だけに SQL の設定も書いておきたいわけです。
 </para>
 
 <para>
@@ -260,14 +283,21 @@ sql_find	=	select * from ...
 		...
 </screen>
 config.cf の中に別の名前空間を定義していると考えてもらってかまいません。
+ここは Unix より MS-DOS の config.ini 形式風ですが、
+Unix では該当するものが思いつけないので .ini となりました。
 </para>
 
 <para>
-IO::Adapter は
+RDBMS や LDAP に対し $config の情報が必要なため、IO::Adapter は
 <screen>
 new IO::Adapter "mysql:members", $config;
 </screen>
-のように呼び出します。
+のように呼び出す必要があります。
+よって、各ソフトウエアでは、つねに 
+<screen>
+new IO::Adapter $map, $config; 
+</screen>
+と書いておく必要があります。
 この $config は次のようなハッシュ・リファレンスになっていることが
 期待されています。通常 $config は FML::Config オブジェクトそのものです。
 <screen>
@@ -278,9 +308,9 @@ $config => {
 	}
 }
 </screen>
-FML::Config は .cf から上のようなハッシュを構成します。
-よって IO::Adapter の new() の際には、
-FML::Config のオブジェクトを引数で渡せば OK です。
+FML::Config は .cf から上のようなハッシュ・リファレンスを構成します。
+よって IO::Adapter で new() を呼び出す際には、
+つねに FML::Config オブジェクトを引数で渡すようにしてください。
 </para>
 
 
@@ -292,8 +322,8 @@ FML::Config のオブジェクトを引数で渡せば OK です。
 	</title>
 
 <para>
-関数が呼ばれた時に始めて決まる変数もあるので
-cf で全部定義することはできません。
+関数が呼ばれた際に、初めて決まる変数もあるので
+config.cf ですべてを定義するわけにもいきません。
 そこで、lexical scope で取り扱われる変数の表現があれば解決でしょうか？
 現在は、この目的のために &amp;varname 記法(下記)を使っています。
 </para>
@@ -307,12 +337,9 @@ cf で全部定義することはできません。
 <para>
 例: 
 以下は、受信者リストとメンバーリストが食い違う例で、
-アドレスの登録をする際に、fml_recepient という値が異なります。
-その場合、member と recipient は少し異なる SQL 命令になるので
-別々に定義します。
-off/on 命令を無視するとか、
-fml は sql からデータを読むだけで書き込むことはしないなら、
-話は簡単になるわけです。
+アドレスの登録をする際に、fml_address という値が異なります。
+その場合、
+member と recipient は少し異なる SQL 命令になるので別々に定義します。
 <screen>
 member_maps 	= 	mysql:members
 
@@ -406,6 +433,13 @@ sql_find	=	select * from $sql_table
 </screen>
 </para>
 
+<para>
+off/on 命令を無視するとか、
+fml が SQL からデータを読むだけで書き込むことはしないのであれば、
+話は簡単になるわけですが…
+避けるのは難しいですね。
+</para>
+
 </sect2>