clean up a little ...

4 files changed, 175 insertions, 90 deletions

diff --git a/fml/doc/ja/tutorial/command/dataflow.sgml b/fml/doc/ja/tutorial/command/dataflow.sgml
index f3209c90..6ac30ba2 100644
--- a/fml/doc/ja/tutorial/command/dataflow.sgml
+++ b/fml/doc/ja/tutorial/command/dataflow.sgml
@@ -1,11 +1,11 @@
 <!--
-   $FML: dataflow.sgml,v 1.5 2005/06/25 15:11:28 fukachan Exp $
+   $FML: dataflow.sgml,v 1.6 2008/08/17 18:28:36 fukachan Exp $
 -->
 
 
 <sect1 id="fml.command.dataflow">
 	<title>
-	コマンドの処理のフロー
+	コマンド処理のフロー
 	</title>
 
 
@@ -14,13 +14,13 @@
 -->
 
 <para>
-すべての処理は最終的に「FML::Command」クラス経由で「FML::Command::モー
-ド::コマンド」クラスを呼び出します。GUI および CUI、コマンドメールは、
-そこに至る前処理の段階が異なるだけです。
+すべてのコマンド(&fml8; への命令)処理は最終的に「FML::Command」クラス
+経由で「FML::Command::モード::コマンド」クラスを呼び出します。GUI およ
+び CUI、コマンドメールは、そこに至る前処理の段階が異なるだけです。
 </para>
 
 
-<sect2>
+<sect2 id="fml.command.dataflow.newframework">
 	<title>
 	コマンドメールの処理
 	</title>
@@ -32,7 +32,13 @@
 </caution>
 
 <para>
-まず、コマンドは行単位で、解析されます。
+本節はコマンドメールの話です。
+メールの本文が複数行あり、それが複数の命令を含むと想定します。
+</para>
+
+<para>
+まず、メールは行単位で解析されます。
+これは、一行に一つのコマンドが書いてあるという想定です。
 </para>
 
 <para>
@@ -41,21 +47,26 @@
 </para>
 
 <para>
-1) guideやsubscribeのようにメンバー以外にも許されるコマンドであれば、
-   直接コマンド呼び出しルーチンへ処理が移ります。
+1) guide や subscribe のようにメンバー以外にも許されるコマンドであれば、
+   そこから直接、コマンド呼び出しルーチンへ処理が移ります。
    ここで許されるコマンドは anonymous_command_mail_allowed_commands
-   で定義されているコマンドです。
+   変数で定義されているコマンドです。
 </para>
 
 <para>
-2) メンバーだけに許されるコマンドの場合、
-   command_mail_restrictionsのルールに従って他の条件を確認し、
+2) あらかじめ指定されたユーザだけに許されるコマンドの場合、
+   command_mail_restrictions のルールに従って他の条件を確認し、
    許されたなら、呼び出しルーチンへ処理が移ります。
    ここで許されるコマンドは user_command_mail_allowed_commands
    で定義されているコマンドです。
 </para>
 
 <para>
+「あらかじめ指定されたユーザ」には、一般ユーザと管理者が含まれます。
+ただし、それぞれの処理のフローが異なります。
+</para>
+
+<para>
 「呼び出しルーチン」では、
 (コマンドに依存した)返事の送り先の確認と
 (コマンドに依存する)シンタックスチェックを経て、
@@ -64,24 +75,25 @@ FML::Command クラス経由でコマンドが実行されます。
 </para>
 
 <para>
-admin コマンドの実行は、ここでは行なわれません。「admin ...」コマンド
-は、まず一般ユーザ権限の admin コマンド
+admin コマンドも「あらかじめ指定されたユーザ」ですが、
+admin コマンドの実行は、ここでは行なわれません。
+「admin ...」コマンドは、まず一般ユーザ権限の admin コマンド
 <footnote>
 <para>
 注: admin コマンドは user_command_mail_allowed_commands で許されています
 </para>
 </footnote>
-として処理が進められ、最終的に「FML::Command::User::admin」クラスが呼
-び出されます。このクラスの中で、$admin_command_mail_restrictions に基
-づいてリモート権限があるか？が確認され、もう一度「FML::Command」クラス
-経由で管理者権限の「FML::Command::Admin::コマンド」クラスが呼び出され
-ます(つまりトランポリンメカニズムです)。
+の実行として処理が進められ、最終的に「FML::Command::User::admin」クラ
+スが呼び出されます。このクラスの中で、admin_command_mail_restrictions 
+変数 に基づいてリモート権限があるか？が確認され、もう一度
+「FML::Command」クラス経由で管理者権限の「FML::Command::Admin::コマン
+ド」クラスが呼び出されます(つまりトランポリン・メカニズムです)。
 </para>
 
 </sect2>
 
 
