diff options
| -rw-r--r-- | fml/doc/en/tutorial/command/internal.sgml | 100 | ||||
| -rw-r--r-- | fml/doc/en/tutorial/internals/credential.sgml | 39 | ||||
| -rw-r--r-- | fml/doc/en/tutorial/internals/dbms.sgml | 52 | ||||
| -rw-r--r-- | fml/doc/en/tutorial/message/discussion.sgml | 159 | ||||
| -rw-r--r-- | fml/doc/en/tutorial/message/language.sgml | 48 |
5 files changed, 398 insertions, 0 deletions
diff --git a/fml/doc/en/tutorial/command/internal.sgml b/fml/doc/en/tutorial/command/internal.sgml new file mode 100644 index 00000000..d671dcf0 --- /dev/null +++ b/fml/doc/en/tutorial/command/internal.sgml @@ -0,0 +1,100 @@ +<!-- + $FML$ + $jaFML: internal.sgml,v 1.6 2003/04/15 14:51:36 fukachan Exp $ +--> + +<sect1 id="fml.command.internal.change"> + <title> + How differ coding style among &fml4; and &fml8; + </title> + +<para> +(... not yet translated ...) +</para> + +<para> +Consider help command which send back help message to the sender, an +example of command. +</para> + +<para> +In the case of &fmldevel;, the main code of help command locates at +FML::Command::User::help class. This class is called by +FML::Process::Command via AUTOLOAD of FML::Command. +</para> + +<warning> +<para> +All commands are implemented as either of FML::Command::User +FML::Command::Admin classes. CUI (makefml, fml) and GUI (CGI) uses +FML::Command::Admin class. Command mail users both classes according +to the context. +</para> +</warning> + +<para> +The real content of help command is process() method in +FML::Command::User::help class. +<screen> +sub process +{ + my ($self, $curproc, $optargs) = @_; + my $config = $curproc->{ config }; + my $charset = $config->{ reply_message_charset }; + my $help_file = $config->{ help_file }; + + # template substitution: kanji code, $varname expansion et. al. + my $params = { + src => $help_file, + charset_out => $charset, + }; + my $help_template = $curproc->prepare_file_to_return( $params ); + + if (-f $help_template) { + $curproc->reply_message( { + type => "text/plain; charset=$charset", + path => $help_template, + filename => "help", + disposition => "help", + }); + } + else { + croak("no help file ($help_template)\n"); + } +} +</screen> +where $curproc is an object, which type is hash reference. +It corresponds to %Envelope of &fml4;. +It contains several references to objects for this process. +$config is an object, but global in $fml4;. +</para> + +<para> +prepare_file_to_return() converts the message language and expands the +arguments in the message templtes. + </para> + +<para> +$curproc->reply_message() inserts the specified mesage string into the +queue. +</para> + +<para> +The error/log messages queued in are aggergated to one message at the +last of the current process. It is driven by Mail::Delivery class to +send it. If needed, the aggregator handles text strings and multipart +properly. +</para> + +<para> +This mechanism is same as Notify() of &fml4; but the last aggregator +is different. +</para> + +<para> +FYI: commands such as get for the file manipulation uses the same +message queuing mechanism. This is different from &fml4;'s Notify() +fundamentally. +</para> + +</sect1> diff --git a/fml/doc/en/tutorial/internals/credential.sgml b/fml/doc/en/tutorial/internals/credential.sgml new file mode 100644 index 00000000..4a9409b6 --- /dev/null +++ b/fml/doc/en/tutorial/internals/credential.sgml @@ -0,0 +1,39 @@ +<!-- + $FML$ + $jaFML: credential.sgml,v 1.3 2003/04/15 14:51:40 fukachan Exp $ +--> + +<chapter id="credential"> + <title> + User authentication + </title> + +<para> +User authentication is provydes by methods of FML::Credential class. +</para> + + + +<sect1> + <title> + Discussion: FML::Credential implementation + </title> + + +<sect2> + <title> + case sensitive / case insensitive + </title> + +<para> +For the user@domain address, we handle user part as case sensitively +and domain as case insensitively. Is it better to prepare the option +that handling of user part is insensitive. +</para> + +</sect2> + +</sect1> + + +</chapter> diff --git a/fml/doc/en/tutorial/internals/dbms.sgml b/fml/doc/en/tutorial/internals/dbms.sgml new file mode 100644 index 00000000..25a2d32a --- /dev/null +++ b/fml/doc/en/tutorial/internals/dbms.sgml @@ -0,0 +1,52 @@ +<!-- + $FML$ + $jaFML: dbms.sgml,v 1.5 2003/05/31 08:51:09 fukachan Exp $ +--> + +<chapter id="dbms"> + <title> + database management system + </title> + + +<sect1 id="dbms.overview"> + <title> + Overview + </title> + +<para> +Communication with DBMS (database management system) +via +<link linkend="module.io.adapter"> +IO::Adapter +</link> +class. +</para> + +<para> +This class provides fundamental functions such as insersion and +deletion of data. If more complex operation is needed, the +preprocessing module calling IO::Adapter should handle it. +</para> + +</sect1> + + +<sect1 id="dbms.todo"> + <title> + TODO + </title> + +<para> +Consider if methods are least set or not. +But +<link linkend="module.io.adapter"> +IO::Adapter +</link> +is enough ? +</para> + +</sect1> + + +</chapter> diff --git a/fml/doc/en/tutorial/message/discussion.sgml b/fml/doc/en/tutorial/message/discussion.sgml new file mode 100644 index 00000000..3d4e48b2 --- /dev/null +++ b/fml/doc/en/tutorial/message/discussion.sgml @@ -0,0 +1,159 @@ +<!-- + $FML$ + $jaFML: discussion.sgml,v 1.4 2003/04/15 14:51:42 fukachan Exp $ +--> + +<sect1> + <title> + Discussion: how to send back language dependent error mesages + </title> + +<para> +fml needs to send back language dependent error mesages. +How we should implement it ? +</para> + + +<!-- ===================================================== --> +<sect2> + <title> + &fml4; case + </title> + +<para> +In the case of &fml4;, call language dependent message converter like +this: +<screen> + Mesg(*e, KEYWORD, DEFAULT MESSAGE, ARGUMENT); +</screen> +</para> + +<para> +Mesg() searches the specified keyword in files +/usr/local/fml/messages/Japanese/ directory. Each file contains +messages with keywords to be substituted properly. +</para> + +<para> +For example, the keyword not_found matches not_found entry in +/usr/local/fml/messages/Japanese/kern file. +</para> + +</sect2> + + + +<!-- ===================================================== --> +<sect2> + <title> + What &fmldevel; should do ? + </title> + +<para> +Hmm, which is better ? "One file has one keyword" and "one file for +one category, so one file contains plural entries". +I don't determine it. +</para> + +<sect3> + <title> + X/Open Portability Guide Issue 4 Version 2 (``XPG4.2'') + </title> + +<para> +If you use XPG (X/Open standard), +<screen> +catgets(catd, set_id, msg_id, char *s); +</screen> +function converts the message specified by LOCALE_XXX. + <footnote> + <para> + "s" is the default message. + </para> + </footnote> +For example, the usage is as follows: +<screen> +printf(catgets(catd, 30, 4, "%s: Internal match error.\n"), progname); +</screen> +Thie function uses se 30 and entry 4 in th local definition file such +as /usr/pkg/share/nls/ja_JP.EUC/PROGNAME.cat. +</para> + +</sect3> + +<sect3> + <title> + &fmldevel;: design (temporary ?) + </title> + +<para> +One problem is whether we should use locale or not ? +By considering CUI e.g. makefml, it is better to use locale. +For example, prepare +<screen> +/usr/local/lib/fml/$fml_version/messages/ja_JP.EUC/kern + +1: %s not found +2: %s (error number = %d) +</screen> +. +</para> + +<para> +Instead one file for one message may be useful. +Especially we can customize only one message. +</para> + +<para> +To try the latter case, we can prepare a lot of classes such as +<screen> +FML::Message::ja::KEYWORD +</screen> +For example, there are 200 or 300 files such as +<screen> +FML::Message::ja::not_found +</screen> +. +</para> + +<para> +This methods has the following problems: +<itemizedlist> + <listitem> + <para> + separete files but in contrast more customizable. + </para> + </listitem> + + <listitem> + <para> + locale friendly? may be no. + </para> + </listitem> + +</itemizedlist> +</para> + + +<para> +Consider the example. In the latter case, +the message module will be like this? +<screen> +sub not_found +{ + my .. = @_; + + return <<"_EOF_" +$sender is ... something ... +_EOF_ +} +</screen> +hmm, is it good ??? +</para> + +</sect3> + + +</sect2> + +</sect1> diff --git a/fml/doc/en/tutorial/message/language.sgml b/fml/doc/en/tutorial/message/language.sgml new file mode 100644 index 00000000..7e34be55 --- /dev/null +++ b/fml/doc/en/tutorial/message/language.sgml @@ -0,0 +1,48 @@ +<!-- + $FML$ + $jaFML: language.sgml,v 1.5 2003/04/15 14:51:42 fukachan Exp $ +--> + + +<sect1 id="message.nl"> + <title> + message internationalization: + the usage of reply_message_nl() + </title> + +<para> +For the message internationalization, +use reply_message_nl() + <footnote> + <para> + See FML::Process::Kernel module. + </para> + </footnote> +like this: +<screen> +$curproc->reply_message_nl('error.already_member', + 'already member', + { _arg_address => $address }); +</screen> +This function uses the message template at +/usr/local/share/fml/$fml_version/message/$language/error/already_member +. +</para> + +<para> +$_arg_VARNAME in the message such as +<screen> +$_args_address +</screen> +is expanded by using the value specified as the argument of +reply_mesage_nl(). +</para> + +<para> +Usual $VARIABLE is also expaned by replacing it with value of config.cf. +For example, $ml_name is expanded to ML name defined in config.cf +$_arg_ prefix is used for lexical scope variables to avoid +conflicts against variables in config.cf. +</para> + +</sect1> |