@c $Id: tm-view=ja.texi,v 7.11 1996/02/28 14:36:34 morioka Exp $

+[tm-view]
@cindex tm-view

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

tm-view は @code{mime/viewer-mode} という MIME message を見るための 
major-mode を MUA に対して提供します。MUA の設計者はこの mode を利用す
ることでその MUA に MIME 機能を付加することができます。

tm-view は MIME message を閲覧するための user interface の核であり、そ
の上で各 content-type/sub-type を扱うための @strong{method} と呼ばれる
プログラムを動作させます。また、MIME message の表示の仕方を決める 
@strong{filter} と呼ばれるプログラムを起動時に呼び出します。
@strong{method} と @strong{filter} を tm-view に組み込む事によって、
@code{mime/viewer-mode} でさまざまな MIME type を扱う事ができます。

@menu
* MIME display::         mime/viewer-mode の画面構成
* method::               decoding 操作の実現
* Mechanism of tm-view:: tm-view の仕組み
* Functions of tm-view:: tm-view の関数
@end menu


++[MIME display] mime/viewer-mode の画面構成

mime/viewer-mode では各 content に対して

@example
	[content-subject]
	(content-header)
	
	(content-body)
	(content-separator)
@end example

という情報を表示します。これらは content-type 毎に design を変更したり、
表示を抑制することができます。

@menu
* content-subject::
* content-header::
* content-body::
* content-separator::
@end menu


+++[content-subject]
@cindex content-subject

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

標準では

@example
        [1.3 test (text/plain)]
@end example

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

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

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

@itemize @bullet
@item Content-Type field の name paramater もしくは x-name parameter 
に書かれた file 名
@item Content-Description field もしくは Subject field に書かれた表題
@item uuencode の場合の file 名
@end itemize

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

３番目の括弧の中の情報はその content の content-type/subtype を表しま
す。非 MIME part の場合、@code{nil} が表示されます。

この content-subject は content-header, content-body を表示しない場合、
icon のような役割を果たします。例えば、

@example
        [2  (image/gif)]
@end example

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


@defvr{Variable} mime-viewer/content-subject-omitting-Content-Type-list

content-subject を表示しない Content-Type を指定する。関数 
@code{mime-viewer/default-content-subject-function} によって参照される。
@end defvr


@deffn{Function} mime-viewer/default-content-subject-function rcnum cinfo ctype params subj

標準の content-subject 表示関数。変数 
@code{mime-viewer/content-subject-omitting-Content-Type-list} を参照し
ている。
@end deffn


@defvar mime-viewer/content-subject-function rcnum cinfo ctype params subj

content-subject 表示関数を設定するための変数。既定値は関数 
@code{mime-viewer/default-content-subject-function} である。

この変数に、関数 @code{mime-viewer/default-content-subject-function} 
以外の関数を設定した場合、変数 
@code{mime-viewer/content-subject-omitting-Content-Type-list} の有効性
は保証されないので注意すること。
@end defvar


+++[content-header]
@cindex content-header

ある content の reversed-content-number を関数 
@code{mime-viewer/header-visible-p} 与えた時の返り値が @code{t} になる
場合、その content の content-header が表示されます。この判定関数は、
一番上の content でなく、その content の親の content-type が変数 
@code{mime-viewer/childrens-header-showing-Content-Type-list} で指定さ
れている場合に @code{t} を返します。

この条件を変えたい場合は、この関数を再定義して下さい。但し、標準では、
変数 @code{mime-viewer/childrens-header-showing-Content-Type-list} を
参照しますが、再定義した場合、この変数の有効性は保証されないので注意し
て下さい。

content-header が表示される場合、content-header は 
content-header-filter によって整形されます。呼ばれる 
content-header-filter は article buffer の major-mode を key として変
数 @code{mime-viewer/content-header-filter-alist} から探されます。もし、
content-header-filter が見つからなかった場合、関数 
@code{mime-viewer/default-content-header-filter} が呼ばれます。


@defvar mime-viewer/childrens-header-showing-Content-Type-list

ある content の子に当たる content の content-header を表示すべき 
Content-Type を収めた list. 既定値は "message/rfc822" である。

この変数は関数 @code{mime-viewer/header-visible-p} によって参照される。
@end defvar