-<sect2>
+<sect2 id="fml.command.dataflow.cui">
 	<title>
 	CUI (makefml/fml)の処理
 	</title>
@@ -94,8 +106,9 @@ admin コマンドの実行は、ここでは行なわれません。「admin ...」コマンド
 </para>
 
 <para>
-なお、サーバにリモートで入れるようにする際、SSH で「RSA 2048 bit 鍵の
-み許す」といった設定および運用ルールにしてください。
+なお、サーバへリモートからログインするためには SSH で「RSA 2048 ビット
+以上の鍵のみを許す、パスワード認証は認めない」といった強固な運用ルール
+を課して下さい。
 </para>
 
 </sect2>
diff --git a/fml/doc/ja/tutorial/command/extension.sgml b/fml/doc/ja/tutorial/command/extension.sgml
index 4f7e7b05..24469544 100644
--- a/fml/doc/ja/tutorial/command/extension.sgml
+++ b/fml/doc/ja/tutorial/command/extension.sgml
@@ -1,5 +1,5 @@
 <!--
-   $FML: extension.sgml,v 1.13 2005/06/25 15:11:28 fukachan Exp $
+   $FML: extension.sgml,v 1.14 2008/08/17 18:28:36 fukachan Exp $
 -->
 
 
@@ -18,25 +18,35 @@
 
 <warning>
 <para>
-このホスト上の「全ての ML で利用可能な」コマンドを作りたい場合は、
+「拡張した機能を許可する範囲」が制御できます。
+</para>
+
+<para>
+このホスト上の「全てのＭＬで利用可能な」コマンドを作りたい場合は、
 拡張したモジュールを
 <screen>
 /usr/local/lib/fml/site_local/
 </screen>
 以下に配置して下さい。
-一方、特定のＭＬだけを拡張する場合は、各ＭＬのホーム以下の local/lib/
-以下において下さい。
+</para>
+
+<para>
+一方、特定のＭＬだけで利用可能な機能拡張であれば、
+各ＭＬのホーム以下の local/lib/ 以下において下さい。
 <screen>
 ＭＬのホーム/local/lib/
 
-例:
+例: elena ( ML のホームが /var/spool/ml/elena/ )
 /var/spool/ml/elena/local/lib/
 </screen>
 </para>
 
 <!--
 <para>
-以下では、このホスト全ての ML で有効にする場合を考えます。
+以下では、すべてのＭＬで有効にする場合を考えます。
+</para>
+
+<para>
 もちろん、どちらのケースでもモジュールの書き方は一緒です。
 </para>
 -->
@@ -51,25 +61,31 @@
 
 <para>
 ユーザ向けのコマンド uja を作りたい場合、
-FML::Command::User 以下のモジュールから適当に cut and paste して
+(1)
+FML::Command::User 以下のモジュールから適当にコピー＆ペーストして
 <screen>
 /usr/local/lib/fml/site_local/FML/Command/User/uja.pm
 </screen>
-というファイルを作り、設定ファイルで
-uja を許可するコマンドリストに追加して下さい。
+というファイルを作ってください。
+(2) 次に、設定ファイルで uja を許可してください。
+</para>
 
-全ての ML で有効にする場合は、site_default_config.cf で、
-許可するコマンドリストに追加してください。
+<para>
+すべてのＭＬで有効にする場合は、site_default_config.cf で、
+「許可するコマンドのリスト」に追加してください。
 <screen>
 user_command_mail_allowed_commands += uja
 </screen>
+user_command_mail_allowed_commands 変数は、
+一般ユーザに許すコマンドのリスト一覧です。
+</para>
 
-elena ML だけで有効にする場合は、elena ML の config.cf で、
+<para>
+elena MＬだけで有効にする場合は、elena ＭＬの config.cf で、
 許可するコマンドリストに追加してください。
 <screen>
 user_command_mail_allowed_commands += uja
 </screen>
-
 </para>
 
 </sect2>
@@ -81,23 +97,26 @@ user_command_mail_allowed_commands += uja
 	</title>
 
 <para>
-admin 向けのコマンド uja を作りたい場合、
-FML::Command::Admin 以下から適当に cut and paste して
+管理者向けのコマンド(admin コマンド)の uja を作りたい場合、
+FML::Command::Admin 以下から適当にコピー＆ペーストして
 <screen>
 /usr/local/lib/fml/site_local/FML/Command/Admin/uja.pm
 </screen>
 というファイルをつくってください。
