reviewed. alignment cosmetics.

1 files changed, 72 insertions, 46 deletions

diff --git a/fml/doc/ja/tutorial/module/IO.sgml b/fml/doc/ja/tutorial/module/IO.sgml
index 0faa260a..a7476689 100644
--- a/fml/doc/ja/tutorial/module/IO.sgml
+++ b/fml/doc/ja/tutorial/module/IO.sgml
@@ -22,9 +22,10 @@ LDAP など、さまざまな形式で管理できます。
 </para>
 
 <para>
-&fml8; でのメンバーリストの読み書き、たとえばアドレスの登録/削除は
-IO::Adapter という抽象クラスを通じて行ないます。ようは Unix で 
-vfs/vnode インターフェイスを導入した時のような感じですね。
+&fml8; でのメンバーリストの読み書き、
+たとえばメールアドレスの登録/削除は
+IO::Adapter という抽象クラスを通じて行ないます。
+ようは Unix における vfs/vnode インターフェイスの導入です。
 使い方は次のようになります。
 <screen>
 use IO::Adapter;
@@ -37,8 +38,8 @@ $io->close;
 
 <para>
 $map は「map:識別子」形式です。
-現在のところ $map は次のようなものが使えます。
-file: は省略可能です。
+現在のところ $map は次のようなものが指定可能です。
+なお file: は省略可能です。
 <screen>
 file:/var/spool/ml/elena/recipients
 unix.group:root
@@ -51,10 +52,12 @@ ldap:id
 
 <para>
 file: は通常のファイルです。
-unix.group:root は /etc/group の root のエントリにあるユーザのリストを、
+unix.group:root は
+/etc/group の root のエントリにあるユーザのリスト、
 nis.group:root は NIS の root のエントリにあるユーザのリストです。
-mysql:id は MySQL、postgresql:id は PostgreSQL へのアクセスです。
-ldap:id は LDAP への通信を可能とします。
+mysql:id は MySQL、
+postgresql:id は PostgreSQL へのアクセスです。
+ldap:id は LDAP へのアクセスです。
 </para>
 
 <para>
@@ -111,17 +114,22 @@ REGEXP は正規表現ですが、たいていはメールアドレスです。
 </para>
 
 <para>
-多くのマップを同じように扱うために、
-メソッドは極力最少限に、少数精鋭なものだけに限定する必要があります。
+多くのマップを同じようにあつかうために、
+データの操作方法を考え、
+最少限の少数精鋭のメソッドだけを実装しています。
 </para>
 
 <para>
 メソッド群の定義は、実際に実装し、実験運用を通じて選ばれました。
-その際、ファイルの IO よりは、SQL との IO を想定しつつ、
-メソッドの組を考えています。
+その際、
+ファイルの IO よりは、SQL との IO を想定しつつ、
+メソッドの仕様を考えています。
 そのため、&fml4; のファイルを前提にした処理とくらべると、
 少し不自由に思えるでしょうが、
-そのおかげで抽象化が高くなっています。
+そのぶん抽象度合いは高くなっています。
+そして、
+これを実装し、長年運用できているので、
+現在の仕様で必要十分のようです。
 </para>
 
 </sect1>
@@ -134,11 +142,12 @@ REGEXP は正規表現ですが、たいていはメールアドレスです。
 
 <para>
 メソッドの型は、
-get_next_key() のように引数なしか STR を引数にし STR を返り値にしています。
+get_next_key()
+のように引数なしか STR を引数にし STR を返り値にしています。
 これは、
 ファイルの一覧を見るとか、
-特定のアドレスに対する何かの値を取り寄せる、
-といった操作がよく使われるためです。
+特定のメールアドレスに対して何かの値を取り寄せる、
+といった操作が多く使われるためです。
 </para>
 
 <para>
@@ -152,8 +161,9 @@ KEY_STR => [
 ]
 </screen>
 のようなデータ構造が返ってくることを期待する場合です。
-たとえば &fml4; の actives 
-はメールアドレスに対していくつかのオプションの値を記述するので、
+たとえば
+&fml4; の actives は、
+メールアドレスに対していくつかのオプションの値を記述するので、
 こういったデータ構造と考えられます。
 <screen> 
 例
