method
======

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'.