SEMI 1.8 Manual

SEMI 1.8 Manual
***************

This file documents SEMI, a MIME user interface for GNU Emacs.

What is SEMI?
*************

SEMI is a package for GNU Emacs to provide features related with MIME user interface.

SEMI provides two user interfaces: MIME-View and MIME-Edit.

MIME-View is a kernel of user interface to display or operate MIME messages, STD 11 messages or ``localized RFC 822'' messages.

MIME-Edit is a user interface to compose MIME messages.

Each MUA can use powerful MIME features to combine these features.

MIME message viewing
********************

MIME-View は GNU Emacs で動作する汎用的な MIME viewer です。

MIME-View は MIME message を閲覧するための利用者界面 (user interface) の核であり、この上で presentation-method と呼ばれる表示を作るプログラムを動かしたり、acting-method と呼ばれる entity の処理プログラムを動かすことが可能で、さまざまな種類の entity を扱う事ができるようになっています。

Basic design
============

Internet の電子書簡・ネットニュースなどの書面 (message) の表現形式は STD 11 に基づいています。STD 11 の書面本体 (message body) は行を唯一の構造とする簡易文面 (plain text) であり、文字符号も us-ascii と定められています。実際には、文字符号を us-ascii の代わりにその言語圏で用いられる文字符号とした『地域化された STD 11』書面も用いられてきましたが、この場合も書面の文字符号は１つです。このため、利用者界面 (Message User Agent) は、しばしば、byte 列 = us-ascii 文字列、ないしは、byte 列 = その言語圏で用いる文字符号の文字列のように見倣してきました。

しかしながら、MIME では書面は entity を単位とする木構造になり、また、１つの書面で複数の文字符号を用いることができます。また、entity の内容は文面や絵のような単純に表示可能なものだけでなく、音声や動画などの一定時間再生されるようなものや特定のアプリケーションのデータやプログラムのソース、あるいは、ftp や mail service の利用法や URL といった形で表された外部参照などのさまざまなものが考えらます。このため、表示だけを考えていた STD 11 における利用者界面の単純な延長では MIME の全ての機能を扱うことはできません。つまり、MIME の形式に合わせて復号するだけでは不十分であり、利用者との対話的な再生処理を考慮する必要があります。MIME 書面の形式は自動処理がしやすく設計されていますが、MIME 書面に含まれる内容の中にはセキュリティー上の問題から自動処理をするべきでないものがあり、こういったものの再生に関しては利用者の判断を仰ぐように設計されるべきでしょう。結局、MIME 書面を扱うためには STD 11 および MIME の構文で記述されたメッセージの情報交換用表現とその解釈結果である表示画面や再生等の処理を区別して考える必要があります。また、利用者との対話的な再生処理が必要です。

このため、MIME-View は１つの書面に対して、情報交換用表現を格納する mime-raw-buffer と表示用表現を格納する mime-preview-buffer の２つの buffer を用います。

MIME-View は mime-preview-buffer に対して mime-view-mode という MIME message を閲覧するための mode を提供します。利用者はここで各 entity に対して操作を行うことができます。

Presentation of mime-preview-buffer
===================================

mime-view-mode では各 entity に対して

     	[entity-button]
     	(header)

     	(body)
     	(separator)

という情報を表示します。これらは条件に従って design を変更したり、表示を抑制することもできます。