@@ -169,8 +179,9 @@ rudo@nuinui.net => [
 </para>
 
 <para>
-まとめると引数は「ない」か「STR」(正規表現も文字列の一種)なので 
-STR とひとまとめにしても良いでしょう。
+まとめると、
+引数は「ない」か「STR」(正規表現も文字列の一種)なので 
+STR 型と一まとめに考えてかまいません。
 一方、返り値は STR か ARRAY_REF になります。
 <screen>
 引数    返り値
@@ -194,7 +205,9 @@ STR  => [STR, STR, ... ]
 	</title>
 
 <para>
-『file:ファイル名』もしくは単なる『ファイル名』は
+「file:ファイル名」
+もしくは単なる
+「ファイル名」は、
 ごく普通のテキストファイルへの IO を抽象化したものです。
 </para>
 
@@ -228,8 +241,10 @@ root
 rudo
 kenken
 </screen>
-のようなファイルとみなされます。
-つまり 3 行のファイルを読みだすようにみなされているわけです。
+のようなファイルとみなしています。
+つまり
+/etc/group (上述の行)を、
+合計3行のファイルを読みだす処理と同じと見なしています。
 </para>
 
 </sect1>
@@ -241,8 +256,9 @@ kenken
 	</title>
 
 <para>
-/etc/group のケースとほぼ同様ですが、ソースが
-NIS/YP から group にあたるものを引っ張ってくるところだけが異なります。
+/etc/group のケースとほぼ同様ですが、
+ソースが
+NIS/YP から group にあたる情報を出してきている点だけが異なります。
 </para>
 
 </sect1>
@@ -254,15 +270,21 @@ NIS/YP から group にあたるものを引っ張ってくるところだけが異なります。
 	</title>
 
 <para>
-保守性をあげるためには、一箇所に設定をまとめておきたい。
-つまり、一つの cf ファイルにいろいろ書けるようにしておきたい。
-たとえば &fml8; の場合、
-config.cf の中だけに SQL の設定も書いておきたいわけです。
+運用部隊としては
+「保守性をあげるためには、一箇所に設定をまとめておきたい」
+つまり
+「一つの cf ファイルにいろいろ書けるようにしておきたい」
+と考えます(あとで diff を取るとか考えると、このほうが便利です)。
+そこで、
+&fml8; の場合、
+config.cf の中に SQL の設定も書けるなら書いておきたいと考えます。
 </para>
 
 <para>
-そこで、[mysql:members] (から終りまで、もしくは次の =head 文まで)の
-ブロックで、マップのタイプと識別子を表現しています。
+そこで、
+[mysql:members]
+(このキーワードから終りまで、もしくは次の =head 文まで)のブロックで、
+マップのタイプと識別子を表現しています。
 <screen>
 config.cf の記述例
 
@@ -284,11 +306,12 @@ sql_find	=	select * from ...
 </screen>
 config.cf の中に別の名前空間を定義していると考えてもらってかまいません。
 ここは Unix より MS-DOS の config.ini 形式風ですが、
-Unix では該当するものが思いつけないので .ini となりました。
+Unix では該当するものが見つからないので .ini 風となりました。
 </para>
 
 <para>
-RDBMS や LDAP に対し $config の情報が必要なため、IO::Adapter は
+RDBMS や LDAP に対し $config の情報が必要なため、
+IO::Adapter は
 <screen>
 new IO::Adapter "mysql:members", $config;
 </screen>
@@ -298,8 +321,9 @@ new IO::Adapter "mysql:members", $config;
 new IO::Adapter $map, $config; 
 </screen>
 と書いておく必要があります。
-この $config は次のようなハッシュ・リファレンスになっていることが
-期待されています。通常 $config は FML::Config オブジェクトそのものです。
+この $config は、
+次のようなハッシュ・リファレンスになっていることが期待されています。
+通常 $config は FML::Config オブジェクトそのものです。
 <screen>
 $config => {
 	[mysql:members] => {
@@ -308,7 +332,8 @@ $config => {
 	}
 }
 </screen>
-FML::Config は .cf から上のようなハッシュ・リファレンスを構成します。
+FML::Config は
+.cf から上のようなハッシュ・リファレンスを構成します。
 よって IO::Adapter で new() を呼び出す際には、
 つねに FML::Config オブジェクトを引数で渡すようにしてください。
 </para>
@@ -322,24 +347,25 @@ FML::Config は .cf から上のようなハッシュ・リファレンスを構成します。
 	</title>
 
 <para>
-関数が呼ばれた際に、初めて決まる変数もあるので
-config.cf ですべてを定義するわけにもいきません。
-そこで、lexical scope で取り扱われる変数の表現があれば解決でしょうか？
+関数が呼ばれた際に、
+初めて決まる変数もあるので config.cf で定義は完結しません。
+lexical scope で取り扱われる変数の表現が必要になります。
 現在は、この目的のために &amp;varname 記法(下記)を使っています。
 </para>
 
 <para>
-ただ、どこで呼ばれるか？を考えないと分からないので、利用可能なローカル
-スコープの変数一覧表を作るのは、かなり困難です。
-どうしたものかと…
+ただ、どこで呼ばれるか？を考えないと分からないので、
+利用可能なローカルスコープの変数一覧表を作るのは困難です。
+どうしたものかというところですが…
 </para>
 
 <para>
 例: 
-以下は、受信者リストとメンバーリストが食い違う例で、
-アドレスの登録をする際に、fml_address という値が異なります。
-その場合、
-member と recipient は少し異なる SQL 命令になるので別々に定義します。
+以下は、
+受信者リストとメンバーリストが食い違う例です。
+メールアドレスの登録をする際に、fml_address という値が異なります。
+この場合、
+member と recipient は少し異なる SQL 命令になるので別々に定義しています。
 <screen>
 member_maps 	= 	mysql:members