-*-tm manual-*-
tm-view manual

tm-view 7.16 Reference manual
*****************************

The tm-view is a general MIME viewer running on GNU Emacs.

tm-view provides the major-mode called mime/viewer-mode to read MIME message for MUA. MUA implementer can use it to add MIME function.

What is tm-view?
****************

tm-view is a general MIME viewer for GNU Emacs.

It provides a major-mode to navigate MIME message to each MUAs.

tm-view managements two buffers, one is for raw message called article buffer, another one is to preview for user called preview buffer.

When called mime/viewer-mode, tm-view analyzes article buffer, and sets its result to the variable mime::article/content-info.

After that, tm-view create a preview buffer corresponded to the article buffer. As this time, tm-view modifies header and body of each contents of the message. It is done by definition for Content-Types.

On the preview buffer created by tm-view, user can manipulate a message to decode, such as run external vewer, extract files, or print.

Notice: In this document, I call content-type as content-type/subtype of Content-Type field.

How to run mime/viewer-mode
***************************

Command mime/viewer-mode &optional mother ctl encoding

Parse current-buffer as a MIME message, and create preview buffer to display to user, then enter mime/viewer-mode.

MOTHER is used to specify original article buffer. It may be useful when an article buffer is assembled from message/partial.

CTL is used to specify Content-Type field information. Its format is output format of mime/Content-Type. When CTL is specified, tm-view uses it instead of Content-Type field of the article buffer.

ENCODING is used to specify field-body of Content-Transfer-Encoding field. When is is specified, tm-view uses it instead of Content-Type field of the article buffer.

Commands of mime/viewer-mode
****************************

mime/viewer-mode has following functions:

u
     goes to the upper content (returns to the Summary mode if the cursor is sitting on the top content (*1))

p
     goes to the previous content

n
     goes to the next content

SPC
     scrolls up

M-SPC
     scrolls down

DEL
     scrolls down

RET
     goes to the next line

M-RET
     goes to the previous line

v
     playbacks a content            (*2)

e
     extracts a file from a content (*2)

C-c C-p
     prints a content               (*2)

[Notice]

 1. Not return to the Summary mode unless tm-view has been setup using tm-mh-e, tm-gnus, tm-rmail etc.

 2. Actual playback/extract/print will be performed by a method.

Screen design of preview buffer
*******************************

In preview buffer, following are displayed for each content:

     	[content-subject]
     	(content-header)

     	(content-body)
     	(content-separator)

You can change design or stop to display if you specify for each content-types.