以下に、表示例を示します。

     From: morioka@jaist.ac.jp (守岡 知彦 / MORIOKA Tomohiko)
     Subject: Re: 質問？
     Newsgroups: zxr.message.mime
     Date: 22 Oct 93 11:02:44
     Mime-Version: 1.0
     Organization: Japan Advanced Institute of Science and Technology,
             Ishikawa, Japan

     [1  (text/plain)]
       MIME-Edit mode における、MIME message の作り方。

       C-c C-x ? を押すと help が出てくる。

     C-c C-x C-t	insert a text message.
     C-c C-x TAB	insert a (binary) file.
     C-c C-x C-e	insert a reference to external body.
     C-c C-x C-v	insert a voice message.
     C-c C-x C-y	insert a mail or news message.
     C-c C-x RET	insert a mail message.
     C-c C-x C-s	insert a signature file at end.
     C-c C-x t	insert a new MIME tag.
     C-c C-x a	enclose as multipart/alternative.
     C-c C-x p	enclose as multipart/parallel.
     C-c C-x m	enclose as multipart/mixed.
     C-c C-x d	enclose as multipart/digest.
     C-c C-x s	enclose as PGP signed.
     C-c C-x e	enclose as PGP encrypted.
     C-c C-x C-k	insert PGP public key.
     C-c C-x C-p	preview editing MIME message.
     ...

     って訳で、C-c C-x C-i を押して、挿入したい binary file を指定します。

       binary file の MIME encoding には、普通、Base64 を指定します。

     [2  (image/gif)]

     [3  (text/plain)]

       こんな風に、絵入り message のでき上がり。

     〓〓〓〓〓〓〓〓〓〓〓 ロシアン・ティーを一杯。 〓〓〓〓〓〓〓〓〓〓〓
     〓〓〓〓〓  ☆ ジャムではなくマーマレードでもなく蜂蜜で ☆  〓〓〓〓〓
     〓〓〓〓〓         МОРいОКА  ТОМОХИКО         〓〓〓〓〓
     〓〓〓〓〓〓〓  Internet E-mail: <morioka@jaist.ac.jp>  〓〓〓〓〓〓〓

entity-button
-------------

entity-button は entity の先頭にあって、その entity に関する大まかな情報を表示する部分です。

標準では

             [1.3 test (text/plain)]

のような感じに表示されます。

最初の数字は message 中のこの entity の位置を節番号のように表したもので、 entity-number と呼びます。

２番目の文字列は表題を表します。この情報は、

 1. Content-Description field もしくは Subject field に書かれた表題

 2. Content-Disposition field の filename parameter に書かれた file 名

 3. Content-Type field の name parameter に書かれた file 名

 4. uuencode の場合の file 名

から作ります。どれも存在しない場合は空白が表示されます。

３番目の括弧の中の情報はその entity の media-type/subtype を表します。非 MIME entity の場合、nil が表示されます。

この entity-button は entity の内容を象徴する icon のような役割を果たします。例えば、

             [2  (image/gif)]

の上で v を押せばここに入っている絵が表示されます。

また、mouse 操作が可能な場合、entity-button を第２ボタン（3 button mouse の場合、中央のボタン）で押せば、同様にその絵が表示されます。

entity-header
-------------

entity-header はある entity の header を表示する部分です（「そのままやんけ」って怒らないで。そういうもんなんです）。

entity-body
-----------

entity-body は part の内容を表示する部分です。

これもひねりが足りないですが、まあ、そういうもんです。

とはいえ、実際には少しひねってます。

text entity の場合は charset に応じて code 変換したりしますし、XEmacs では image entity を変換しないといけないし。

詳しくはまた後で。

Operation in mime-preview-buffer
================================

mime-preview-buffer には以下の機能があります。

u
     上の part に戻る（message の一番上の part でこれを行なうと Summary mode に戻る (*1)）

p
     前の part に移動する

M-TAB
     前の part に移動する

n
     次の part に移動する

TAB
     次の part に移動する

SPC
     scroll up する

M-SPC
     scroll down する

DEL
     scroll down する

RET
     次の行に移動する

M-RET
     前の行に移動する

v
     part を再生する (*2)

e
     part から file を取り出す (*2)

C-c C-p
     part を印刷する (*2)

mouse-button-2
     preview-buffer 中の mouse button を起動する

     content-button を押せば、その part が再生される(*2)

     URL-button を押せば、その WWW browser が起動される

[注意]

     (*1) MUA で mime-view の設定をしていない場合、Summary mode には戻りません。

     (*2) 実際の動作は対応する method に依ります。

MIME message editing
********************

MIME-Edit is a general MIME composer for GNU Emacs.

Minor-mode to edit MIME message
===============================

mime-edit-mode is a minor mode to compose MIME message.  In this mode, tag represents various kinds of data, so you can edit multi part message consists of various kinds of data, such as text, image, audio, etc.

