diff options
| author | fukachan <fukachan> | 2010-03-18 20:28:04 +0000 |
|---|---|---|
| committer | fukachan <fukachan> | 2010-03-18 20:28:04 +0000 |
| commit | 86a52769ded52eebbd7c4819e15ab67070e1a613 (patch) | |
| tree | b44024947d70795f9c60804c0c65673049a2915b /fml | |
| parent | abd10b8bb57d469af413f1a4f1365d24ea97c45c (diff) | |
| download | fml8-86a52769ded52eebbd7c4819e15ab67070e1a613.tar.gz fml8-86a52769ded52eebbd7c4819e15ab67070e1a613.tar.bz2 fml8-86a52769ded52eebbd7c4819e15ab67070e1a613.zip | |
fixed and clean up.
Diffstat (limited to 'fml')
26 files changed, 930 insertions, 560 deletions
diff --git a/fml/doc/ja/tutorial/internals/config.cf.sgml b/fml/doc/ja/tutorial/internals/config.cf.sgml index b89f4749..952422b5 100644 --- a/fml/doc/ja/tutorial/internals/config.cf.sgml +++ b/fml/doc/ja/tutorial/internals/config.cf.sgml @@ -1,5 +1,5 @@ <!-- - $FML: config.cf.sgml,v 1.15 2005/12/15 03:08:11 fukachan Exp $ + $FML: config.cf.sgml,v 1.16 2008/08/18 13:21:42 fukachan Exp $ --> @@ -22,22 +22,23 @@ <para> そのために &fml4; では各ＭＬのホームディレクトリ $DIR (例: -/var/spool/ml/elena)に config.ph というファイルがあります。これは .ph -という名前でわかる通り perl script です。 +/var/spool/ml/elena)に config.ph というファイルがあります。 +これは .ph という名前でわかる通り perl script です。 </para> <para> 一方 &fml8; では config.cf というファイルです。 -フォーマットは postfix や .ini 風の +フォーマットは Postfix や .ini 風の <screen> 変数 = 値 </screen> 形式になっています。 +複数行の値も可能です(後述)。 </para> <para> -perl module と同様に、=cut の後には perl script を書くようになっていま -す。「キーワード = 値」形式の記述は =cut の前に書いて下さい。 +perl module と同様に、=cut の後には perl script を書くようになっています。 +「キーワード = 値」形式の記述は =cut の前に書いて下さい。 </para> <sect2> @@ -46,28 +47,31 @@ perl module と同様に、=cut の後には perl script を書くようになっていま </title> <para> -&fml4; の perl script 方式にはいくつか問題があります。 -例えば perl script なので、perl が許す限りの自由な書き方ができます。 +&fml4; の perl script 方式には、いくつか問題があります。 +</para> + +<para> +メリットとしては、 +perl script なので、perl が許す限りの自由な書き方ができます。 これは人間にとっては嬉しいのですが、 機械処理の観点からは問題です。というのは makefml や CGI をはじめとする設定インターフェイスを書きにくいのです。 そこで &fml4; では、 cf というファイルと config.ph という -2 つのフォーマットの異なるファイルが使われています。 +2 つのフォーマットの異なるファイルが使われることになりました。 <footnote> <para> .mc から .cf を作る点で、なんとなく sendmail みたいですね;) </para> </footnote> +しかし、これでは２つのファイルに分かれてしまう点で保守がしにくくなります。 </para> <para> -しかし、これはこれで２つのファイルに分かれてしまう点が -保守しにくさを生みます。 よって &fml8; では、 -設定インターフェイスにやさしい新フォーマットを提唱します。 -それが config.cf です。 -これは本質的に postfix 風のフォーマットです。 +設定インターフェイスにやさしい新フォーマットとしました。 +それが config.cf で、 +本質的に Postfix 風フォーマットです。 </para> </sect2> @@ -100,7 +104,7 @@ config.cf のフォーマットは <para> 変数定義内での $ による変数の展開も可能です。 -例えば +たとえば <screen> a = 値1 b = $a/値2 @@ -115,19 +119,19 @@ b = 値1/値2 <para> -展開は、すべての変数定義を読み込んだ後に行なわれます。 -そのため、以下のような定義をすると +展開は、すべての変数定義を読みこんだ後に行なわれます。 +そのため、以下のように定義をすると <screen> a = 値1 b = $a/値2/$c c = 値3 a = 値4 </screen> -次のように +すべてを読み込んだあとに解釈されるため <screen> b = 値4/値2/値3 </screen> -と解釈されます。 +と判断されます。 </para> </sect1> @@ -136,7 +140,7 @@ b = 値4/値2/値3 <!-- ======================================= --> <sect1 id="config.cf.format.extension"> <title> - postfix style のさらなる拡張 + Postfix スタイルのさらなる拡張 </title> <para> @@ -190,15 +194,15 @@ x = a b c d e 『デフォルトの定義』、 『サイト固有の定義』、 『ドメイン固有の定義』 -などを別のファイルに分離し、上書きしつつ多重読み込みをすることができま -す。これをするため、デフォルトでは、いくつかの .cf ファイルに分離され -ています。 +などを別ファイルに分離し、 +上書きしつつ多重読み込みをすることができます。 +このために、デフォルトでは、いくつかの .cf ファイルに分離されています。 </para> <para> -fml は起動時にそれらのファイルを順番に読みこみ、 +&fml8; は起動時にそれらのファイルを順番に読みこみ、 最後にＭＬ固有の config.cf を読み込みます。 -そして、すべてのファイルを読み込んだ後に変数の展開処理を行ないます。 +そして、すべての設定ファイルを読み込んだ後に変数の展開処理を行ないます。 </para> </sect1> @@ -210,18 +214,22 @@ fml は起動時にそれらのファイルを順番に読みこみ、 </title> <para> -$ をふくむ変数の値の代入が行なわれると、 -次に値を取り出すメソッド +$ をふくむ変数に値の代入が行なわれると、 +その場では評価されません。 +</para> + +<para> +次に、値を取り出すメソッド <footnote> <para> - perl の tie 操作 + perl の tie() 操作 </para> </footnote> -が呼ばれた際に、変数の再展開が行なわれます。 +が呼ばれた際に、初めて変数の再展開が行なわれます。 </para> <para> -例えば +たとえば <screen> $config->{ key } = '$ml_home_dir/value'; </screen> @@ -229,7 +237,9 @@ $config->{ key } = '$ml_home_dir/value'; <screen> $config->{ another_key } </screen> -(キーはなんでもよい)メソッドが呼ばれた際に再評価されることになります。 +(キーはなんでもよい)メソッドが呼ばれた際に、 +変数群すべてが再評価されます +(たがいに依存関係があるため、すべての変数が評価されなければなりません)。 </para> @@ -239,14 +249,21 @@ $config->{ another_key } </title> <para> -内部構造の話をすると、 -まず %_fml_config に キーと値 の組が保存されます。 -これは $dir/$file のような形式のままです。 +少し内部構造の話をします。 +</para> -get() はこのハッシュではなく %_fml_config_result の値を返しています。 -このハッシュ中の値は $dir などが展開された後の値で、 +<para> +値の代入操作が行なわれると、 +まずは %_fml_config に キーと値 の組が保存されます。 +これは $dir/$file のような代入した値そのままです。 +</para> + +<para> +get() メソッドは、 +%_fml_config ではなく %_fml_config_result の値を返しています。 +%_fml_config_result 中の値は $dir などが展開された後の値で、 /var/spool/ml/elena/file などとなっています。 -この変数の値の展開は get() なりが呼ばれた際に始めて行なわれます。 +この変数の値の展開は get() メソッドなりが呼ばれた際に初めて行なわれます。 </para> </sect2> @@ -292,15 +309,21 @@ config.cf 内で使って良い関数はどれですか？ <answer> <para> -つまり、フックで利用可能な関数は何ですか？ということになりますが、 -それは「$curproc のメソッド」です。 +つまり、フックで利用可能な関数は何ですか？という設問ですが、 +公式には「$curproc オブジェクトが提供するメソッド」となります。 +</para> + +<para> +たいていのオブジェクトに今あるメソッドは将来も廃止されないと思いますが、 +いちおう $curproc オブジェクトが提供するメソッドとしておくのが安心です。 </para> <para> +注意: &fml4; の設定ファイル config.ph と異なり &fml8; の config.cf では =cut より前は変数を書く場所です。 perl の関数を書く場所ではありません。 -=cut よりうしろにはフックつまり perl script を書きます。 +=cut の後にはフックつまり perl script を書きます。 </para> </answer> diff --git a/fml/doc/ja/tutorial/internals/credential.sgml b/fml/doc/ja/tutorial/internals/credential.sgml index 213aea8e..7bfbdb29 100644 --- a/fml/doc/ja/tutorial/internals/credential.sgml +++ b/fml/doc/ja/tutorial/internals/credential.sgml @@ -1,5 +1,5 @@ <!-- - $FML: credential.sgml,v 1.3 2003/04/15 14:51:40 fukachan Exp $ + $FML: credential.sgml,v 1.4 2004/10/06 09:07:38 fukachan Exp $ --> @@ -9,8 +9,8 @@ </title> <para> -ユーザ認証は FML::Credential クラスの提供するメソッドを使って -行ないます。 +ユーザ認証は +FML::Credential クラスの提供するメソッドを使って行ないます。 </para> @@ -22,7 +22,7 @@ <sect2> <title> - case sensitive / case insensitive + case sensitive or insensitive ? </title> <para> @@ -31,8 +31,8 @@ USER パートは sensitive ドメインパートは insensitive </screen> -オプションで、USER パートも insensitive にできるように -できた方がよいですよね？ +オプションで、USER パートも +insensitive にできるようにできた方がよいのですよね？ </para> </sect2> diff --git a/fml/doc/ja/tutorial/internals/dbms.sgml b/fml/doc/ja/tutorial/internals/dbms.sgml index 162943d6..cf60b7d1 100644 --- a/fml/doc/ja/tutorial/internals/dbms.sgml +++ b/fml/doc/ja/tutorial/internals/dbms.sgml @@ -1,18 +1,34 @@ <!-- - $FML: dbms.sgml,v 1.7 2005/06/25 15:11:34 fukachan Exp $ + $FML: dbms.sgml,v 1.8 2008/08/18 13:21:42 fukachan Exp $ --> <chapter id="dbms"> <title> - データベース管理システム + データベース管理システム(DBMS)との連携 </title> <para> -メンバーリストなどの永続性の必要なデータに対しデータベースを用いたいな -ら、きちんと DBMS (データベース管理システム)を使うべきです。ここで述べ -ているデータベースとは、そういった意味合いのデータを相手にしています。 -一方 &fml8; が動作する上で内部的に使うデータベースモジュールについては +メンバーリストなど永続性の必要なデータにたいし、 +DBMS (データベース管理システム)を使い、 +理路整然と管理したい。 +当然の欲求です。 +</para> + +<para> +そういった場合、もちろん DBMS (データベース管理システム)を使うべきです +(ただし、きちんとしたものを使いましょう;-)。 +本章が対象としているデータベースとは、 +そういった意味合いの DBMS を相手にしています。 +</para> + +<para> +現在、利用可能な DBMS は +RDBMS (MySQL と PostgreSQL) および LDAP です。 +</para> + +<para> +&fml8; が動作する上で内部的に使うデータベースモジュールについては <link linkend="db.module"> <xref linkend="db.module"> </link> @@ -34,9 +50,12 @@ IO::Adapter </para> <para> -データの挿入や削除といった基本的な機能はこのクラスが提供します。 -それらの原始的な機能を組み合わせた複雑な操作は -IO::Adapter の前段階のプログラムが頑張る必要があります。 +このクラスが、データの挿入や削除といった基本的な機能を提供します。 +</para> + +<para> +逆に言うと、それらの原始的な機能を組み合わせた複雑な操作は +IO::Adapter の前段階で処理する必要があります。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/design.sgml b/fml/doc/ja/tutorial/internals/design.sgml index 52a9b326..1351c286 100644 --- a/fml/doc/ja/tutorial/internals/design.sgml +++ b/fml/doc/ja/tutorial/internals/design.sgml @@ -1,5 +1,5 @@ <!-- - $FML: design.sgml,v 1.11 2004/10/06 09:07:38 fukachan Exp $ + $FML: design.sgml,v 1.12 2008/07/12 12:53:05 fukachan Exp $ --> @@ -21,52 +21,39 @@ <para> <ulink url="http://www.fml.org/software/fml8/"> -fml-devel +&fml8; プロジェクト(初期コードネーム fml-devel) </ulink> -とも呼ばれている &fml8; プロジェクトは、 -&fml4; の再構想(refactoring)とその実装(例)の構築 -を行なっています。 -</PARA> - -<para> -<ulink url="http://www.fml.org/software/fml8/"> -http://www.fml.org/software/fml8/ -</ulink> -は将来の fml-current についてのデザインや実装例を紹介しています。 -</PARA> - +は、 +&fml4; の再構想(refactoring)です。 +</para> <para> -現状の fml-devel はアイデアを実装し、運用テストするための fml 8.0 のア -ルファ版です。ですが、すでに動く実装例をダウンロードできますし、fml -1.2 相当ないしはそれ以上の機能を使うこともできます。しかしながら、変数 -名もアーキテクチャアも本決まりではないので、将来変わる可能性があります。 -でも、概ね固まったと思う。 -</PARA> +&fml8; はβ版ですが、何年ものあいだ安定した試験運用を続けています。 +変数名もアーキテクチャアも、おおむね固まったと思います。 +</para> <para> -自分がふだん使うには全然困らないのですが、&fml4; との互換性をいいだす -と、まだ多くの機能が実装されていないといえます。これは、デザインを最初 -から考え直すに当たり、アイデアや意見を募集するためにまだまだ原型にとど -まっているためでもあります。 -</PARA> +自分が使うには全然困らないのですが、 +&fml4; との互換性は不十分かもしれません。 +&fml4; の全ての機能を実装する必要があるとは思えませんが、 +&fml4; の対応機能は、すでにかなりの部分が &fml8; にあります。 +</para> <para> -ものによっては &fml8; 用に作られたモジュールを &fml4; へ輸入/輸出 -することも検討しています。IPv6 はすでに輸出されました。たとえば 4.0 で -も独立性の高い mead (エラーメール解析プログラム)などはその良い例だろう -し、新機能を提供するモジュールなども再輸入(輸出)可能なものは順次マージ -していきます。 -</PARA> +ものによっては &fml8; 用に作られたモジュールを &fml4; へ輸入/輸出しています。 +IPv6 はすでに輸出されました。 +たとえば 4.0 でも独立性の高い +mead (エラーメール解析プログラム)などは輸出可能な例でしょう。 +</para> <para> これらのマージおよび 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> +</para> </sect1> @@ -75,7 +62,7 @@ http://www.fml.org/software/fml8/ <sect1 id="design.idea.detail"> <title> - 構想（詳細) + 初期構想（詳細) </title> <itemizedlist> @@ -88,7 +75,7 @@ http://www.fml.org/software/fml8/ <listitem> <para> - 全部 perl module 形式 (要 perl 5.00504 以降) + すべて perl module 形式 (要 perl 5.00504 以降) </para> </listitem> @@ -162,7 +149,7 @@ http://www.fml.org/software/fml8/ <listitem> <para> - SQL (MySQL は実装済み) + SQL (MySQL、PostgreSQL 実装済み) </para> </listitem> @@ -194,11 +181,11 @@ http://www.fml.org/software/fml8/ <!-- ======================================================== --> <sect1 id="design.refactoring"> <title> - fml をリファクトリングするアイデア + fml をリファクタリングするアイデア </title> <table> - <title> リファクトリング TODO </title> + <title> リファクタリング TODO </title> <tgroup cols=3> <thead> @@ -217,7 +204,7 @@ http://www.fml.org/software/fml8/ </row> <row> - <entry> </entry> + <entry> done. </entry> <entry> イメージ/モティーフ</entry> <entry> &fml4; から &fml8; へは、 @@ -237,7 +224,7 @@ http://www.fml.org/software/fml8/ </row> <row> - <entry> </entry> + <entry> done. </entry> <entry> 再利用性(自主開発はできるだけ避ける) </entry> <entry> 可能な限りあらゆる CPAN モジュールなどを使う。 @@ -251,7 +238,7 @@ http://www.fml.org/software/fml8/ <row> - <entry> </entry> + <entry> done. </entry> <entry> 設定ファイルの形式は cf と config.ph を統合化したようなもので、 @@ -312,7 +299,7 @@ http://www.fml.org/software/fml8/ <row> - <entry> </entry> + <entry> done. </entry> <entry> tools </entry> <entry> BSD make を使わない。 diff --git a/fml/doc/ja/tutorial/internals/directory.sgml b/fml/doc/ja/tutorial/internals/directory.sgml index b0cb0756..cda71fc4 100644 --- a/fml/doc/ja/tutorial/internals/directory.sgml +++ b/fml/doc/ja/tutorial/internals/directory.sgml @@ -1,5 +1,5 @@ <!-- - $FML: directory.sgml,v 1.7 2005/11/29 14:05:11 fukachan Exp $ + $FML: directory.sgml,v 1.8 2008/08/18 13:21:42 fukachan Exp $ --> @@ -15,8 +15,8 @@ </title> <para> -たとえば、HTML化された記事は、 -こんな階層に置かれていますが、どうでしょう？ +たとえば、HTML 化された記事は、 +次のような一段階の階層構造で置かれています。どうでしょう？ <screen> 200201/msg○○.html </screen> @@ -27,25 +27,30 @@ </para> <para> -現代の性能では、ディレクトリ中に 1000 くらいの構造なら、あってもほとん -ど瞬時に ls は返ってきますが、10000 ともなるとちょっと考えます。 +現代の PC の性能なら、 +ディレクトリ中に 1000 くらいのファイルがあっても +ほとんど瞬時に ls は返ってきますが、 +10000 ともなるとちょっと考えます。 </para> <para> HTML 化されたファイルをおくサブディレクトリを 1000 ごとに用意すると、 -たとえば spool/sub/file みたいにすると、 spool/ 以下で 10^6 ( million ) -くらいはそれなりのアクセス速度を保ちつつ格納できるはず。 +たとえば spool/sub/file みたいにすると spool/ 以下の記事が 10^6 ( million ) +くらいは、それなりのアクセス速度を保ちつつ格納できるはずです。 </para> <para> -一つのＭＬで 100 万通はなかなかいかないだろうから、まぁいいとこでしょう。 -もう一段階いくと 10^9 くらいいくけど、そこまでいかんだろう。 +一つのＭＬで 100 万通は、なかなかいきません。 +この予想は、悪くはないでしょう。 +もう一段階いくと 10^9 くらいいきますが、 +そこまで長くＭＬが続くことは少ない。 </para> <para> -なお Maildir/ なんかは 100 万くらいじゃちょっとつらいだろうから、２レ -ベルくらいにするだろうと。ここでは関係ない議論だけど。 -メールを一万通ためる人が100人いるだけでもうだめ。 +なお直接には関係ない議論ですが、 +Maildir/ でも 100 万くらいで少しつらい。 +二段階くらいにはしないといけない。 +メールを 10,000 通ためる人が 100 人いるだけでもうだめ。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/errormail.sgml b/fml/doc/ja/tutorial/internals/errormail.sgml index 503286e0..24f3350b 100644 --- a/fml/doc/ja/tutorial/internals/errormail.sgml +++ b/fml/doc/ja/tutorial/internals/errormail.sgml @@ -1,5 +1,5 @@ <!-- - $FML: errormail.sgml,v 1.7 2005/06/25 14:43:08 fukachan Exp $ + $FML: errormail.sgml,v 1.8 2008/08/18 13:21:42 fukachan Exp $ --> @@ -9,13 +9,16 @@ </title> <para> -libexec/error は &fml4; の libexec/mead に相当するものです。 +/usr/local/libexec/fml/error は &fml4; の +mead (libexec/mead) に相当するエラー解析プログラムです。 </para> <para> -$use_error_mail_analyzer_function を yes にすると、エラー解析機能が有効にな -ります。ちなみに、デフォルトで $use_error_mail_analyzer_function は yes つま -りエラー解析機能は有効になっています。このあたりは &fml4; と異なります。 +$use_error_mail_analyzer_function を yes にすると、 +エラー解析機能が有効になります。 +ちなみに、デフォルトで $use_error_mail_analyzer_function は yes +つまりエラー解析機能は有効になっています。 +このあたりは &fml4; と異なります。 </para> <para> @@ -30,14 +33,16 @@ $use_error_mail_analyzer_function を yes にすると、エラー解析機能が有効にな </title> <para> -ＭＬ作成時に $ml-admin のアドレスは libexec/error を呼び出すように設定 -されます。 +ＭＬ作成時に $ml-admin アドレス宛のメールは +/usr/local/libexec/fml/error を呼び出すように設定されます。 </para> <para> -libexec/distribute などと同様に libexec/error は標準入力からメールを読 -みこみ、それを解析し、Mail::Message オブジェクトの鎖を作ります。そして、 -Mail::Bounce クラスがエラー内容の解析をします。 +/usr/local/libexec/fml/distribute などと同様に +/usr/local/libexec/fml/error +は標準入力からメールを読みこみ、 +それを解析し、Mail::Message オブジェクトの鎖を作ります。 +そして Mail::Bounce クラスがエラー内容の解析をします。 </para> <para> @@ -50,9 +55,15 @@ Mail::Bounce は、エラーメールについて「どの MTA が生成したものか？」 </para> <para> -一定時間以上経過すると、$error_mail_analyzer_function がキャッシュのデータ -を解析し、あるメールアドレスが存在しないように思えるか否か？を判定しま -す。その結果、消すべきだと判断されると、削除されます。 +一定時間以上経過すると、 +$error_mail_analyzer_function がキャッシュのデータを解析し、 +あるメールアドレスが存在しないように思えるか否か？を判定します。 +その結果、消すべきだと判断されると、削除されます。 +</para> + +<para> +「一定時間」と「消すべきか？という判断」 +の二つが主なチューニングパラメータになります。 </para> </sect1> @@ -64,9 +75,11 @@ Mail::Bounce は、エラーメールについて「どの MTA が生成したものか？」 </title> <para> -$error_mail_analyzer_function_select_list にある関数名が利用し得るアル -ゴリズムです。現在は simple_count histgram という２つのアルゴリズムが -あり、histgram がデフォルトです。 +$error_mail_analyzer_function_select_list +にある関数名が利用し得るアルゴリズムです。 +デフォルトでは +simple_count と histgram という２つのアルゴリズムが用意されており、 +histgram がデフォルトです。 </para> @@ -76,14 +89,17 @@ $error_mail_analyzer_function_select_list にある関数名が利用し得るアル </title> <para> -単純にエラーが返ってきたメールの総数で、エラーか否かを判定します。 +単純にエラーが返ってきたメールの総数で「削除するか否か」の決断を判定します。 </para> <para> -単純にエラーの数ですので、たまたま受信者が設定を少しの間だけ間違えてい -て、たまたまその日の流量が多い場合には、その受信者はエラーとみなされる -でしょう。 -そういった場合にも、ようしゃなく削除するのが、この方法の問題点です。 +単純にエラー数なので、”たまたま”受信者が設定を少しの間だけ間違えていて、 +”たまたま”その日の流量が多い場合、 +その受信者は「削除対象」とみなされることになります。 +</para> + +<para> +そういった場合にも、ようしゃなく削除してしまうのが、この方法の問題点です。 </para> </sect2> @@ -95,8 +111,9 @@ $error_mail_analyzer_function_select_list にある関数名が利用し得るアル </title> <para> -エラーが連続してＮ日続いた時に限り、削除を行ないます。 -デフォルトでは14日連続してエラーの場合に削除が行なわれます。 +エラーが連続してＮ日続いた時に限り削除を行ないます。 +デフォルトでは 14 日(つまり二週)のあいだ連続してエラーの場合に、 +はじめてアドレスの削除が行なわれます。 </para> <para> @@ -113,8 +130,8 @@ $error_mail_analyzer_function_select_list にある関数名が利用し得るアル </para> <para> -注意: 当然のことながら、流量が一日一通に満たないような、まったりとした -ＭＬでは、このアルゴリズムは動作しません:-) +注意: 当然のことながら、流量が一日一通に満たないような、 +まったりとしたＭＬでは、このアルゴリズムは動作しません:-) </para> </sect2> @@ -128,19 +145,21 @@ $error_mail_analyzer_function_select_list にある関数名が利用し得るアル </title> <para> -解析結果は $error_mail_analyzer_cache_dir ディレクトリに格納されます。 +各エラーメール(らしきもの)の解析結果は +$error_mail_analyzer_cache_dir ディレクトリに格納されます。 </para> <para> 現在、キャッシュの入出力には Tie::JournaledDir クラスを使っていますが、 -正確には FML::Error::Cache 経由で Tie::JournaledDir への IO を行ないま -す。 +正確には FML::Error::Cache 経由で Tie::JournaledDir +への IO を行なっています。 </para> <para> -FML::Error::Cache が Tie::JournaledDir の直前に位置し、アダプタとなり -ます。すべての IO は、FML::Error::Cache が提供する primitive なメソッ -ドを通じてのみ行なわなければなりません。 +FML::Error::Cache が Tie::JournaledDir の直前に位置し、 +アダプタ層となっています。 +すべての IO は、FML::Error::Cache が提供する +primitive なメソッドを通じてのみ行なわなければなりません。 </para> </sect1> @@ -155,14 +174,16 @@ FML::Error::Cache が Tie::JournaledDir の直前に位置し、アダプタとなり <screen> $maintainer_recipient_maps </screen> -で、エラーメッセージの転送先を指定することができます。 -デフォルトは未定義で、転送は行なわれません。 -&fml8; がログを残すだけです。 +を使うと、エラーメッセージの転送先を指定することができます。 +デフォルトは「未定義」で、転送は行なわれません。 +つまり &fml8; がエラーメールのログを残すだけです(安全ですので推奨)。 </para> <para> -現在は、単にエラーメールをフォワーディングしてるだけです。中身は -message/rfc822 一通だけの無味乾燥な mime/multipart です。 +フォワードする設定をした場合は？というと、 +単にエラーメールのフォワーディングが行なわれるだけです。 +エラーメール( message/rfc822 )を一通だけ含む無味乾燥な +mime/multipart がＭＬの管理者へ送信されます。 </para> <!-- diff --git a/fml/doc/ja/tutorial/internals/filename.sgml b/fml/doc/ja/tutorial/internals/filename.sgml index f3becfed..8827e45e 100644 --- a/fml/doc/ja/tutorial/internals/filename.sgml +++ b/fml/doc/ja/tutorial/internals/filename.sgml @@ -1,5 +1,5 @@ <!-- - $FML: filename.sgml,v 1.3 2003/04/15 14:51:41 fukachan Exp $ + $FML: filename.sgml,v 1.4 2004/10/06 09:07:39 fukachan Exp $ --> @@ -35,13 +35,13 @@ members-役割 <para> さらに配送リスト以外でも同じルールを適用します。 -例えば +たとえば <screen> passwd-admin passwd-moderator passwd-cgiadmin </screen> -というようなぐあいにです。 +といったぐあいです。 </para> @@ -56,8 +56,9 @@ recipient-役割 </para> <para> -一応、使い分けるつもりですが、実際、どういう場合に役立つのかはよくわか -らないです。が、とりあえず理論的に美しいほうを採用することとします。 +一応、使い分けるつもりですが、実際、 +どういう場合に役立つのかはよくわからないです。 +悩んだときは、理論的に美しい方を採用することにしています。 </para> </sect1> @@ -134,6 +135,11 @@ etc/passwd-admin <para> 4.0 では etc/passwd でした。 </para> + +<para> +パスワード認証以外の場合もあり得るので、 +ちゃんと「ファイル名-役割」としたかったというわけです。 +</para> </warning> </sect1> diff --git a/fml/doc/ja/tutorial/internals/filter.sgml b/fml/doc/ja/tutorial/internals/filter.sgml index ffaa3a0a..dd14d289 100644 --- a/fml/doc/ja/tutorial/internals/filter.sgml +++ b/fml/doc/ja/tutorial/internals/filter.sgml @@ -1,5 +1,5 @@ <!-- - $FML: filter.sgml,v 1.10 2008/08/18 20:52:59 fukachan Exp $ + $FML: filter.sgml,v 1.11 2008/08/19 03:22:17 fukachan Exp $ --> @@ -17,14 +17,23 @@ <caution> <para> -ここでいうフィルタとは、特にこだわらない限り、投稿された記事に対するフィ -ルタです。このフィルタは FML::Filter クラスに実装されています。 +本章でいうフィルタとは、 +特にこだわらない限り「投稿された記事に対するフィルタ」を指します。 </para> <para> -また、記事ではなくコマンドメール特有の特別なフィルタなども考えられます。 -この場合 FML::Filter にあるとはかぎりません。 -たとえばコマンドメールのコマンドの長さ制限などは +この「記事に対するフィルタ」システムは +FML::Filter クラスに実装されています。 +</para> + +<para> +もちろん「記事」ではなく +「コマンドメール」を対象としたフィルタシステムなども考えられます。 +この場合、その特殊なフィルタシステムが +FML::Filter のサブクラスにあるとはかぎりませんので注意して下さい。 +コマンドメールが対象であれば、 +コマンド処理のクラス中に実装されたフィルタシステムを呼び出しています。 +たとえばコマンドメールのコマンドの長さを制限する機能(フィルタ)は FML::Command::Filter クラスが担当しています。 </para> @@ -37,13 +46,19 @@ FML::Command::Filter クラスが担当しています。 </title> <para> -コンテンツを検査するフィルタには大きく分けて３種類あります。それは、 -ヘッダ、 -メール本文、 -MIME 構造を元にしたフィルタ(mime component filter)の３つです。 -メール本文に対するフィルタには MIME でないものをどうするか？ -text/plain に対してより厳しいシンタックスチェックを行なうフィルタも -あるので、大きく分けると４つというほうがよいかもしれません。 +コンテンツを検査するフィルタには大きく分けて三種類あります。それは、 +「ヘッダに対するフィルタ」 +「メール本文に対するフィルタ」 +「MIME 構造を元にしたフィルタ(mime component filter)」の３つです。 +</para> + +<para> +もっとも「メール本文に対するフィルタ」にも、 +「 MIME でないメールに対するフィルタ」 +と +「text/plain に対するフィルタ」 +の二種類があるので、 +大きく分けると四種類が正しい説明かもしれません。 <screen> 大まかな区分け @@ -51,16 +66,16 @@ text/plain に対してより厳しいシンタックスチェックを行なうフィルタも body non-mime - permit / reject (4.0 の content filter の !MIME) + permit / reject (fml 4.0 の content filter の !MIME) mime component filter - 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 @@ -68,14 +83,14 @@ text/plain に対してより厳しいシンタックスチェックを行なうフィルタも bogofilter </screen> 本当はこれ以外に、SMTP もしくは LMTP を使って、外部の virus scanner な -りに飛ばす迂回路(postfix の content_filter 相当)が必要だと思うんだけど -今はまだ考えていません。とりあえず、それは postfix でやってください。 +りに飛ばす迂回路(postfix の content_filter 相当)が必要だと思うのですが、 +(それは Postfix でやればいいとおもいますので)実装していません。 </para> <!-- XXX-TODO トラフィックベースのフィルタ --> <para> -また、これら以外にトラフィックベースのフィルタがあります（まだかなりの -部分が未実装なので省略します）。 +また、これら以外にトラフィックベースのフィルタがあります +(ほとんど未実装なので解説は省略 _o_)。 </para> </sect1> @@ -83,12 +98,14 @@ text/plain に対してより厳しいシンタックスチェックを行なうフィルタも <sect1 id="internals.filter.config"> <title> - 設定変数 + フィルタに関する設定 </title> <para> -配送やコマンドメールといった機能別に「フィルタを使うか使わないか？」 -「使うフィルタルールは？」などが定義されています。 +配送やコマンドメールといった機能別に +「フィルタを使うか使わないか？」 +「使うフィルタルールは？」 +などの変数が定義されています。 </para> <para> @@ -109,19 +126,21 @@ use_機能A = yes か no <sect1 id="internals.filter.size"> <title> - サイズ制限 + フィルタ: サイズ制限 </title> <para> -ヘッダ部分およびメール本文の部分のサイズに制限がかけられます。また、変 -数は記事とコマンドメールについてそれぞれ別に存在します。必要なケースで -だけ使うとか、○○の場合だけサイズ制限の機能を切るといった使い方も可能 -です。 +ヘッダ部分およびメール本文の部分のサイズに制限がかけられます。 +また、変数は記事とコマンドメールについてそれぞれ別に存在します。 +必要なフィルタのみを有効にするとか、 +○○の場合だけサイズ制限の機能を切るといった使い方も可能です( +もっとも、あまり複雑な条件下でのみフィルタといったことをしようとすると +HOOK による対応になるとおもいますが…)。 </para> <para> -余談: - parse() する時にサイズもはかっているので、このフィルタの実装は簡単です:) +余談: Mail::Message クラスがメールを解析したさいに、 +メールの各部分のサイズも分析済みなので、このフィルタの実装は簡単です:) </para> &var.filter.size; @@ -131,13 +150,16 @@ use_機能A = yes か no <sect1 id="internals.filter.command"> <title> - コマンドメールへの制限 + フィルタ: コマンドメールへの制限 </title> <para> -コマンドメールには「一通当たりのコマンド数」とか「コマンド依存の制限一 -回のコマンドメールで get できるファイルは100個まで」といったコマンド固 -有の制限があります。 +コマンドメールには +「一通当たりのコマンド数」 +や、 +コマンド依存の制限、 +たとえば「一回のコマンドメールで get できるファイルは 100 個までとする」 +がありえます。 </para> <!-- &table.list.filter.commandmail; --> @@ -147,24 +169,24 @@ use_機能A = yes か no <sect1 id="internals.filter.mimecomponent"> <title> - mime component filter のルール構成法 + フィルタ: mime component filter のルール構成法 </title> <para> &fml4; の content filter とは異なり、 -&fml8; の mime component filter は +&fml8; の mime component filter のルールは <screen> text/plain permit text/html reject * permit </screen> -みたいな空白区切りのフォーマットで書きます。 +のような空白区切りのフォーマットで書いてあります。 </para> <para> -MIME が前提なので、!MIME (MIME 以外を対象とする)という命令はありません -が、text/plain と multipart/mixed 中の text/plain を区別するために、こ -ういう書き方である必要があるとおもうわけです。 +MIME が前提なので、!MIME (MIME 以外を対象とする)という命令はありませんが、 +text/plain と multipart/mixed 中の text/plain を区別するために、 +こういう書き方である必要があるとおもうわけです。 <screen> 全体 部分 アクション ---------------------------------------------- @@ -174,7 +196,7 @@ multipart/mixed text/html reject multipart/mixed image/* cutoff * * permit </screen> -さらに、将来はこういうのもありか？ +さらに、将来はこういうのもありえるでしょうか？(未実装) <screen> text/plain :uuencoded: cutoff text/plain :size>500k cutoff @@ -182,7 +204,7 @@ text/plain :size>500k cutoff </para> <para> -ルールの構成上の問題点はいくつかあります。 +ただし、このルールに関しても構成上の問題点がいくつかあります。 </para> <sect2> @@ -192,7 +214,8 @@ text/plain :size>500k cutoff <para> アクションには first match のものとそうでないものがあります。reject は -大抵 first match ですが、cutoff は first match ではないとおもわれます。 +たいてい first match ですが、 +cutoff は first match ではないとおもわれます。 さて？ </para> @@ -205,13 +228,14 @@ text/plain :size>500k cutoff </title> <para> -では、permit はどうでしょう？実のところ文脈依存と考えられますが、何が -正しいのかよくわかりません。たとえば、multipart のメールの中身が +では、permit はどうでしょう？実のところ文脈依存と考えられますが、 +何が正しいのかよくわかりません。 +たとえば、multipart のメールの中身が <screen> text/plain + image/jpeg + text/html </screen> -のように３つの異なるタイプのパートからなる場合、どういうルールなら曖昧 -さがないでしょうか？ +のように３つの異なるタイプのパートからなる場合、 +どういうルールなら「あいまいさ」がないでしょうか？ </para> <para> @@ -222,7 +246,7 @@ text/plain + image/jpeg + text/html <para> 『permit は「個別に許す」という意味である』説と、『permit は「メール全 -体を許す」という意味である』説の両方があります。たとえば、 +体を許す」という意味である』説の両方がありえます。たとえば、 <screen> text/plain * permit * * reject @@ -232,9 +256,9 @@ text/plain * permit </para> <para> -一方、『permit は「メール全体を許す」という意味である』説があります。 -たとえば text/plain のメールだけを許したいとしましょう。 直観的にはこ -う書くとおもいます。 +一方で『permit は「メール全体を許す」という意味である』説がありえます。 +たとえば text/plain のメールだけを許したいとしましょう。 +直観的には、次のようなルールを書くとおもいます。 <screen> text/plain * permit * * reject @@ -243,9 +267,9 @@ text/plain * permit <screen> * * reject </screen> -と一緒になってしまうわけです。だから permit は"メール全体を OK として -ルールとの照らし合わせ処理をそこで終りにする"という意味にしないといけ -ません。よって、次のようなルールはありえないことになります。 +と一緒になってしまうわけです。だから permit は「メール全体を OK として +ルールとの照らし合わせ処理をそこで終りにする」という意味にとらないとい +けません。よって、次のようなルールはありえないことになります。 <screen> text/plain * permit multipart/mixed text/plain permit @@ -368,7 +392,7 @@ multipart/* text/html reject </title> <para> -じゃ、これはどうよ？これは簡単なルールが書けない例でんな。 +これはどうでしょう？これは簡単なルールが書けない例です。 <screen> text/plain * permit multipart/* text/plain permit @@ -384,8 +408,8 @@ text/plain + text/plain + text/plain text/plain + text/plain + image/jpeg text/plain + image/jpeg + text/html </screen> -これらも 2 番めのルールで permit されてしまう。 -だめじゃん。 +これらも二番目のルールで permit されてしまいます。 +うまく書けない例です。 </para> </sect2> @@ -393,11 +417,11 @@ text/plain + image/jpeg + text/html <sect2> <title> - ケーススタディ: 前の例のバリエーションで reject ではなく cutoff + ケーススタディ: 前例のバリエーションで reject ではなく cutoff </title> <para> -前の例のバリエーションで reject ではなく cutoff。 +前例のバリエーションで reject ではなく cutoff の場合。 <screen> text/plain * permit multipart/* image/* cutoff @@ -412,11 +436,12 @@ text/plain + text/plain + text/plain <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> diff --git a/fml/doc/ja/tutorial/internals/hook.sgml b/fml/doc/ja/tutorial/internals/hook.sgml index 00914acf..e4dbfd4c 100644 --- a/fml/doc/ja/tutorial/internals/hook.sgml +++ b/fml/doc/ja/tutorial/internals/hook.sgml @@ -1,13 +1,40 @@ <!-- - $FML: hook.sgml,v 1.7 2006/01/16 10:24:27 fukachan Exp $ + $FML: hook.sgml,v 1.8 2008/08/18 20:52:59 fukachan Exp $ --> <chapter id="hook"> <title> - HOOK + HOOK(フック) </title> +<para> +HOOK とは、&fml8; の内部にあらかじめ用意されている +「小さな perl のプログラムを実行する」 +機能です(専門用語でいえば HOOK を eval() するということです)。 +</para> + +<para> +HOOK は要所要所に用意されています。 +</para> + +<para> +もちろん、HOOK は、そのコンテキストの中で実行されます。 +その意味で本質的に危険な機能です。 +ある程度、&fml8; の中身について理解していないと +HOOK を書くことはできません。 +</para> + +<para> +その一方、 +HOOK をうまく使うことで、 +少しの手間で複雑な動作を実現することが可能になります。 +</para> + +<para> +ものは使い用です。 +</para> + <sect1 id="hook.problems"> <title> @@ -15,15 +42,23 @@ </title> <para> -HOOK は微妙な修正、もしくは複雑なカスタマイズのために是非必要です。 -ですが、実装においてはいくつかの問題があります。 +HOOK は微妙な修正、もしくは複雑なカスタマイズのために是非必要な機能ですが、 +実装においては、いくつかの問題があります。 </para> <para> -まず、&fml4; の $START_HOOK のような曖昧なものではなく、 -HOOK の名前に一定の基準が必要でしょう。 -そのため &fml8; では、ある関数の最初と最後にHOOKを用意する場合、 -次のようなスタイルの HOOK 名称になっています。 +まず、&fml4; の $START_HOOK のような曖昧なものでは、 +プログラムごとに異なる動作をさせることが難しい。 +たとえば $START_HOOK を設定すると、 +配送システムとコマンドメールシステムで同じ $START_HOOK を実行します。 +それが便利な場合もあるのですが、プログラムの役割ごとに異なる動作をさせ +ようとすると面倒で分かりにくい設定になります。 +</para> + +<para> +そのため HOOK の名前に一定の基準が必要でしょう。 +&fml8; では、ある関数の最初と最後に HOOK を用意する場合、 +次のようなスタイルの HOOK 名称としています。 <screen> $役割_関数_start_hook $役割_関数_end_hook @@ -32,9 +67,9 @@ $役割_関数_end_hook <para> これにより配送システムとコマンドメールシステムで共通の HOOK などという -ものはなくなり、別々のHOOKをしかけることができるようになります。逆に、 -共通のものをしかけようとするなら、一杯書いて下さい;)ということです。 -まぁコピーすればいいだけだから、さして難しくないですよね？(と思いたい) +ものはなくなり、別々の HOOK をしかけることができるようになります。逆に、 +共通のものをしかけようとするなら、一杯書いて下さい;)ということです。まぁ +コピーすればいいだけだから、さして難しくないですよね？(と思いたい) <screen> $distribute_XXX_start_hook = q{ ... }; $YYY_XXX_start_hook = $distribute_XXX_start_hook; @@ -43,12 +78,23 @@ $YYY_XXX_start_hook = $distribute_XXX_start_hook; <para> また、HOOK の書き方が少々良くなくても動かないと困るでしょう。 -通常、各モジュールでは +というのは「少しだけ修整する」というケースでは、 +Perl の素人さんが行なうことも多いからです。 +</para> + +<para> +現場では、欲しい機能を実現したい場合、美しいコードを書くことよりも、少 +しでも早く実現することが求められます。そこは「美しさ」にこだわるべきで +はない点と考えます。 +</para> + +<para> +というわけで、通常、各モジュールでは <screen> use strict; </screen> -になっていますが、HOOK を評価する lexical scope では無視するようにして -あります。 +になっていますが、 +HOOK を評価する lexical scope では無視するようにしてあります。 実際には、HOOK を評価する際に、つねに <screen> no strict; @@ -58,11 +104,17 @@ HOOK の内容 </para> <para> -&fml4; と &fml8; の大きな違いのひとつは変数、関数のスコープです。 -&fml4; はグローバルなので、どんな関数でも使えますが、&fml8; では、そう -はいきません。とはいえ、まったく手がかりがないのも困るので、$curproc -が使えるような場所にのみ HOOK を用意するといったルールが必要でしょう。 -いまのところ、そういう方針になっています。 +&fml4; と &fml8; の大きな違いのひとつは変数・関数のスコープです。 +注意して下さい。 +&fml4; の関数は全てグローバル関数なので、どんな関数でも使えますが、 +&fml8; では、そうはいきません。 +とはいえ、まったく手がかりがないのも困るので、HOOK が利用できる環境では +$curproc オブジェクトだけは常にアクセス可能であることを保証しています。 +</para> + +<para> +つまり HOOK を書く際には、 +$curproc オブジェクトのアクセスメソッドだけを使って書くようにして下さい。 </para> </sect1> @@ -80,12 +132,12 @@ HOOK 名前の標準的な形式については 役割名_メソッド名_end_hook </screen> などとすることにしました。ここで役割名は「use_XXX_function」(例: -use_article_post_function)のXXX部分です。もっと粒度の細かいHOOKについ -ては、この形式でないものもあります。 +use_article_post_function)の XXX 部分です。 +もっと粒度の細かい HOOK については、この形式でないものもあります。 </para> <para> -たとえば、fmlconf コマンドのメインの部分 run() の HOOK の名前は +たとえば、fmlconf コマンドのメインメソッド run() の HOOK の名前は <screen> fmlconf_run_start_hook fmlconf_run_end_hook @@ -114,12 +166,14 @@ sub run </screen> </para> +<!-- <para> 現実にはもっといろいろな場所に HOOK がないと不便でしょうが、 その名前は上述の HOOK 以外に設定します。 単純に hook2 でいいのかもしれないし、 可能であればもう少し理解しやすい名前にするべきでしょう。 </para> +--> </sect1> diff --git a/fml/doc/ja/tutorial/internals/io_abstraction.sgml b/fml/doc/ja/tutorial/internals/io_abstraction.sgml index 88c15e98..c76210da 100644 --- a/fml/doc/ja/tutorial/internals/io_abstraction.sgml +++ b/fml/doc/ja/tutorial/internals/io_abstraction.sgml @@ -1,16 +1,21 @@ <!-- - $FML: io_abstraction.sgml,v 1.5 2005/06/25 15:11:34 fukachan Exp $ + $FML: io_abstraction.sgml,v 1.6 2008/08/18 20:52:59 fukachan Exp $ --> <chapter id="io.abstraction"> <title> - IO インターフェイスとオペレーション + IO インターフェイス </title> <para> -移植性や拡張性のためには UNIX における Vnode/VFS interface (vnode(9)参 -照)のような構造をあらゆるレイヤーに導入する必要があります。 +将来の移植性/拡張性を見据えるなら、ＭＬサーバの設計においても +UNIX における Vnode/VFS interface (vnode(9)参照) +のような構造をあらかじめ導入しておくべきでしょう。 +</para> + +<para> +例: NetBSD の vnode 構造体。 <screen> struct vnode { ... @@ -27,28 +32,33 @@ v_op の先に、 vop_open() vop_read() vop_getattr() -などが定義されています。 +などが定義されます。 </para> <para> つまり struct vnode の **v_op (vnode operation vector) にあたるものが -IO に使われるクラスの各メソッドです。たとえば、IO::Adapter はユーザリ -ストというオブジェクトに対する IO インターフェイスを抽象化したものです。 +IO に使われるクラスの各メソッドです。 +</para> + +<para> +&fml8; では IO::Adapter クラスという抽象化されたインターフェイスを使います。 +このクラスはユーザリストというオブジェクトに対する +IO インターフェイスを抽象化したものです。 </para> <sect1 id="io.abstraction.overview"> <title> - 基本形としての IO::Adapter + IO::Adapter の基本形 </title> <para> -&fml8; 全体の基調となる型は +&fml8; の設計上の手本となるクラスは <link linkend="module.io.adapter"> IO::Adapter </link> -といえるでしょう。実装もすでに完成形であり、primitive なメソッドは何か -などについて十分考えられています。 +といえるでしょう。実装もすでに完成形であり、primitive なメソッドは何か？ +などについても十分考えぬかれています。 </para> <para> @@ -64,7 +74,7 @@ KEY => VALUE KEY => [ VALUE, VALUE2, VALUE3 ] </screen> のいづれかの型のデータ構造を抽象化していると考えられます。 -つまり、これは RDBMS の基礎理論同様の表型のデータ構造です。 +つまり、これは RDBMS の基礎理論同様の表型データ構造です。 </para> <screen> KEY1 VALUE1-1 "" "" @@ -75,7 +85,7 @@ KEY4 VALUE4-1 VALUE4-2 VALUE4-3 <para> ユーザリストを管理する上で必要最低限の基本メソッド群は、 -IO::Adapter の裏にあるオブジェクト本体を呼びだすための +IO::Adapter の <screen> open() close() @@ -88,7 +98,7 @@ find(KEY or REGEXP) get_next_key() </screen> があれば十分のようです。 -少なくとも、ユーザ管理はこれらだけで十分書けます。 +少なくとも、ユーザ管理は、これらのメソッドだけで十分書けます。 </para> </sect1> @@ -96,7 +106,7 @@ get_next_key() <sect1 id="io.abstraction.ops"> <title> - メソッド / operation vector + メソッド </title> <para> @@ -117,16 +127,35 @@ get_next_key() 必要なら適宜、ディストラクタも定義して下さい。 </para> + +<sect2> + <title> + new() + </title> + <para> オブジェクトを生成するのは new() です。 たとえば IO::Adapter であれば、 <screen> $obj = new IO::Adapter マップ; +もしくは +$obj = new IO::Adapter マップ, パラメータ(ハッシュリファレンス); </screen> などとオブジェクトタイプを引数(マップ)で指定するため、 -それに応じた初期化を行ないます。 +マップに応じた初期化を行ないます。 </para> +<para> +呼び出しの基本形は引数の多い方に合わせるので、次のようになります。 +<screen> +my $config = $curproc->config(); +my $obj = new IO::Adapter $map, $config; +</screen> +HOOK なので利用する際にも、つねに、この形で書いておくべきです。 +</para> + +</sect2> + <sect2> <title> @@ -134,7 +163,8 @@ $obj = new IO::Adapter マップ; </title> <para> -ファイルであれば open(2)、RDBMS であれば SQL サーバへの接続を確立する +ファイルであれば open(2)、 +RDBMS であれば SQL サーバへの接続を確立する、 といった具合です。 </para> @@ -147,7 +177,7 @@ $obj = new IO::Adapter マップ; </title> <para> -すなおに open() の逆です。 +すなおに open() の逆の動作をします。 </para> </sect2> @@ -159,20 +189,21 @@ $obj = new IO::Adapter マップ; </title> <para> -KEY (プライマリキー)もしくは、KEY および KEY に付随するデータをオブジェ -クトに書き込みます。なお、ARGV はクラス依存のデータ渡しのためにある引 -数で、この引数が使われないこともあります。 +KEY (プライマリキー)もしくは +KEY および KEY に付随するデータをオブジェクトに書き込みます。 +なお、ARGV はクラス依存のデータ渡しのためにある引数で、 +この引数が使われないこともあります。 </para> <para> -UNIX と異なり、オブジェクトの構造に一定の型があります。型とは RDBMS の -ようなテーブルの形です。 +UNIX と異なり、オブジェクトの構造に一定の型があります。 +型とは RDBMS のようなテーブルの形です。 </para> <para> -また、プライマリキーとなるのは通常メールアドレスです。この前提が多くの -場面で正しいため、メールアドレスをプライマリキーにしたテーブル型が基本 -的なデータ構造といえるわけです。 +また、プライマリキーとなるのは通常メールアドレスです。 +この前提が多くの場面で正しいため、メールアドレスをプライマリキーにした +テーブル型が基本的なデータ構造といえます。 </para> </sect2> @@ -248,7 +279,7 @@ XXX すなおに、key() もしくは get_key() でも良い気がする？ <sect2> <title> - ARRAY_REF でほしい？ + 返り値を ARRAY_REF 型で欲しい場合？ </title> <para> @@ -267,15 +298,15 @@ PRIMARY KEY の一覧くらいか？ <para> 定石は全部読んでみること、つまり get_next_key() を呼びまくるコードです。 専用のメソッドがあった方が便利でしょうけど、 -滅多にそんなコードは必要ないようなので、 -専用メソッドがなくても問題はないようです。 +めったにそんなコードは書かないので、 +専用メソッドがなくても問題はないと考えます。 </para> <para> もし、あるとしたら get_primary_keys() みたいな名前のメソッド？で、 ARRAY_REF で返すのでしょうかね？でも、find('*', { all => 1 }) などとす -ると全部の KEY の値がARRAY_REF で返りますんで、別のメソッドも不要な気 -がするねぇ。 +ると全部の KEY の値がARRAY_REF で返りますんで、 +別のメソッドも不要な気がします。 <screen> (KEY1 KEY2) </screen> @@ -290,27 +321,19 @@ ARRAY_REF で返すのでしょうかね？でも、find('*', { all => 1 }) などとす </title> <para> -これこそ、どういうデータ構造が欲しいんでしょうねぇ？ -返り値が HASH_REF であるようなメソッドが欲しいのだろうか？ +これこそ、どういうデータ構造が欲しい場合なんでしょうか？ +返り値が HASH_REF とは、次のような構造が返り値になる場合です。 <screen> 返り値 = { 変数１ => 値１、 変数２ => 値２、 } </screen> -って、つまり getattr(KEY) とかいうメソッドかなぁ。だが、HASH_REF 中の -属性のキーがオブジェクトに強く依存するわけですが…そんなので modular -といえるのか？ -</para> - -<para> -単に、表のＮ番めじゃなくて、Ｎ番目の名前はこれこれ…っていう情報のタグ -をつけて返すと思えば、あまり変わらないといえば変わらない。 </para> <para> -メールアドレスに属性をつけることを考えるとこういったものが必要でしょう。 -たとえば、まとめ送りがその例といえる。 +メールアドレスに属性をつける場合、こういった型での返り値が欲しいでしょうか。 +たとえば、まとめ送り(&fml4; の例)。 <screen> メールアドレス => { 送り間隔 => ３時間、 @@ -318,18 +341,13 @@ ARRAY_REF で返すのでしょうかね？でも、find('*', { all => 1 }) などとす フォーマット => mime/multipart }; </screen> +注意: +&fml8; では、まとめ送りの複雑なオプションはサポートしていませんので、 +この操作は不要です。 </para> <para> -ただ、キャッシュを抽象化したアダプタ層はこの形になりうるでしょう。 -たとえば -<screen> -FML::Error -> FML::Error::Cache -> Tie::JournaledDir -</screen> -こういったキャッシュのアダプター層のために、標準規格があるとよいです。 -全部 Tie でやるってのもあるけど、Tie で書きまくると、どんどん HASH の -中身が複雑になって、一番下の Tie:: の替えがきかなかったりしそうで、な -んかいやなかんじではあります。 +結局、実装する必要がないというのが現状。 </para> </sect2> diff --git a/fml/doc/ja/tutorial/internals/language.sgml b/fml/doc/ja/tutorial/internals/language.sgml index eb8160cf..8a42b46b 100644 --- a/fml/doc/ja/tutorial/internals/language.sgml +++ b/fml/doc/ja/tutorial/internals/language.sgml @@ -1,5 +1,5 @@ <!-- - $FML: language.sgml,v 1.3 2004/10/06 09:07:39 fukachan Exp $ + $FML: language.sgml,v 1.4 2008/08/18 20:52:59 fukachan Exp $ --> @@ -15,25 +15,47 @@ </title> <para> -一番単純なモデルは「このＭＬは日本人用と設定しているなら、メッセージは -常に日本語で返す」というものです。このモデルでは、ＭＬ作成時に何言語用 -かを指定する必要があります。しかしながら、間違って(日本語が読めない人 -から)送られてきたメールに対しても、日本語でエラーを返します。 +一番単純なモデルは +「このＭＬは日本人用と仮定している。 +よって、自動応答メッセージは、つねに日本語で返す」 +というものです。 +もちろん、さまざまな問題が考えられます。 </para> <para> -一方、日本人だからといって、今、メールを読んでいる環境で日本語が使えな -いかも知れないし、Accept-Language: を無視するのもよろしくありません。 -とはいえ、みんながちゃんとAccept-Language:をつけているわけではないので、 -問題はいろいろと山積みです。 +第一に、このモデルでは、ＭＬ作成時に何言語用かを指定する必要があります。 </para> <para> -たとえば、Accept-Language: ja などとしてある場合は ja が優先だと分かり -ます。しかしながら、そういったものがなく、かつ、「日本人が help という -メールを送ってきた」場合、返事を us-ascii なのか iso-2022-jp で返すべ -きなのか？が、プログラムには良く分かりません。たとえば、こんなメールで -は、どう判断するのが正しいでしょう？ +第二に、間違って(日本語が読めない人から)送られてきたメールに対しても、 +日本語でエラーメッセージを返します。 +</para> + +<para> +第三に、日本人がメールを送ってきていたとしても、 +今、メールを読んでいる環境で日本語が使えないかもしれませんし、 +</para> + +<para> +メールヘッダの Accept-Language: がアテになるでしょうか？ +</para> + +<para> +おそらく、少しはアテになるでしょう。 +よって、メールヘッダの Accept-Language: を無視するのもよろしくありません。 +ただし、きちんと Accept-Language: がつけられているとも限りません。 +</para> + +<para> +たとえば、 +Accept-Language: ja などとしてある場合は ja が優先だと分かります。 +しかしながら、そういったものがなく、かつ、「日本人が help というメール +を送ってきた」場合、返事を us-ascii で返すべきなおんか？それとも +iso-2022-jp で返すべきなのか？が、プログラムには判断できません。 +</para> + +<para> +たとえば、こんなメールでは、どう判断するのが正しいでしょう？ <screen> 例: @@ -47,17 +69,21 @@ help </para> <para> -charsetを素直に考えると、英語で返すべきですが、これは本文が英語だけな +charset を素直に考えると、英語で返すべきですが、これは本文が英語だけな ので charset=us-ascii になっているだけです。しょうがないので、このＭＬ が(日本人相手のため)日本語優先と設定されているなら、日本語と英語のメッ -セージ両方を返すべきでしょう。英語のＭＬなら、英語を返すだけでいいです。 +セージ両方を返すべきでしょう。 +</para> + +<para> +英語のＭＬという想定なら、英語のメッセージを返すだけでいいはずです。 </para> <para> -逆に、Accept-Lanaguage: が指定されていれば、それを尊重するべきです。英 -語のＭＬ(language_preference_order = en)の場合でも、Accept-Lanaguage: -ja なら（できるだけ）日本語で返事をするべきでしょう。&fml8; 標準のメッ -セージであれば、この動作が可能です。なので、そうするべきと考えます。 +逆に、Accept-Lanaguage: が指定されていれば、それを尊重するべきです。 +英語のＭＬ(language_preference_order = en)の場合でも、 +Accept-Lanaguage: ja なら（できるだけ）日本語で返事をするべきでしょう。 +&fml8; 標準のメッセージであれば、この動作が可能です。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/lock.sgml b/fml/doc/ja/tutorial/internals/lock.sgml index 5a377696..dc816996 100644 --- a/fml/doc/ja/tutorial/internals/lock.sgml +++ b/fml/doc/ja/tutorial/internals/lock.sgml @@ -1,5 +1,5 @@ <!-- - $FML: lock.sgml,v 1.5 2005/06/25 15:11:34 fukachan Exp $ + $FML: lock.sgml,v 1.6 2008/08/18 20:52:59 fukachan Exp $ --> @@ -9,9 +9,9 @@ </title> <para> -プロセス間の同期化はロックを用いて行ないます。&fml8; でサポートされて -いるロックメカニズムは flock(2) もしくは lockf(2) を元にしたロック機構 -のみです。 +プロセス間の同期化はロックを用いて行ないます。 +&fml8; でサポートされているロックメカニズムは +flock(2) もしくは lockf(2) を元にしたロック機構のみです。 </para> @@ -29,8 +29,8 @@ </para> <para> -たとえば、Mail::Delivery 関連はメンバーリストにアクセスするので、いろ -いろとロックが必要です。 +たとえば、Mail::Delivery 関連はメンバーリストにアクセスするので、 +いろいろとロックが必要です。 </para> <para> @@ -40,26 +40,27 @@ FML::Process::Delivery の２箇所しかない)の中でロック処理をしています。 </para> <para> -一方、Mail::Delivery::Queue は見るだけ (mailq コマンド)か、並列操作可 -能なものだけなので、ロックは考えなくて良いはずです。 +一方、Mail::Delivery::Queue は見るだけ (mailq コマンド)か、 +並列操作可能なものだけなので、ロックは考えなくて良いはずです。 </para> <para> -そして、write lock とは限らないが、一般に map を使うモジュールには -ロックが必要です。write が必要とは限りません。 +そして、reader writer lock まで大げさでなくとも +一般に map を使うモジュールにはロックが必要です。 +write 用の lock が必要とは限りません。 たとえば FML/Command/UserControl.pm や FML/Command/Auth.pm -には write lock が必要ですが、 +には write 用の lock が必要ですが、 FML/Credential.pm -は read lock だけでよいです。 +は read 用の lock だけでよいです。 </para> <para> しかしながら、いまのところ reader writer lock は実装されていませんので、 -リソースごとの細かいロック制御で critical region の時間を短くするよう -になっています。 +リソースごとの細かいロック制御で critical region +の時間を短くするようになっています。 </para> </sect1> @@ -71,7 +72,7 @@ FML/Credential.pm </title> <para> -*_maps をよぶまえには MUTEX でロックをする。いや、やりすぎかもしれません。 +*_maps をよぶ前には MUTEX でロックをする。いや、やりすぎかもしれません。 </para> <para> diff --git a/fml/doc/ja/tutorial/internals/main.cf.sgml b/fml/doc/ja/tutorial/internals/main.cf.sgml index 03aec42e..bbb65403 100644 --- a/fml/doc/ja/tutorial/internals/main.cf.sgml +++ b/fml/doc/ja/tutorial/internals/main.cf.sgml @@ -1,5 +1,5 @@ <!-- - $FML: main.cf.sgml,v 1.10 2004/10/06 09:07:39 fukachan Exp $ + $FML: main.cf.sgml,v 1.11 2008/08/18 20:52:59 fukachan Exp $ --> @@ -9,11 +9,14 @@ </title> <para> -/usr/local/etc/fml/main.cf は各ＭＬの設定ではありません。fml のバージョ -ンなどメタレベルの依存性を解決するための設定ファイルで、fml のプログラ -ム群が起動する時に参照します。 -main.cf はディレクトリやプロセスのユーザの指定など最も基本的な情報のみ -が書かれているファイルです。 +main.cf はディレクトリやプロセスのユーザの指定など +最も基本的な情報のみが書かれているファイルです。 +</para> + +<para> +/usr/local/etc/fml/main.cf は各ＭＬの設定ではありません。 +fml のバージョンなどメタレベルの依存性を解決するための設定ファイルで、 +fml のプログラム群が起動する際に”つねに”参照しています。 </para> <para> @@ -31,7 +34,7 @@ main.cf のフォーマットは他の .cf と同様 <screen> # -# $FML: main.cf.sgml,v 1.10 2004/10/06 09:07:39 fukachan Exp $ +# $FML: main.cf.sgml,v 1.11 2008/08/18 20:52:59 fukachan Exp $ # # fml version diff --git a/fml/doc/ja/tutorial/internals/merge.sgml b/fml/doc/ja/tutorial/internals/merge.sgml index 3d053fc5..8a84d24a 100644 --- a/fml/doc/ja/tutorial/internals/merge.sgml +++ b/fml/doc/ja/tutorial/internals/merge.sgml @@ -1,11 +1,11 @@ <!-- - $FML: merge.sgml,v 1.3 2005/06/25 15:11:34 fukachan Exp $ + $FML: merge.sgml,v 1.4 2008/08/18 20:52:59 fukachan Exp $ --> <chapter id="merge.internal.to.fml8"> <title> - 他のＭＬシステムの設定を &fml8; へ変換する処理について + ケーススタディ: 他のＭＬシステムの設定を &fml8; へ変換するには？ </title> @@ -33,7 +33,7 @@ 2) makefml --force newml elena 相当の処理を行なう。&fml8; で必要なファ イルをいろいろと作る必要があるので、newml を実行してしまうほうがよい。 本当に makefml newml を実行するか、newml の実体の処理を呼び出すように -するかはどっちでもよい。たぶん後者でよい。 +するかはどちらでもよい(が、たぶん後者の実装でよい)。 </para> <para> @@ -44,8 +44,7 @@ <para> 3-1) IO::Adapter は ^# の行はコメントだと思って無視している。 -よって、actives で off されているアドレスは消えているように -見える。 +よって、actives で off されているアドレスは消えているように見える。 </para> <para> diff --git a/fml/doc/ja/tutorial/internals/recipes.hook.sgml b/fml/doc/ja/tutorial/internals/recipes.hook.sgml index b3b6c6eb..c88ae796 100644 --- a/fml/doc/ja/tutorial/internals/recipes.hook.sgml +++ b/fml/doc/ja/tutorial/internals/recipes.hook.sgml @@ -1,5 +1,5 @@ <!-- - $FML: recipes.hook.sgml,v 1.1 2006/01/16 10:24:27 fukachan Exp $ + $FML: recipes.hook.sgml,v 1.2 2008/08/18 20:52:59 fukachan Exp $ --> @@ -47,14 +47,14 @@ $config オブジェクトへの代入操作は問題ありません。 </para> <para> -HOOK では $curproc のメソッドでアクセス可能な内容は全て変更して好きな -ように &fml8; を操作することが出来ますが、それ以外のことをするとアップ -グレードしても動作する保証は一切ありません。 +アップグレードしても問題のない HOOK を書くには +$curproc のアクセスメソッドだけを使って書くようにしてください。 </para> <para> -アップグレードしても問題のない HOOK を書くには -$curproc のアクセスメソッドだけを使って書くようにしてください。 +HOOK では $curproc のメソッドでアクセス可能な内容は +全て変更して好きなように &fml8; を操作することが出来ますが、 +それ以外のことをするとアップグレードしても動作する保証がありません。 </para> </answer> diff --git a/fml/doc/ja/tutorial/internals/restriction.sgml b/fml/doc/ja/tutorial/internals/restriction.sgml index ee0107c7..2996f41b 100644 --- a/fml/doc/ja/tutorial/internals/restriction.sgml +++ b/fml/doc/ja/tutorial/internals/restriction.sgml @@ -1,5 +1,5 @@ <!-- - $FML: restriction.sgml,v 1.10 2005/08/03 13:45:11 fukachan Exp $ + $FML: restriction.sgml,v 1.11 2008/08/18 20:52:59 fukachan Exp $ --> @@ -9,8 +9,14 @@ </title> <para> -入力データ(特にコマンドなど)は FML::Restriction クラスが提供する -正規表現で検査します。 +当然、 +入力データ(特にコマンドなど)に対する正当性の検査( input validation ) +が行なわれています。 +</para> + +<para> +全プログラムで統一された検査を行なうため、 +FML::Restriction クラスに基づいて検査が行なわれます。 </para> @@ -21,27 +27,33 @@ <sect2> <title> - 投稿 + 投稿メールに対して </title> <para> そもそも記事に対する入力制限(入力データの表現範囲の制限)というものは考 -えにくいです。実際 FML::Restriction クラスによる入力データチェックはあ -りません。 +えにくい概念です。 +実際 FML::Restriction クラスによる入力データチェックは行なわれていません。 +</para> + +<caution> +<para> +(SPAM であろうと思われる)一行メールなどをはじくために +FML::Filter クラスによるフィルタチェックが行なわれ得ます。 </para> <para> -(FML::Restriction の対象としている操作とは意味合いが異なりますが)一行 -メールなどをはじくために FML::Filter クラスによるフィルタチェックがデ -フォルトで適用されています。 +ただし、これは記事の内容に対するチェックではないので、 +FML::Restriction の対象としている操作とは意味合いが異なります。 </para> +</caution> </sect2> <sect2> <title> - コマンドメール + コマンドメールに対して </title> <para> @@ -56,12 +68,12 @@ FML::Command::{User,Admin}::コマンド の実行に進むことができます。 <sect2> <title> - CGI + CGI に対して </title> <para> -CGI の各プログラムでは、safe_param_XXX() という関数経由でのみ HTTP セッ -ションからのデータを受けとることができます。 +CGI の各プログラムでは、safe_param_XXX() +という関数経由でのみ HTTP セッションからのデータを受けとることができます。 </para> <para> @@ -86,9 +98,10 @@ FML::Restriction::Base を継承している)経由でパターンの検査をし、 </title> <para> -コマンドラインで実行するので「入力チェックなし」がデフォルトです。つま -り、そのシェルが取れる時点で正規のユーザであると認証されているはずなの -で「正しいユーザ/そのユーザのすることはすべて正しい」と信じています。 +コマンドラインで実行する(シェルの上での操作が可能である)ので +「入力チェックをしない」のがデフォルトです。 +つまり、そのシェルが取れる時点で正規のユーザであると認証されているはず +なので「正しいユーザ/そのユーザのすることはすべて正しい」と信じています。 </para> <para> @@ -122,7 +135,8 @@ FML::Restriction::CGI クラスのモジュールを用いて <para> FML::Restriction 以下では Base を継承していますが、他のモジュールでは、 -FML::Restriction クラスを object composition して使って下さい。例えば、 +FML::Restriction クラスを object composition して使って下さい。 +たとえば、 <screen> use FML::Restriction::CGI; $safe = new FML::Restriction::CGI; @@ -160,7 +174,7 @@ for my $dirty_buf (param()) { ... check ... } </screen> -のような構文は許す必要はあるでしょうが、 +のような構文を許す必要があるでしょうが、 <screen> param($dirtty_buf) </screen> @@ -182,22 +196,25 @@ for my $key (param()) { <sect1> <title> - 議論: FML::Restriction の制限はきびし過ぎる？ + 議論: FML::Restriction の制限はきびし過ぎるか？ </title> <para> -FML::Restriction のクラスでは RFC などで許されている表現のごく一部だけ -を許しています。 +FML::Restriction のクラスでは +RFC などで許されている表現のごく一部だけを許しています。 </para> <para> -RFC の定義が広すぎるんで…手抜きといえば手抜きといわれちゃいますが、 -安全側に倒しています。 +そもそも RFC の定義が広すぎるので、 +手抜きといえば手抜きになりますが、 +コードは安全側にたおしています。 </para> <para> -FML::Restriction::Command はコマンドのシンタックスチェックはもうちょっ -と粒度を上げるべきなのかもしれませんが、現状ではしていません。 +ただし +FML::Restriction::Command はコマンドのシンタックスチェックは、 +もうちょっと粒度を上げるべきなのかもしれません。 +現状では未実装。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/internals/style.sgml b/fml/doc/ja/tutorial/internals/style.sgml index b499b393..1e6acacd 100644 --- a/fml/doc/ja/tutorial/internals/style.sgml +++ b/fml/doc/ja/tutorial/internals/style.sgml @@ -1,5 +1,5 @@ <!-- - $FML: style.sgml,v 1.13 2004/10/06 09:07:40 fukachan Exp $ + $FML: style.sgml,v 1.14 2005/06/25 15:11:35 fukachan Exp $ --> @@ -9,13 +9,13 @@ </TITLE> <para> -ここでは、プログラミング上のいくつかの諸問題についてまとめます。 +本章は、プログラミング・スタイルに関する諸問題についてのメモです。 </para> <para> -FML.ORG のソフトウエアのコーディングスタイルについては +FML.ORG のソフトウエア・コーディング・スタイルの詳細は <ulink url="http://www.fml.org/software/FNF/"> -FNF +FNF (FML.ORG Natural Form) </ulink> を参照して下さい。 </para> @@ -29,19 +29,24 @@ FNF <para> default という単語をどこにはさむか？は悩ましいです。 -一番左に来る（たいてはい最初の _ までの）文字列部分は、 -大きな括りでのクラスを意味すると考えられます。 </para> <para> -たとえば article_* であれば記事関連の変数が全て article_ 以下に -定義されていると期待するでしょう。 +一般に、一番左に来る（たいてはい最初の _ までの）文字列部分は、 +大きな”くくり”でのクラスを意味すると考えられます。 </para> <para> -そう考えると、我々の場合は、default_* (つまり default クラスが存在する -と考える)より、「クラス_default_変数」ないしは「クラス_変数_default」 -というシンタックスの方が素直な分類方式のような気がします。 +たとえば article_* であれば記事関連の変数がすべて +article_* (article の右側に単語が続く変数群) +に定義されていると期待するでしょう。 +</para> + +<para> +そう考えると、 +default_* (つまり default クラスが存在すると考える)より、 +「クラス_default_変数」ないしは「クラス_変数_default」 +というシンタックスが素直に思えます。 </para> @@ -61,7 +66,7 @@ mail は「いわゆるメール」つまり messager/rfc822 形式のものです。 fml システムへ入力されるものも mail だし、出ていくものも mail です。 それらは mail から派生したサブクラスと考えられるため、 「PREFIX_mail_属性」形式に統一する方が良いでしょう。 -が、ものすごく厳密にやると、逆に、わけがわからないのでほどほどに。 +ただし、ものすごく厳密に行なうと、逆に、わけがわからないのでほどほどに。 </para> <para> @@ -182,7 +187,7 @@ use_変数 = yes か no var2 </screen> - </sect2> +</sect2> <sect2> @@ -193,7 +198,7 @@ use_変数 = yes か no <screen> プログラム_変数_属性 </screen> - </sect2> +</sect2> </sect1> @@ -265,6 +270,7 @@ Srting::is_japanese_string() <warning> <para> ログとして、原案のメモ(注: 単なる走り書き)をここに記録しておきます。 +読みづらいですが、失礼。 </para> </warning> @@ -309,7 +315,7 @@ Srting::is_japanese_string() <listitem> <para> - perl 5 だと必然的にオブジェクトぽくなってしまうが、 + Perl 5 だと必然的にオブジェクトぽくなってしまうが、 オブジェクト、オブジェクト、オブジェクトし過ぎないように バランス感覚に注意しよう。 </para> diff --git a/fml/doc/ja/tutorial/internals/userctl.sgml b/fml/doc/ja/tutorial/internals/userctl.sgml index 156c0df7..ff9ee2e3 100644 --- a/fml/doc/ja/tutorial/internals/userctl.sgml +++ b/fml/doc/ja/tutorial/internals/userctl.sgml @@ -1,5 +1,5 @@ <!-- - $FML: userctl.sgml,v 1.2 2004/04/07 11:07:08 fukachan Exp $ + $FML: userctl.sgml,v 1.3 2004/10/06 09:07:40 fukachan Exp $ --> @@ -15,9 +15,9 @@ </title> <para> -ユーザの追加と削除は何に対して行なうか？というと -追加は primary_*_map に対しておこないます。 -削除も primary_*_map に対しておこないます。 +ユーザの追加と削除は、 +ともに「primary_*_map に対して」 +おこないます。 </para> <para> @@ -30,20 +30,22 @@ primary_admin_member_map と primary_admin_recipient_map から </para> <para> -これを admin_member_maps と admin_recipient_maps にすると問題があります。 +操作対象を +admin_member_maps と admin_recipient_maps +にしてしまうのは問題があります +(ここには &fml4; の反省がいかされています ;-)。 </para> <para> -追加は、明らかに複数の map に追加してしまうので、一つに限定するべきです。 +追加対象は一つに限定しなくてはいけません。 だから、primary_*_map 一つに対して行なう。 -つまり、メンバーは primary_xxx_member_map ひとつに、 -受信者は primary_xxx_recipient_map 一つに対して行ないます。 +操作対象が *_maps では複数の map のどれに追加してよいのか曖昧です。 </para> <para> -削除は、一見 *_maps でもよいような気がしますが、 +逆に、削除は、いっけん *_maps が操作対象で問題ない気がしますが、 実は駄目です。消し過ぎになってしまうことがあるからです。 -特に問題になるのは、権限の異なる map が混在している場合です。 +特に問題になるのは、*_maps に「権限の異なる map 」が混在している場合です。 </para> <para> @@ -52,8 +54,15 @@ primary_admin_member_map と primary_admin_recipient_map から member_maps = $primary_member_map $admin_member_maps </screen> -そのため、member_maps に対して削除を試みると、勢いあまってリモート管理 -者の分も削除してしまうことになるというわけです。 +そのため、member_maps に対して削除を試みると、 +勢いあまってリモート管理者の分も削除してしまうことになるというわけです。 +</para> + +<para> +こういった曖昧さを避けるために、 +primary_XXX_map と XXX_maps +という分離が考案されたいというわけです +(ようするに &fml4; の反省がいかされています ;-)。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/message/chapter.sgml b/fml/doc/ja/tutorial/message/chapter.sgml index 0b7370a7..f1869484 100644 --- a/fml/doc/ja/tutorial/message/chapter.sgml +++ b/fml/doc/ja/tutorial/message/chapter.sgml @@ -1,5 +1,5 @@ <!-- - $FML: chapter.sgml,v 1.7 2004/10/06 09:07:40 fukachan Exp $ + $FML: chapter.sgml,v 1.8 2008/08/19 03:16:56 fukachan Exp $ --> @@ -13,9 +13,9 @@ <link linkend="module.mail.message"> Mail::Message クラス </link> -のほうを見て下さい。 +を見て下さい。 このクラスが基本的な操作法を提供しています。 -Mail::Bounce や Mail::Delivery を始め、 +Mail::Bounce や Mail::Delivery をはじめ、 あらゆる関数がこのクラスに依存しています。 </para> @@ -27,15 +27,17 @@ Mail::Bounce や Mail::Delivery を始め、 </title> <para> -メールはヘッダに始まりボディ(メール本文)が続きます。MIME/Multipart の -ように、ボディは複数の部分(パート)から成ることもありますが、いずれにせ -よ数珠つなぎ構造です。 +メールはヘッダに始まりボディ(メール本文)が続きます。 +MIME/Multipart のように、 +ボディは複数の部分(パート)から成ることもありますが、 +いずれにせよ数珠つなぎ構造です。 </para> <para> -メールの配送処理だけを考えると、メール本文の細部の構造を気にする必要は -ありません。一方で、フィルタリングを始めとして、メール本文の解析を必要 -としている処理は多々あります。 +メールの配送処理だけを考えるなら、 +メール本文の細部の構造を気にする必要はありません。 +一方で、フィルタリングをはじめとして、 +メール本文の解析を必要としている処理が多々あります。 </para> <para> @@ -51,7 +53,7 @@ Mail::Bounce や Mail::Delivery を始め、 </para> <para> -例えば、このような使い方をします。 +たとえば、このような使い方をします。 <screen> my $fh = new FileHandle $file; my $msg = Mail::Message->parse( { fd => $fh } ); @@ -99,7 +101,9 @@ Mail::Bounce や Mail::Delivery を始め、 </title> <para> -これはメールを構築する際に用いるクラスですが、単なるアダプタです。 +これはメール、 +特にコマンドメールの処理を返す場合などの返答 +などを構築する際に用いるクラスですが、単なるアダプタです。 メールを作成する実体は CPAN の MIME::Lite クラスです。 作成のリクエストは diff --git a/fml/doc/ja/tutorial/message/discussion.sgml b/fml/doc/ja/tutorial/message/discussion.sgml index 03a872b9..bb8ea8de 100644 --- a/fml/doc/ja/tutorial/message/discussion.sgml +++ b/fml/doc/ja/tutorial/message/discussion.sgml @@ -1,5 +1,5 @@ <!-- - $FML: discussion.sgml,v 1.6 2005/06/25 15:11:35 fukachan Exp $ + $FML: discussion.sgml,v 1.7 2008/08/19 03:16:56 fukachan Exp $ --> @@ -10,8 +10,13 @@ <para> ＭＬドライバは、適宜、エラーメッセージを送信者に返す必要があります。 -そしてエラーメッセージは言語依存です。 -よって、何らかの形で言語変換をしてから送り出す必要があります。 +そしてエラーメッセージは送信者の言語依存でないといけないでしょう。 +</para> + +<para> +よって、 +多国語化対応と適切な文字コード変換をしてから送り出す必要があります。 +そして、そのための処理関数群が必要です。 </para> @@ -26,14 +31,14 @@ <screen> Mesg(*e, キーワード, デフォルトのメッセージ, 変換に使う引数); </screen> -の形で呼び出す関数がありました。 +の形で呼び出すメッセージ処理関数がありました。 </para> <para> Mesg() は /usr/local/fml/messages/Japanese/ 以下にあるファイル群に対し て、キーワード検索を行ないます。各ファイルにはカテゴリごとに分類された -キーワードとメッセージが定義されています。つまり各ファイルに複数のキー -ワードが定義されています。 +キーワードとメッセージが定義されています。 +つまり各ファイルに複数のキーワードが定義されています。 </para> <para> @@ -42,6 +47,11 @@ Mesg() は /usr/local/fml/messages/Japanese/ 以下にあるファイル群に対し ファイルの not_found という欄が該当します。 </para> +<para> +あまり素敵なものではありませんでした。 +といって、locale が素敵というものでもないですなぁ… +</para> + </sect2> @@ -95,8 +105,8 @@ locale の定義ファイル( <para> 言語問題の一つは locale に対応するか？という問題です。 -makefml を筆頭に、各種コマンド群のエラーメッセージの日本語化 -を考えると、 +makefml を筆頭に、 +各種コマンド群のエラーメッセージの日本語化を考えると、 locale を考えておくのも悪くはないのかとも思います。 この場合は locale ぽくするために <screen> @@ -119,11 +129,11 @@ locale を考えておくのも悪くはないのかとも思います。 FML::Message::ja::キーワード </screen> というクラスをじゃんじゃん作るような作り方になるでしょう。 -例えば +たとえば <screen> FML::Message::ja::not_found </screen> -などと2、300個のファイルが作られることになります。 +などと 2、300 個のファイルが作られることになります。 </para> <para> diff --git a/fml/doc/ja/tutorial/message/language.sgml b/fml/doc/ja/tutorial/message/language.sgml index 34364ef5..5ef79bc0 100644 --- a/fml/doc/ja/tutorial/message/language.sgml +++ b/fml/doc/ja/tutorial/message/language.sgml @@ -1,5 +1,5 @@ <!-- - $FML: language.sgml,v 1.7 2005/06/25 15:11:35 fukachan Exp $ + $FML: language.sgml,v 1.8 2008/08/19 03:16:56 fukachan Exp $ --> @@ -36,21 +36,22 @@ $curproc->reply_message_nl('error.already_member', <screen> $_arg_address </screen> -は reply_message_nl の引数のハッシュリファレンスとして与えられた値へ展 -開されます。上の例でいえば、メッセージテンプレート中の $_arg_address +は reply_message_nl() +の引数のハッシュリファレンスとして与えられた値へ展開されます。 +上の例でいえば、メッセージテンプレート中の $_arg_address が引数中の _arg_address の値で展開されます。 </para> <para> -また config.cf 中で定義されている変数も同様に展開可能です。 -例えばテンプレート中の $ml_name はＭＬ名に展開されるようになっています。 +また config.cf 中で定義されている変数はメッセージ中でも展開可能です。 +たとえばテンプレート中の $ml_name は +config.cf 中と同様にＭＬ名に自動展開されます。 </para> <para> -こういったことがあるので、渡す引数に $_arg_ などという prefix をつけて -いるわけです。つまり、config.cf の変数群とぶつからないようにするため。 +このため、 +つまり config.cf の変数群とぶつからないようにするため、 +渡す引数に $_arg_ などという prefix をつけているわけです。 </para> </sect1> - - 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 で取り扱われる変数の表現があれば解決でしょうか？ 現在は、この目的のために &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> diff --git a/fml/doc/ja/tutorial/module/Message.sgml b/fml/doc/ja/tutorial/module/Message.sgml index 560f703e..f76444a6 100644 --- a/fml/doc/ja/tutorial/module/Message.sgml +++ b/fml/doc/ja/tutorial/module/Message.sgml @@ -1,5 +1,5 @@ <!-- - $FML: Message.sgml,v 1.3 2005/06/25 15:11:36 fukachan Exp $ + $FML: Message.sgml,v 1.4 2008/08/19 03:16:57 fukachan Exp $ --> <chapter id="module.mail.message"> @@ -13,8 +13,8 @@ </title> <para> -このオブジェクトモジュールはメールの解析と、 -解析されたデータ構造へのさまざまな操作手段を提供しています。 +Mail::Message クラスはメールの解析と、 +解析されたデータ構造へのさまざまな操作手段を提供します。 </para> <para> @@ -39,18 +39,18 @@ header -> preamble -> part1 -> part2 -> trailor </para> <para> -header は Mail::Message のタイプが text/rfc822-headers で、 -data が Mail::Header オブジェクトになります。 +メールヘッダは Mail::Message のタイプが text/rfc822-headers で、 +その data が Mail::Header オブジェクトになります。 一方 part1 は text/plain で、 -data 部分が文字列へのリファレンスです。 +data 部分が文字列(テキスト)へのリファレンスです。 </para> <para> 参照: <ulink url="../../en/modules/Mail/Message.txt"> -Mail::Message モジュールのマニュアル +Mail::Message モジュールのマニュアル(英語) </ulink> </para> @@ -64,12 +64,13 @@ Mail::Message モジュールのマニュアル <para> parse() メソッドは引数で与えられたファイル(名)かファイルディスクリプタ -に対しメッセージの解析をします。 +に対しメッセージの解析を試みます。 </para> <para> data_type_list() は鎖の列の情報を返します。情報は ARRAY REFERENCE の形 -で返されます。例えば MIME/Multipart は次のように表現されています。 +で返されます。例えば MIME/Multipart は次のように表現されています +(ちなみに、以下の表示はデバッグモードで出力されるものです)。 <screen> type[ 1]: text/rfc822-headers | multipart/mixed type[ 2]: multipart/mixed | multipart/mixed @@ -82,7 +83,7 @@ data_type_list() は鎖の列の情報を返します。情報は ARRAY REFERENCE の形 type[ 9]: text/plain | multipart/mixed </screen> 真中の列が各オブジェクトの種別を表しています。 -右端は全体の mime type です。 +右端はメール全体の mime type です。 </para> </sect1> @@ -98,21 +99,21 @@ new() メソッドは通常、新しいメッセージを作る際に使われます。 </para> <para> -MIME/multipart 専用のためのメソッドもあります。 +MIME/multipart 作成専用のメソッドもあります。 <screen> build_mime_multipart_chain($args) parse_and_build_mime_multipart_chain($args) build_mime_header($args) </screen> -これらのメソッドを直接呼び出すことは実際ないので、 -これらは private に移行するかもしれません。 -だから、とりえあずこれらは使わないでください。 +注意: これらのメソッドを直接呼び出すことは実際ないので、 +将来、これらは private methods に移行するかもしれません。 +これらのメソッドは使わないでください。 </para> <para> -しかしながら、MIME/mulitpart の作成には -Mail::Message::Compose クラスがあります。 -実のところ、このクラスの実態は MIME::Lite そのものです :-) +実際のところ MIME/mulitpart の作成には +Mail::Message::Compose クラスを使っています。 +実のところ、このクラスの実態は CPAN の MIME::Lite そのものです :-) </para> </sect1> @@ -125,39 +126,45 @@ Mail::Message::Compose クラスがあります。 <para> dup_header() メソッドは -RFC822 型のメッセージのヘッダ部分のみのコピーを行ないます。 -メールの本体の部分はそのままです。 +RFC822 型メッセージのヘッダ部分のみをコピーします。 +メール本体の部分はそのままです。 複製されたヘッダオブジェクトからのリンクは メールの本体です。 <screen> +$header1 = $message0->dup_header0; + |<--------------- メール本体 -------------> -header0 ----> part1 -> part2 -> ... - A - | -dup_header0 --- +$header0 ---> part1 -> part2 -> ... + A + | +$header1 ------+ </screen> </para> <para> -whole_message_header() -はメッセージの中のヘッダ部分のオブジェクトを返します。 -文字列ではないことに注意して下さい。 +whole_message_header() +メソッドはメッセージ中の「ヘッダ部分のオブジェクト」を返します。 +「文字列ではない」ことに注意して下さい。 </para> <para> __head_message() は鎖の先頭のオブジェクトを返します。 __last_message() は鎖の最後のオブジェクトを返します。 -プライベートなので、これらのメソッドは使わないで下さい。 -__head_message() は、通常、図の header オブジェクトを返すことになりま -すので、多くの場合 whole_message_header() と等価です。 +モジュールの中で使われていますが、 +これらはプライベート・メソッドなので、 +これらのメソッドは使わないで下さい。 +将来、これらのコードは消去します。 +なお __head_message() は、 +通常、図の header オブジェクトを返すことになりますので、 +多くの場合 whole_message_header() と等価です。 </para> <para> header_data_type() -はメール全体のタイプ(文字列)を返します。 -つまり、このメッセージは単なるテキストなのかマルチパートなのか？などを -教えてくれます。 +メソッドはメール全体のタイプ(文字列)を返します。 +つまり、このメッセージは単なるテキストなのかマルチパートなのか？ +などの情報を教える関数です。 </para> </sect1> @@ -169,7 +176,7 @@ header_data_type() </title> <para> -以下では、このような鎖を例にとることにします。 +本節では、次のようなオブジェクトの鎖を例にとることにします。 <screen> (multipart でない場合) @@ -181,19 +188,20 @@ header -> preamble -> part1 -> part2 -> trailor </screen> </para> +<para> +(一部、前述の繰り返しになります)。 +</para> <para> -まず header_data_type() -はメール全体のタイプ(文字列)を返します。 -つまり、このメッセージは単なるテキストなのかマルチパートなのか？などを -教えてくれます。 -つまり header の Content-Type で得られる情報です。 +header_data_type() +メソッドはメール全体のタイプ(文字列)を返します。 +つまり、header の Content-Type で得られる情報です。 </para> <para> whole_message_body() メソッドは body ないしは part1 の部分のオブジェクトを返します。 -whole_message_body_head() メソッドも同じ操作をします。 +whole_message_body_head() メソッドも同じ返り値です。 </para> <para> @@ -222,8 +230,10 @@ plain/text タイプのメッセージ部分に着目することが多いので </title> <para> -find() メソッドは Mail::Message の特定のタイプを探し、 +find() メソッドは Mail::Message オブジェクトの特定のタイプを探し、 最初に見つけたオブジェクトを返します。 +ヘッダの Content-Type: ではありません。 +注意。 </para> </sect1> @@ -264,7 +274,7 @@ reset_print_mode() <para> size() は(鎖の一つ一つの Mail::Message)オブジェクトのサイズを返します。 -メール全体ではありません。 +メール全体ではありません。注意。 header_size() や body_size() @@ -273,8 +283,13 @@ body_size() <para> is_empty() -はオブジェクトが空かどうかを教えてくれます。 +はオブジェクトのデータが空かどうかを教えてくれます。 +</para> + +<para> +これらはフィルタリングで有用です。 </para> + </sect2> @@ -285,25 +300,25 @@ is_empty() <para> envelope_sender() -は -メールの送信者情報(文字列)を返します。 +はメールの送信者情報(文字列)を返します。 +文字通り、いわゆる Envelope Sender 情報です。 </para> <para> data_type() -は +メソッドは Mail::Message オブジェクトのタイプ(文字列)を返します。 -これは、メール全体のタイプ（マルチパートとか text/plain) -どではなく、鎖の各部分のオブジェクトのタイプであることに注意して下さい。 +これは、メール全体のタイプ（マルチパートとか text/plain)ではなく、 +鎖の各部分のオブジェクト・タイプであることに注意して下さい。 </para> <para> encoding_mechanism() -は +メソッドは Mail::Message オブジェクトのエンコーディングメカニズム(文字列)を返します。 -エンコーディングされていないなら undef が返ります。 -これは、メール全体のタイプ（マルチパートとか text/plain) -ではなく、鎖の各部分のオブジェクトのタイプであることに注意して下さい。 +エンコーディングされていない場合 undef が返ります。 +これは、メール全体のタイプ（マルチパートとか text/plain)ではなく、 +鎖の各部分のオブジェクト・タイプであることに注意して下さい。 </para> </sect2> @@ -311,12 +326,12 @@ Mail::Message オブジェクトのエンコーディングメカニズム(文字列)を返します。 <sect2> <title> - Mail::Message 内の構造 + Mail::Message オブジェクト内部の構造を知る </title> <para> num_paragraph() -は +メソッドは、 その Mail::Message オブジェクトの中に 何個のパラグラフがあるか(数字)を返します。 </para> @@ -324,23 +339,25 @@ num_paragraph() <para> nth_paragraph(数字) -は +メソッドは 「数字」番目のパラグラフの内容を文字列として返します。 例えば、一番目のパラグラフは 0 ではなく 1 と指定して下さい。 -ここは、わざとＣ言語風ではなく人間に分かりやすいようにしてあります。 +ここは、わざとＣ言語風ではなく人間に分かりやすいように +「 1から始まる仕様」としてあります。 </para> <para> header() -は +メソッドは MIME/multipart の各ブロックにあるヘッダ部分を返します。 data() -は、データの部分です。 +メソッドは、データの部分です。 それぞれ message_fields($size) +および message_text($size) -の alias です。 +メソッドの alias になっています。 </para> </sect2> @@ -356,7 +373,7 @@ message_text($size) <para> <ulink url="../../en/modules/Mail/Message.txt"> -Mail::Message モジュールの(英語)マニュアル +Mail::Message モジュールマニュアル(英語) </ulink> </para> </sect1> diff --git a/fml/doc/ja/tutorial/module/create.sgml b/fml/doc/ja/tutorial/module/create.sgml index d3340ec3..93e39e51 100644 --- a/fml/doc/ja/tutorial/module/create.sgml +++ b/fml/doc/ja/tutorial/module/create.sgml @@ -1,5 +1,5 @@ <!-- - $FML: create.sgml,v 1.3 2005/06/25 15:11:36 fukachan Exp $ + $FML: create.sgml,v 1.4 2008/08/19 03:16:57 fukachan Exp $ --> <chapter id="module.create"> @@ -9,11 +9,38 @@ <para> -ここでは、単純なスケジュール表示ソフトを例にとり、&fml8; のフレームワー -クの中で新しいプログラムを追加するにはどうすれば良いのかを説明します。 +ここでは、単純なスケジュール表示ソフトを例にとり、 +&fml8; のフレームワーク中で +新しいプログラムを追加するにはどうすれば良いのかを説明します。 以下、プログラム名は fmlsch とし、その CGI 版が fmlsch.cgi です。 </para> +<para> +なお、&fml8; ＋サードパーティ拡張として出荷するソフトウエアでは、 +3rdparty/ 以下に同様の配置でファイルを生成し、 +<footnote> + +<para> +とはいえ、さすがに設定ファイルは、 +さすがに fml リポジトリ以下の設定を変更する必要がありますね。 +「追加で済むもの」 +であればサードパーティ以下にスクリプトを作ればすむかと… +</para> + +<para> +たぶん、そういった場合は、 +サードパーティ以下に fml リポジトリ以下を参考に、 +インストーラを一式作るほうが楽でしょう。 +</para> + +<para> +それでも、トップディレクトリの Makefile と configure の変更は必要ですなぁ。 +</para> + +</footnote> +インストーラ等の設定ファイルを変更して下さい。 +</para> + <sect1> <title> @@ -29,12 +56,13 @@ <para> fml/bin/fmlsch.in シェルスクリプトを用意し、 fml/etc/install.cf.in の bin_programs 変数に fmlsch を追加します。 -bin_programs にあるスクリプトはインストーラがインストールしてくれます。 +bin_programs にあるスクリプトはインストーラが +$prefix/bin/ へインストールする対象です。 </para> <para> fml/bin/fmlsch および fml/etc/install.cf の生成は -configure が行ないます。 +configure (GNU configure)が行ないます。 configure.in に、この２つのファイルの変数展開をするように登録し、 autoconf を実行して configure を生成して下さい。 </para> @@ -54,10 +82,10 @@ fml/lib/FML/Demo/Calendar.pm を書きます。 </para> <para> -また、必要な他にライブラリがあれば適宜輸入してください。 +また、ほかに必要なライブラリがあれば適宜輸入してください。 今回は CPAN から HTML-CalendarMonthSimple-1.02.tar.gz -を輸入します。 +をインストールする必要があります。 </para> <para> @@ -75,9 +103,17 @@ Date-Calc も必要なので適宜インストールしてください。 <para> 仕事のほとんどの部分は FML::Demo::Calendar が実行しますが、 &fml8; のブートローダから FML::Demo::Calendar を呼び出すために -FML::Process:: クラスを修正する必要があります。 +FML::Process::Calender クラスを作成します。 </para> +<caution> +<para> +クラスの階層は fml/etc/modules の設定次第なので、 +FML::Process::Calender である必要はなく、 +どの階層でも(もちろん FML:: 以外でも)かまいません。 +</para> +</caution> + <para> まず、fmlsch プロセスの初期化から実行といった大まかな一連の手順を fml/lib/FML/Process/Calender.pm @@ -89,12 +125,12 @@ fml/lib/FML/Process/Calender.pm </para> <para> -そして、ブートローダーへ fmlsch の場合は FML::Process::Calender を呼び -出せば良いことを教えるために -etc/modules +そして、ブートローダーへ fmlsch プログラムが起動された場合には +FML::Process::Calender を呼び出すことを教えるために +fml/etc/modules ファイル と -etc/command_line_options -に fmlsch のモジュール名との対応関係を追加します。 +fml/etc/command_line_options ファイルに +fmlsch のモジュール名との対応関係を追加します。 </para> @@ -120,15 +156,22 @@ FML::Process::Calender::run() メソッドだけ用意すればおしまいです。 <para> -改造の仕方はモジュールが FML::CGI:: クラスになる以外は fmlsch の場合と -同様です。FML::CGI::Calender は FML::Process::CGI のサブクラスです。 +改造の仕方はモジュールが +FML::CGI:: クラスになる以外は fmlsch の場合と同様です。 +FML::CGI::Calender は FML::Process::CGI のサブクラスです。 +</para> + +<para> +未定義のものについては FML::Process::CGI や FML::Process::Kernel +がよきにはからいます。 </para> <para> -未定義のものについては FML::Process::CGI や FML::Process::Kernel がよ -きにはからいます。また、CGI.pm は FML::Process::CGI が使い、HTTP -header を生成しています。あくまでも最低限の処理なので -FML::CGI:: のモジュールで適宜 HTML の出力を補佐してあげます。 +また、HTML 言語のほとんどは FML::Process::CGI が +Perl デフォルトの CGI.pm を使っています。 +HTTP header などの生成も CGI.pm モジュールです。 +これらは、あくまでも最低限の処理なので +FML::CGI:: 以下のモジュール群が適宜 HTML の出力を補正しています。 </para> </sect1> diff --git a/fml/doc/ja/tutorial/module/encode.sgml b/fml/doc/ja/tutorial/module/encode.sgml index 5309876e..6449d220 100644 --- a/fml/doc/ja/tutorial/module/encode.sgml +++ b/fml/doc/ja/tutorial/module/encode.sgml @@ -1,5 +1,5 @@ <!-- - $FML$ + $FML: encode.sgml,v 1.2 2003/04/15 14:51:42 fukachan Exp $ --> <chapter id="module.mail.message.encode"> @@ -7,6 +7,12 @@ Mail::Message::Encode クラス </title> + +<sect1 id="module.mail.message.encode.examplee"> + <title> + Mail::Message::Encode の使い方の見本 + </title> + <para> [リファレンス] fml-help ML's Count: 02012, 02013, 02016 など @@ -15,6 +21,8 @@ fml-help ML's Count: 02012, 02013, 02016 など <screen> [使い方の例] + * fml 8.0 風の使い方 + use Mail::Message::Encode; my $encode = new Mail::Message::Encode; my $str_euc = $encode->convert( $s, 'euc-jp' ); @@ -27,19 +35,22 @@ fml-help ML's Count: 02012, 02013, 02016 など my $fp = sub { ... }; $encode->run_in_chcode( $fp, $oout, $in ); - * 4.0 互換 + * fml 4.0 互換風の使い方 + ues Mail::Message::Encode qw(STR2EUC); my $euc_s = STR2EUC( $s ); </screen> +</sect1> + -<sect1> +<sect1 id="module.mail.message.encode.specification"> <title> - Mail::Message::Encode の仕様 + Mail::Message::Encode の仕様の粗筋 </title> <para> -本体は _convert_str_ref() にまとめる。 +本体はプライベートメソッド _convert_str_ref() にまとめてある。 <screen> sub convert # 引数が STR @@ -100,29 +111,56 @@ $x = $encode->base64($s); </sect1> -<sect1> +<sect1 id="module.mail.message.encode.run.in.code"> <title> - run_in_chcode() + ユーティリティ run_in_chcode() </title> <para> -言語依存処理の過程では、プログラムの扱いやすいコードに変換し、処理を行 -なう関数が多数存在します。そこで、そういった関数を用意すると便利です。 -<screen> -run_in_chcode の実装例 +言語依存処理の過程では、プログラムの扱いやすい文字コードに変換し、 +処理を行なう関数が多数存在します。 +そこで、そういった処理のための下請け関数を用意すると便利です。 +</para> -sub run_in_chcode +<para> +run_in_chcode() は、 +関数 $proc を実行します。 +引数は、あらかじめ指定された文字コードに変換後、 +関数 $proc に渡されるという仕様です。 +</para> + +<para> +<screen> +sub run_in_code { - my ($self, $proc, $s, $out_code, $in_code) = @_; + my ($self, $proc, $s, $args, $out_code, $in_code) = @_; + my $proc_status = undef; + + my $obj = new Mail::Message::Encode; + my $conv_status = $obj->convert_str_ref(\$s, $out_code, $in_code); - my $conv_status = convert_str_ref($s, $EUC_JP, $in_code); - my $proc_status = &$proc($s, @_); - convert_str_ref($s, $out_code, $EUC_JP) if $conv_status && $out_code; - return wantarray ? ($conv_status, $proc_status): $conv_status; + # XXX-TODO: validate $proc name regexp. + eval q{ + $proc_status = &$proc($s, $args); + }; + + # XXX-TODO: correct ? + if ($conv_status && $out_code) { + $obj->convert_str_ref($s, $out_code, $in_code); + } + + return wantarray ? ($conv_status, $proc_status): $conv_status; } </screen> +これは、次のように動作します。 +<screen> +$s は EUC-JP へ変換。 +$proc($s, $args); を実行 +$proc の実行結果を返す。 +</screen> </para> </sect1> + </chapter> diff --git a/fml/doc/ja/tutorial/module/nativelanguage.sgml b/fml/doc/ja/tutorial/module/nativelanguage.sgml index f8334d4b..583b86f2 100644 --- a/fml/doc/ja/tutorial/module/nativelanguage.sgml +++ b/fml/doc/ja/tutorial/module/nativelanguage.sgml @@ -1,5 +1,5 @@ <!-- - $FML: nativelanguage.sgml,v 1.3 2003/04/15 14:51:43 fukachan Exp $ + $FML: nativelanguage.sgml,v 1.4 2008/08/19 03:16:57 fukachan Exp $ --> <chapter id="nativelanguage"> @@ -8,14 +8,18 @@ </title> <para> -fml 内部では言語に依存した変換処理が必要です。 -例えば、JIS と EUC の相互変換は随所で必要です。 -これはメールでは JIS が使われますが、 -プログラムでは EUC の方が扱いやすいためです。 +&fml8; 内部では言語と文字コードに依存した変換処理が必要です。 +たとえば、JIS (ISO-2022-JP)と EUC の相互変換は随所で行なわれています。 +これはメールでは JIS コードが使われますが、 +プログラムでは EUC コードの方が扱いやすいためです。 </para> <para> -コマンドの返事の言語依存性については +本章では、言語依存の処理関数について解説します。 +</para> + +<para> +なお、コマンドに対する返事の言語依存性については <link linkend="message.nl"> 『メッセージの他国語化』 </link> @@ -25,22 +29,22 @@ fml 内部では言語に依存した変換処理が必要です。 <sect1 id="nativelanguage.overview"> <title> - 何か::Language:: + クラス::Language:: </title> <para> -言語依存のクラス名は「なにか::Language::」となります。これらの階層以下 -に言語依存モジュール群が配置されます。 +言語依存のクラス名は「クラス::Language::」となります。 +これらの階層以下に言語依存モジュール群が配置されます。 </para> <para> -例えば以下のようなモジュールがあります。 +たとえば次のようなモジュールがあります。 <screen> FML::Language::Japanese::String.pm Mail::Bounce::Language::Japanese.pm </screen> -前者は、FML モジュール群のために日本語依存の文字列処理関数を -提供しています。 +前者は、FML モジュール群のために、 +日本語依存の文字列処理関数を提供しています。 後者は Mail::Bounce 階層以下のモジュールに対して、 日本語に依存したエラーメール解析ルーチンを提供しています。 </para> |