Example:

     From: MORIOKA Tomohiko <morioka@jaist.ac.jp>
     Newsgroups: zxr.comp.emacs.tm-english
     Subject: tm6.63.tar.gz
     Date: Mon, 26 Jun 1995 17:39:50 JST
     Organization: Chamonix, JAIST, Tatsunokuchi, Ishikawa, Japan
     Reply-To: tm-eng@chamonix.jaist.ac.jp
     To: tm-eng@chamonix.jaist.ac.jp
     In-Reply-To: Your message of "Sun, 25 Jun 1995 23:20:49 MST"
     X-Mua: mh-e 4.1 + tm 6.63 / Mule 2.2 (WAKAMURASAKI) PL02
     X-Mime-Composer: mime.el + tiny-mime 5.12
     X-Ml-Count: 32

     [1  (text/plain)]
       I put tm6.63.tar.gz in ftp.jaist.ac.jp.

       In this version, tm-view uses new MIME encoding/decoding engine
     ``mel (MIME encoding library''. This library has internal/external
     encoding/decoding engine. If data is smaller than a limit, tm-view
     uses internal decoder, otherwise external decoder.

     [2 tm6.63.tar.gz ([anon-ftp] ftp.jaist.ac.jp:/pub/GNU/elisp/mime/alpha)]

     [3  (text/plain)]
     ----
     MORIOKA, Tomohiko <morioka@jaist.ac.jp>

content-subject
===============

content-subject is a part to display abstract for the content. It is placed in top of content.

In default, it is displayed following design:

             [1.3 test (text/plain)]

First number field represents position of a content in the message. It is called `content-number'. It can be considered as the chapter number in the message.

Second string part represents title. It is created by following:

  * name paramater or x-name parameter in Content-Type field

  * Content-Description field or Subject field

  * filename of uuencode

If they are not exists, space is displayed.

Third parenthesis part represents content-type/subtype of the content. If it is non-MIME part, nil is displayed.

Content-subject is used like icon when content-header and content-body are hidden. For example,

             [2  (image/gif)]

if you press `v' key, GIF image is displayed.

Variable mime-viewer/content-subject-omitting-Content-Type-list

List of content-type. If content-type of a content is a member of this list, its content-subject is not displayed.

This variable is referenced by function mime-viewer/default-content-subject-function.

Function mime-viewer/default-content-subject-function cnum cinfo ctype params subj

Default value of the variable mime-viewer/content-subject-function. It refers variable mime-viewer/content-subject-omitting-Content-Type-list.

 -- Variable: mime-viewer/content-subject-function cnum cinfo ctype params subj

     Variable to specify content-subject display function. Default value is the function mime-viewer/default-content-subject-function.

content-header
==============

A content header shows the header portion of a content in the preview buffer.

When the function mime-viewer/header-visible-p returns t for content-number of a content, content-header is displayed. This judge function returns t when a content is root or content-type of its parent is a member of the variable mime-viewer/childrens-header-showing-Content-Type-list.

If you want to change this condition, please redefine it.

When content-header is displayed, content-header are formated by content-header-filter. Content-header-filter is searched from variable mime-viewer/content-header-filter-alist. Its key is major-mode of the article buffer. If not found, function mime-viewer/default-content-header-filter is called.

 -- Variable: mime-viewer/childrens-header-showing-Content-Type-list

     List of content-type. If content-type of parent of a content is a member of this variable, its content-header is displayed. Default value is "message/rfc822".

     This variable is referred by the function mime-viewer/header-visible-p.

Function mime-viewer/header-visible-p cnum cinfo &optional ctype

Returns t if a content is displayed.

CNUM is content-number. CINFO is content-info. If you know content-type, you can specify by CTYPE.

 -- Variable: mime-viewer/content-header-filter-alist

     Association-list whose key is major-mode of a article buffer, value is content-header-filter.

Function mime-viewer/default-content-header-filter

It is called when content-header-filter is not found in variable mime-viewer/content-header-filter-alist.

content-body
============

Content-body represents content of the message. tm-view does not display raw content body. For example, if a content has binary, it is hidden. If a content has richtext, it is formated. Namely content body is hidden or formated.

Function mime-viewer/body-visible-p is a judge function whether content-body of a content is displayed. If it returns nil, content-body is hidden. In default, it returns non-nil when content-type of a content is a member of variable mime-viewer/default-showing-Content-Type-list.

When content-body of a content is displayed, content-body is formated by content-filter. Content-filter is searched from variable mime-viewer/content-filter-alist. At this time, major-mode of the article buffer is used as the key.

If it is not found, function mime-viewer/default-content-filter is called.

 -- Variable: mime-viewer/default-showing-Content-Type-list

     List of content-type. If content-type of a content is a member of this variable, its body is displayed.

Function mime-viewer/body-visible-p cnum cinfo &optional ctype

Return non-nil, if content-type of a content is displayed. CNUM is content-number of a content. CINFO is content-info of the message. If you know content-type of a content, you can specify it as argument CTYPE.

 -- Variable: mime-viewer/content-filter-alist

     Association-list whose key is major-mode of a article buffer, value is content-filter.

Function mime-viewer/default-content-filter cnum cinfo ctype params subj

It is called when content-body of a content should be displayed and content-filter is not found in mime-viewer/content-filter-alist.

In default, it does nothing.

content-separator
=================

Content-separator is displayed to represent boundary of contents.

Content-separator is displayed by function mime-viewer/default-content-separator. In default, it displays line-break when content-header and content-body are not displayed.

If you want to change this condition, please redefine this function.

Function mime-viewer/default-content-separator cnum cinfo ctype params subj

Display content-separator. CNUM is content-number of a content. CINFO is content-info of the message. CTYPE is content-type of a content. PARAMS is Content-Type field parameters of a content. SUBJ is subject.

In default, it displays line-break when content-header and content-body are not displayed.

Decoding
********

In mime/viewer-mode, you can do play (v), extract (e), or print (C-c C-p) for each content. These operations are called ``decoding operation(s) (for a content)''. And kind of decoding operations are called decoding-mode.

When decoding operation is driven, tm-view calls a procedure matched for the condition, such as content-type. This procedure is called method.

There are two kinds of method. One is Emacs Lisp function, called internal method. Another one is external program, called external method.

Internal method operates in Emacs, so it can do carefully.

External method is called as asynchronous process, so Emacs does not wait while method is running. So it is good for big data, such as audio, image or video.

Setting of content decoding condition
=====================================

When decoding operation is driven, tm-view calls a method matched for the condition searched from the variable mime/content-decoding-condition.

Variable mime/content-decoding-condition is defined as a list with the following syntax:

             (condition1 condition2 ...)

Each condition are association-list with the following syntax:

             ((field-type_1 . value_1)
              (field-type_2 . value_2)
              ...)

For example, if you want to call the external method named tm-plain to decode every text/plain type content, you can define the condition like

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

As you notice, now you can define the arguments to pass to a external method.  Refer to see Format of method value section for more explanation.

This condition definition will match all contents whose types are text/plain. Here is an another example:

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

This will match the content whose type is text/plain and the mode is play.

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

This will match all contents which have a mode of play.

The conditions defined in a mime/content-decoding-condition variable are examined from top to bottom.  The first matching condition becomes valid and the method specified in that condition definition will be executed.

Format of method value part
===========================

You can specify the method field of the decoding-condition definition in two different ways,

             (method . SYMBOL)

or

             (method  STRING  FLAG  ARGUMENT1  ARGUMENT2  ...)

can be accepted.

When a symbol is specified in the method field, a function whose name is SYMBOL will be called as an internal method.

When a list is specified in the method field, it will be called as an external method.

The list below shows the meaning of the parameters when the external method is specified in the method field.

STRING
     name of an external method

FLAG
     If t, both the content header and the content body are passed to an external method. if nil, only the content body is passed to an external method.

ARGUMENTs
     list of arguments passed to an external method

An argument passed to an external method can be in one of the following formats:

STRING
     string itself

'SYMBOL
     value gotten using SYMBOL as a key (see below)

'STRING
     value gotten using STRING as a key (see below)

'SYMBOL can be one of the following:

'file
     name of a file holding the original content

'type
     content-type/sub-type of Content-Type field

'encoding
     field body of Content-Transfer-Encoding field

'mode
     decoding-mode

'name
     name of a file created by decode operation

'STRING is used to search a parameter of the Content-Type field whose name matches with it, and pass the value of that parameter to the external method.

Examples of decoding-condition
==============================

The default definition of a mime/content-decoding-condition variable is shown below.

     (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"))
         ))

For example, if you want to use metamail to decode any contents,

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

will work.

A mime/content-decoding-condition variable provides you of very flexible way to define the conditions of decoding.  It can be simple if you only need the a few decoding methods, while it can be very complicated if you want to use the separate decoding method for each type/mode combination.

Following function may be useful to set decoding-condition. It is a function of tl-atype.el.

Function set-atype symbol alist

Add condition ALIST to symbol SYMBOL.

Example:

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

environment variables
*********************

Standard methods of tm-view reference some environment variables. You can specify them to customize.

TM_TMP_DIR
     Directory for temporary files or extracted files. Default value is `/tmp/'.

VIDEO_DITHER
     Dither for mpeg_play. Default value is `gray'.

TM_WWW_BROWSER
     WWW browser name. Default value is `netscape'.

encoded-word
************

tm-view can decode encoded-word defined in RFC 1522.

Command mime/decode-message-header

It decodes encoded-words in message header of current buffer.

Command mime-eword/decode-region beg end &optional unfolding

It decodes encoded-words in region BEG to END.

If UNFOLDING is non-nil, folded fields are unfolded.

Function mime-eword/decode-string str

It decodes encoded-words in STR.

Folded string is unfolded.