There are 2 kinds of tags:

  * single-part tag

  * multi-part tag

single-part tag represents single part, this form is following:

             --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
             OPTIONAL-FIELDS]

TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of Content-Type ((mime-en)Content-Type) field.  TYPE/SUBTYPE is required, PARAMETERS is optional.

ENCODING indicates Content-Transfer-Encoding ((mime-ja)Content-Transfer-Encoding) field.  It is optional too.

OPTIONAL-FIELDS is to represent another fields except Content-Type field and Content-Transfer-Encoding field.

multi-part tags represent multi part ((mime-en)multipart).  They consist of a pair of multi-part beginning tag and multi-part ending tag.

multi-part beginning tag's form is following:

             --<<TYPE>>-{

multi-part ending tag's form is following:

             --}-<<TYPE>>

A region from multi-part beginning tag to multi-part ending tag is called as enclosure.

Operations for single-part
==========================

Operations to make single-part are following:

C-c C-x C-t
     Insert single-part tag indicates text part.

C-c C-x C-i
     Insert file as a MIME attachment.  If C-u is followed by it, it asks media-type, subtype or encoding even if their default values are specified. (cf. tag specification for inserted file)

C-c C-x C-e
     Insert external part.

C-c C-x C-v
     Record audio input until C-g is pressed, and insert as a audio part. (It requires /dev/audio in default.)

C-c C-x C-y
     Insert current (mail or news) message. (It is MUA depended.)

C-c C-x C-m
     Insert mail message. (It is MUA depended.)

C-c C-x C-w, C-c C-x C-s
     Insert signature.

C-c C-x C-k
     Insert PGP (PGP) public key. (It requires Mailcrypt package.)

C-c C-x t
     Insert any single-part tag.

Operations for enclosure
========================

Operations to make enclosure are following:

C-c C-m C-a
     Enclose specified region as multipart/alternative.

C-c C-x C-p
     Enclose specified region as multipart/parallel.

C-c C-x C-m
     Enclose specified region as multipart/mixed.

C-c C-x C-d
     Enclose specified region as multipart/digest.

C-c C-x C-s
     Digital-sign to specified region. (cf. PGP)

C-c C-x C-e
     Encrypt to specified region. (cf. PGP)

C-c C-x C-q
     avoid to encode tags in specified region.  In other words, tags is interpreted as such string.

Other operations
================

There are another operations in mime-edit-mode.

C-c C-c
     Send current editing message.

C-c C-x p
     Preview current editing message. (cf. MIME-View)

C-c C-x C-z
     Exit mime-edit-mode without sending.

C-c C-x /
     Set current editing message to enable automatic splitting or not. Form of automatic split messages is message/partial.

C-c C-x 7
     Set 7bit ((mime-en)7bit) to transfer level (transfer level).

C-c C-x 8
     Set 8bit ((mime-en)8bit) to transfer level (transfer level).

C-c C-x v
     Set current editing message to digital-sign or not. (cf. PGP)

C-c C-x h
     Set current editing message to encrypt or not. (cf. PGP)

C-c C-x ?
     Display help message.

How to detect tag for inserted file
===================================

When C-c C-x C-i (mime-edit-insert-file) is pressed, tag parameters for inserted file, such as media-type or encoding, are detected by variable mime-file-types.

When C-u is followed by it or parameter is not found from the variable, it asks from user.  (When C-u is followed by it, detected value is used as default value)

If you want to change default value for file names, please change variable mime-file-types.

 -- Variable: mime-file-types

     Specification of default value of tag for file name of inserted file.

     It is a list of following list:

          	(FILE_PAT TYPE SUBTYPE PARAMS ENCODING
          	 DISPOSITION_TYPE DISPOSITION_PARAMS)

     Each element of the list is following:

     FILE_PAT
          regular expression of file name

     TYPE
          primary-type of media-type

     SUBTYPE
          subtype of media-type

     PARAMS
          parameters of Content-Type field

     ENCODING
          Content-Transfer-Encoding

     DISPOSITION_TYPE
          disposition-type

     DISPOSITION_PARAMS
          parameters of Content-Disposition field

     Example: Specify application/rtf as default media type for *.rtf

          (eval-after-load
              "mime-edit"
            '(set-alist 'mime-file-types
          	      "\\.rtf$"
          	      '("application" "rtf" nil nil
          		"attachment" (("filename" . file)))
          	      ))