+</para>
 
-
-全ての ML で有効にする場合は、site_default_config.cf で、
+<para>
+すべてのＭＬでコマンドを有効にする場合は、site_default_config.cf で、
 許可するコマンドリストに追加してください。
 <screen>
 admin_command_mail_allowed_commands += uja
 </screen>
+admin_command_mail_allowed_commands 変数は
+管理者に許すコマンドのリスト一覧です。
 </para>
 
 <para>
-elena ML だけで有効にする場合は、elena ML の config.cf で、
+elena ＭＬだけで有効にする場合は、elena ＭＬの config.cf で、
 許可するコマンドリストに追加してください。
 <screen>
 admin_command_mail_allowed_commands += uja
@@ -134,20 +153,28 @@ admin_command_mail_allowed_commands += uja
 </para>
 
 <para>
-以下では、このホスト全ての ML で有効にする場合を考えます。
+以下では、すべてのＭＬで有効にする場合を考えます。
 </para>
 </warning>
 
 
 <para>
-makefml でコマンド uja を作いたい場合、
-FML::Command::Admin 以下から適当に cut and paste して
+makefml でコマンド uja を作りたい場合、
+FML::Command::Admin 以下から適当にコピー＆ペーストして
 <screen>
 /usr/local/lib/fml/site_local/FML/Command/Admin/uja.pm
 </screen>
 というファイルをつくるだけで有効になります
-つまりモジュールを置くだけで有効になります。
-*_allowed_commands 系の変数の設定変更は不要です。
+</para>
+
+<para>
+makefml では「モジュールを置くだけで有効」になります。
+許されるコマンド一覧 *_allowed_commands 系の変数設定変更は不要です。
+</para>
+
+<para>
+makefml を利用できる時点で、そのＭＬサーバの特権権限を奪取できているわ
+けですから、それ以上複雑な制限をつけても使いにくいだけでしょうから。
 </para>
 
 
@@ -164,17 +191,20 @@ FML::Command::Admin 以下から適当に cut and paste して
 <warning>
 
 <para>
-以下の記述で利用可能な機能を追加することが出来ますが、
-別途、画面の作り込みが必要です。
+以下の記述で「利用可能な機能の追加」が出来ますが、
+それとは別に CGI 画面の作り込みは必要です。
 </para>
 
 <para>
-このホスト全ての ML で有効にする場合、
+このホスト上のすべてのＭＬで有効にする場合、
 拡張するモジュールを
 <screen>
 /usr/local/lib/fml/site_local/
 </screen>
 以下に配置して下さい。
+</para>
+
+<para>
 一方、特定のＭＬだけを拡張する場合は、各ＭＬのホーム以下の local/lib/
 以下において下さい。
 <screen>
@@ -186,30 +216,37 @@ FML::Command::Admin 以下から適当に cut and paste して
 </para>
 
 <para>
-以下では、このホスト全ての ML で有効にする場合を考えます。
+以下では、すべてのＭＬで有効にする場合を考えます。
 </para>
 </warning>
 
+<para>
+CGI での拡張は、一般ユーザ向けということは少なく、
+たいていは管理者向けのものと考えます。
+よって、以下、管理者向け機能拡張のみを取り上げます。
+</para>
 
 <para>
-admin 向けのコマンド uja を作りたい場合、
-FML::Command 以下から適当に cut and paste して
+管理者向けのコマンド uja を作りたい場合、
+FML::Command 以下から適当にコピー＆ペーストして
 <screen>
 /usr/local/lib/fml/site_local/FML/Command/Admin/uja.pm
 </screen>
-というファイルを置いてください。
+というファイルを作ってください。
 </para>
 
 <para>
-全ての ML で有効にする場合は、site_default_config.cf で、
+すべてのＭＬで uja コマンドを有効にしたい場合、site_default_config.cf で、
 許可するコマンドリストに追加してください。
 <screen>
 admin_cgi_allowed_commands += uja
 </screen>
+admin_cgi_allowed_commands 変数は管理者用 CGI インターフェイスで許可す
+るコマンドの一覧です。
 </para>
 
 <para>
-elena ML だけで有効にする場合は、elena ML の config.cf で、
+elena ＭＬだけで有効にする場合は、elena ＭＬの config.cf で、
 許可するコマンドリストに追加してください。
 <screen>
 admin_cgi_allowed_commands += uja
