doc/tm-view-m_en.texi

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