transfer level
==============

Each content inserted in a message is represented by 7bit ((mime-en)7bit), 8bit ((mime-en)8bit) or binary ((mime-en)binary).

If a message is translated by 7bit-through MTA ((mime-en)MTA), there is no need to encode 7bit data, but 8bit and binary data must be encoded to 7bit data.

Similarly, if a message is translated by 8bit-through MTA, there is no need to encode 7bit or 8bit data, but binary data must be encoded to 7bit or 8bit data.

[Memo]

     EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be encoded by base64.  But I don't know EBCDIC. (^_^;

     Similarly, I wish ASCII-printable only MTA and code-conversion MTA disappeared. (^_^;

     Maybe there are binary-through MTA, but I think it is not major.

transfer level represents how range data are available.  mime-edit has a variable mime-transfer-level to represent transfer level.

 -- Variable: mime-transfer-level

     transfer level.

     If transfer level of a data is over it, a data is encoded to 7bit.

     Currently, 7 or 8 is available.  Default value is 7.

     In extension plan, EBCDIC will be 5, ASCII printable only will be 6, binary will be 9.  But it will not be implemented.

[Memo]

     transfer level is only for body, not for message header (header). MIME extends RFC 822 ((mime-en)RFC 822) to use 8bit data in body, but it requires to use us-ascii ((mime-en)us-ascii) in header.

Splitting
=========

 -- Variable: mime-edit-split-message

     Split large message if it is non-nil.

 -- Variable: mime-edit-message-default-max-lines

     Default maximum lines of a message.

 -- Variable: mime-edit-message-max-lines-alist

     Alist of major-mode vs maximum lines of a message.

     If it is not specified for a major-mode, mime-edit-message-default-max-lines is used.

 -- Variable: mime-edit-split-blind-field-regexp

     Regular expression to match field-name to be ignored when split sending.

Miscellaneous
*************

PGP
===

mime-edit provides PGP encryption, signature and inserting public-key features based on PGP/MIME (RFC 2015) or PGP-kazu (draft-kazu-pgp-mime-00.txt).  In current version, PGP 5.0i and GnuPG are supported as well.

This feature requires PGP or GnuPG commands and its interface package, such as Mailcrypt package ((mailcrypt)).

 -- Variable: pgp-version

     Version of PGP or GnuPG command to be used for encryption or sign. The value should be a symbol.  Allowed versions are gpg, pgp50 or pgp.

 -- Variable: pgp-function-alist

     Alist of service names vs. corresponding functions and its filenames. Each element looks like (SERVICE FUNCTION FILE).

     SERVICE is a symbol of PGP processing.  It allows `verify', `decrypt', `fetch-key', `snarf-keys', `mime-sign', `traditional-sign', `encrypt' or `insert-key'.

     Function is a symbol of function to do specified SERVICE.

     FILE is string of filename which has definition of corresponding FUNCTION.

 -- Function: pgp-function method

     Return function to do service METHOD.

 -- Function: mime-mc-setversion version

     Select `pgp-version' and `mc-default-scheme' if possible. VERSION should be a string or a symbol.

Mouse button
============

 -- Variable: mime-button-face

     Face used for content-button or URL-button of MIME-Preview buffer.

 -- Variable: mime-button-mouse-face

     Face used for MIME-preview buffer mouse highlighting.

 -- Variable: mime-browse-url-function

     Function to browse URL.

Utility for configuration
=========================

 -- Function: mime-add-condition target-type condition &optional mode file

     Add CONDITION to database specified by TARGET-TYPE.

     TARGET-TYPE must be preview or action.

     If optional argument MODE is strict or nil (omitted), CONDITION is added strictly.

     If optional argument MODE is with-default, CONDITION is added with default rule.

     If optional argument FILE is specified, it is loaded when CONDITION is activate.