@deffn{Function} mime-viewer/header-visible-p rcnum cinfo &optional ctype

content-info @var{cinfo} 中の reversed-content-number が @var{rcnum} 
である content の header が表示される場合、t を返す。その content の 
content-type があらかじめわかっている場合、@var{ctype} に引数として渡
すことができる。
@end deffn


@defvar mime-viewer/content-header-filter-alist

article-buffer の major-mode を key とした連想リストで、値部には 
content-header-filter が入っている。
@end defvar


@deffn{Function} mime-viewer/default-content-header-filter

ある content の content-header を表示すべき時、変数 
@code{mime-viewer/content-header-filter-alist} の中に 
content-header-filter が見つからなかった場合に呼び出される。

変数 @code{mime-viewer/ignored-field-regexp} を参照する。
@end deffn


@defvar mime-viewer/ignored-field-list

content-header を表示する時に、表示しない field を指定する。

正規表現の list になっており、この値を元に変数 
@code{mime-viewer/ignored-field-regexp} が作られる。

この変数は直接操作せず、関数 @code{tm:add-fields} や 
@code{tm:delete-fields} を使って操作する。
@end defvar


+++[content-body]
@cindex content-body

ある content の content-body を表示するかどうかは、関数 
@code{mime-viewer/body-visible-p} が @code{t} になるかどうかで決まりま
す。標準では、ある content の content-type が変数 
@code{mime-viewer/default-showing-Content-Type-list} に設定されている
時に表示されます。

ある content の content-body が表示される時、preview buffer には 
content-body を content-filter によって整形されたものが表示されます。
呼ばれる content-filter は article buffer の major-mode を key として
変数 @code{mime-viewer/content-filter-alist} から探されます。もし、こ
の変数に登録されていなかった場合、関数 
@code{mime-viewer/default-content-filter} が呼ばれます。


@defvar mime-viewer/default-showing-Content-Type-list

content-body を表示すべき content-type を要素とする list.
@end defvar


@deffn{Function} mime-viewer/body-visible-p rcnum cinfo &optional ctype

reversed-content-number が @var{rcnum} である content が表示される場合、
@code{t} を返す。その content の content-type があらかじめわかっている
場合、@var{ctype} に引数として渡すことができる。
@end deffn


@defvar mime-viewer/content-filter-alist

article buffer の major-mode を key とした連想リストで、値部には 
content-filter が入っている。
@end defvar


@deffn{Function} mime-viewer/default-content-filter rcnum cinfo ctype params subj

ある content の content-body を表示すべき時、変数 
@code{mime-viewer/content-filter-alist} の中に content-filter が見つか
らなかった場合に呼び出される。

標準では何もしない。
@end deffn


+++[content-separator]
@cindex content-separator

content-separator は content の一番最後に content 間の境目を明らかにす
るために表示されます。

content-separator は関数 @code{mime-viewer/default-content-separator} 
によって表示されます。標準では、content-header も content-body も表示
されない場合のみ、改行を表示します。

content-separator の設定を変更したい場合は、この関数を再定義して下さい。


@deffn{Function} mime-viewer/default-content-separator rcnum cinfo ctype params subj

content-number が @var{cnum} である content の content-separator を表
示する。標準では、content-header も content-body も表示されない場合の
み、改行を表示する。
@end deffn


++ [method]
@cindex method

@code{mime/viewer-mode} では、各 content に対して、play (@key{v}),
extract (@key{e}), print (@key{C-c C-p}) という操作を行なうことができ
ます。こうした操作のことを『（content に対する）decode 操作』と呼ぶこ
とにします。また、@strong{play}, @strong{extract}, @strong{print} とい
う decode 操作の種類のことを @strong{decoding-mode} と呼ぶことにします。

decode 操作が行なわれた時、その content の content-type などの条件やそ
の場の環境に応じて実際にその操作を実行する手続きが呼ばれます。この手続
きのことを @strong{method} と呼びます。

method には、Emacs Lisp で書かれた @strong{内部 method} と、外部 
program で実現された @strong{外部 method} があります。内部 method は 
Emacs の機能を使ってきめ細かい処理を行なうことができます。外部 method 
は非同期プロセス呼び出しを使って実現されているので、実行中待たされずに
すみます。このため、静止画や動画などの巨大な data を再生するのに良いで
しょう。