diff --git a/fml/doc/ja/tutorial/command/internal.sgml b/fml/doc/ja/tutorial/command/internal.sgml
index da15a09a..7a0e8cb5 100644
--- a/fml/doc/ja/tutorial/command/internal.sgml
+++ b/fml/doc/ja/tutorial/command/internal.sgml
@@ -1,5 +1,5 @@
 <!--
-   $FML: internal.sgml,v 1.12 2005/08/03 13:44:54 fukachan Exp $
+   $FML: internal.sgml,v 1.13 2008/08/17 18:28:36 fukachan Exp $
 -->
 
 
@@ -43,10 +43,10 @@ FML::Process::Command クラスから
 
 <warning>
 <para>
-全てのコマンドは FML::Command::User::コマンドもしくは
-FML::Command::Admin::コマンドクラスとして実装されています。なお 
-makefml や CGI は FML::Command::Admin::コマンド を使います。コマンドメー
-ルは User や Admin を権限に応じて適宜使い分けます。
+全てのコマンドは「FML::Command::User::コマンド」クラスもしくは
+「FML::Command::Admin::コマンド」クラスとして実装されています。なお 
+makefml は「FML::Command::Admin::コマンド」を使います。
+コマンドメールや CGI は User や Admin を権限に応じて適宜使い分けます。
 </para>
 </warning>
 
@@ -56,7 +56,7 @@ help コマンドの実体は FML::Command::User::help の process() 関数です。
 sub process
 {
     my ($self, $curproc, $optargs) = @_;
-    my $config    = $curproc->{ config };
+    my $config    = $curproc->config();
     my $charset   = $config->{ report_mail_charset_ja };
     my $help_file = $config->{ help_file };
 
@@ -80,27 +80,29 @@ sub process
     }
 }
 </screen>
-ここで $curproc はハッシュリファレンスで、&fml4; の %Envelope に概ね相
-当します。名前の通り、Unix カーネルでおなじみの current process 構造体
-へのポインタのようなもので、プロセスに関連するいろいろなデータ構造やオ
-ブジェクトへのリファレンスを含んでいます。
+ここで $curproc はハッシュリファレンスで、&fml4; の %Envelope におおむ
+ね相当します。名前の通り、Unix カーネルでおなじみの current process 構
+造体へのポインタのようなもので、プロセスに関連するいろいろなデータ構造
+やオブジェクトへのリファレンスを含んでいます。
 </para>
 
 <para>
-変数ですが、&fml4; では全てグローバルです。一方 &fml8; では $config オ
-ブジェクトを通じてアクセスできる設定変数空間の中にあります。
+&fml4; の変数は、すべてグローバル変数です。一方 &fml8; では $config オ
+ブジェクトを通じてアクセスできる設定変数空間の中にあります。常に
+$config オブジェクトを通じて読み書きをしてください。
 </para>
 
 <para>
-reply_message_prepare_template() はメッセージテンプレートの中にある変
-数の展開や文字コード変換を適宜行ない、準備したテンプレートへのファイル
-パスを返します。
+reply_message_prepare_template() メソッドは送り返すメッセージのテンプ
+レート中にある変数の展開や文字コード変換を行ない、生成されたテンプレー
+トへのファイルパスを返します(テンプレートファイルは $tmp_dir ディレク
+トリに作られます)。
 </para>
 
 <para>
 首尾良くテンプレートファイルを用意できたら、
 $curproc->reply_message() というプロセス全体のメッセージ処理を行なう関
-数群ののトップレベルメソッドを呼び出し、メッセージの処理を依頼します。
+数群のトップレベルメソッドを呼び出し、メッセージの返送処理を依頼します。
 </para>
 
 <para>
@@ -109,6 +111,11 @@ $curproc->reply_message() は引数によって振舞いがことなりますが、
 </para>
 
 <para>
+コマンドモジュールでの処理は、キューに入れたところで終りとなります。
+以下の返送処理は、どんな時でも行なわれる通常のフローの一部です。
+</para>
+
+<para>
 メッセージキューに入れられたメッセージ群は、プロセスの終了直前に受信者
 ごとにメッセージがまとめられ一通のメールとして組み立てなおされます。
 メッセージキューの種類がファイルとメッセージが混在している場合は適宜 
@@ -123,16 +130,16 @@ Mail::Delivery クラスが送信処理を担当するモジュールです。
 </para>
 
 <para>
