3 @setfilename tm-view_en.info
4 @settitle{tm-view manual}
7 @title tm-view Manual (English Version)
8 @author by MORIOKA Tomohiko
9 @code{$Id: tm-view_en.texi,v 7.2 1995/10/18 18:11:46 morioka Exp $}
13 @node Top, Abstract, (tm_en.info), (tm_en.info)
14 @comment node-name, next, previous, up
16 @top tm-view 7.16 Reference manual
18 The tm-view is a general MIME viewer running on GNU Emacs.
20 tm-view provides the major-mode called @code{mime/viewer-mode} to read
21 MIME message for MUA. MUA implementer can use it to add MIME function.
25 * Abstract:: What is tm-view?
26 * How to run:: How to run mime/viewer-mode.
27 * Commands:: Commands of mime/viewer-mode.
28 * Preview Buffer:: Screen design of preview buffer.
29 * Decoding:: Mechanism of decoding operations for
31 * environment variables:: environment variables for standard methods
33 * encoded-word:: encoded-word decoding
36 * Preview Buffer:: Screen design of preview buffer.
43 * Decoding:: Mechanism of decoding operations for contents.
44 * decoding-condition:: Setting of content decoding condition.
45 * Format of method value:: Format of method value part.
46 * Example of decoding-condition:: Examples of decoding-condition.
55 @node Abstract, How to run, Top, Top
56 @comment node-name, next, previous, up
57 @chapter What is tm-view?
60 tm-view is a general MIME viewer for GNU Emacs.
62 It provides a major-mode to navigate MIME message to each MUAs.
64 tm-view managements two buffers, one is for raw message called
65 @strong{article buffer}, another one is to preview for user called
66 @strong{preview buffer}.
68 When called @code{mime/viewer-mode}, tm-view analyzes article buffer,
69 and sets its result to the variable @code{mime::article/content-info}.
71 After that, tm-view create a preview buffer corresponded to the
72 article buffer. As this time, tm-view modifies header and body of each
73 contents of the message. It is done by definition for Content-Types.
75 On the preview buffer created by tm-view, user can manipulate a
76 message to decode, such as run external vewer, extract files, or
79 Notice: In this document, I call @strong{content-type} as
80 content-type/subtype of Content-Type field.
83 @node How to run, Commands, Abstract, Top
84 @comment node-name, next, previous, up
85 @chapter How to run mime/viewer-mode
86 @cindex How to run mime/viewer-mode
88 @deffn{Command} mime/viewer-mode &optional mother ctl encoding
90 Parse current-buffer as a MIME message, and create preview buffer to
91 display to user, then enter @code{mime/viewer-mode}.
93 @var{mother} is used to specify original article buffer. It may be
94 useful when an article buffer is assembled from message/partial.
96 @var{ctl} is used to specify Content-Type field information. Its
97 format is output format of @code{mime/Content-Type}. When @var{ctl} is
98 specified, tm-view uses it instead of Content-Type field of the
101 @var{encoding} is used to specify field-body of
102 Content-Transfer-Encoding field. When is is specified, tm-view uses it
103 instead of Content-Type field of the article buffer.
107 @node Commands, Preview Buffer, How to run, Top
108 @comment node-name, next, previous, up
109 @chapter Commands of mime/viewer-mode
110 @cindex Commands of mime/viewer-mode
112 @code{mime/viewer-mode} has following functions:
116 goes to the upper content (returns to the Summary mode if the
117 cursor is sitting on the top content (*1))
119 goes to the previous content
121 goes to the next content
129 goes to the next line
131 goes to the previous line
133 playbacks a content (*2)
135 extracts a file from a content (*2)
137 prints a content (*2)
143 Not return to the Summary mode unless tm-view has been setup using
144 tm-mh-e, tm-gnus, tm-rmail etc.
147 Actual playback/extract/print will be performed by a method.
151 @node Preview Buffer, Decoding, Commands, Top
152 @comment node-name, next, previous, up
153 @chapter Screen design of preview buffer
154 @cindex Screen design of preview buffer
156 In preview buffer, following are displayed for each content:
166 You can change design or stop to display if you specify for each
172 From: MORIOKA Tomohiko <morioka@@jaist.ac.jp>
173 Newsgroups: zxr.comp.emacs.tm-english
174 Subject: tm6.63.tar.gz
175 Date: Mon, 26 Jun 1995 17:39:50 JST
176 Organization: Chamonix, JAIST, Tatsunokuchi, Ishikawa, Japan
177 Reply-To: tm-eng@@chamonix.jaist.ac.jp
178 To: tm-eng@@chamonix.jaist.ac.jp
179 In-Reply-To: Your message of "Sun, 25 Jun 1995 23:20:49 MST"
180 X-Mua: mh-e 4.1 + tm 6.63 / Mule 2.2 (WAKAMURASAKI) PL02
181 X-Mime-Composer: mime.el + tiny-mime 5.12
185 I put tm6.63.tar.gz in ftp.jaist.ac.jp.
187 In this version, tm-view uses new MIME encoding/decoding engine
188 ``mel (MIME encoding library''. This library has internal/external
189 encoding/decoding engine. If data is smaller than a limit, tm-view
190 uses internal decoder, otherwise external decoder.
192 [2 tm6.63.tar.gz ([anon-ftp] ftp.jaist.ac.jp:/pub/GNU/elisp/mime/alpha)]
196 MORIOKA, Tomohiko <morioka@@jaist.ac.jp>
204 * content-separator::
208 @node content-subject, content-header, Preview Buffer, Preview Buffer
209 @comment node-name, next, previous, up
210 @section content-subject
211 @cindex content-subject
213 content-subject is a part to display abstract for the content. It is
214 placed in top of content.
216 In default, it is displayed following design:
219 [1.3 test (text/plain)]
222 First number field represents position of a content in the message. It
223 is called `content-number'. It can be considered as the chapter number
226 Second string part represents title. It is created by following:
229 @item name paramater or x-name parameter in Content-Type field
230 @item Content-Description field or Subject field
231 @item filename of uuencode
234 If they are not exists, space is displayed.
236 Third parenthesis part represents content-type/subtype of the
237 content. If it is non-MIME part, @code{nil} is displayed.
239 Content-subject is used like icon when content-header and content-body
240 are hidden. For example,
246 if you press `v' key, GIF image is displayed.
249 @defvr{Variable} mime-viewer/content-subject-omitting-Content-Type-list
251 List of content-type. If content-type of a content is a member of this
252 list, its content-subject is not displayed.
254 This variable is referenced by function
255 @code{mime-viewer/default-content-subject-function}.
259 @deffn{Function} mime-viewer/default-content-subject-function cnum cinfo ctype params subj
261 Default value of the variable
262 @code{mime-viewer/content-subject-function}.
264 @code{mime-viewer/content-subject-omitting-Content-Type-list}.
268 @defvar mime-viewer/content-subject-function cnum cinfo ctype params subj
270 Variable to specify content-subject display function. Default value is
271 the function @code{mime-viewer/default-content-subject-function}.
275 @node content-header, content-body, content-subject, Preview Buffer
276 @comment node-name, next, previous, up
277 @section content-header
278 @cindex content-header
280 A content header shows the header portion of a content in the preview
283 When the function @code{mime-viewer/header-visible-p} returns @code{t}
284 for content-number of a content, content-header is displayed. This
285 judge function returns @code{t} when a content is root or content-type
286 of its parent is a member of the variable
287 @code{mime-viewer/childrens-header-showing-Content-Type-list}.
289 If you want to change this condition, please redefine it.
291 When content-header is displayed, content-header are formated by
292 content-header-filter. Content-header-filter is searched from variable
293 @code{mime-viewer/content-header-filter-alist}. Its key is major-mode
294 of the article buffer. If not found, function
295 @code{mime-viewer/default-content-header-filter} is called.
298 @defvar mime-viewer/childrens-header-showing-Content-Type-list
300 List of content-type. If content-type of parent of a content is a
301 member of this variable, its content-header is displayed.
302 Default value is "message/rfc822".
304 This variable is referred by the function
305 @code{mime-viewer/header-visible-p}.
309 @deffn{Function} mime-viewer/header-visible-p cnum cinfo &optional ctype
311 Returns @code{t} if a content is displayed.
313 @var{cnum} is content-number. @var{cinfo} is content-info. If you know
314 content-type, you can specify by @var{ctype}.
318 @defvar mime-viewer/content-header-filter-alist
320 Association-list whose key is major-mode of a article buffer, value is
321 content-header-filter.
325 @deffn{Function} mime-viewer/default-content-header-filter
327 It is called when content-header-filter is not found in variable
328 @code{mime-viewer/content-header-filter-alist}.
332 @node content-body, content-separator, content-header, Preview Buffer
333 @comment node-name, next, previous, up
334 @section content-body
337 Content-body represents content of the message. tm-view does not
338 display raw content body. For example, if a content has binary, it is
339 hidden. If a content has richtext, it is formated. Namely content body
340 is hidden or formated.
342 Function @code{mime-viewer/body-visible-p} is a judge function whether
343 content-body of a content is displayed. If it returns @code{nil},
344 content-body is hidden. In default, it returns non-@code{nil} when
345 content-type of a content is a member of variable
346 @code{mime-viewer/default-showing-Content-Type-list}.
348 When content-body of a content is displayed, content-body is formated
349 by content-filter. Content-filter is searched from variable
350 @code{mime-viewer/content-filter-alist}. At this time, major-mode of
351 the article buffer is used as the key.
353 If it is not found, function @code{mime-viewer/default-content-filter}
357 @defvar mime-viewer/default-showing-Content-Type-list
359 List of content-type. If content-type of a content is a member of this
360 variable, its body is displayed.
364 @deffn{Function} mime-viewer/body-visible-p cnum cinfo &optional ctype
366 Return non-@code{nil}, if content-type of a content is displayed.
367 @var{cnum} is content-number of a content. @var{cinfo} is content-info
368 of the message. If you know content-type of a content, you can specify
369 it as argument @var{ctype}.
373 @defvar mime-viewer/content-filter-alist
375 Association-list whose key is major-mode of a article buffer, value is
380 @deffn{Function} mime-viewer/default-content-filter cnum cinfo ctype params subj
382 It is called when content-body of a content should be displayed and
383 content-filter is not found in
384 @code{mime-viewer/content-filter-alist}.
386 In default, it does nothing.
390 @node content-separator, , content-body, Preview Buffer
391 @comment node-name, next, previous, up
392 @section content-separator
393 @cindex content-separator
395 Content-separator is displayed to represent boundary of contents.
397 Content-separator is displayed by function
398 @code{mime-viewer/default-content-separator}. In default, it displays
399 line-break when content-header and content-body are not displayed.
401 If you want to change this condition, please redefine this function.
404 @deffn{Function} mime-viewer/default-content-separator cnum cinfo ctype params subj
406 Display content-separator. @var{cnum} is content-number of a
407 content. @var{cinfo} is content-info of the message. @var{ctype} is
408 content-type of a content. @var{params} is Content-Type field
409 parameters of a content. @var{subj} is subject.
411 In default, it displays line-break when content-header and
412 content-body are not displayed.
416 @node Decoding, environment variables, Preview Buffer, Top
417 @comment node-name, next, previous, up
421 In @code{mime/viewer-mode}, you can do play (@key{v}), extract
422 (@key{e}), or print (@key{C-c C-p}) for each content. These operations
423 are called ``decoding operation(s) (for a content)''. And kind of
424 decoding operations are called @strong{decoding-mode}.
426 When decoding operation is driven, tm-view calls a procedure matched
427 for the condition, such as content-type. This procedure is called
430 There are two kinds of method. One is Emacs Lisp function, called
431 @strong{internal method}. Another one is external program, called
432 @strong{external method}.
434 Internal method operates in Emacs, so it can do carefully.
436 External method is called as asynchronous process, so Emacs does not
437 wait while method is running. So it is good for big data, such as
438 audio, image or video.
441 * decoding-condition:: Setting of content decoding condition.
442 * Format of method value:: Format of method value part.
443 * Example of decoding-condition:: Examples of decoding-condition.
447 @node decoding-condition, Format of method value, Decoding, Decoding
448 @comment node-name, next, previous, up
449 @section Setting of content decoding condition
450 @cindex Setting of content decoding condition
452 When decoding operation is driven, tm-view calls a method matched for
453 the condition searched from the variable
454 @code{mime/content-decoding-condition}.
456 Variable @code{mime/content-decoding-condition} is defined as a list
457 with the following syntax:
460 (condition1 condition2 ...)
463 Each condition are association-list with the following syntax:
466 ((field-type_1 . value_1)
467 (field-type_2 . value_2)
471 For example, if you want to call the external method named tm-plain to
472 decode every text/plain type content, you can define the condition
476 ((type . "text/plain")
477 (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
480 As you notice, now you can define the arguments to pass to a external
481 method. Refer to @xref{Format of method value} section for more
484 This condition definition will match all contents whose types are
485 text/plain. Here is an another example:
488 ((type . "text/plain")
489 (method "tm-plain" nil 'file 'type 'encoding 'mode 'name)
493 This will match the content whose type is text/plain and the mode is
497 ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file)
501 This will match all contents which have a mode of play.
503 The conditions defined in a mime/content-decoding-condition variable
504 are examined from top to bottom. The first matching condition becomes
505 valid and the method specified in that condition definition will be
509 @node Format of method value, Example of decoding-condition, decoding-condition, Decoding
510 @comment node-name, next, previous, up
511 @section Format of method value part
512 @cindex Format of method value part
514 You can specify the method field of the decoding-condition definition
515 in two different ways,
524 (method STRING FLAG ARGUMENT1 ARGUMENT2 ...)
529 When a symbol is specified in the method field, a function whose name
530 is SYMBOL will be called as an internal method.
532 When a list is specified in the method field, it will be called as an
535 The list below shows the meaning of the parameters when the external
536 method is specified in the method field.
540 name of an external method
542 If @code{t}, both the content header and the content body are
543 passed to an external method. if nil, only the content body is
544 passed to an external method.
546 list of arguments passed to an external method
549 An argument passed to an external method can be in one of the
556 value gotten using SYMBOL as a key (see below)
558 value gotten using STRING as a key (see below)
561 'SYMBOL can be one of the following:
565 name of a file holding the original content
567 content-type/sub-type of Content-Type field
569 field body of Content-Transfer-Encoding field
573 name of a file created by decode operation
576 'STRING is used to search a parameter of the Content-Type field whose
577 name matches with it, and pass the value of that parameter to the
581 @node Example of decoding-condition, , Format of method value, Decoding
582 @comment node-name, next, previous, up
583 @section Examples of decoding-condition
584 @cindex Examples of decoding-condition
586 The default definition of a mime/content-decoding-condition variable
590 (defvar mime/content-decoding-condition
591 '(((type . "text/plain")
592 (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
593 ((type . "text/x-latex")
594 (method "tm-latex" nil 'file 'type 'encoding 'mode 'name))
595 ((type . "audio/basic")
596 (method "tm-au" nil 'file 'type 'encoding 'mode 'name))
597 ((type . "image/gif")
598 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
599 ((type . "image/jpeg")
600 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
601 ((type . "image/tiff")
602 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
603 ((type . "image/x-tiff")
604 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
605 ((type . "image/x-xbm")
606 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
607 ((type . "image/x-pic")
608 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
609 ((type . "video/mpeg")`
610 (method "tm-mpeg" nil 'file 'type 'encoding 'mode 'name))
611 ((type . "application/octet-stream")
612 (method "tm-file" nil 'file 'type 'encoding 'mode 'name))
613 ((type . "message/partial")
614 (method . mime/decode-message/partial-region))
615 ((method "metamail" t
616 "-m" "tm" "-x" "-d" "-z" "-e" 'file)(mode . "play"))
620 For example, if you want to use metamail to decode any contents,
623 (setq mime/content-decoding-condition
625 ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file))
631 A mime/content-decoding-condition variable provides you of very flexible
632 way to define the conditions of decoding. It can be simple if you only
633 need the a few decoding methods, while it can be very complicated if you
634 want to use the separate decoding method for each type/mode combination.
637 Following function may be useful to set decoding-condition. It is a
638 function of tl-atype.el.
641 @deffn{Function} set-atype symbol alist
643 Add condition @var{alist} to symbol @var{symbol}.
648 (set-atype 'mime/content-decoding-condition
649 '((type . "message/external-body")
650 ("access-type" . "anon-ftp")
651 (method . mime/decode-message/external-ftp)
657 @node environment variables, encoded-word, Decoding, Top
658 @comment node-name, next, previous, up
659 @chapter environment variables
660 @cindex environment variables
662 Standard methods of tm-view reference some environment variables. You
663 can specify them to customize.
668 Directory for temporary files or extracted files. Default value is
672 Dither for mpeg_play. Default value is `gray'.
675 WWW browser name. Default value is `netscape'.
679 @node encoded-word, Concept Index, environment variables, Top
680 @comment node-name, next, previous, up
681 @chapter encoded-word
683 @cindex non-ASCII field
684 @cindex message header
686 tm-view can decode encoded-word defined in RFC 1522.
688 @deffn{Command} mime/decode-message-header
690 It decodes encoded-words in message header of current buffer.
694 @deffn{Command} mime-eword/decode-region beg end &optional unfolding
696 It decodes encoded-words in region @var{beg} to @var{end}.
698 If @var{unfolding} is non-nil, folded fields are unfolded.
702 @deffn{Function} mime-eword/decode-string str
704 It decodes encoded-words in @var{str}.
706 Folded string is unfolded.
710 @node Concept Index, Command Index, encoded-word, Top
711 @unnumbered Concept Index
716 @node Command Index, Variable Index, Concept Index, Top
717 @unnumbered Command and Function Index
722 @node Variable Index, , Command Index, Top
723 @unnumbered Variable Index