translated

4 files changed, 465 insertions, 0 deletions

diff --git a/fml/doc/en/tutorial/customize/ml.hier.ml b/fml/doc/en/tutorial/customize/ml.hier.ml
new file mode 100644
index 00000000..6aeb282a
--- /dev/null
+++ b/fml/doc/en/tutorial/customize/ml.hier.ml
@@ -0,0 +1,49 @@
+<!--
+   $FML$
+   $jaFML: ml.hier.ml,v 1.1 2002/07/29 12:16:19 fukachan Exp $
+
+-->
+
+<sect1 id="config.hier.ml">
+	<title>
+	case study: hierarchical ML
+	</title>
+
+<para>
+Consider usual ML's which allows post from registered members.
+For example, sales 1, 2 and 3 division.
+</para>
+
+<para>
+Create sales-1, sales-2 and sales-3 ML.
+Each division manages each member list.
+Also, create sales ML other than that to inform the whole sales members.
+If you send a mail to sales ML, the mail is sent to all members of
+sales-1, sales-2 and sales-3 ML.
+</para>
+
+<para>
+Define the following $recipient_maps in the config.cf of sales ML.
+<screen>
+recipient_maps 	+=	$ml_home_dir/../sales-1/recipients
+recipient_maps 	+=	$ml_home_dir/../sales-2/recipients
+recipient_maps 	+=	$ml_home_dir/../sales-3/recipients
+</screen>
+</para>
+
+<para>
+Define $member_maps in the same way to allow post from all sales
+members:
+<screen>
+member_maps 	+=	$ml_home_dir/../sales-1/members
+member_maps 	+=	$ml_home_dir/../sales-2/members
+member_maps 	+=	$ml_home_dir/../sales-3/members
+</screen>
+Instead of $member_maps change, it is simple that you allow post from
+anybody. If so set
+<screen>
+post_restrictions	=	permit_anyone
+</screen>
+</para>
+
+</sect1>
diff --git a/fml/doc/en/tutorial/delivery/chapter.sgml b/fml/doc/en/tutorial/delivery/chapter.sgml
new file mode 100644
index 00000000..2b5cc36a
--- /dev/null
+++ b/fml/doc/en/tutorial/delivery/chapter.sgml
@@ -0,0 +1,125 @@
+<!--
+   $FML$
+   $jaFML: chapter.sgml,v 1.12 2003/04/15 14:51:37 fukachan Exp $
+-->
+
+<chapter id="delivery">
+	<TITLE>
+	&fmldevel; mail delivery system
+	</TITLE>
+
+<sect1 id="fmldevel-delivery">
+	<title>
+	The difference between &fml4; and &fmldevel;
+	</title>
+
+<para>
+One of puposes of &fmldevel; is unification and abstraction of member
+list operations. Mail distribution is based on the following module
+Mail::Delivery.
+</para>
+
+<para>
+Mail::Delivery class provides SMTP, ESMTP and LMTP delivery library
+interface. Mail::Delivery is an adapter layer for Mail::Delivery
+subclass ( SMTP ESMTP LMTP ).
+</para>
+
+<para>
+For example,
+<screen>
+    use Mail::Delivery::SMTP;
+    my $service = new Mail::Delivery::SMTP;
+    if ($service->error) { Log($service->error); return;}
+
+    $service->deliver(
+                      {
+                          mta             => '127.0.0.1:25',
+
+                          smtp_sender     => 'rudo@nuinui.net',
+                          recipient_maps  => $recipient_maps,
+                          recipient_limit => 1000,
+
+                          mesage          => $message
+                      });
+</screen>
+where $message is a 
+<link linkend="module.mail.message">
+Mail::Message
+</link>
+object.
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	<link linkend="module.mail.message">
+	Mail::Message
+	</link>
+	object
+	</title>
+
+<para>
+This object provies message analyzer.
+It analyzes a message and build the following object chains
+<screen>
+header -> body
+header -> preamble -> part1 -> part2 -> trailor (multipart)
+</screen>
+</para>
+
+<para>
+<link linkend="module.mail.message">
+Mail::Message
+</link>
+class provides such data structure described above.
+</para>
+
+</sect1>
+
+
+<!-- mail queue -->
+&sect.mailqueue;
+
+
+<sect1>
+	<title>
+	Discussion: FML::Mailer is apropriate ?
+	</title>
+
+<para>
+Only FML::Process::QueueManager uses FML::Mailer.
+So, independent FML::Mailer class is needed ?
+</para>
+
+<para>
+In usual codes, reply_message() handles all message operations.
+FML::Mailer is always behind it.
+But modules other than reply_message() is created in the future ?
+Hmm, ...
+</para>
+
+<para>
+FML::Mailer should be merged into FML::Process::QueueManager class?
+</para>
+
+</sect1>
+
+
+<sect1 id="recipes.delivery">
+	<title>
+	Delivery TIPS 	
+	</title>
+
+<qandaset>
+
+&recipe.delivery.forward;
+
+</qandaset>
+
+</sect1>
+
+
+</chapter>
diff --git a/fml/doc/en/tutorial/delivery/queue.sgml b/fml/doc/en/tutorial/delivery/queue.sgml
new file mode 100644
index 00000000..5436ed46
--- /dev/null
+++ b/fml/doc/en/tutorial/delivery/queue.sgml
@@ -0,0 +1,122 @@
+<!--
+    $FML$
+    $jaFML: queue.sgml,v 1.3 2003/04/15 14:51:37 fukachan Exp $
+-->
+
+<sect1 id="message.reply">
+	<TITLE>
+	fml sends back a mail message
+	</TITLE>
+
+<para>
+Mail::Delivery::Queue class inserts a message to send back into the
+mail queue. Later FML::Process::QueueManager handles the real delivery
+process.
+</para>
+
+
+<sect2>
+	<title>
+	How to write
+	</title>
+
+<para>
+use like this:
+<screen>
+$curproc->reply_message( "you are not a ML member." );
+</screen>
+If no recipient specified, the recipient is the sender of the message
+(From: address).
+</para>
+
+
+<para>
+To send a file, like this:
+<screen>
+$curproc->reply_message( {
+        type        => "text/plain; charset=iso-2022-jp",
+        path        => "/etc/fml/main.cf",
+        filename    => "main.cf",
+        disposition => "main.cf example",
+    });
+
+$curproc->reply_message( {
+        type        => "image/gif",
+        path        => "/some/where/logo001.gif",
+        filename    => "logo.gif",
+        disposition => "attachment",
+    });
+</screen>
+</para>
+
+</sect2>
+
+</sect1>
+
+
+<sect1 id="message.queue">
+	<TITLE>
+	mail queue and delivery system
+	</TITLE>
+
+<para>
+FML::Process::QueueManager pick up one queue from the queue directory.
+Mail::Message parses it.
+Mail::Delivery process the real delivery via FML::Mailer.
+<screen>
+Mail::Delivery::Queue
+   |
+   | ---> queue directory
+   V
+FML::Process::QueueManager
+   |
+   | <--- queue directory
+   V
+FML::Mailer
+   |
+   V
+Mail::Delivery
+</screen>
+</para>
+
+</sect1>
+
+
+<sect1>
+	<TITLE>
+	mail queue directory
+	</TITLE>
+
+<para>
+The queue directory consists of the following plural directories:
+<screen>
+new/
+active/
+deferred/
+info/sender/
+info/recipients/
+</screen>
+info/ stores envelope information
+</para>
+
+<para>
+In creating a new queue file, 
+make a temporary file in new/ once.
+When the delivery preparation is ended, 
+move the queue from new/ to active/.
+Hence files under active/ is delivery ready.
+</para>
+
+<sect2>
+	<title>
+	lock the queue
+	</title>
+
+<para>
+When we need to handle the specific queue file,
+use lock()/unlock() method for each $queue_id object.
+lock algorithm is based on flock(2) for the file.
+</para>
+</sect2>
+
+</sect1>
diff --git a/fml/doc/en/tutorial/devel/create_program.sgml b/fml/doc/en/tutorial/devel/create_program.sgml
new file mode 100644
index 00000000..4268fe76
--- /dev/null
+++ b/fml/doc/en/tutorial/devel/create_program.sgml
@@ -0,0 +1,169 @@
+<!--
+   $FML$
+   $jaFML: create_program.sgml,v 1.6 2003/04/15 14:51:38 fukachan Exp $
+-->
+
+<chapter id="program.create">
+	<title>
+	Create a new program
+	</title>
+
+
+<sect1>
+	<title>
+	Create a pgoram (CUI)
+	</title>
+
+<para>
+Firstly, prepare a new module in FML::Process class. See
+FML::Process::Scheduler as the least model, see
+FML::Process::Distribute for the most complicated class.
+</para>
+
+<para>
+See FML::Process::Flow::ProcessStart() for mandatory methods to
+implement. FML::Process::Flow::ProcessStart() kicks off several
+methods sequentially.
+At 2002/07, these methods are mandatory.
+<screen>
+new()
+prepare()
+verify_request()
+run()
+finish()
+</screen>
+See FML::Process::Distribute as a complicated example.
+</para>
+
+<para>
+<screen>
+        FML::Process::Kernel
+                |       uses-a FML::Process::{Flow,Utils} FML::Parse ...
+                |
+                A
+        FML::Process::???
+                        uses-a FML::Something
+                        uses-a CPAN module
+                        uses-a ...
+</screen>
+</para>
+
+<para>
+If you have prepared FML::Process::MODULE, define relation at
+etc/modules. Define available command line options at
+etc/command_line_options if needed.
+</para>
+
+<para>
+The preparation is done. Symlink loader and the new program name.
+For example, 
+<screen>
+% ls -l /usr/local/libexec/fml
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 command@ -> loader
+drwxr-xr-x  2 root  wheel   512 Apr 14 18:25 current-20030414/
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 digest@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 distribute@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 error@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fml@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fml.pl@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fmladdr@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fmlalias@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fmlconf@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fmldoc@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fmlhtmlify@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fmlsch@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 fmlserv@ -> loader
+-rwxr-xr-x  1 root  wheel  6863 Apr 14 18:24 loader*
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 makefml@ -> loader
+lrwxr-xr-x  1 root  wheel     6 Apr 14 18:25 mead@ -> loader
+</screen>
+</para>
+
+</sect1>
+
+
+<sect1>
+	<title>
+	Create a program (CGI)
+	</title>
+
+<para>
+The main CGI program locates at FML::CGI::XXX class.
+These modules has the following relation.
+<screen>
+        FML::Process::Kernel
+                |
+                A
+        FML::Process::CGI::Kernel   uses-a CGI
+                |
+                A
+        FML::Process::CGI
+                |
+                A
+        FML::CGI::XXX
+</screen>
+</para>
+
+<para>
+How to write CGI programs are same as one of CUI.
+CUI modules locates under FML::CGI to clarifyd CUI and GUI.
+</para>
+
+
+<para>
+In the case of CGI, 
+prepare the following methods for looks on screen:
+<screen>
+html_start()
+html_end()
+</screen>
+and
+<screen>
+run_cgi_main()
+run_cgi_title()
+run_cgi_navigator()
+run_cgi_menu()
+run_cgi_command_help()
+run_cgi_options()
+</screen>
+These methods are called from verify_request() and run() in
+FML::Process::CGI.
+</para>
+
+<para>
+CGI process is driven by FML::Process::CGI.
+run() method calls
+<screen>
+$curproc->html_start($args);
+</screen>
+call a set of run_cgi_xxx() methods
+<screen>
+$curproc->html_end($args);
+</screen>
+to control screen.
+</para>
+
+<para>
+At 2001/11, FML::Process::CGI::Kernel consists of the following methods:
+	<footnote>
+	<para>
+	Almost cases,
+	FML::Process::Kernel method is overloaded by other modules.
+	So, not called directly.
+	</para>
+	</footnote>
+<screen>
+new()
+prepare()
+verify_request()
+run()
+finish()
+</screen>
+You do not need edit these files.
+FML::CGI:: is called at run() method.
+</para>
+
+</sect1>
+
+
+</chapter>