merge 01_* with tutorial/

5 files changed, 247 insertions, 15 deletions

diff --git a/fml/doc/ja/tutorial/book.sgml b/fml/doc/ja/tutorial/book.sgml
index 4545810d..aabb4d24 100644
--- a/fml/doc/ja/tutorial/book.sgml
+++ b/fml/doc/ja/tutorial/book.sgml
@@ -2,7 +2,7 @@
 This is an sgml using DocBook dtd. Use sgmltools version 2.0.x or above
 to generate various output formats.
 
-$FML: book.sgml,v 1.50 2003/02/18 02:24:46 fukachan Exp $
+$FML: book.sgml,v 1.51 2003/02/18 13:40:19 fukachan Exp $
 -->
 
 <!doctype book public "-//FML//DTD DocBook V3.1-Based Extension//EN" [
@@ -174,6 +174,7 @@ $FML: book.sgml,v 1.50 2003/02/18 02:24:46 fukachan Exp $
 	&chapter.module.io.adapter;
 	&chapter.module.mail.message;
 	&chapter.module.nl;
+	&chapter.module.encode;
 	&chapter.module.create;
   </part>
 
diff --git a/fml/doc/ja/tutorial/include/chapters.ent b/fml/doc/ja/tutorial/include/chapters.ent
index ee79aa3e..d19b6b2e 100644
--- a/fml/doc/ja/tutorial/include/chapters.ent
+++ b/fml/doc/ja/tutorial/include/chapters.ent
@@ -1,5 +1,5 @@
 <!--
-	$FML: chapters.ent,v 1.64 2003/02/18 02:29:13 fukachan Exp $
+	$FML: chapters.ent,v 1.65 2003/02/18 13:40:20 fukachan Exp $
 -->
 
 <!entity versin "1.1">
@@ -168,6 +168,7 @@
 <!entity chapter.module.mail.message SYSTEM "module/Message.sgml">
 <!entity chapter.module.nl           SYSTEM "module/nativelanguage.sgml">
 <!entity chapter.module.create       SYSTEM "module/create.sgml">
+<!entity chapter.module.encode       SYSTEM "module/encode.sgml">
 
 
 
diff --git a/fml/doc/ja/tutorial/internals/bootloader.sgml b/fml/doc/ja/tutorial/internals/bootloader.sgml
index 56fe2d9d..f436e301 100644
--- a/fml/doc/ja/tutorial/internals/bootloader.sgml
+++ b/fml/doc/ja/tutorial/internals/bootloader.sgml
@@ -1,5 +1,5 @@
 <!--
-   $FML: bootloader.sgml,v 1.7 2002/07/02 10:39:35 fukachan Exp $
+   $FML: bootloader.sgml,v 1.8 2002/07/06 14:55:18 fukachan Exp $
 -->
 
 <chapter id="bootloader">
@@ -13,18 +13,32 @@
 めに、本章で述べるようなブートストラップの過程があります。
 
 <screen>
-fml が boot していくイメージ
-
-libexec/loader ->
-     FML::Process::Switch ->
-         FML::Process::Flow ->
-              FML::Process::それぞれのプログラムのモジュール
+fml (libexec/distribute) が boot していくイメージ
+
+       functions                class
+       ----------------------------------------
+
+       main::Bootstrap()        libexec/loader
+            |
+            V
+       main::Bootstrap2()       FML::Process::Switch
+            |
+            V
+       ProcessSwitch()          FML::Process::Switch
+            |
+            |
+            | switch to ($obj = FML::Process:Distribute)
+            |
+            V                   
+       ProcessStart($obj,$args) FML::Process::Flow
 </screen>
 </para>
 
 
-<sect1>
-   <title> 例: 配送の場合 </title>
+<sect1 id="bootloader.example.distribute">
+	<title>
+	例: 配送の場合
+	</title>
 
 <para>
 loader から次々と呼ばれていく様子は、例えば配送処理の場合、次のよう
@@ -59,8 +73,10 @@ FML::Process::Distribute を実行していくという流れになります。
 </sect1>
 
 
-<sect1>
-  <title> FML::Process:: クラスの階層構造 </title>
+<sect1 id="bootloader.classes">
+	<title>
+	FML::Process:: クラスの階層構造
+	</title>
 
 <para>
 <screen>
@@ -77,7 +93,7 @@ FML::Process::Mead       >-|    |
 </sect1>
 
 
-<sect1>
+<sect1 id="bootloader.classes2">
 	<title>
 	プロセス実行時に使われるモジュール群
 	</title>
@@ -167,4 +183,54 @@ $process->finish($args);
 </sect1>
 
 
+<sect1 id="bootloader.resolv.mlxxx">
+	<title>
+	ml_name と ml_domain の値はどこで解決するのが正しいか？
+	</title>
+
+<para>
+<screen>
+main::Bootstrap()
+
+	main.cf から fml のバージョン依存性を解く
+
+	hints を渡す (CGI のみ)	
+		◎ CGI だけ
+		嘘の入力がありうる
+		そのため、loader に hints として
+		ml_domain や ml_name がハードコードされている。 
+
+
+main::Bootstrap2()
+ProcessSwitch()
+
+	使うモジュール( Process::なんか )を決める
+		読み込むべき cf ファイルの決定（なんで？）
+		ライブラリパスの決定や @INC の修正など
+
+	hints を渡す？使う？ (CGI のみ？)	
+
+
+ProcessStart($obj,$args)
+
+   処理本体のスタート
+
+	new
+
+	prepare
+		ml_name と ml_domain の決定
+		CGI からの入力を解析する
+			hints を使う？(CGI のみ？)	
+
+		読み込むべき cf ファイルの決定
+
+		parse
+			メールを読み込む
+			コマンドラインを解析する
+</screen>
+</para>
+
+</sect1>
+
+
 </chapter>
diff --git a/fml/doc/ja/tutorial/internals/cgi.sgml b/fml/doc/ja/tutorial/internals/cgi.sgml
index 8525bde4..8ab251d4 100644
--- a/fml/doc/ja/tutorial/internals/cgi.sgml
+++ b/fml/doc/ja/tutorial/internals/cgi.sgml
@@ -1,5 +1,5 @@
 <!--
-   $FML: cgi.sgml,v 1.8 2002/07/19 03:21:55 fukachan Exp $
+   $FML: cgi.sgml,v 1.9 2002/07/23 09:34:34 fukachan Exp $
 -->
 
 <chapter id="internalcgi">
@@ -99,6 +99,47 @@ sw   south  se
 </para>
 
 
+<sect2>
+	<title>
+	現在の CGI の画面の構造	
+	</title>
+
+<para>
+以下のような３x３のテーブル構造をとっており、
+<screen>
+run_cgi_main
+			run_cgi_title
+run_cgi_navigator	run_cgi_menu	run_cgi_command_help
+run_cgi_options
+</screen>
+HTML のレベルでは、TABLE 命令を使って疑似的なナビゲーションバーのよう
+なものを作っている。そして、ハッシュテーブルで定義されている関数を決め
+られた順番で実行し、テーブルを作成している。
+</para>
+
+<para>
+run_cgi_main() は何らかの処理をしない限り何も表示しない。
+大抵は「なし」か「OK …」程度。エラーメッセージを表示することもある。
+また、この関数はＭＬ一覧などをきちんと最新の情報にするために、
+画面を描く前に実行する必要がある。
+</para>
+
+<para>
+ちなみに、run_cgi_main() は個々の関数を呼び出すためのトップレベルのア
+ダプター層で、FML::CGI::Menu::Admin に定義されている。個々のコマンドは 
+makefml の時と同様にこの関数経由で実行される。
+</para>
+
+<para>
+ただし、ログやメンバーリスト一覧のように run_cgi_menu() から結果の表示
+をしているものもある。これは表示のオプションの指定をさせるために、
+run_cgi_main() ではなく run_cgi_menu() 経由で表示しているともいえるの
+だが、なにしろコマンドの結果の表示が長いので、今のように menu() 経由の
+ほうがよいと思われる。
+</para>
+
+</sect2>
+
 </sect1>
 
 
diff --git a/fml/doc/ja/tutorial/module/encode.sgml b/fml/doc/ja/tutorial/module/encode.sgml
new file mode 100644
index 00000000..42e7e346
--- /dev/null
+++ b/fml/doc/ja/tutorial/module/encode.sgml
@@ -0,0 +1,123 @@
+<chapter id="module.mail.message.encode">
+	<title>
+	Mail::Message::Encode クラス
+	</title>
+
+<para>
+[リファレンス]
+fml-help ML's Count: 02012, 02013, 02016 など
+</para>
+
+<screen>
+[使い方の例]
+
+	use Mail::Message::Encode;
+	my $encode  = new Mail::Message::Encode;
+	my $str_euc = $encode->convert( $s, 'euc-jp' );
+	my $str_euc = $encode->convert( $s, 'euc-jp', 'iso-2022-jp' );
+
+	my $encode  = new Mail::Message::Encode;
+	my $status  = $encode->convert_str_ref( \$s, 'euc-jp' );
+	my $status  = $encode->convert_str_ref( \$s, 'euc-jp', 'jis' );
+
+	my $fp = sub { ... };
+	$encode->run_in_chcode( $fp, $oout, $in );
+
+   * 4.0 互換
+	ues Mail::Message::Encode qw(STR2EUC);
+	my $euc_s = STR2EUC( $s );
+</screen>
+
+
+<sect1>
+	<title>
+	仕様
+	</title>
+
+<para>
+本体は _convert_str_ref() にまとめる。
+
+<screen>
+   sub convert # 引数が STR
+   {
+	my ($self, $str, $out_code, $in_code) = @_;
+	_convert_str_ref(\$str, $out, $in);
+
+        return $str;
+   }
+
+
+   sub convert_str_ref # 引数が STR_REF
+   {
+	my ($self, $str, $out, $in) = @_;
+	_convert_str_ref($str, $out, $in);
+   }
+
+
+   sub _convert_str_ref # 引数が STR_REF
+   {
+        my ($str, $out, $in) = @_;
+
+        # 1. 推測
+        もし $in がない → 推測 → 失敗 → 0 をかえす？ 
+
+        # 2. 変換をトライ
+        if ($in がわかった or $in が指定された) {
+                $out へ変換
+                jcode, Jcode, Encode は perl バージョンによって
+                よろしく変換をがんばる
+                return 1 ; ＃成功
+        }
+        else { # principle of least surprise ?
+                なにもしない＃ str はそのまま返す
+        }
+
+        return 0 ; # 失敗
+   }
+</screen>
+
+<screen>
+   sub base64 {}
+   sub quoted_printable {}
+
+	があるといいかな〜
+
+	$x = $encode->base64($s);
+</screen>
+
+また、互換性というか便宜上、STR2XXX() も準備する。
+<screen>
+   STR2EUC(  $str, [$icode] )
+   STR2JIS(  $str, [$icode] )
+   STR2SJIS( $str, [$icode] )
+</screen>
+は convert_str_ref を wrap する。
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	特別な関数
+	</title>
+
+<para>
+euc にしてごにょごにょ する典型的なコードは全部 wrap する。
+<screen>
+# change code and do $proc
+sub run_in_chcode
+{
+   my ($self, $proc, $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;
+}
+</screen>
+</para>
+
+</sect1>
+
+</chapter>