-この仕組みは &fml4; の Notify() と同様ですが、あらゆるメッセージがキュー
-に入れられ、最後に一気に処理されるという点で大きく異なります。
+この返送の大筋は &fml4; の Notify() と同様ですが、あらゆるメッセージが
+一度キューに入れられ、最後に一気に処理されるという点で大きく異なります。
 </para>
 
 <para>
 なお get コマンドなども同じキューイングの仕組みを使っています。つまり 
 &fml4; の Notify() 相当部分が(通常の記事配送以外の)あらゆる送信機能を
-担当し、かつキューイングのみをしています。そしてキューイングされたメッ
-セージは最後に一気に処理されます。この点において、送信のキューイングの
-メカニズムは &fml4; と大きく異なっています。
+担当し、かつキューイングのみをします。そしてキューイングされたメッセー
+ジは最後に一気に処理されます。この点において、送信のキューイングのメカ
+ニズムが &fml4; と大きく異なっているわけです。
 </para>
 
 </sect1>
diff --git a/fml/doc/ja/tutorial/command/module.sgml b/fml/doc/ja/tutorial/command/module.sgml
index 0d34d49f..a3de06ac 100644
--- a/fml/doc/ja/tutorial/command/module.sgml
+++ b/fml/doc/ja/tutorial/command/module.sgml
@@ -1,5 +1,5 @@
 <!--
-   $FML: module.sgml,v 1.5 2004/04/07 11:07:00 fukachan Exp $
+   $FML: module.sgml,v 1.6 2008/08/17 18:28:36 fukachan Exp $
 -->
 
 
@@ -25,9 +25,10 @@ FML::Command::Admin	管理者用コマンド群
 例えば、(コマンドメールでの)ユーザ用コマンドの場合
 FML::Command を経由して
 FML::Command::User::コマンド
-モジュールを使うことになります。
+モジュールを呼び出しています。
 </para>
 
+
 <sect2>
 	<title>
 	(コマンドメールでの)一般ユーザ用コマンド
@@ -36,33 +37,34 @@ FML::Command::User::コマンド
 <para>
 FML::Process::Command から
 FML::Command 経由で
-FML::Command::User::コマンド
+「FML::Command::User::コマンド」
 を呼び出しています。
 </para>
 
 <para>
 最終的に
-FML::Command::Admin::コマンド
+「FML::Command::Admin::コマンド」
 を使うモジュールもあります。
-例えば登録と削除の実作業は
-FML::Command::Admin::コマンド
-内のコードが行なっています。
-登録/削除の実体のコードをすべてのプログラムで共有するためです。
+たとえば登録と削除の実作業は
+「FML::Command::Admin::コマンド」
+にあるコードが行なっています。
+すべてのプログラムで登録/削除作業の実体部分を共有するためです。
 この場合、
-FML::Command::User::コマンド
-のコマンドは confirm を行なうための wrapper という位置付けになります。
+「FML::Command::User::コマンド」は
+confirm を行なうための wrapper という位置付けになります。
 </para>
 </sect2>
 
+
 <sect2>
 	<title>
-	(メールでの) adminコマンド
+	(コマンドメールでの) 管理者用コマンド (admin コマンド)
 	</title>
 
 <para>
 FML::Process::Command から
 FML::Command 経由で
-FML::Command::Admin::コマンド
+「FML::Command::Admin::コマンド」
 を呼び出しています。
 </para>
 
@@ -71,13 +73,20 @@ FML::Command::Admin::コマンド
 
 <sect2>
 	<title>
-	makefml のコマンド
+	makefml
 	</title>
 
+<warning>
+<para>
+makefml を実行できる時点で、
+サーバにログインできる管理者権限があるとみなされています。
+</para>
+</warning>
+
 <para>
 FML::Process::Configure から
 FML::Command 経由で
-FML::Command::Admin::コマンド
+「FML::Command::Admin::コマンド」
 を呼び出しています。
 </para>
 
@@ -89,11 +98,30 @@ FML::Command::Admin::コマンド
 	CGI
 	</title>
 
+<warning>
+<para>
+CGI も一般ユーザむけの CGI と管理者用の CGI があります。
+</para>
 
 <para>
+管理者用の CGI については、それを実行できる時点で、
+管理者権限があるとみなされています。
+</para>
+</warning>
+
+<para>
+アドレス登録/削除などのためにある一般ユーザ用の CGI は、
 FML::Process::CGI から
 FML::Command 経由で
-FML::Command::Admin::コマンド
+「FML::Command::User::コマンド」
+を呼び出しています。
+コマンドメールと同様に confirm のための wrapper という位置付けです。
+</para>
+
+<para>
+管理者用の CGI は、FML::Process::CGI から
+FML::Command 経由で
+「FML::Command::Admin::コマンド」
 を呼び出しています。
 </para>