@menu
* decoding-condition::            content の decode 条件の設定
* Format of method value::        method の値部の書式
* Example of decoding-condition:: 設定例
* environment variables::         環境変数
@end menu


+++[decoding-condition] content の decode 条件の設定
@cindex content decoding condition

tm-view は decode 操作が行なわれると、変数 
@code{mime/content-decoding-condition} からその時の条件に合致した 
method を捜し出して、それを呼び出します。

変数 @code{mime/content-decoding-condition} は

@lisp
        (条件1 条件2 ...)
@end lisp

という形をした list で、各条件は

@lisp
        ((field-type_1 . value_1)
         (field-type_2 . value_2)
         ...)
@end lisp

という形の連想 list になっています。

例えば、text/plain の時、tm-plain を起動する時、

@lisp
        ((type . "text/plain")
         (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
@end lisp

という条件を書きます。この method の value 部の書式については後で詳し
く述べます。

この条件は content-type が text/plain である content なら全ての 
decoding-mode で有効です。しかし、

@lisp
        ((type . "text/plain")
         (method "tm-plain" nil 'file 'type 'encoding 'mode 'name)
         (mode . "play"))
@end lisp

なら、play mode の時しか有効になりません。

逆に、

@lisp
        ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file)
         (mode . "play"))
@end lisp

なら、全ての content-type の play mode で有効になります。

こうして各条件を前から見て行き、最初に有効になった条件が実行されます。


+++[Format of method value] method の値部の書式
@cindex method の値部の書式

decode-condition の method field は

@lisp
        (method . SYMBOL)
@end lisp

か

@lisp
        (method  文字列  FLAG  引数1  引数2  ...)
@end lisp

という形をしています。

前者は内部 method を指定するための形式で、decode 操作が行なわれた時、
SYMBOL という関数が関数呼び出しによって内部 method として呼び出されま
す。

後者は外部 method を指定するための形式で、decode 操作が行なわれた時、
文字列で指定された外部 program が非同期プロセス呼び出しによって外部 
method として呼び出されます。


外部 method を指定する場合の method field の書式は以下の通りです。

@table @samp
@item 文字列
        外部 method の名前
@item FLAG
        @code{t} なら content-header も外部 method に渡す。@code{nil} 
        なら content-body のみを渡す。
@item 引数列
        外部 method の引数
@end table

また、外部 method の引数は次のような形式で書きます。

@table @samp
@item 文字列
        その文字列を渡す
@item 'SYMBOL
        SYMBOL を key とした decoding-condition の値を渡す
@item '文字列
        文字列を key とした decoding-condition の値を渡す
@end table

'SYMBOL で指定できるものには、

@table @samp
@item 'file
        content を渡すための file 名
@item 'type
        Content-Type field の content-type/subtype
@item 'encoding
        Content-Transfer-Encoding field の field body
@item 'mode
        decoding-mode
@item 'name
        file に落す場合の file 名
@end table

などがあり、'文字列 では Content-Type field の parameter の値が指定で
きます。


+++[Example of decoding-condition] decoding-condition の例
@cindex decoding-condition の例

以下に decoding-condition の設定例を示します。

@lisp
(defvar mime/content-decoding-condition
  '(((type . "text/plain")
     (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
    ((type . "text/x-latex")
     (method "tm-latex" nil 'file 'type 'encoding 'mode 'name))
    ((type . "audio/basic")
     (method "tm-au"    nil 'file 'type 'encoding 'mode 'name))
    ((type . "image/gif")
     (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
    ((type . "image/jpeg")
     (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
    ((type . "image/tiff")
     (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
    ((type . "image/x-tiff")
     (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
    ((type . "image/x-xbm")
     (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
    ((type . "image/x-pic")
     (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
    ((type . "video/mpeg")`
     (method "tm-mpeg"  nil 'file 'type 'encoding 'mode 'name))
    ((type . "application/octet-stream")
     (method "tm-file"  nil 'file 'type 'encoding 'mode 'name))
    ((type . "message/partial")
     (method . mime/decode-message/partial-region))
    ((method "metamail" t
             "-m" "tm" "-x" "-d" "-z" "-e" 'file)(mode . "play"))
    ))
@end lisp

例えば、「全部 metamail 使うんや」という場合、

@lisp
(setq mime/content-decoding-condition
      '(
        ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file))
       ))
@end lisp

とすれば OK です。

工夫すれば、かなり複雑な条件が書けるでしょう。


以下に、decoding-condition を設定するための有用な関数を紹介します。


@deffn{Function} set-atype symbol alist

@var{symbol} に条件 @var{alist} を追加します。

例：

@lisp
(set-atype 'mime/content-decoding-condition
	   '((type . "message/external-body")
	     ("access-type" . "anon-ftp")
	     (method . mime/decode-message/external-ftp)
	     ))
@end lisp
@end deffn


+++ [environment variables] 環境変数
@cindex environment variables

以下に tm-view の標準 method が参照する環境変数を示します。

@table @var
@item TM_TMP_DIR
一時的に作成される file や file 出力する場合の default の出力先として
用いられる directory を指定する。省略された場合、/tmp/ が用いられる。

@item VIDEO_DITHER
mpeg_play での dither のかけ方を指定する。既定値は `gray'.

@item TM_WWW_BROWSER
WWW browser を指定する。既定値は `netscape'.
@end table

@include tm-view-m=ja.texi


++ [Mechanism of tm-view] tm-view の仕組み

tm-view は、MIME 処理を行なう前の生の message が入っている 
@strong{article-buffer} とその内容を user に簡潔に表示し、user が操作
するための @strong{preview-buffer} という２つの buffer を管理します。
article-buffer の major-mode はもともとの MUA の article 表示用の 
major-mode であり、preview-buffer の major-mode は mime/viewer-mode と
なります。

@code{mime/viewer-mode} を実行すると、tm-view はまず article-buffer の
内容を解析し、その message の構造を article-buffer の buffer local 変
数 @code{mime::article/content-info} に記録します。

次に、この結果を元に article-buffer に対応する preview-buffer を作りま
す。この際、content-type に応じて、content 単位で header や body を加
工することができます。この header を加工するプログラムを 
@strong{header-filter}, body を加工するプログラムを 
@strong{content-filter} と呼び、これらを総称して @strong{filter} と呼
びます。

preview-buffer を作成する時に、message の表示上の構造を記録した 
preview-buffer の buffer local 変数 @code{mime::preview/content-list} 
が作られます。tm-view は article-buffer 上の 
@code{mime::article/content-info} と preview-buffer 上の 
@code{mime::preview/content-list} を用いて message を管理します。


注意： この説明書では、Content-Type field の content-type/subtype のこ
とを称して @strong{content-type} と呼びます。


@menu
* article-buffer::       article-buffer
* preview-buffer::       preview-buffer
@end menu


+++ [article-buffer]

@defvr{Structure} mime::content-info rcnum point-min point-max type parameters encoding children

article-buffer における MIME content に関する情報を格納するための構造
体。単に @strong{content-info} とも呼ぶ。

@table @var
@item rcnum
@strong{reversed content-number} (list)

@item point-min
article-buffer における先頭 point

@item point-max
article-buffer における末尾 point

@item type
content-type/sub-type（文字列、または、nil）

@item parameters
Content-Type field の parameter （連想 list）

@item encoding
Content-Transfer-Encoding（文字列、または、nil）

@item children
この content に含まれる contents（content-info の list）
@end table

ある content が multipart もしくは message/rfc822 などの別の content 
を含むような content であった場合、@var{children} に別の content の 
content-info が含まれる事によって、content-info は木構造になる。

この構造体を参照するには、@code{mime::content-info/スロット名} という
content-info を引数にとる関数を用いる。

@end defvr


@defvar mime::article/content-info

article-buffer を MIME message として解析した結果 (content-info)
@end defvar


@defvar mime::article/preview-buffer

article-buffer に対応する preview-buffer.
@end defvar


@defun mime-article/point-content-number point &optional cinfo

content-info @var{cinfo} で管理される領域において、@var{point} に対応
する content-number を返す。

@var{cinfo} が省略された場合は、@code{mime::article/content-info} が用
いられる。
@end defun


@defun mime-article/rcnum-to-cinfo rcnum &optional cinfo

content-info @var{cinfo} で管理される領域において、
reversed-content-number @var{rcnum} に対応する content-info を返す。

@var{cinfo} が省略された場合は、@code{mime::article/content-info} が用
いられる。
@end defun


@defun mime-article/cnum-to-cinfo rcnum &optional cinfo

content-info @var{cinfo} で管理される領域において、content-number
@var{rcnum} に対応する content-info を返す。

@var{cinfo} が省略された場合は、@code{mime::article/content-info} が用
いられる。
@end defun


@defun mime/flatten-content-info &optional cinfo

content-info @var{cinfo} 中に納められた全 contents の content-info の 
list を返す。

@var{cinfo} が省略された場合は、@code{mime::article/content-info} が用
いられる。
@end defun


+++[preview-buffer]

@defvar mime::preview/mother-buffer

この preview-buffer の親に相当する buffer.
@end defvar


@defvr{Structure} mime::preview-content-info point-min point-max buffer content-info

preview-buffer における MIME content に関する情報を格納するための構造
体。単に @strong{preview-content-info} とも呼ぶ。

@table @var
@item point-min
preview-buffer における先頭 point

@item point-max
preview-buffer における末尾 point

@item buffer
この content に対応する article-buffer

@item content-info
この content に対応する content-info
@end table

@end defvr


@defvar mime::preview/content-list

この preview-buffer の構造をあらわす preview-content-info の list.
@end defvar


@defvar mime::preview/article-buffer

この preview-buffer に対応する article-buffer.
@end defvar


@defvar mime::preview/original-major-mode

この preview-buffer のもとになった buffer の major-mode.
@end defvar


@defvar mime::preview/original-window-configuration

@code{mime/viewer-mode} を実行して、この preview-buffer 作る直前の 
window-configuration.
@end defvar


@defun mime-preview/point-pcinfo point &optional pcl

preview-content-info @var{pcl} で管理される preview-buffer 中の領域に
おいて、@var{point} に対応する content の preview-content-info を返す。

@var{cinfo} が省略された場合は、@code{mime::preview/content-list} が用
いられる。
@end defun


++ [Functions of tm-view] MIME message の decode に関する関数

tm-view の提供する関数を各 MUA に組み込む事によって、各 MUA に MIME 再
生機能を付加する事ができます。

tm-view が各 MUA に提供する関数は、MIME preview を行うための関数 
@code{mime/viewer-mode} と RFC 1522 encoded-word を decode するための
関数群です。

Memo: 旧 tiny-mime.el にあった RFC 1522 encoded-word を decode するた
めの関数群は tm-view に引き継がれました。


@menu
* function to preview:: MIME message を preview するための関数
* encoded-word decoding:: encoded-word を decode するための関数
@end menu


+++ [function to preview] MIME message を閲覧するための関数
@cindex mime/viewer-mode

@deffn{Command} mime/viewer-mode &optional mother ctl encoding

current-buffer を MIME message として解析して、その内容を閲覧するため
の preview-buffer を作成し、@code{mime/viewer-mode} に入ります。

@var{mother} は、解析の対象とする article-buffer が message/partial 形
式の分割された message を結合して作成した場合などにおける元の buffer 
を指定するために使います。

@var{ctl} は Content-Type field の field-body を 
@code{mime/Content-Type} の出力正式にしたものを入れます。この引数があ
る場合、article-buffer の Content-Type field よりもこの引数を優先しま
す。

@var{encoding} は Content-Transfer-Encoding field の field-body を入れ
ます。この引数がある場合、article-buffer の Content-Transfer-Encoding
field よりもこの引数を優先します。
@end deffn


+++[encoded-word decoding]
@cindex encoded-word
@cindex non-ASCII field
@cindex message header

tm-view は RFC 1522 で規定された encoded-word を decode するための関数
を持っています。


@deffn{Command} mime/decode-message-header

current buffer の message header 中の encoded-word を decode します。
@end deffn


@deffn{Command} mime-eword/decode-region beg end &optional unfolding

@var{beg} と @var{end} で囲まれた領域中の encoded-word を decode しま
す。

@var{unfolding} が non-nil の場合、fold された field を unfolding しま
す。
@end deffn


@deffn{Function} mime-eword/decode-string str

@var{str} の encoded-word を decode します。

fold された文字列は unfolding されます。
@end deffn