diff options
| author | Ken'ichi Fukamachi <fukachan@fml.org> | 2018-09-17 11:04:05 +0900 |
|---|---|---|
| committer | Ken'ichi Fukamachi <fukachan@fml.org> | 2018-09-17 11:04:05 +0900 |
| commit | 1463208a4d73709567603432111aa1e6f27c31d1 (patch) | |
| tree | c04f6092acb842343622ad286e7a03050b7adc0d | |
| parent | 7baee02a04361945d0db9e5f306427e62d063b4f (diff) | |
| download | fml8-1463208a4d73709567603432111aa1e6f27c31d1.tar.gz fml8-1463208a4d73709567603432111aa1e6f27c31d1.tar.bz2 fml8-1463208a4d73709567603432111aa1e6f27c31d1.zip | |
reviewed. alignment cosmetics.
22 files changed, 726 insertions, 531 deletions
diff --git a/fml/doc/ja/tutorial/internals/bootloader.sgml b/fml/doc/ja/tutorial/internals/bootloader.sgml index d76df137..6f7ee44f 100644 --- a/fml/doc/ja/tutorial/internals/bootloader.sgml +++ b/fml/doc/ja/tutorial/internals/bootloader.sgml @@ -9,8 +9,9 @@ </title> <para> -&fml8; にはインストールされている fml のバージョン依存性を考慮するため -に、本章で述べるようなブートストラップの過程があります。 +&fml8; には、 +インストールされている fml のバージョン依存性を解決するために、 +本章で述べるブートストラップ過程があります。 <screen> fml (libexec/distribute) が boot していく様子 @@ -36,7 +37,7 @@ fml (libexec/distribute) が boot していく様子 <sect1 id="bootloader.example.distribute"> <title> - 例: 配送の場合 + 例: 配送処理の場合 </title> <para> @@ -45,33 +46,39 @@ loader から次々とモジュールが呼ばれていく様子は次のようになります。 </para> <para> -/usr/local/libexec/fml/distributre (の実体 -/usr/local/libexec/fml/loader) は /usr/local/etc/fml/main.cf を読みこ -み、fml_version 変数から使うべきライブラリのバージョンを決めます。 -たとえば fml_vesrion が current-20010501 となっていたら -/usr/local/lib/fml/current-20010501/ 以下にあるライブラリを使うといっ -たぐあいです。 +/usr/local/libexec/fml/distributre +(の実体は /usr/local/libexec/fml/loader) +は +/usr/local/etc/fml/main.cf を読みこみ、 +fml_version 変数から使うべきライブラリのバージョンを決めます。 +たとえば fml_vesrion が 8.0.0 となっていれば、 +/usr/local/lib/fml/8.0.0/ +以下にあるライブラリを使うといった具合です。 </para> <para> @INC を再設定した後、 loader は FML::Process::Switch をロードし、 $0 (プロセス名)を調べます。 -その名前から自分の仕事は配送処理なので -FML::Process::Distribute クラスをロードし、配送処理に移ります。 +プロセス名から自分の仕事は配送処理なので、 +FML::Process::Distribute クラスをロードすればよいことを理解します。 +このクラスをロードし、配送処理に移ります。 +ここで、プロセス名とロードするべきクラスの対応関係は +/usr/local/etc/fml/defaults/バージョン/modules +(例 /usr/local/etc/fml/defaults/8.0.0/modules) +に定義されています。 </para> <para> -なお、プログラム名とクラスの対応関係は -/usr/local/etc/fml/defaults/バージョン/modules -で定義されています。 -</para> - -<para> -こういった処理は見かけ上 FML::Process::Flow::ProcessStart() という関数 -が制御しています。ProcessStart() が引数として FML::Process::Distribute -オブジェクトを渡され、FML::Process::Distribute オブジェクトを実行して -いくという流れになります。 +こういった処理は、 +見かけ上 +FML::Process::Flow::ProcessStart() +という関数が制御しています。 +ProcessStart() が引数として +FML::Process::Distribute +オブジェクトを渡され、 +FML::Process::Distribute +オブジェクトを実行していくという流れになります。 </para> </sect1> @@ -99,84 +106,100 @@ FML::Process::Mead >-| | <sect1 id="bootloader.classes2"> <title> - プロセス実行時に使われるモジュール群 + プロセス実行時の様子 </title> <itemizedlist> <listitem> <para> - /usr/local/libexec/fml/loader (wrapper)。 - これは Bootstrap() を実行します。 - distribute などは、皆この loader へのシンボリックリンクです。 + [/usr/local/libexec/fml/loader (wrapper)の実行] + </para> + + <para> + この段階では、まだ &fml8; Perl モジュール群に制御が移っていません。 + このプログラムは、loader 内の関数 Bootstrap() を実行します。 + </para> + + <para> + distribute など libexec/ 以下にあるプログラム群は、 + どれも、この loader へのシンボリックリンクです。 /usr/local/libexec/fml/ 以下を参照してください。 </para> </listitem> <listitem> - <itemizedlist> - <listitem> + <para> + [loader 内 Bootstrap() 関数の実行] + </para> + <para> /usr/local/etc/fml/main.cf を読み込み、 - fml のバージョンを知ります。 - また、main.cf の値から @INC (Perl のライブラリサーチパス)を再設定し、 + 実行するべき fml のバージョンを知ります。 + また、 + main.cf の値から + @INC (Perl のライブラリサーチパス)を再設定し、 読み込むべきライブラリのバージョン依存性を解決します。 default_config.cf.{ja,en} はバージョン依存ですので、 設定ファイルを読み込む前に、 - この段階でバージョンを評価しなければいけないことに注意してください。 + この段階でバージョンを評価しなければいけません。 </para> - </listitem> - <listitem> <para> - @ARGV (実行されたプログラムの引数 )を評価し、 - どのＭＬの config.cf (設定ファイル)群を読み込むのかを判断します。 + @ARGV (実行されたプログラムの引数)を評価し、 + どのＭＬの config.cf (設定ファイル)群を読み込むべきか？を判断します。 </para> - </listitem> + </listitem> - <listitem> + <listitem> <para> - 次に + このあと、ようやく FML::Process::Switch (バージョン依存)クラスをロードします。 </para> - <itemizedlist> - <listitem> - <para> - Bootstrap2() および ProcessSwitch() を実行し、 - 配送用、コマンドメール用などの各プロセスへ制御を移します。 - この時点で、すでに $0 から、 - どのプロセスへ成りかわればいいのかは分かっています。 - </para> - </listitem> - - <listitem> - <para> - (ポリモーフィズムの例) - モジュールをダイナミックバインディングし、 - 該当するプロセスオブジェクトを生成、 - そして、プロセスをスタートさせます。 - - FML::Process::Flow の中に、 - どのように fml8 プロセスを実行するかが - 定義されています。おおまかには + <para> + Bootstrap2() および ProcessSwitch() を実行し、 + FML::Process::Flow 経由で、 + 配送用、コマンドメール用などの各プロセスへ制御を移していきます。 + </para> + + <para> + この時点で、 + どのモジュール(例: FML::Process::Distribute) + をロードするのかは分かっています。 + FML::Process::Distribute オブジェクトなどは、 + FML::Process::Flow の関数を呼び出す際に引数として渡されています。 + </para> + + </listitem> + + <listitem> + <para> + FML::Process::Flow 経由で、 + 各モジュール(例: FML::Process::Distribute) + のメソッドを呼び出します。 + </para> + + <para> + FML::Process::Flow の中には、 + どのように &fml8; プロセスを実行するかが規格化/定義されています。 + おおむね、どのプロセスも <screen> -$process = new FML::Process::なにか; +$process = new FML::Process::なになに; $process->prepare($args); $process->verify_request($args); $process->run($args); $process->finish($args); </screen> - のような実行順です。 - 各プロセスは、それぞれについて適当なメソッドを - FML::Process:: 以下のクラスで用意する必要があります。 - </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </listitem> + を実行していきます。 + のため、各プロセスは、 + それぞれについて適当なメソッドを + 「FML::Process::なになに」 + 以下のクラスに用意する必要があります。 + ダミーでもいいので、全メソッドの定義が必要です。 + </para> + </listitem> </itemizedlist> </sect1> @@ -187,13 +210,16 @@ $process->finish($args); </title> <para> -現在では、FML::Process:: の prepare() あたりで解決しています。 +現在は +「FML::Process::なになに」 +の prepare() メソッドあたりで解決しています。 </para> <para> -以下、内部構造について、２、３の走り書き/おぼえがきを残しておきます。 +以下、内部構造についての走り書き/おぼえがきです。 一応、こういった構造を考慮して、 -prepare() メソッドあたりに持ってきているわけです。 +prepare() +に持ってきています。 <screen> main::Bootstrap() @@ -209,9 +235,9 @@ main::Bootstrap() main::Bootstrap2() ProcessSwitch() - 使うモジュール( Process::なんか )を決める + 使うモジュール( Process::なんか )を決定する 読み込むべき cf ファイルの決定（なんで？） - ライブラリパスの決定や @INC の修正など + ライブラリパスの決定や @INC の修正などを行う hints を渡す？使う？ (CGI のみ？) diff --git a/fml/doc/ja/tutorial/internals/cgi.examples.sgml b/fml/doc/ja/tutorial/internals/cgi.examples.sgml index d08bf4e4..6a903df4 100644 --- a/fml/doc/ja/tutorial/internals/cgi.examples.sgml +++ b/fml/doc/ja/tutorial/internals/cgi.examples.sgml @@ -96,22 +96,26 @@ $curproc->_drive_cgi_by_table() メソッドは、 </para> <para> -たとえばコマンドを実行するメイン部分が run_cgi_main です。これは、 +たとえば、コマンドを実行するメイン部分が run_cgi_main です。 +これは、 cgi_execute_command (FML::Process::CGI::Kernel) を呼び出し、 FML::Command 経由で「FML::Command::Admin::コマンド」クラスを実行します。 これが、GUI からコマンドを実行するコードの本体です。 </para> <para> -画面の表示をするには別のメソッド群が呼ばれています。 +画面の表示をする際には、 +別のメソッド群が呼ばれています。 </para> <para> たとえば GUI から「ユーザのメールアドレスを登録する」場合、 run_cgi_menu() が入力画面の生成をおこないます。 -run_cgi_menu() は cgi_execute_cgi_menu() 経由で各コマンドクラスの +run_cgi_menu() は cgi_execute_cgi_menu() 経由で、 +各コマンドクラスの 「FML::Command::Admin::コマンド::cgi_menu()」を実行しています。 -この場合 FML::Command::Admin::subscribe::cgi_menu() +この場合 +FML::Command::Admin::subscribe::cgi_menu() メソッドを呼び出しています。 </para> @@ -123,16 +127,17 @@ FML::Command::Admin::subscribe::process() <para> 他にも run_cgi_* 関数がありますが、 -これらは画面の作りに関係する補助的なものたちといってよいでしょう。 +これらは画面の作りに関係する補助的な関数と言ってよいでしょう。 </para> <para> -次の２つのメソッドは、たいていデフォルトのものを使っています。 +次の２つのメソッドは、たいていデフォルトの関数を呼び出しています。 <screen> run_cgi_title FML::Process::CGI::Kernel クラス (タイトル表示) run_cgi_options FML::Process::CGI::Kernel クラス (言語選択画面) </screen> -また、この .cgi 固有の画面作り関連メソッド群として次のものがあります。 +また、 +この .cgi 固有の画面作り関連メソッド群として次のものがあります。 <screen> run_cgi_navigator FML::CGI::Menu クラス run_cgi_help FML::CGI::Menu クラス @@ -140,8 +145,11 @@ run_cgi_command_help FML::CGI::Menu クラス run_cgi_menu FML::CGI::Menu クラス </screen> ヘルプなどはコマンドごとに違うわけですから、当たり前ですね？ -ただ、メッセージが異なるとかいうだけで、モジュールが違っても、 -ほぼ似たようなつくりです。 +もっとも、 +これらは、 +メッセージなどが異なるだけで、 +モジュールが違っても、 +ほぼ似たようなつくりになっています。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/cgi.sgml b/fml/doc/ja/tutorial/internals/cgi.sgml index ba614b7b..4ed37bd2 100644 --- a/fml/doc/ja/tutorial/internals/cgi.sgml +++ b/fml/doc/ja/tutorial/internals/cgi.sgml @@ -15,7 +15,7 @@ </title> <para> -FML::CGI:: の階層にあるクラス(たとえば FML::CGI::ML)は、 +FML::CGI:: の階層にあるクラス(たとえば FML::CGI::ML)では、 以下のメソッド群を実装して下さい。 <screen> html_start() @@ -78,19 +78,23 @@ finish() </para> <para> -ヘッダ部分(HTTP ヘッダではなく、HTML の DOCTYPE から BODY あたり)やフッ -タの部分は html_start() および html_end() で HTML コードを生成します。 +ヘッダ部分(HTTP ヘッダではなく、HTML の DOCTYPE から BODY あたり)や、 +フッタの部分は +html_start() および html_end() で HTML コードを生成しています。 </para> <para> -一方、HTML BODY の中身は真中の３ｘ３のテーブル状の部分で、run_cgi() から呼 -ばれるメソッドが生成しています。 +一方、 +HTML BODY の中身は中央の3x3テーブル状の部分で、 +run_cgi() から呼ばれるメソッドが生成しています。 </para> <para> -run_cgi() の中身をもっと細かくすることと、画面上のどの部分をどのメソッ -ドが記述するのかを指定できるアクセスメソッドが必要です。また、これにあ -わせて BODY の中身もより細かく次のような３x３の精度で表現されています。 +(1) run_cgi() の粒度をあげる(中身をより細かくする)、 +(2)「画面上のどの部分をどのメソッドが記述するのか」を指定できるメソッド、 +が必要でしょう。 +また、 +これにあわせて BODY の中身もより細かく次のような3x3の精度で表現されています。 <screen> nw north ne west center east @@ -113,30 +117,38 @@ run_cgi_main run_cgi_navigator run_cgi_menu run_cgi_command_help run_cgi_options </screen> -HTML のレベルでは、TABLE 命令を使って疑似的なナビゲーションバーを作っ -ています。そして、ハッシュテーブルで定義されている関数を決められた順番 -で実行し、テーブルを作成しています。 +HTML のレベルでは、 +TABLE 命令を使って疑似的なナビゲーションバーを作っています。 +そして、 +ハッシュテーブルで定義されている関数を決められた順番で実行し、 +テーブルを作成しています。 </para> <para> -run_cgi_main() は何らかの処理をしない限り何も表示しません。大抵は「な -し」か「OK …」程度です。エラーメッセージを表示することもあります。ま -た、この関数はＭＬ一覧などをきちんと最新の情報にするために、画面を描く -前に実行する必要があります。 +run_cgi_main() は何らかの処理をしない限り何も表示しません。 +たいていは「なし」か「OK …」程度です。 +エラーメッセージを表示することもあります。 +また、 +この関数はＭＬ一覧などをきちんと最新の情報にするために、 +画面を描く前に実行する必要があります。 </para> <para> -ちなみに、run_cgi_main() は個々の関数を呼び出すためのトップレベルのア -ダプター層で、FML::CGI::Menu::Admin に定義されています。個々のコマンド -は、makefml の時と同様に、この関数経由で実行されます。 +ちなみに、 +run_cgi_main() は個々の関数を呼び出すためのトップレベルのアダプター層で、 +FML::CGI::Menu::Admin に定義されています。 +個々のコマンドは、makefml の時と同様に、この関数経由で実行されます。 </para> <para> -ただし、ログやメンバーリスト一覧のように run_cgi_menu() から結果の表示 -をしているものもあります。これは表示のオプションの指定をさせるために、 -run_cgi_main() ではなく run_cgi_menu() 経由で表示しているともいえるの -ですが、なにしろコマンドの結果の表示が長いので、今のように menu() 経由 -のほうがよいと思います。 +ただし、 +ログやメンバーリスト一覧のように +run_cgi_menu() から結果の表示をしているものもあります。 +これは表示のオプションの指定をさせるために、 +run_cgi_main() ではなく +run_cgi_menu() 経由で表示しているともいえるのですが、 +なにしろコマンドの結果の表示が長いので、 +今のように menu() 経由のほうがよいと思います。 </para> </sect2> @@ -157,8 +169,7 @@ FML::Command:: FML::Command:: の中に実体があるとは限らず object composition の形式で -FML::CGI:: クラスが提供するメニュー生成クラスを -使うことになっています。 +FML::CGI:: クラスが提供するメニュー生成クラスを使うことになっています。 たとえば subscribe の場合 <screen> FML::CGI::Admin::Main → @@ -175,18 +186,15 @@ Mach のトランポリン機構のように、いったりきたりしています。 <sect1 id="cgi.internal.problems"> <title> - 備考: FML::CGI::Admin:: ではハードコーディングするしかない？ + 備考: FML::CGI::Admin:: ではハードコーディングするしかないのか？ </title> <para> たとえば FML::CGI::Admin::User では -$comname と maps の関係がハードコーディングされてるけれど、 -でも、これはある程度はしかたないでしょう。 -</para> - -<para> -設定ファイルに追い出すと、とてつもなくいっぱい変数が必要になりそうです -が、できるだけ config.cf で変更可能であるようにこころがけています。 +$comname と maps の関係がハードコーディングされていますが、 +設定ファイルに移動するには非常に多くの変数が必要になりそうなので、 +ある程度のハードコーディングは仕方ないでしょう。 +できるだけ config.cf で変更可能であるように心がけたいとは思うのですが… </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/config.cf.sgml b/fml/doc/ja/tutorial/internals/config.cf.sgml index 45364e9d..366ef035 100644 --- a/fml/doc/ja/tutorial/internals/config.cf.sgml +++ b/fml/doc/ja/tutorial/internals/config.cf.sgml @@ -21,14 +21,15 @@ </para> <para> -そのために &fml4; では各ＭＬのホームディレクトリ $DIR (例: -/var/spool/ml/elena)に config.ph というファイルがあります。 -これは .ph という名前でわかる通り perl script です。 +そのために &fml4; では、 +各ＭＬのホームディレクトリ $DIR (例: /var/spool/ml/elena)に +config.ph というファイルがあります。 +これは .ph という名前でわかるとおり、普通の perl スクリプトです。 </para> <para> -一方 &fml8; では config.cf というファイルです。 -フォーマットは Postfix や .ini 風の +一方 &fml8; では config.cf というファイルになっています。 +.cf のフォーマットは Postfix や .ini 風の <screen> 変数 = 値 </screen> @@ -37,8 +38,12 @@ </para> <para> -perl module と同様に、=cut の後には perl script を書くようになっています。 -「キーワード = 値」形式の記述は =cut の前に書いて下さい。 +perl モジュールと同様に、 +=cut の後は +perl スクリプトが書けるようになっています。 +よって、 +「キーワード = 値」 +形式の記述は =cut の前に書く必要があります。 </para> <sect2> @@ -47,31 +52,33 @@ perl module と同様に、=cut の後には perl script を書くようになっています。 </title> <para> -&fml4; の perl script 方式には、いくつか問題があります。 +&fml4; の perl スクリプト方式には、いくつか問題があります。 </para> <para> メリットとしては、 -perl script なので、perl が許す限りの自由な書き方ができます。 +perl スクリプトなので、perl が許す限りの自由な書き方ができます。 これは人間にとっては嬉しいのですが、 -機械処理の観点からは問題です。というのは +機械処理の観点からは問題です。 +というのは、 makefml や CGI をはじめとする設定インターフェイスを書きにくいのです。 そこで &fml4; では、 -cf というファイルと config.ph という -2 つのフォーマットの異なるファイルが使われることになりました。 +cf というファイルと +config.ph という2つのフォーマットの異なるファイルが使われることになりました。 <footnote> <para> .mc から .cf を作る点で、なんとなく sendmail みたいですね;) </para> </footnote> -しかし、これでは２つのファイルに分かれてしまう点で保守がしにくくなります。 +しかしながら、 +これでは２つのファイルに分かれてしまうため保守が大変です。 </para> <para> よって &fml8; では、 -設定インターフェイスにやさしい新フォーマットとしました。 +設定インターフェイスの構築にやさしい新フォーマットとしました。 それが config.cf で、 -本質的に Postfix 風フォーマットです。 +本質的に Postfix 風フォーマットですが、少し拡張されています。 </para> </sect2> @@ -131,7 +138,7 @@ a = 値4 <screen> b = 値4/値2/値3 </screen> -と判断されます。 +と解釈されます。 </para> </sect1> @@ -254,16 +261,20 @@ $config->{ another_key } <para> 値の代入操作が行なわれると、 -まずは %_fml_config に キーと値 の組が保存されます。 +まずは +FML::Config +の内部変数 +%_fml_config に、キーと値の組が保存されます。 これは $dir/$file のような代入した値そのままです。 </para> <para> -get() メソッドは、 +FML::Config の get() メソッドは、 %_fml_config ではなく %_fml_config_result の値を返しています。 %_fml_config_result 中の値は $dir などが展開された後の値で、 /var/spool/ml/elena/file などとなっています。 -この変数の値の展開は get() メソッドなりが呼ばれた際に初めて行なわれます。 +この変数の値の展開は +get() メソッドなど値を取り出すメソッドが呼ばれた際に初めて行なわれます。 </para> </sect2> @@ -302,20 +313,22 @@ get() メソッドは、 <question> <para> -config.cf 内で使って良い関数はどれですか？ +config.cf 内で使ってよい関数はどれですか？ </para> </question> <answer> <para> -つまり、フックで利用可能な関数は何ですか？という設問ですが、 -公式には「$curproc オブジェクトが提供するメソッド」となります。 +つまり、フックで利用可能な関数は何ですか？という質問だと思いますが、 +公式には「$curproc オブジェクトが提供するメソッド」としておきます。 </para> <para> -たいていのオブジェクトに今あるメソッドは将来も廃止されないと思いますが、 -いちおう $curproc オブジェクトが提供するメソッドとしておくのが安心です。 +各クラス(e.g. FML::ほげほげ Mail::ほげほげ)に現状実装されているメソッドは、 +将来も廃止されないと思いますが、 +いちおう +$curproc オブジェクトが提供するメソッドとしておくのが安心だと思います。 </para> <para> @@ -323,7 +336,7 @@ config.cf 内で使って良い関数はどれですか？ &fml4; の設定ファイル config.ph と異なり &fml8; の config.cf では =cut より前は変数を書く場所です。 perl の関数を書く場所ではありません。 -=cut の後にはフックつまり perl script を書きます。 +=cut の後にはフックつまり perl スクリプト を書きます。 </para> </answer> @@ -332,7 +345,6 @@ perl の関数を書く場所ではありません。 </qandaset> - </sect1> diff --git a/fml/doc/ja/tutorial/internals/credential.sgml b/fml/doc/ja/tutorial/internals/credential.sgml index 26341a44..dacb7922 100644 --- a/fml/doc/ja/tutorial/internals/credential.sgml +++ b/fml/doc/ja/tutorial/internals/credential.sgml @@ -10,7 +10,8 @@ <para> ユーザ認証は -FML::Credential クラスの提供するメソッドを使って行ないます。 +FML::Credential +クラスの提供するメソッドを使って行ないます。 </para> @@ -19,24 +20,20 @@ FML::Credential クラスの提供するメソッドを使って行ないます。 議論: FML::Credential の実装 </title> - -<sect2> - <title> - case sensitive or insensitive ? - </title> - <para> -今は +これらの変数により、ふるまいを制御できます。 <screen> -USER パートは sensitive -ドメインパートは insensitive +use_address_compare_function = yes +address_compare_function_domain_matching_level = 3 +address_compare_function_type = user_part_case_insensitive </screen> -オプションで、USER パートも -insensitive にできるようにできた方がよいのですよね？ +$address_compare_function_type +は、 +ユーザパート(@の左側)の比較の際に、 +大文字小文字の区別をするかいなかを設定できます。 +デフォルトでは区別しません。 </para> -</sect2> - </sect1> diff --git a/fml/doc/ja/tutorial/internals/db_modules.sgml b/fml/doc/ja/tutorial/internals/db_modules.sgml index 65e73722..43b448a1 100644 --- a/fml/doc/ja/tutorial/internals/db_modules.sgml +++ b/fml/doc/ja/tutorial/internals/db_modules.sgml @@ -19,20 +19,27 @@ </title> <para> -ＭＬドライバはメールのさまざまな要素をデータとして保存する必要がありま -す。しかしながら、永続的に持つべきデータと、一定時間経過後に捨てて良い -データがあります。 +ＭＬドライバは、 +メールのさまざまな要素をデータとして保存する必要があります。 +しかしながら、 +永続的に持つべきデータと、 +一定時間経過後に捨てて良いデータが混在しています。 </para> <para> -前者の例はスレッドのデータです。一方、後者の例はフィルタシステムの持っ -ている message-id cache などです。スレッドデータベースも同じく -message-id のデータを持っていますし、記事の分については重複しています。 -ですが、２つの有効期間は異なるため別々に取り扱う必要があります。 +前者の例は(メール)スレッドのデータです。 +一方、 +後者の例はフィルタシステムの持っている message-id cache などです。 +スレッドデータベースも同じく message-id のデータを持っていますし、 +記事の分については重複しています。 +しかしなが、 +これら２つの有効期間は異なるため、別々に取り扱う必要があります。 </para> <para> -とはいえ実際問題スレッド関係とそれ以外に集約できそうなので、 +とはいえ、 +実際問題、 +スレッド関係とそれ以外に集約できそうなので、 各モジュールの理想的な関係は次のようになるのでしょう。 <screen> モジュールＡ ---|ア|----- スレッド DB @@ -44,20 +51,23 @@ message-id のデータを持っていますし、記事の分については重複しています。 <link linkend="threadtrack.db"> Mail::Message::DB </link> -のようなものとし、アダプタ層が差異を吸収して欲しい。 -キャッシュについては、現在のところ Tie::JournaledDir もしくは -FML::Cache::Ring のいづれかが使われることとなっています。 +のようなものとし、アダプタ層が差異を吸収して欲しいと考えました。 +そこで、 +キャッシュについては、 +現在のところ Tie::JournaledDir もしくは FML::Cache::Ring +のいづれかが使われています。 </para> <para> なお、 -メンバーリストなどの永続性の必要なデータに対してデータベースを使う場合は、 +メンバーリストなど永続的データに対しては、 本来、きちんとした DBMS (データベース管理システム)を使うべきです。 </para> <para> -本章で述べるデータベースはそれとは異なり、 -&fml8; が動作する上で内部的に使っているデータベースのことです。 +それらとは異なり、 +本章で述べるデータベースとは、 +&fml8; が動作する上で内部的に使っているデータ操作の話になります。 </para> </sect1> @@ -69,12 +79,19 @@ FML::Cache::Ring のいづれかが使われることとなっています。 </title> <para> -永続的にデータを保持する方法はいくつかあります。いい加減なものから大真 -面目なものまでいろいろです。大真面目に考えると、LRU などの機能を持った -モジュールを利用して作るのかもしれませんが、やや大げさで、いまひとつしっ -くりこない気がします。つまり、そこまで真面目に virtual memory のような -実装をしなくてもよいのでは？ということです。それに、もし切実な必要があ -るのなら、なんらかの +ここでは &fml8; 内部で使っているモジュールの解説をします。 +</para> + +<para> +永続的にデータを保持する方法はいくつかあります。 +いい加減なものから大真面目な実装までいろいろです。 +大真面目に考えると、 +LRU などの機能を持ったモジュールを利用して作るのかもしれませんが、 +やや大げさで、いまひとつしっくりこない気がします。 +つまり、 +そこまで真面目に virtual memory のような実装をしなくてもよいのでは？ +ということです。 +それに、もし切実な必要があるのなら、なんらかの <link linkend="dbms"> DBMS </link> @@ -87,16 +104,12 @@ DBMS </para> <para> -ここでは &fml8; 内部で使っているモジュールの解説をします。 -</para> - -<para> -&fml8; では、データの expire の仕方に応じて２つのデータ保持クラスを用 -意しています。 -それは +&fml8; では、 +データの expire の仕方に応じて二種類のデータ保持クラスを用意しています。 +二つあるのは、 「サイズを気にせず、時間を区切って expire するのか？」 -「使用する領域のサイズをある程度気にするか？」 -の２種類です。 +「使用する領域のサイズをあるていど気にするか？」 +という異なる要求に応えるためです。 </para> </sect1> @@ -116,16 +129,18 @@ DBMS クラスが提供します。 </para> - <para> -このクラスは、データを追加する場合にも使われていますし、過去のデータを -参照したい場合にも用いられますが、追加のオペレーションしか行なえません。 -つまり LFS (Log Structured File System) のような振舞いです。 +このクラスは、 +データを追加する場合にも使われていますし、 +過去のデータを参照したい場合にも用いられますが、 +追加のオペレーションしか行なえません。 +つまりジャーナル型ファイルシステム +(Journalized-FS, LFS (Log Structured File System)( +ような振舞いです。 </para> - <para> -参照する際は最後に追加したデータが取り出されます。 +参照する際は、最後に追加したデータが取り出されます。 つまり、値は追加された値を last match で取り出しています。 <footnote> <para> @@ -137,11 +152,13 @@ DBMS </para> <para> -このクラスは、サイズを度外視して一定期間のあいだ記録しておきたいデータ -に対して使います。たとえば、登録時の confirmation のキャッシュや -message-id キャッシュです。これらは expire を時間で制御したいからです。 -このクラスは引数でファイル名を与えることになっているので、ファイル名に -日付つきのファイルを選ぶと良いでしょう。 +このクラスは、 +サイズを度外視して一定期間のあいだ記録しておきたいデータに対して使います。 +たとえば、 +登録時の confirmation や message-id のキャッシュです。 +これらは expire を時間で制御したいからです。 +このクラスは引数でファイル名を与えることになっているので、 +ファイル名に日付つきのファイルを選ぶと良いでしょう。 </para> @@ -157,16 +174,17 @@ key => [ 型のデータ取り出しをしたい場合があります。 この形のデータ取り出しは get_all_values_as_hash_ref() -メソッドを使えば可能です。 +メソッドを使うことで可能です。 </para> <warning> <para> なお検索時の挙動の first match と last match は切替えることができます。 -どちらの戦略で探すのか、クラスオブジェクトを生成する際に明示的に指定す -ることが推奨されます。デフォルトは last match です(最後に書き込んだデー -タが返される振舞いが自然です)。 +どちらの戦略で探すのか、 +クラスオブジェクトを生成する際に明示的に指定することが推奨されます。 +デフォルトは last match です +(最後に書き込んだデータが返される振舞いが自然です)。 </para> </warning> @@ -183,31 +201,33 @@ get_all_values_as_hash_ref() <ulink url="../../en/modules/File/CacheDir.txt"> FML::Cache::Ring </ulink> -クラスは、主にサイズに上限を設けたいタイプのデータを蓄える場合に用 -います。時間(expire)については気にしません。 +クラスは、 +主にサイズに上限を設けたいタイプのデータを蓄える場合に用います。 +時間(expire)については気にしません。 時間ではなくデータのサイズで有無を言わさずデータを廃棄します。 </para> - <para> デバッグ等に用いるデータであれば、こういった扱いで十分と考えます。 普段は使わないデバッグのために、 ハードディスクを使われてしまうのは嫌ですから。 </para> - <para> -このクラスは、あるディレクトリ(例: db/)中に作られた有限個のファイル群 -の中にデータを蓄えています。 -たとえば db/ ディレクトリに 1 〜 100 の名前のファイルがつくられ、 +このクラスは、 +あるディレクトリ(例: db/) +中に作られた有限個のファイル群の中にデータを蓄えています。 +たとえば db/ ディレクトリに 1 〜 100 の名前のファイルが作られ、 順番に使われてきます。 これらのファイルはぐるぐる回って(1 2 3 4 ...)使われ、 -一周してしまう(100 を超えると)と、元に戻って上書き(1 2 3 4 ...)されます。 +一周してしまう(100 を超えると)と、 +元に戻って上書き(1 2 3 4 ...)されます。 </para> <warning> <para> +ノート: 旧 RingBuffer は FML::Cache::Ring に統合されました。 また、FML::Cache::Ring は File::CacheDir から作られました。 </para> diff --git a/fml/doc/ja/tutorial/internals/dbms.sgml b/fml/doc/ja/tutorial/internals/dbms.sgml index 56e51986..9c80ef01 100644 --- a/fml/doc/ja/tutorial/internals/dbms.sgml +++ b/fml/doc/ja/tutorial/internals/dbms.sgml @@ -11,8 +11,7 @@ <para> メンバーリストなど永続性の必要なデータにたいし、 DBMS (データベース管理システム)を使い、 -理路整然と管理したい。 -当然の欲求です。 +理路整然と管理したいというのは当然の欲求です。 </para> <para> @@ -54,7 +53,8 @@ IO::Adapter </para> <para> -逆に言うと、それらの原始的な機能を組み合わせた複雑な操作は +逆に言うと、 +それらの原始的な機能を組み合わせた複雑な操作は IO::Adapter の前段階で処理する必要があります。 </para> diff --git a/fml/doc/ja/tutorial/internals/design.sgml b/fml/doc/ja/tutorial/internals/design.sgml index 52394624..39008f66 100644 --- a/fml/doc/ja/tutorial/internals/design.sgml +++ b/fml/doc/ja/tutorial/internals/design.sgml @@ -5,7 +5,7 @@ <chapter id="design"> <title> - 原案: &fml8; (仮名) のデザインコンセプト + [採録] 原案: &fml8; のデザインコンセプト </title> @@ -28,7 +28,7 @@ </para> <para> -&fml8; はβ版ですが、何年ものあいだ安定した試験運用を続けています。 +&fml8; は、何年ものあいだ安定した試験運用を続けています。 変数名もアーキテクチャアも、おおむね固まったと思います。 </para> @@ -41,17 +41,19 @@ <para> ものによっては &fml8; 用に作られたモジュールを &fml4; へ輸入/輸出しています。 -IPv6 はすでに輸出されました。 +IPv6 は、すでに輸出されました。 たとえば 4.0 でも独立性の高い mead (エラーメール解析プログラム)などは輸出可能な例でしょう。 </para> <para> -これらのマージおよび 4.0 自体のコードの保守をしつつ 4.0 および &fml8; は -並行開発されていく予定です。 +これらのマージおよび +4.0 自体のコードの保守をしつつ +4.0 および &fml8; は並行開発されていく予定です。 そのため 4.0 系は stable に近い current という位置付けになります。 -そして 4.0 の bug fix は 4.0.x (4.0.1 4.0.2 …)としてまとめられ -リリースれていく予定です。 +そして 4.0 の bug fix は +4.0.x (4.0.1 4.0.2 …)としてまとめられ、 +リリースされていく予定です。 逆に &fml8; は本当の開発用のコード( fml-current )ということになります。 </para> @@ -75,7 +77,7 @@ mead (エラーメール解析プログラム)などは輸出可能な例でしょう。 <listitem> <para> - すべて perl module 形式 (要 perl 5.00504 以降) + すべて perl モジュール形式 (要 perl 5.00504 以降) </para> </listitem> @@ -84,7 +86,7 @@ mead (エラーメール解析プログラム)などは輸出可能な例でしょう。 CUI (makefml) インターフェイスおよび CGI インターフェイス </para> <para> - これは従来通りのもの。 + これは従来どおりのもの。 ただしより統合化され、 よりメニューなどが書きやすいものであるように (実装者が楽できる設定ファイル形式がのぞましい et.al.) @@ -107,9 +109,9 @@ mead (エラーメール解析プログラム)などは輸出可能な例でしょう。 <listitem> <para> - CPAN モジュール使いまくり + できるだけ CPAN モジュールを使う (ただし、できるだけ直接使うより、 - 一層被せておくほうがよい) + 一層かぶせておくほうがよい) </para> </listitem> @@ -124,7 +126,7 @@ mead (エラーメール解析プログラム)などは輸出可能な例でしょう。 <listitem> <para> - 統一化されたメンバーリストなどへのアクセスをできるだけ抽象化する。 + 統一化されたメンバーリストなどへのアクセスをできるだけ抽象化する </para> <itemizedlist> @@ -240,10 +242,10 @@ mead (エラーメール解析プログラム)などは輸出可能な例でしょう。 <row> <entry> done. </entry> <entry> - 設定ファイルの形式は + 設定ファイルの形式は cf と config.ph を統合化したようなもので、 配列を表現できる形式とする。 - メニュープログラムが楽できるフォーマットにしたい。 + メニュープログラムが楽になるフォーマットにしたい。 原則として”設定ファイル”という名のものは どれも同じフォーマットとする。 </entry> @@ -261,9 +263,10 @@ mead (エラーメール解析プログラム)などは輸出可能な例でしょう。 また、NOT_USE などは禁止する( default_config に書くこと)。 attribute にあたるものが - 群れになってしまうのはしょうがない。しかし、 - 配列表現が可能なため、現在の ifdef の群れで表現する - ようなことが少なくなるはず。 + 群れになってしまうのはしょうがない。 + しかし、 + 配列表現が可能なため、 + 現在の ifdef の群れで表現するようなことが少なくなるはず。 </entry> </row> diff --git a/fml/doc/ja/tutorial/internals/directory.sgml b/fml/doc/ja/tutorial/internals/directory.sgml index 5c8ffff0..99b42420 100644 --- a/fml/doc/ja/tutorial/internals/directory.sgml +++ b/fml/doc/ja/tutorial/internals/directory.sgml @@ -15,42 +15,41 @@ </title> <para> -たとえば、HTML 化された記事は、 -次のような一段階の階層構造で置かれています。どうでしょう？ +デフォルトは一段階を前提にしています。 +たとえば、 +HTML 化された記事は、 +次のような一段階の階層構造になっています。 <screen> 200201/msg○○.html </screen> </para> <para> -デフォルトは一段階を前提にしています。 -</para> - -<para> 現代の PC の性能なら、 -ディレクトリ中に 1000 くらいのファイルがあっても +ディレクトリ中に 1000 個ファイルがあっても ほとんど瞬時に ls は返ってきますが、 -10000 ともなるとちょっと考えます。 +10000 ともなると少し考えます。 </para> <para> HTML 化されたファイルをおくサブディレクトリを 1000 ごとに用意すると、 -たとえば spool/sub/file みたいにすると spool/ 以下の記事が 10^6 ( million ) -くらいは、それなりのアクセス速度を保ちつつ格納できるはずです。 +たとえば spool/sub/file みたいにすると、 +spool/ 以下の記事が 10^6 ( million )くらいまでは、 +それなりのアクセス速度を保ちつつ格納できるはずです。 </para> <para> 一つのＭＬで 100 万通は、なかなかいきません。 この予想は、悪くはないでしょう。 もう一段階いくと 10^9 くらいいきますが、 -そこまで長くＭＬが続くことは少ない。 +そこまで長くＭＬが続くことは少ないと考えます。 </para> <para> なお直接には関係ない議論ですが、 -Maildir/ でも 100 万くらいで少しつらい。 -二段階くらいにはしないといけない。 -メールを 10,000 通ためる人が 100 人いるだけでもうだめ。 +Maildir/ でも 100 万くらいで少しつらいようです。 +メールを 10,000 通ためる人が 100 人いるだけでもうダメだということになります。 +100万のオーダになると、二段階くらいにはしないといけません。 </para> </sect1> @@ -67,16 +66,16 @@ Maildir/ でも 100 万くらいで少しつらい。 <question> <para> -ディレクトリ名はどこに定義されていますか？ +ディレクトリ名は、どこに定義されていますか？ </para> </question> <answer> <para> /usr/local/etc/fml/defaults/$VERSION/default_config.cf -にデフォルトの定義が書かれています。 +にデフォルト値が定義されています。 各ＭＬの config.cf で上書きも出来ます。 -動作時に使っている値は fmlconf で表示させるとよいでしょう。 +動作時に使っている値は fmlconf で表示させて確認してください。 <screen> % fmlconf ＭＬ名 | grep _dir diff --git a/fml/doc/ja/tutorial/internals/errormail.sgml b/fml/doc/ja/tutorial/internals/errormail.sgml index acc98f60..5027000d 100644 --- a/fml/doc/ja/tutorial/internals/errormail.sgml +++ b/fml/doc/ja/tutorial/internals/errormail.sgml @@ -9,21 +9,30 @@ </title> <para> -/usr/local/libexec/fml/error は &fml4; の +/usr/local/libexec/fml/error +は +&fml4; +の mead (libexec/mead) に相当するエラー解析プログラムです。 </para> <para> $use_error_mail_analyzer_function を yes にすると、 エラー解析機能が有効になります。 -ちなみに、デフォルトで $use_error_mail_analyzer_function は yes +ちなみに、 +デフォルトで +$use_error_mail_analyzer_function は yes +です。 つまりエラー解析機能は有効になっています。 このあたりは &fml4; と異なります。 </para> <para> つまるところ、 -&fml8; では &fml4; でよく使う機能は初めから有効になっています。 +&fml8; +では +&fml4; +でよく使う機能は初めから有効になっています。 </para> @@ -33,8 +42,10 @@ $use_error_mail_analyzer_function を yes にすると、 </title> <para> -ＭＬ作成時に $ml-admin アドレス宛のメールは -/usr/local/libexec/fml/error を呼び出すように設定されます。 +ＭＬ作成時に +$ml-admin アドレス宛のメールは +/usr/local/libexec/fml/error +を呼び出すように設定されます。 </para> <para> @@ -46,24 +57,32 @@ $use_error_mail_analyzer_function を yes にすると、 </para> <para> -Mail::Bounce は、エラーメールについて「どの MTA が生成したものか？」 -「エラーを引き起こしたメールアドレス」「エラーの理由」を分析します。 +Mail::Bounce は、エラーメールについて +「どの MTA が生成したものか？」 +「エラーを引き起こしたメールアドレス」 +「エラーの理由」 +を分析します。 </para> <para> -解析結果は $error_mail_analyzer_cache_dir ディレクトリに格納されます。 +解析結果は +$error_mail_analyzer_cache_dir +ディレクトリに格納されます。 </para> <para> 一定時間以上経過すると、 -$error_mail_analyzer_function がキャッシュのデータを解析し、 +$error_mail_analyzer_function +がキャッシュのデータを解析し、 あるメールアドレスが存在しないように思えるか否か？を判定します。 その結果、消すべきだと判断されると、削除されます。 </para> <para> -「一定時間」と「消すべきか？という判断」 -の二つが主なチューニングパラメータになります。 +「一定時間」 +と +「消すべきか？という判断」 +この二つが主なチューニングパラメータになります。 </para> </sect1> @@ -78,7 +97,10 @@ $error_mail_analyzer_function がキャッシュのデータを解析し、 $error_mail_analyzer_function_select_list にある関数名が利用し得るアルゴリズムです。 デフォルトでは -simple_count と histgram という２つのアルゴリズムが用意されており、 +simple_count +と +histgram +という２つのアルゴリズムが用意されており、 histgram がデフォルトです。 </para> @@ -93,9 +115,12 @@ histgram がデフォルトです。 </para> <para> -単純にエラー数なので、”たまたま”受信者が設定を少しの間だけ間違えていて、 +単純にエラー数なので、 +”たまたま”受信者が設定を少しの間だけ間違えていて、 ”たまたま”その日の流量が多い場合、 -その受信者は「削除対象」とみなされることになります。 +その受信者は +「削除対象」 +とみなされることになります。 </para> <para> @@ -111,7 +136,7 @@ histgram がデフォルトです。 </title> <para> -エラーが連続してＮ日続いた時に限り削除を行ないます。 +エラーが連続してＮ日続いた時にかぎり削除を行ないます。 デフォルトでは 14 日(つまり二週)のあいだ連続してエラーの場合に、 はじめてアドレスの削除が行なわれます。 </para> @@ -146,20 +171,20 @@ histgram がデフォルトです。 <para> 各エラーメール(らしきもの)の解析結果は -$error_mail_analyzer_cache_dir ディレクトリに格納されます。 +$error_mail_analyzer_cache_dir +ディレクトリに格納されます。 </para> <para> -現在、キャッシュの入出力には Tie::JournaledDir クラスを使っていますが、 -正確には FML::Error::Cache 経由で Tie::JournaledDir -への IO を行なっています。 -</para> - -<para> -FML::Error::Cache が Tie::JournaledDir の直前に位置し、 -アダプタ層となっています。 +現在、キャッシュの入出力には +Tie::JournaledDir +クラスを使っています。 +正確には +FML::Error::Cache というアダプタ層が Tie::JournaledDir の直前に位置し、 +FML::Error::Cache 経由で Tie::JournaledDir への IO を行ないます。 すべての IO は、FML::Error::Cache が提供する -primitive なメソッドを通じてのみ行なわなければなりません。 +primitive +なメソッドを通じてのみ行なわなければなりません。 </para> </sect1> @@ -191,8 +216,10 @@ mime/multipart がＭＬの管理者へ送信されます。 --> <para> -そのうち、ヘッダ情報 + そのエラーメールのアドレスの分析レポートとか -なんか付けてやれや〜とかちょっと思っています。 +そのうち、 +「ヘッダ情報 + そのエラーメールのアドレスの分析レポート」 +など、もう少し付加的な情報もつけるべきでしょうか +(と考えつつ、未実装のままです)？ </para> <para> diff --git a/fml/doc/ja/tutorial/internals/filename.sgml b/fml/doc/ja/tutorial/internals/filename.sgml index 0bbd4d6a..35aa6420 100644 --- a/fml/doc/ja/tutorial/internals/filename.sgml +++ b/fml/doc/ja/tutorial/internals/filename.sgml @@ -22,7 +22,7 @@ </title> <para> -基本系は +基本形は <screen> ファイル名-役割 </screen> @@ -35,7 +35,7 @@ members-役割 </para> <para> -さらに配送リスト以外でも同じルールを適用します。 +さらに配送リスト以外にも同じルールを適用します。 たとえば <screen> passwd-admin @@ -45,19 +45,19 @@ passwd-cgiadmin といったぐあいです。 </para> - <para> 将来も同様に、新たな『役割』を新設するごとに <screen> members-役割 -recipient-役割 +recipients-役割 </screen> を作ることにします。 -でも、たいてい recipient-* はダミーに過ぎないないことが多いでしょう:) +でも、たいてい recipients-* はダミーに過ぎないないことが多いでしょう:) </para> <para> -一応、使い分けるつもりですが、実際、 +一応、使い分けているつもりですが、 +実際、 どういう場合に役立つのかはよくわからないです。 悩んだときは、理論的に美しい方を採用することにしています。 </para> @@ -74,16 +74,17 @@ recipient-役割 <screen> primary_recipient_maps = recipients -# 互換性のため actives をいれておく +# 互換性のため actives をいれてあります recipient_maps = recipients actives </screen> </para> +<!-- <para> -[TODO] warning 出るところがあるので、なんとかせな +[TODO] warning 出るところがあるので、なんとかせな、あきません </para> - +--> </sect1> @@ -139,7 +140,9 @@ etc/passwd-admin <para> パスワード認証以外の場合もあり得るので、 -ちゃんと「ファイル名-役割」としたかったというわけです。 +きちんと +「ファイル名-役割」 +名にしました。 </para> </warning> diff --git a/fml/doc/ja/tutorial/internals/filter.sgml b/fml/doc/ja/tutorial/internals/filter.sgml index f91a8c58..b4dc4e2f 100644 --- a/fml/doc/ja/tutorial/internals/filter.sgml +++ b/fml/doc/ja/tutorial/internals/filter.sgml @@ -18,7 +18,7 @@ <para> 本章でいうフィルタとは、 -特にこだわらない限り「投稿された記事に対するフィルタ」を指します。 +特にこだわらない限り「投稿された記事に対するフィルタ」を指しています。 </para> <para> @@ -27,14 +27,20 @@ FML::Filter クラスに実装されています。 </para> <para> -もちろん「記事」ではなく -「コマンドメール」を対象としたフィルタシステムなども考えられます。 +もちろん +「記事」 +ではなく +「コマンドメール」 +を対象としたフィルタシステムなども考えられます。 この場合、その特殊なフィルタシステムが -FML::Filter のサブクラスにあるとはかぎりませんので注意して下さい。 -コマンドメールが対象であれば、 +FML::Filter +のサブクラスにあるとは限りませんので注意して下さい。 +現在、 +コマンドメールを対象としたフィルタは、 コマンド処理のクラス中に実装されたフィルタシステムを呼び出しています。 たとえばコマンドメールのコマンドの長さを制限する機能(フィルタ)は -FML::Command::Filter クラスが担当しています。 +FML::Command::Filter +クラスが担当しています。 </para> </caution> @@ -46,14 +52,17 @@ FML::Command::Filter クラスが担当しています。 </title> <para> -コンテンツを検査するフィルタには大きく分けて三種類あります。それは、 +コンテンツを検査するフィルタには大きく分けて三種類あります。 +それは、 「ヘッダに対するフィルタ」 「メール本文に対するフィルタ」 「MIME 構造を元にしたフィルタ(mime component filter)」の３つです。 </para> <para> -もっとも「メール本文に対するフィルタ」にも、 +もっとも +「メール本文に対するフィルタ」 +にも、 「 MIME でないメールに対するフィルタ」 と 「text/plain に対するフィルタ」 @@ -69,27 +78,29 @@ FML::Command::Filter クラスが担当しています。 permit / reject (fml 4.0 の content filter の !MIME) mime component filter - (fml 4.0 でいうところ content filter 相当) + (fml 4.0 の content filter 相当) text/plain filter - ja, en, ... (言語依存フィルタ) - 非言語依存パート (M$ GUID scanner のたぐい) - 先頭部分の text/plain パートに対するフィルタ - (シンタックスチェック) + ja, en, ... (言語依存フィルタ) + 非言語依存パート (M$ GUID scanner のたぐい) + 先頭部分の text/plain パートに対するシンタックスチェック 外部フィルタ (ウィルス/SPAM チェッカを呼び出す) clamav spamassassin bogofilter </screen> -本当はこれ以外に、SMTP もしくは LMTP を使って、外部の virus scanner な -りに飛ばす迂回路(postfix の content_filter 相当)が必要だと思うのですが、 +本当は、 +これ以外に、SMTP もしくは LMTP を使い、 +外部の virus scanner なりを呼び出す迂回路 +(postfix の content_filter 相当)が必要だと思うのですが、 (それは Postfix でやればいいとおもいますので)実装していません。 </para> <!-- XXX-TODO トラフィックベースのフィルタ --> <para> -また、これら以外にトラフィックベースのフィルタがあります +また、 +これら以外にトラフィックベースのフィルタがあります (ほとんど未実装なので解説は省略 _o_)。 </para> @@ -109,7 +120,7 @@ FML::Command::Filter クラスが担当しています。 </para> <para> -変数名体系の基本は以下の通りです。 +変数名の命名規則体系の基本は以下のとおりです。 <screen> use_サービス_filter = yes か no サービス_filter_functions = 機能A 機能B @@ -131,7 +142,7 @@ use_機能A = yes か no <para> ヘッダ部分およびメール本文の部分のサイズに制限がかけられます。 -また、変数は記事とコマンドメールについてそれぞれ別に存在します。 +また、変数は記事とコマンドメールそれぞれに存在します。 必要なフィルタのみを有効にするとか、 ○○の場合だけサイズ制限の機能を切るといった使い方も可能です( もっとも、あまり複雑な条件下でのみフィルタといったことをしようとすると @@ -139,7 +150,9 @@ HOOK による対応になるとおもいますが…)。 </para> <para> -余談: Mail::Message クラスがメールを解析したさいに、 +余談: +Mail::Message クラスが最初にメールを解析して数珠つなぎ構造を作ります。 +この際に、 メールの各部分のサイズも分析済みなので、このフィルタの実装は簡単です:) </para> @@ -158,8 +171,9 @@ HOOK による対応になるとおもいますが…)。 「一通当たりのコマンド数」 や、 コマンド依存の制限、 -たとえば「一回のコマンドメールで get できるファイルは 100 個までとする」 -がありえます。 +たとえば +「一回のコマンドメールで get できるファイルは 100 個までとする」 +といった制限をかけたい需要があります。 </para> <!-- &table.list.filter.commandmail; --> @@ -186,7 +200,7 @@ text/html reject <para> MIME が前提なので、!MIME (MIME 以外を対象とする)という命令はありませんが、 text/plain と multipart/mixed 中の text/plain を区別するために、 -こういう書き方である必要があるとおもうわけです。 +このような書き方をする必要があります。 <screen> 全体 部分 アクション ---------------------------------------------- @@ -213,9 +227,9 @@ text/plain :size>500k cutoff </title> <para> -アクションには first match のものとそうでないものがあります。reject は -たいてい first match ですが、 -cutoff は first match ではないとおもわれます。 +アクションには first match のものとそうでないものがあります。 +reject は、たいてい first match ですが、 +cutoff は first match では"ない"と思われます。 さて？ </para> @@ -228,8 +242,9 @@ cutoff は first match ではないとおもわれます。 </title> <para> -では、permit はどうでしょう？実のところ文脈依存と考えられますが、 -何が正しいのかよくわかりません。 +では、permit はどうでしょう？ +実のところ文脈依存と考えられますが、 +何が正しいのか少し曖昧です。 たとえば、multipart のメールの中身が <screen> text/plain + image/jpeg + text/html @@ -239,14 +254,19 @@ text/plain + image/jpeg + text/html </para> <para> -結論をいえば、cutoff や reject を指定するタイプのルールしかうまく機能 -しない、つまり「特定の○○を削除ないしは拒否する」ことならうまくできる -と言えそうです。ゆえにデフォルトは permit にするしかありません。 +結論をいえば、 +cutoff や reject を指定するタイプのルールしかうまく機能しません、 +つまり「特定の○○を削除ないしは拒否する」フィルタは、 +うまく動作します。 +ゆえにデフォルトは permit にするしかありません。 </para> <para> -『permit は「個別に許す」という意味である』説と、『permit は「メール全 -体を許す」という意味である』説の両方がありえます。たとえば、 +「permit は『個別に許す』という意味である」 +説と、 +「permit は『メール全体を許す】という意味である」 +説の両方がありえます。 +たとえば、 <screen> text/plain * permit * * reject @@ -256,7 +276,8 @@ text/plain * permit </para> <para> -一方で『permit は「メール全体を許す」という意味である』説がありえます。 +一方、 +「permit は『メール全体を許す』という意味である」説もありえます。 たとえば text/plain のメールだけを許したいとしましょう。 直観的には、次のようなルールを書くとおもいます。 <screen> @@ -267,9 +288,11 @@ text/plain * permit <screen> * * reject </screen> -と一緒になってしまうわけです。だから permit は「メール全体を OK として -ルールとの照らし合わせ処理をそこで終りにする」という意味にとらないとい -けません。よって、次のようなルールはありえないことになります。 +と一緒になってしまうわけです。 +よって permit は +「メール全体を OK としてルールとの照らし合わせ処理をそこで終りにする」 +という意味に解釈しないとうまく動作しません。 +よって、次のようなルールはありえないことになります。 <screen> text/plain * permit multipart/mixed text/plain permit @@ -284,9 +307,12 @@ multipart/mixed text/html reject multipart/mixed image/* cutoff * * permit </screen> -つまり permit 命令で処理が終ってしまうとすれば、multipart に対しては事 -実上使ってはいけないことになる。『デフォルトの処理』か『text/plain * 』 -のようなものに対してのみ permit 命令は意味があるわけです。 +つまり permit 命令で処理が終わるとすれば、 +multipart に対しては事実上使ってはいけないことになります。 +「デフォルトの処理」 +か +「text/plain * 」 +のようなルールに対してのみ permit 命令は意味があるわけです。 </para> <para> @@ -302,18 +328,19 @@ multipart/mixed image/* cutoff </title> <para> -暗黙のデフォルトルールは、他の header や text フィルタとの整合性を考え -ると「とりあえず通す」ですかね？ +暗黙のデフォルトルールは、 +他の header や text フィルタとの整合性を考えると「とりあえず通す」でしょうか？ <screen> * * permit </screen> -これは content filter の「ルールをうまく書けない」という別の理由によっ -ても支持されるでしょう。 +これは content filter の +「ルールをうまく書けない」という別の理由によっても支持されるでしょう。 </para> <para> -なお、デフォルトの挙動を reject に変更するには * * reject を最後に付け -加えてください。 +なお、 +デフォルトの挙動を reject に変更するには +* * reject を最後に付け加えてください。 </para> </sect2> @@ -321,7 +348,7 @@ multipart/mixed image/* cutoff <sect2> <title> - ケーススタディ: text/plain (全体)のみをゆるす + ケーススタディ: text/plain (全体)のみを許可 </title> <para> @@ -340,7 +367,7 @@ text/plain * permit </title> <para> -text/plain があれば何でも許す。それ以外の型は拒否する。 +「text/plain があれば何でも許し、それ以外の型は拒否する」 これは簡単なルールが書けない例です。 <screen> text/plain * permit @@ -355,7 +382,8 @@ text/plain + text/plain + text/plain <screen> text/plain + text/plain + image/jpeg </screen> -でもどっちも OK になってしまうのね。だめじゃん。 +でもどっちも OK になってしまいます。 +だめですね。 もっとも not オペレータ(!)があれば、解決は可能でしょう。 <screen> text/plain * permit @@ -363,7 +391,7 @@ multipart/* !text/plain reject multipart/* text/plain permit * * reject </screen> -たぶん、これが期待される plain/text のみを通すルールだとおもいます。 +たぶん、これが期待される plain/text のみを通すルールだと思います。 </para> </sect2> @@ -399,11 +427,13 @@ multipart/* text/plain permit multipart/* * reject * * reject </screen> -multipart の中身が text/plain からのみなるメールなら許す。つまり、 +「multipart の中身が text/plain からのみなるメールなら許す」 +つまり、 <screen> text/plain + text/plain + text/plain </screen> -は、OK。でも、 +は許可します。 +しかしながら <screen> text/plain + text/plain + image/jpeg text/plain + image/jpeg + text/html @@ -421,7 +451,7 @@ text/plain + image/jpeg + text/html </title> <para> -前例のバリエーションで reject ではなく cutoff の場合。 +reject の代わりに cutoff を使う前例のバリエーションです。 <screen> text/plain * permit multipart/* image/* cutoff @@ -432,16 +462,17 @@ multipart/* text/plain permit <screen> text/plain + text/plain + text/plain </screen> -は、OK。一方、 +は OK です。 +一方、 <screen> text/plain + text/plain + image/jpeg </screen> -のメールは image/jpeg 部分を削って、3番めのルールで permit される。 -もっとも、これだけだと +のメールは image/jpeg 部分を削りますが、3番めのルールで permit されます。 +もっとも、これだけなら <screen> text/plain + image/jpeg + text/html </screen> -が通過可能ですが… +も通過可能ですか… </para> </sect2> @@ -484,19 +515,20 @@ text/plain + text/plain + text/html </para> <para> -結論を先に書くと、いまの機能でいいようで、content filter の起源となっ -た cutoff の機能はもう不要みたいです。 +結論を先に書くと、 +いまの機能でいいようで、 +content filter の起源となった cutoff の機能はもう不要みたいです。 </para> <para> まずは content filter の使い方をいくつか考えてみます。 <screen> (1) text/plain と multipart の text/plain だけは通す - text/plain じゃないメールなんて○○ ML では不要 - だいたい virus つきかもしれないじゃん + ○○ ML では text/plain 以外のメールは不要という場合 + (添付ファイルなんてウィルスかもしれないじゃないか！) -(2) multipart で text/plain 以外があるようなメールは拒否 - virus つきかもしれないじゃん +(2) multipart で text/plain 以外があるようなメールは拒否する + (添付ファイルなんてウィルスかもしれないじゃないか！) (3) multipart の text/html 部分を削る いわゆる html メール @@ -507,11 +539,13 @@ text/plain + text/plain + text/html (5) text/html のメールなんて spam に決まってるから捨てる </screen> -で、アンケートの結果をまとめると、通常は (1) を使う。これは決まりみた -いです。規模とポリシー(きびしくできるか否かなど)によって(2)もアリかも -しれない。 +アンケートの結果をまとめると、 +通常は (1) のケースが多いということでしょう。 +これが定番のようです。 +規模とポリシー(きびしくできるか否かなど)によっては、 +(2)もアリかもしれません。 たとえば社内ＭＬのようにメールの型を厳しくできないＭＬは、 -そもそも mime component filter を on にしないというわけです。 +そもそも mime component filter を on にできないと思います。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/hook.sgml b/fml/doc/ja/tutorial/internals/hook.sgml index b79432bf..113f0a61 100644 --- a/fml/doc/ja/tutorial/internals/hook.sgml +++ b/fml/doc/ja/tutorial/internals/hook.sgml @@ -9,7 +9,8 @@ </title> <para> -HOOK とは、&fml8; の内部にあらかじめ用意されている +HOOK とは、 +&fml8; の内部にあらかじめ用意されている 「小さな perl のプログラムを実行する」 機能です(専門用語でいえば HOOK を eval() するということです)。 </para> @@ -21,8 +22,8 @@ HOOK は要所要所に用意されています。 <para> もちろん、HOOK は、そのコンテキストの中で実行されます。 その意味で本質的に危険な機能です。 -ある程度、&fml8; の中身について理解していないと -HOOK を書くことはできません。 +また、 +ある程度 &fml8; の中身について理解していないと HOOK を書くことはできません。 </para> <para> @@ -42,22 +43,27 @@ HOOK をうまく使うことで、 </title> <para> -HOOK は微妙な修正、もしくは複雑なカスタマイズのために是非必要な機能ですが、 +HOOK は微妙な修正、 +もしくは複雑なカスタマイズのために是非必要な機能ですが、 実装においては、いくつかの問題があります。 </para> <para> -まず、&fml4; の $START_HOOK のような曖昧なものでは、 -プログラムごとに異なる動作をさせることが難しい。 +まず、 +&fml4; の $START_HOOK のような曖昧な名称では、 +プログラムごとに異なる動作をさせることが難しいです。 たとえば $START_HOOK を設定すると、 配送システムとコマンドメールシステムで同じ $START_HOOK を実行します。 -それが便利な場合もあるのですが、プログラムの役割ごとに異なる動作をさせ -ようとすると面倒で分かりにくい設定になります。 +それが便利な場合もあるのですが、 +プログラムの役割ごとに異なる動作をさせようとすると、 +面倒で分かりにくい設定になります +(HOOK 内に if else ... が必要になります)。 </para> <para> そのため HOOK の名前に一定の基準が必要でしょう。 -&fml8; では、ある関数の最初と最後に HOOK を用意する場合、 +&fml8; では、 +ある関数の最初と最後に HOOK を用意する場合、 次のようなスタイルの HOOK 名称としています。 <screen> $役割_関数_start_hook @@ -66,10 +72,12 @@ $役割_関数_end_hook </para> <para> -これにより配送システムとコマンドメールシステムで共通の HOOK などという -ものはなくなり、別々の HOOK をしかけることができるようになります。逆に、 -共通のものをしかけようとするなら、一杯書いて下さい;)ということです。まぁ -コピーすればいいだけだから、さして難しくないですよね？(と思いたい) +これにより、 +配送システムとコマンドメールシステムで共通の HOOK などというものはなくなり、 +別々の HOOK をしかけることができるようになります。 +逆に、 +共通のものをしかけようとするなら、一杯書いて下さい;)ということです。 +まぁコピーすればいいだけなので難しくないですよね？(と思いたい) <screen> $distribute_XXX_start_hook = q{ ... }; $YYY_XXX_start_hook = $distribute_XXX_start_hook; @@ -77,15 +85,16 @@ $YYY_XXX_start_hook = $distribute_XXX_start_hook; </para> <para> -また、HOOK の書き方が少々良くなくても動かないと困るでしょう。 +また、HOOK の書き方が少々よくなくても動かないと困るでしょう。 というのは「少しだけ修整する」というケースでは、 Perl の素人さんが行なうことも多いからです。 </para> <para> -現場では、欲しい機能を実現したい場合、美しいコードを書くことよりも、少 -しでも早く実現することが求められます。そこは「美しさ」にこだわるべきで -はない点と考えます。 +現場では、 +欲しい機能を実現したい場合、 +美しいコードを書くことよりも、少しでも早く実現することが求められます。 +そこは「美しさ」にこだわるべきではない点と考えます。 </para> <para> @@ -104,11 +113,12 @@ HOOK の内容 </para> <para> -&fml4; と &fml8; の大きな違いのひとつは変数・関数のスコープです。 +&fml4; と &fml8; の大きな違いの一つは変数・関数のスコープです。 注意して下さい。 &fml4; の関数は全てグローバル関数なので、どんな関数でも使えますが、 &fml8; では、そうはいきません。 -とはいえ、まったく手がかりがないのも困るので、HOOK が利用できる環境では +とはいえ、まったく手がかりがないのも困るので、 +HOOK が利用できる環境では $curproc オブジェクトだけは常にアクセス可能であることを保証しています。 </para> @@ -126,13 +136,15 @@ $curproc オブジェクトのアクセスメソッドだけを使って書くようにして下さい。 </title> <para> -HOOK 名前の標準的な形式については +HOOK の名前の標準形式は <screen> 役割名_メソッド名_start_hook 役割名_メソッド名_end_hook </screen> -などとすることにしました。ここで役割名は「use_XXX_function」(例: -use_article_post_function)の XXX 部分です。 +です。 +ここで役割名は +「use_XXX_function」(例: use_article_post_function)の +XXX 部分です。 もっと粒度の細かい HOOK については、この形式でないものもあります。 </para> @@ -142,7 +154,7 @@ use_article_post_function)の XXX 部分です。 fmlconf_run_start_hook fmlconf_run_end_hook </screen> -となり、run() の中での hook 呼び出しは次のようなコードになります。 +となり、run() の中での hook 呼び出しは次のようなコードになっています。 <screen> sub run { diff --git a/fml/doc/ja/tutorial/internals/io_abstraction.sgml b/fml/doc/ja/tutorial/internals/io_abstraction.sgml index f5d96870..6f2c1873 100644 --- a/fml/doc/ja/tutorial/internals/io_abstraction.sgml +++ b/fml/doc/ja/tutorial/internals/io_abstraction.sgml @@ -9,8 +9,9 @@ </title> <para> -将来の移植性/拡張性を見据えるなら、ＭＬサーバの設計においても -UNIX における Vnode/VFS interface (vnode(9)参照) +将来の移植性/拡張性を見すえるなら、 +ＭＬサーバの設計においても +Unix における Vnode/VFS interface (vnode(9)参照) のような構造をあらかじめ導入しておくべきでしょう。 </para> @@ -36,14 +37,17 @@ vop_getattr() </para> <para> -つまり struct vnode の **v_op (vnode operation vector) にあたるものが +つまり +struct vnode の **v_op (vnode operation vector) にあたるものが、 IO に使われるクラスの各メソッドです。 </para> <para> -&fml8; では IO::Adapter クラスという抽象化されたインターフェイスを使います。 -このクラスはユーザリストというオブジェクトに対する -IO インターフェイスを抽象化したものです。 +&fml8; では +IO::Adapter クラスという抽象化されたインターフェイスを使います。 +このクラスは、 +たいていはメールアドレスの一覧という行指向のリスト型データに対する +IO を抽象化したものです。 </para> @@ -57,7 +61,9 @@ IO インターフェイスを抽象化したものです。 <link linkend="module.io.adapter"> IO::Adapter </link> -といえるでしょう。実装もすでに完成形であり、primitive なメソッドは何か？ +といえるでしょう。 +実装もすでに完成形であり、 +primitive なメソッドは何か？ などについても十分考えぬかれています。 </para> @@ -151,7 +157,7 @@ $obj = new IO::Adapter マップ, パラメータ(ハッシュリファレンス); my $config = $curproc->config(); my $obj = new IO::Adapter $map, $config; </screen> -HOOK なので利用する際にも、つねに、この形で書いておくべきです。 +HOOK で利用する際にも、つねに、この形で書いておくべきです。 </para> </sect2> @@ -196,14 +202,15 @@ KEY および KEY に付随するデータをオブジェクトに書き込みます。 </para> <para> -UNIX と異なり、オブジェクトの構造に一定の型があります。 +Unix とは異なり、 +オブジェクトの構造に一定の型があります。 型とは RDBMS のようなテーブルの形です。 </para> <para> また、プライマリキーとなるのは通常メールアドレスです。 -この前提が多くの場面で正しいため、メールアドレスをプライマリキーにした -テーブル型が基本的なデータ構造といえます。 +この前提が多くの場面で正しいため、 +メールアドレスをプライマリキーにしたテーブル型が基本的なデータ構造といえます。 </para> </sect2> @@ -258,7 +265,8 @@ while ($obj->get_next_key()) { ... } <para> これはハッシュの FIRST_KEY() と NEXT_KEY() にあたるといえます。 -しかしながら、我々の場合は open() などのメソッドが別途用意されているため、 +しかしながら、 +我々の場合は open() などのメソッドが別途用意されているため、 FIRST_KEY() と NEXT_KEY() のように２つに分ける必要はありません。 </para> @@ -283,8 +291,8 @@ XXX すなおに、key() もしくは get_key() でも良い気がする？ </title> <para> -うーん、どういうデータ構造が欲しいんでしょうねぇ？ -PRIMARY KEY の一覧くらいか？ +どういうデータ構造が欲しいのでしょうか？ +PRIMARY KEY の一覧でしょうか？ </para> </sect2> @@ -298,15 +306,17 @@ PRIMARY KEY の一覧くらいか？ <para> 定石は全部読んでみること、つまり get_next_key() を呼びまくるコードです。 専用のメソッドがあった方が便利でしょうけど、 -めったにそんなコードは書かないので、 +そのようなコードは、まず書かれないので、 専用メソッドがなくても問題はないと考えます。 </para> <para> -もし、あるとしたら get_primary_keys() みたいな名前のメソッド？で、 -ARRAY_REF で返すのでしょうかね？でも、find('*', { all => 1 }) などとす -ると全部の KEY の値がARRAY_REF で返りますんで、 -別のメソッドも不要な気がします。 +もし、 +あるとしたら get_primary_keys() みたいな名前のメソッド？があり、 +ARRAY_REF で返すでしょうか？ +でも、 +find('*', { all => 1 }) を実行すれば、 +すべての KEY の値がARRAY_REF で返りますので専用メソッドは不要でしょう。 <screen> (KEY1 KEY2) </screen> @@ -321,7 +331,7 @@ ARRAY_REF で返すのでしょうかね？でも、find('*', { all => 1 }) などとす </title> <para> -これこそ、どういうデータ構造が欲しい場合なんでしょうか？ +これこそ、どういうデータ構造が欲しい場合でしょうか？ 返り値が HASH_REF とは、次のような構造が返り値になる場合です。 <screen> 返り値 = { @@ -347,7 +357,7 @@ ARRAY_REF で返すのでしょうかね？でも、find('*', { all => 1 }) などとす </para> <para> -結局、実装する必要がないというのが現状。 +結局、実装する必要がないというのが現状だと考えます。 </para> </sect2> diff --git a/fml/doc/ja/tutorial/internals/lock.sgml b/fml/doc/ja/tutorial/internals/lock.sgml index 95b7b811..9ee5d56e 100644 --- a/fml/doc/ja/tutorial/internals/lock.sgml +++ b/fml/doc/ja/tutorial/internals/lock.sgml @@ -9,7 +9,7 @@ </title> <para> -プロセス間の同期化はロックを用いて行ないます。 +プロセス間の同期化は(Unixカーネルの提供する)ロック機構を用いて行ないます。 &fml8; でサポートされているロックメカニズムは flock(2) もしくは lockf(2) を元にしたロック機構のみです。 </para> @@ -35,8 +35,9 @@ flock(2) もしくは lockf(2) を元にしたロック機構のみです。 <para> Mail::Delivery::SMTP の操作の際にはメンバーリストのロックが必要です。 -現在は、Mail::Delivery::SMTP を呼び出す FML のクラス(実は FML::Send と -FML::Process::Delivery の２箇所しかない)の中でロック処理をしています。 +現在は、Mail::Delivery::SMTP を呼び出す FML のクラス +(実は FML::Send と FML::Process::Delivery の２箇所しかない) +の中でロック処理をしています。 </para> <para> @@ -45,9 +46,9 @@ FML::Process::Delivery の２箇所しかない)の中でロック処理をしています。 </para> <para> -そして、reader writer lock まで大げさでなくとも -一般に map を使うモジュールにはロックが必要です。 -write 用の lock が必要とは限りません。 +そして、reader writer lock まで大げさでなくとも、 +一般に map へアクセスする際にはロックが必要です。 +そして write 用の lock が必要とは限りません。 たとえば FML/Command/UserControl.pm や @@ -59,8 +60,10 @@ FML/Credential.pm <para> しかしながら、いまのところ reader writer lock は実装されていませんので、 -リソースごとの細かいロック制御で critical region -の時間を短くするようになっています。 +リソースごとの細かいロック制御で +critical region の時間を短くするようにしています +(メーリングリストドライバで、 +RWlock が必要なほど並列度の高い読み込み要求は来ない気がします)。 </para> </sect1> @@ -72,20 +75,23 @@ FML/Credential.pm </title> <para> -*_maps をよぶ前には MUTEX でロックをする。いや、やりすぎかもしれません。 +*_maps をよぶ前には MUTEX でロックをするべき…です？ +いや、やりすぎかもしれません。 </para> <para> -メンバーリストへ IO::Adapter をかます時に、 -READER WRITER LOCK がほしい。 +IO::Adapter 経由でメンバーリストを読む際には +READER WRITER LOCK が欲しい気がしますが、 +それが必要なほど並列度の高い読み込み要求は来ない気がします。 <footnote> <para> -READ ロックは不要か？いや、だめだろ -chaddr の途中で sleep したら敗けやから;) +READ ロックは不要でしょうかか？ +いや、違うでしょう。 +chaddr の途中で sleep したら負けですから;) </para> </footnote> -perl thread をつかえばできるけど、 -汎用的な実装はかなりむつかしいぽい;) +Perl thread をつかえばできるけど、 +汎用的な実装はかなり難しいみたいです;) </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/main.cf.sgml b/fml/doc/ja/tutorial/internals/main.cf.sgml index 2a1cf6d0..4540d384 100644 --- a/fml/doc/ja/tutorial/internals/main.cf.sgml +++ b/fml/doc/ja/tutorial/internals/main.cf.sgml @@ -9,14 +9,12 @@ </title> <para> -main.cf はディレクトリやプロセスのユーザの指定など -最も基本的な情報のみが書かれているファイルです。 -</para> - -<para> /usr/local/etc/fml/main.cf は各ＭＬの設定ではありません。 -fml のバージョンなどメタレベルの依存性を解決するための設定ファイルで、 -fml のプログラム群が起動する際に”つねに”参照しています。 +main.cf は、 +ディレクトリやプロセスのユーザ、 +使用する &fml8; バージョンの指定など、 +メタレベルの基本情報を指定する設定ファイルで、 +fml のプログラム群が起動する際に参照します。 </para> <para> diff --git a/fml/doc/ja/tutorial/internals/merge.sgml b/fml/doc/ja/tutorial/internals/merge.sgml index 9e08b0c1..94d38ed4 100644 --- a/fml/doc/ja/tutorial/internals/merge.sgml +++ b/fml/doc/ja/tutorial/internals/merge.sgml @@ -24,16 +24,20 @@ </para> <para> -1) &fml8; をインストールする。この際、postfix の alias_maps に -/var/spool/ml/etc/mail/aliases (まだ、この段階では中身のないファイルで -よい)を追加する。 +1) &fml8; をインストールする。 +この際、postfix の alias_maps に +/var/spool/ml/etc/mail/aliases +(まだ、この段階では中身のないファイルでよい) +を追加する。 </para> <para> -2) makefml --force newml elena 相当の処理を行なう。&fml8; で必要なファ -イルをいろいろと作る必要があるので、newml を実行してしまうほうがよい。 -本当に makefml newml を実行するか、newml の実体の処理を呼び出すように -するかはどちらでもよい(が、たぶん後者の実装でよい)。 +2) makefml --force newml elena 相当の処理を行なう。 +&fml8; で必要なファイルをいろいろと作る必要があるので、 +newml を実行してしまうほうがよい。 +本当に makefml newml を実行するか、 +newml の実体の処理を呼び出すようにするかはどちらでもよい +(が、たぶん後者の実装でよい)。 </para> <para> @@ -56,14 +60,16 @@ off を s=skip と書いていると on 扱いになってしまう。 3-3) m=... つまりまとめ行が無効になる。 -しかしながら、歴史的に members で # address と書かれていると 4.0 では -OK だが、8.0 ではこのアドレスは見えない(認証する際の候補にならない)。 +しかしながら、 +歴史的に members で # address と書かれていると 4.0 では OK だが、 +8.0 ではこのアドレスは見えない(認証する際の候補にならない)。 フォーマットを検査して warning を出すべきだろうか？ </para> <para> -4) &fml4; の aliases ファイル (/var/spool/ml/etc/fml/aliases) から該当 -するＭＬの部分を消して .db を再生成する。 +4) &fml4; の +aliases ファイル (/var/spool/ml/etc/fml/aliases) +から該当するＭＬの部分を消して .db を再生成する。 </para> </sect2> @@ -79,9 +85,11 @@ OK だが、8.0 ではこのアドレスは見えない(認証する際の候補にならない)。 </para> <para> -移行作業中にＭＬ全体を止めていいなら、&fml4; の -/var/spool/ml/etc/fml/aliases を削除してからケース１を適用する方が楽で -すね。もちろん、移行作業中は MTA を止めてください。 +移行作業中にＭＬ全体を止めていいなら、 +&fml4; の +/var/spool/ml/etc/fml/aliases +を削除したうえで、ケース１を適用するのが楽なやり方でしょう。 +もちろん、移行作業中は MTA を止めてください。 </para> </sect2> @@ -98,9 +106,10 @@ OK だが、8.0 ではこのアドレスは見えない(認証する際の候補にならない)。 <para> 同一ドメインで、&fml4; と &fml8; を半々に使っている場合、 -次のような設定を施しておくとよい？ -いや中途半端なトリックはやめて、 -すなおに、mergeml で変換するか、しないかにしておいた方が無難だと思う。 +次のような設定をほどこしておくとよいでしょうか？ +いや、 +中途半端なトリックはやめて、 +すなおに、mergeml で変換するか、しないかにしておいた方が無難だと思います。 </para> <para> diff --git a/fml/doc/ja/tutorial/internals/recipes.hook.sgml b/fml/doc/ja/tutorial/internals/recipes.hook.sgml index fc0835f1..9aa858f2 100644 --- a/fml/doc/ja/tutorial/internals/recipes.hook.sgml +++ b/fml/doc/ja/tutorial/internals/recipes.hook.sgml @@ -13,7 +13,7 @@ HOOK 内で推奨される変数名は？ <answer> <para> -HOOK 内で使う変数を my() で制限してくれれば、特に制限はないです。 +HOOK 内で使う変数を my() で制限してもらえれば特別な制限は、ありません。 <screen> $hook = q{ my $x = $config->{ xxx }; @@ -42,20 +42,20 @@ HOOK で変更してよい変数はなんですか？ <para> $config オブジェクトへの代入操作は問題ありません。 -また $curproc が提供するアクセスメソッドで変更できるものについても -自由にアクセスメソッドを使って下さい。 +また +$curproc のアクセスメソッドで変更できる変数ついても、 +アクセスメソッドを使って自由に操作してください。 </para> <para> -アップグレードしても問題のない HOOK を書くには +HOOK では、 +$curproc のメソッドでアクセス可能な内容を変更することで、 +&fml8; を好きなように操作することが出来ますが、 +それ以外のことをするとアップグレードしても動作する保証がありません。 +アップグレードしても問題のない HOOK を書くためにも、 $curproc のアクセスメソッドだけを使って書くようにしてください。 </para> -<para> -HOOK では $curproc のメソッドでアクセス可能な内容は -全て変更して好きなように &fml8; を操作することが出来ますが、 -それ以外のことをするとアップグレードしても動作する保証がありません。 -</para> </answer> diff --git a/fml/doc/ja/tutorial/internals/restriction.sgml b/fml/doc/ja/tutorial/internals/restriction.sgml index ddddd490..73c661a6 100644 --- a/fml/doc/ja/tutorial/internals/restriction.sgml +++ b/fml/doc/ja/tutorial/internals/restriction.sgml @@ -16,7 +16,8 @@ <para> 全プログラムで統一された検査を行なうため、 -FML::Restriction クラスに基づいて検査が行なわれます。 +FML::Restriction +クラスに基づいて検査が行なわれます。 </para> @@ -31,20 +32,24 @@ FML::Restriction クラスに基づいて検査が行なわれます。 </title> <para> -そもそも記事に対する入力制限(入力データの表現範囲の制限)というものは考 -えにくい概念です。 -実際 FML::Restriction クラスによる入力データチェックは行なわれていません。 +そもそも、 +記事に対する入力制限(入力データの表現範囲の制限)は考えにくい概念です。 +実際 +FML::Restriction +クラスによる入力データチェックは行なわれていません。 </para> <caution> <para> (SPAM であろうと思われる)一行メールなどをはじくために -FML::Filter クラスによるフィルタチェックが行なわれ得ます。 +FML::Filter +クラスによるフィルタチェックが行なわれ得ます。 </para> <para> ただし、これは記事の内容に対するチェックではないので、 -FML::Restriction の対象としている操作とは意味合いが異なります。 +FML::Restriction +の対象としている操作とは意味合いが異なります。 </para> </caution> @@ -57,10 +62,13 @@ FML::Restriction の対象としている操作とは意味合いが異なります。 </title> <para> -コマンドメールは FML::Process::Command の中で一行ずつ -FML::Restriction::Command で定義されている正規表現にしたがって -入力されたコマンド列が検査されます。検査に合格すれば、 -FML::Command::{User,Admin}::コマンド の実行に進むことができます。 +コマンドメールは +FML::Process::Command +の中で一行ずつ +FML::Restriction::Command +で定義されている正規表現にしたがって入力されたコマンド列が検査されます。 +検査に合格すれば、 +FML::Command::{User,Admin}::コマンドの実行に進むことができます。 </para> </sect2> @@ -72,8 +80,9 @@ FML::Command::{User,Admin}::コマンド の実行に進むことができます。 </title> <para> -CGI の各プログラムでは、safe_param_XXX() -という関数経由でのみ HTTP セッションからのデータを受けとることができます。 +CGI の各プログラムでは、 +safe_param_XXX() という関数経由でのみ +HTTP セッションからのデータを受けとることができます。 </para> <para> @@ -84,8 +93,9 @@ try_cgi_*() </para> <para> -これらの safe_param_XXX() は FML::Restriction::CGI ( -FML::Restriction::Base を継承している)経由でパターンの検査をし、 +これらの safe_param_XXX() は +FML::Restriction::CGI (FML::Restriction::Base を継承している) +経由でパターンの検査をし、 検査に合格した場合にのみ値が返されています。 </para> @@ -99,9 +109,10 @@ FML::Restriction::Base を継承している)経由でパターンの検査をし、 <para> コマンドラインで実行する(シェルの上での操作が可能である)ので -「入力チェックをしない」のがデフォルトです。 -つまり、そのシェルが取れる時点で正規のユーザであると認証されているはず -なので「正しいユーザ/そのユーザのすることはすべて正しい」と信じています。 +「入力チェックをしない」 +のがデフォルトです。 +サーバのシェルが取れる時点で、正規のユーザであると認証されているはずです。 +「正しいユーザ/そのユーザのすることはすべて正しい」と信じています。 </para> <para> @@ -124,17 +135,21 @@ FML::Restriction::Base を継承している)経由でパターンの検査をし、 <para> 入力データや、 コマンドの ACL は -FML::Restriction クラス以下にモジュールを配置することにしています。 +FML::Restriction +クラス以下にモジュールを配置することにしています。 </para> <para> -たとえば、CGI では -FML::Restriction::CGI クラスのモジュールを用いて +たとえば、 +CGI では +FML::Restriction::CGI +クラスのモジュールを用いて 入力データがある正規表現の中に収まるかどうか？の検査をしています。 </para> <para> -FML::Restriction 以下では Base を継承していますが、他のモジュールでは、 +FML::Restriction 以下では Base を継承していますが、 +他のモジュールでは、 FML::Restriction クラスを object composition して使って下さい。 たとえば、 <screen> @@ -156,7 +171,8 @@ if ($value =~ /^$allowed_regexp{$key}$) { ... ok, do something ... ;} </title> <para> -CGI では FML::Restriction::CGI クラスのモジュールを用いて +CGI では +FML::Restriction::CGI クラスのモジュールを用いて、 入力データがある正規表現の中に収まるかどうか？の検査をします。 </para> @@ -212,9 +228,10 @@ RFC などで許されている表現のごく一部だけを許しています。 <para> ただし -FML::Restriction::Command はコマンドのシンタックスチェックは、 -もうちょっと粒度を上げるべきなのかもしれません。 -現状では未実装。 +FML::Restriction::Command +によるコマンドのシンタックスチェックは、 +もう少し粒度を上げるべきなのかもしれません +(現状、未実装です)。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/struct.sgml b/fml/doc/ja/tutorial/internals/struct.sgml index e3d8ed5a..e11dee8b 100644 --- a/fml/doc/ja/tutorial/internals/struct.sgml +++ b/fml/doc/ja/tutorial/internals/struct.sgml @@ -4,7 +4,7 @@ <appendix id="structure"> <title> - データ構造のサンプル + データ構造の実例 </title> @@ -14,7 +14,7 @@ </title> <para> -FML::Process::Distribute が走っている時のデータ構造の例。 +FML::Process::Distribute が走っている時のデータ構造の例です。 </para> &struct.curproc; @@ -28,7 +28,7 @@ FML::Process::Distribute が走っている時のデータ構造の例。 </title> <para> -PCB で使っているカテゴリとモジュール、および関数のリスト。 +PCB で使っているカテゴリとモジュール、および関数のリストです。 </para> &list.pcb; diff --git a/fml/doc/ja/tutorial/internals/style.sgml b/fml/doc/ja/tutorial/internals/style.sgml index 9dde562a..2ed4549f 100644 --- a/fml/doc/ja/tutorial/internals/style.sgml +++ b/fml/doc/ja/tutorial/internals/style.sgml @@ -28,7 +28,7 @@ FNF (FML.ORG Natural Form) </title> <para> -default という単語をどこにはさむか？は悩ましいです。 +default という単語を変数名のどこに入れるか？は悩ましい問題です。 </para> <para> @@ -37,16 +37,18 @@ default という単語をどこにはさむか？は悩ましいです。 </para> <para> -たとえば article_* であれば記事関連の変数がすべて +たとえば article というくくりがあるとします。 +その場合、 +記事関連の変数は、すべて article_* (article の右側に単語が続く変数群) -に定義されていると期待するでしょう。 +という名称だと期待するでしょう。 </para> <para> そう考えると、 default_* (つまり default クラスが存在すると考える)より、 「クラス_default_変数」ないしは「クラス_変数_default」 -というシンタックスが素直に思えます。 +というシンタックスが素直と考えます。 </para> @@ -56,17 +58,19 @@ default_* (つまり default クラスが存在すると考える)より、 </title> <para> -よりシステマティックな変数命名ルールを考えていくと、ここでも、基底クラ -スと継承という考えを（ある程度）導入する方がよいと思うようになりました。 +よりシステマティックな変数命名ルールを考えていくと、 +ここでも、 +基底クラスと継承という考えを（ある程度）導入する方がよいと考えます。 たとえば、次のようなものです。 </para> <para> mail は「いわゆるメール」つまり messager/rfc822 形式のものです。 -fml システムへ入力されるものも mail だし、出ていくものも mail です。 +fml システムへ入力されるデータも mail 、出ていくデータも mail です。 それらは mail から派生したサブクラスと考えられるため、 「PREFIX_mail_属性」形式に統一する方が良いでしょう。 -ただし、ものすごく厳密に行なうと、逆に、わけがわからないのでほどほどに。 +ただし、 +ものすごく厳密に行なうと、逆に、わけがわからないのでほどほどにしましょう。 </para> <para> @@ -83,8 +87,9 @@ outgoing_mail_何とか use_report_mail_何とか report_mail_何とか </screen> -この例でも、厳密には outgoing_report_mail とかするべきなんでしょうけど、 -そこまではやらないのがほどほどってところですね。 +この例でも、 +厳密には outgoing_report_mail とかするべきでしょうけど、 +そこまではやらないのがほどほどってところでしょうね。 </para> <para> @@ -105,7 +110,7 @@ use_command_mail_header_なんとか <link linkend="list.variables.by.class"> クラスの階層構造 </link> -であらわすと、こーんな感じになるとおもいます。 +であらわすと、このような感じになるとおもいます。 <screen> command { SOMETHING_command @@ -246,13 +251,13 @@ $curproc->main_cf(); <para> -@EXPORT @EXPORT_OK はできればやめたい… +@EXPORT @EXPORT_OK は、できれば、やめたい… </para> <para> Srting::is_japanese_string() -くらいの階層に浅くするべきではないかなぁ？ +くらいの階層に浅くするべきではないだろうか？ せめて 3 段目くらいで止まってほしいような〜 </para> @@ -264,13 +269,13 @@ Srting::is_japanese_string() <!-- ==================================================== --> <sect1> <title> - プログラミング・スタイル (原案のメモ(注: 単なる走り書き)) + [再録] プログラミング・スタイル (原案のメモ(注: 単なる走り書き)) </title> <warning> <para> ログとして、原案のメモ(注: 単なる走り書き)をここに記録しておきます。 -読みづらいですが、失礼。 +読みづらくて失礼ですが… </para> </warning> @@ -279,75 +284,57 @@ Srting::is_japanese_string() <itemizedlist> <listitem> <para> - - Perl ではポリモーフィズムと実行時バインディングができることに - 重視すること。多重継承などに頭を使うより + Perl では、 + ポリモーフィズムと実行時バインディングができることに重視。 + 多重継承などに頭を使うより、 ポリモーフィズムと実行時バインディングによる コンポーネント指向ぽい方向性を模索する。 </para> - - </listitem> <listitem> <para> - - Perl 5 のパッケージを使った、オブジェクトぽい書き方は - 変数自身が自分のパッケージを知っているので、 - 単にパッケージ修飾(例: :: )を使わなくてもよいくらいに - 思う方がよい。 + Perl 5 のパッケージを使った、 + オブジェクトぽい書き方は変数自身が自分のパッケージを知っているので、 + 単にパッケージ修飾(例: :: )を使わなくてもよいくらいに思う方がよい。 </para> - - </listitem> <listitem> <para> - そのために、 再利用性と抽象度を高くしたインターフェイスは オブジェクトぽい書きかたが良さそう。 </para> - - </listitem> <listitem> <para> - Perl 5 だと必然的にオブジェクトぽくなってしまうが、 - オブジェクト、オブジェクト、オブジェクトし過ぎないように - バランス感覚に注意しよう。 + オブジェクト、オブジェクト、 + オブジェクトし過ぎないようにバランス感覚に注意しよう。 </para> - - </listitem> <listitem> <para> - 他人のモジュールを使う場合はともかく、 - 自分達で書くモジュールでの - ”深い”継承はできるだけ避けたい。 + 自分達で書くモジュールでの”深い”継承はできるだけ避けたい。 何でも深くすればよいというものではないでしょう。 - </para> </listitem> </itemizedlist> </para> - <para> libexec/ や libkern.pl にある関数は、 main:: に記述される部分は基本的なフローを記述している。 これらは基本的な枠組を示すものであるため、 - $curproc (C でいえば struct *curproc にあたるもの) - を受け渡す、構造化プログラミング的な書き方をしている。 + $curproc (C でいえば struct *curproc にあたるもの)を受け渡す、 + 構造化プログラミング的な書き方をしている。 </para> - - <para> しかし、そのひとつ下の層、そしてさらにその下では、 再利用性とポリモーフィズムに傾いた方がよさそうにおもえる。 diff --git a/fml/doc/ja/tutorial/internals/userctl.sgml b/fml/doc/ja/tutorial/internals/userctl.sgml index aeb64b26..2649f7e9 100644 --- a/fml/doc/ja/tutorial/internals/userctl.sgml +++ b/fml/doc/ja/tutorial/internals/userctl.sgml @@ -11,58 +11,77 @@ <sect1 id="userctl.deladd"> <title> - ユーザの追加と削除は何に対して行なうか？ + ユーザの追加と削除は、どの変数に対して行なうべきでしょうか？ </title> <para> ユーザの追加と削除は、 -ともに「primary_*_map に対して」 -おこないます。 +変数 primary_*_map +に対して行ってください。 </para> <para> -たとえば、リモート管理者は -primary_admin_member_map と primary_admin_recipient_map の両方に -アドレスを追加します。 +たとえば、 +リモート管理者の追加処理であれば、 +primary_admin_member_map +と +primary_admin_recipient_map +の両方にメールアドレスを追加します。 削除の際は、 -primary_admin_member_map と primary_admin_recipient_map から -アドレスを削除します。 +primary_admin_member_map +と +primary_admin_recipient_map +からアドレスを削除しています。 </para> <para> 操作対象を -admin_member_maps と admin_recipient_maps -にしてしまうのは問題があります -(ここには &fml4; の反省がいかされています ;-)。 +admin_member_maps +と +admin_recipient_maps +にすると、いろいろと問題があります +(ここには &fml4; の反省がいかされています ;-)。 </para> <para> -追加対象は一つに限定しなくてはいけません。 -だから、primary_*_map 一つに対して行なう。 -操作対象が *_maps では複数の map のどれに追加してよいのか曖昧です。 +追加つまり書き込む(WRITE)処理対象は一つに限定しなくてはいけません。 +よって、 +primary_*_map +一つに対して行なうべきです。 +読む(READ)のであれば複数あってもかまいませんが、 +WRITE 操作対象を *_maps でもよいことにしてしまうと、 +複数の map のどれに書き込むのかが曖昧になってしまします。 </para> <para> -逆に、削除は、いっけん *_maps が操作対象で問題ない気がしますが、 -実は駄目です。消し過ぎになってしまうことがあるからです。 -特に問題になるのは、*_maps に「権限の異なる map 」が混在している場合です。 +逆に、 +削除処理は、 +一見 +*_maps が操作対象で問題ない気がしますが、 +実は駄目です。 +消し過ぎになってしまうことがあるからです。 +特に問題になるのは、 +*_maps に「権限の異なる map 」が混在している場合です。 </para> <para> -たとえば、member_maps はデフォルトで、リモート管理者を含んでいます。 +たとえば、 +member_maps はデフォルトで、リモート管理者を含んでいます。 <screen> member_maps = $primary_member_map $admin_member_maps </screen> そのため、member_maps に対して削除を試みると、 -勢いあまってリモート管理者の分も削除してしまうことになるというわけです。 +勢いあまってリモート管理者の分も削除する可能性があります。 </para> <para> こういった曖昧さを避けるために、 -primary_XXX_map と XXX_maps +primary_XXX_map +と +XXX_maps という分離が考案されたいというわけです -(ようするに &fml4; の反省がいかされています ;-)。 +(ようするに &fml4; の反省がいかされています ;-)。 </para> </sect1> |