doc/tm-view-m=en.texi

   1 @c $Id: tm-view-m=en.texi,v 3.0 1995/12/17 23:02:56 morioka Exp $
   2
   3 @node method, Mechanism of tm-view, mime/viewer-mode, tm-view
   4 @comment  node-name,  next,  previous,  up
   5 @section method
   6 @cindex method
   7
   8 In @code{mime/viewer-mode}, you can do play (@key{v}), extract
   9 (@key{e}), or print (@key{C-c C-p}) for each content. These operations
  10 are called ``decoding operation(s) (for a content)''. And kind of
  11 decoding operations are called @strong{decoding-mode}.
  12
  13 When decoding operation is driven, tm-view calls a procedure matched
  14 for the condition, such as content-type. This procedure is called
  15 @strong{method}.
  16
  17 There are two kinds of method. One is Emacs Lisp function, called
  18 @strong{internal method}. Another one is external program, called
  19 @strong{external method}.
  20
  21 Internal method operates in Emacs, so it can do carefully.
  22
  23 External method is called as asynchronous process, so Emacs does not
  24 wait while method is running. So it is good for big data, such as
  25 audio, image or video.
  26
  27 @menu
  28 * decoding-condition::     Setting of content decoding condition
  29 * Format of method value::
  30 * Example of decoding-condition::
  31 * environment variables::
  32 @end menu
  33
  34
  35 @node decoding-condition, Format of method value, method, method
  36 @comment  node-name,  next,  previous,  up
  37 @subsection Setting of content decoding condition
  38 @cindex content decoding condition
  39
  40 When decoding operation is driven, tm-view calls a method matched for
  41 the condition searched from the variable
  42 @code{mime/content-decoding-condition}.
  43
  44 Variable @code{mime/content-decoding-condition} is defined as a list
  45 with the following syntax:
  46
  47 @lisp
  48         (condition1 condition2 ...)
  49 @end lisp
  50
  51 Each condition are association-list with the following syntax:
  52
  53 @lisp
  54         ((field-type_1 . value_1)
  55          (field-type_2 . value_2)
  56          ...)
  57 @end lisp
  58
  59 For example, if you want to call the external method named tm-plain to
  60 decode every text/plain type content, you can define the condition
  61 like
  62
  63 @lisp
  64         ((type . "text/plain")
  65          (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
  66 @end lisp
  67
  68 As you notice, now you can define the arguments to pass to a external
  69 method.  Refer to @xref{Format of method value} section for more
  70 explanation.
  71
  72 This condition definition will match all contents whose types are
  73 text/plain. Here is an another example:
  74
  75 @lisp
  76         ((type . "text/plain")
  77          (method "tm-plain" nil 'file 'type 'encoding 'mode 'name)
  78          (mode . "play"))
  79 @end lisp
  80
  81 This will match the content whose type is text/plain and the mode is
  82 play.
  83
  84 @lisp
  85         ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file)
  86          (mode . "play"))
  87 @end lisp
  88
  89 This will match all contents which have a mode of play.
  90
  91 The conditions defined in a mime/content-decoding-condition variable
  92 are examined from top to bottom.  The first matching condition becomes
  93 valid and the method specified in that condition definition will be
  94 executed.
  95
  96
  97 @node Format of method value, Example of decoding-condition, decoding-condition, method
  98 @comment  node-name,  next,  previous,  up
  99 @subsection Format of method value part
 100 @cindex Format of method value part
 101
 102 You can specify the method field of the decoding-condition definition
 103 in two different ways,
 104
 105 @lisp
 106         (method . SYMBOL)
 107 @end lisp
 108
 109 or
 110
 111 @lisp
 112         (method  STRING  FLAG  ARGUMENT1  ARGUMENT2  ...)
 113 @end lisp
 114
 115 can be accepted.
 116
 117 When a symbol is specified in the method field, a function whose name
 118 is SYMBOL will be called as an internal method.
 119
 120 When a list is specified in the method field, it will be called as an
 121 external method.
 122
 123 The list below shows the meaning of the parameters when the external
 124 method is specified in the method field.
 125
 126 @table @samp
 127 @item STRING
 128         name of an external method
 129 @item FLAG
 130         If @code{t}, both the content header and the content body are
 131         passed to an external method. if nil, only the content body is
 132         passed to an external method.
 133 @item ARGUMENTs
 134         list of arguments passed to an external method
 135 @end table
 136
 137 An argument passed to an external method can be in one of the
 138 following formats:
 139
 140 @table @samp
 141 @item STRING
 142         string itself
 143 @item 'SYMBOL
 144         value gotten using SYMBOL as a key (see below)
 145 @item 'STRING
 146         value gotten using STRING as a key (see below)
 147 @end table
 148
 149 'SYMBOL can be one of the following:
 150
 151 @table @samp
 152 @item 'file
 153         name of a file holding the original content
 154 @item 'type
 155         content-type/sub-type of Content-Type field
 156 @item 'encoding
 157         field body of Content-Transfer-Encoding field
 158 @item 'mode
 159         decoding-mode
 160 @item 'name
 161         name of a file created by decode operation
 162 @end table
 163
 164 'STRING is used to search a parameter of the Content-Type field whose
 165 name matches with it, and pass the value of that parameter to the
 166 external method.
 167
 168
 169 @node Example of decoding-condition, environment variables, Format of method value, method
 170 @comment  node-name,  next,  previous,  up
 171 @subsection Examples of decoding-condition
 172 @cindex Examples of decoding-condition
 173
 174 The default definition of a mime/content-decoding-condition variable
 175 is shown below.
 176
 177 @lisp
 178 (defvar mime/content-decoding-condition
 179   '(((type . "text/plain")
 180      (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
 181     ((type . "text/x-latex")
 182      (method "tm-latex" nil 'file 'type 'encoding 'mode 'name))
 183     ((type . "audio/basic")
 184      (method "tm-au"    nil 'file 'type 'encoding 'mode 'name))
 185     ((type . "image/gif")
 186      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 187     ((type . "image/jpeg")
 188      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 189     ((type . "image/tiff")
 190      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 191     ((type . "image/x-tiff")
 192      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 193     ((type . "image/x-xbm")
 194      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 195     ((type . "image/x-pic")
 196      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 197     ((type . "video/mpeg")`
 198      (method "tm-mpeg"  nil 'file 'type 'encoding 'mode 'name))
 199     ((type . "application/octet-stream")
 200      (method "tm-file"  nil 'file 'type 'encoding 'mode 'name))
 201     ((type . "message/partial")
 202      (method . mime/decode-message/partial-region))
 203     ((method "metamail" t
 204              "-m" "tm" "-x" "-d" "-z" "-e" 'file)(mode . "play"))
 205     ))
 206 @end lisp
 207
 208 For example, if you want to use metamail to decode any contents,
 209
 210 @lisp
 211 (setq mime/content-decoding-condition
 212       '(
 213         ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file))
 214        ))
 215 @end lisp
 216
 217 will work.
 218
 219 A mime/content-decoding-condition variable provides you of very flexible
 220 way to define the conditions of decoding.  It can be simple if you only
 221 need the a few decoding methods, while it can be very complicated if you
 222 want to use the separate decoding method for each type/mode combination.
 223
 224 Following function may be useful to set decoding-condition. It is a
 225 function of tl-atype.el.
 226
 227
 228 @deffn{Function} set-atype symbol alist
 229
 230 Add condition @var{alist} to symbol @var{symbol}.
 231
 232 Example:
 233
 234 @lisp
 235 (set-atype 'mime/content-decoding-condition
 236            '((type . "message/external-body")
 237              ("access-type" . "anon-ftp")
 238              (method . mime/decode-message/external-ftp)
 239              ))
 240 @end lisp
 241 @end deffn
 242
 243
 244 @node environment variables,  , Example of decoding-condition, method
 245 @comment  node-name,  next,  previous,  up
 246 @subsection environment variables
 247 @cindex environment variables
 248
 249 Standard methods of tm-view reference some environment variables. You
 250 can specify them to customize.
 251
 252 @table @var
 253 @item TM_TMP_DIR
 254 Directory for temporary files or extracted files. Default value is
 255 `/tmp/'.
 256
 257 @item VIDEO_DITHER
 258 Dither for mpeg_play. Default value is `gray'.
 259
 260 @item TM_WWW_BROWSER
 261 WWW browser name. Default value is `netscape'.
 262 @end table