9 date 94.10.17.03.05.02; author morioka; state Exp;
14 date 94.10.17.02.55.02; author morioka; state Exp;
25 @I added description for vm.
28 @\documentstyle{report}
30 \title{tm Reference Manual (English Edition)}
31 \author{{\Large Morioka Tomohiko} \\
32 {\normalsize $<$morioka@@jaist.ac.jp$>$}\\
34 {\large translated by \Large Ueno Hiroshi} \\
35 {\normalsize $<$jl07715@@yamato.ibm.co.jp$>$}
37 \date{\verb$Id: tm-eng.tex,v 5.2 1994/10/17 02:55:02 morioka Exp morioka $}
46 The tm package is a set of modules to enjoy MIME on GNU Emacs. Using tm,
50 \item playback or view the MIME messages using new mime/viewer-mode
51 \item encode and decode the multi-lingual headers
52 \item use the enhanced MIME functions with mh-e, GNUS, and RMAIL
60 The tm package includes the modules listed below.
63 \item {\bf tiny-mime} : MIME header encoder/decoder
64 \item {\bf tm-view} : MIME message viewer
65 \item {\bf tm-misc} : common part of tm-MUAs
66 \item {\bf tm-MUAs} : MIME function enhancer for MUAs
68 \item {\bf tm-mh-e} : tm-MUA for mh-e
69 \item {\bf tm-gnus} : tm-MUA for GNUS
70 \item {\bf tm-rmail} : tm-MUA for RMAIL
71 \item {\bf tm-vm} : tm-MUA for vm
73 \item {\bf tm-setup} tm-MUA setup module
74 \item {\bf mime-setup} MIME setup module
78 \chapter{Considerations for Each Version of Emacs}
80 \section{Emacs (original)}
82 A single character set can be used if you use the original Emacs.
84 \section{NEmacs, NEpoch}
86 ISO-2022-JP and US-ASCII can be used if you use NEmacs.
91 Mule can handle the multi-lingual text. With Mule, tiny-mime supports
92 ISO-2022-JP, ISO-2022-JP-2, US-ASCII, ISO-8859-1..9, ISO-2022-CN,
93 ISO-2022-KR, EUC-KR, etc. You can also add or change
94 encoding/decoding for character sets by mime/set-charset-and-encoding
98 \chapter{Installation and Setup}
100 \section{Installation}
102 You can install tm by following the procedures below.
105 \item modify bindir definition in Makefile according to your build
107 \item modify the method scripts in methods/ directory so that it
108 can work in your environment. Refer to \ref{sec:method} section
109 for how you can suit the method scripts to your environment.
112 \item copy all files with .el suffix into the directory pointed by Emacs
116 \noindent{\bf [Notes]}
118 \item Make sure mh-e version 3.x has been loaded before byte-compiling
120 \item Make sure GNUS 3 has been loaded before byte-compiling tm-gnus3.el.
121 \item Use Emacs 18 when you byte-compile tl-18.el.
122 \item Use the original Emacs when you byte-compile tl-orig.el.
123 \item Use NEmacs when you byte-compile tl-nemacs.el.
124 \item Use Mule when you byte-compile tl-mule.el.
125 \item Modules byte-compiled by Emacs 19 do not work with Emacs 18.
131 In the tm package, two files, mime-setup.el and tm-setup.el, are provided
132 to ease the setup. A mime-setup.el is used for the whole MIME related
133 setup including MIME encoding, while tm-setup is used to set up tm-MUA
137 \subsection{mime-setup}
143 \noindent will perform various settings of MIME. As mime-setup loads
144 tm-setup, you do not need to load tm-setup when you use mime-setup.
146 You can also set up the "automatic signature selection tool" using
147 mime-setup. If you want to automatically select the signature file
148 depending on how the message headers show, add lines like shown below
149 to your .emacs (Refer to the reference manual of signature.el for
153 (setq signature-file-alist
154 '((("Newsgroups" . "jokes") . "~/.signature-jokes")
155 (("Newsgroups" . ("zxr" "nzr")) . "~/.signature-sun")
156 (("To" . ("ishimaru" "z-suzuki")) . "~/.signature-sun")
157 (("To" . "tea") . "~/.signature-jokes")
158 (("To" . ("sim" "oku" "takuo")) . "~/.signature-formal")
162 mime-setup requires mime.el. if you set up SuperCite via mime-setup,
163 you need the SuperCite package also.
166 \subsection{tm-setup}
168 tm-setup only sets up tm-MUAs. You do not need to explicitly load
169 tm-setup if you are using mime-setup for your setup. tm-setup is useful
170 when you do not want to use mime-setup but want to set up tm-MUAs.
179 If you want use vm, please insert following in .vm or .emacs:
186 \subsection{setting up without loading provided setup files}
188 You may find the valuable hints in tm-setup.el if you want to set up
189 MIME environment without loading the tm-provided setup files.
192 \subsection{setting up MH}
194 If you are using MH-6.8JP2, add the following lines to your
198 scan: -form scan.mime
200 repl: -form replcomps.mime
204 \noindent Emacs will handle the most part of MH processing. You
205 should not specify further options in your MH profile to avoid any
206 possible conflict between MH and Emacs.
212 ``tm-MUA'' is a generic name of the modules which enhance the MIME
213 functions of MUA like mh-e, GNUS, and RMAIL etc.
215 The current version of tm provides the following tm-MUA.
218 \item {\bf tm-mh-e} : tm-MUA for mh-e
219 \item {\bf tm-gnus} : tm-MUA for GNUS
220 \item {\bf tm-rmail} : tm-MUA for RAMIL
223 \noindent You can find the detailed explanations of these modules in
224 the following sections.
227 \section{Summary Mode}
229 If you are using tm-MUA, the following functions are added to the Summary
234 \begin{tabular}{|l|l|}\hline
235 key & function \\ \hline
236 M-t & toggles decoding of MIME headers \\
237 v & enters mime/view-mode \\ \hline
243 \section{mime/viewer-mode}
244 \label{sec:mime/viewer-mode}
246 If you are using tm-MUA, mime/viewer-mode becomes active by pressing
247 {\bf v} key in the Summary mode. In mime/viewer-mode, you can manipulate
248 the MIME messages by the simple key operations. The following list shows
249 the functions and their key bindings which can be used in mime/viewer-mode.
253 \begin{tabular}{|l|l|}\hline
254 key & function \\ \hline
255 u & goes to the upper content \\
256 & returns to the Summary mode if the cursor is sitting on
257 the top content (*1) \\
258 p & goes to the previous content \\
259 n & goes to the next content \\
261 M-SPC & scrolls down \\
262 DEL & scrolls down \\
263 RET & goes to the next line \\
264 M-RET & goes to the previous line \\
265 v & playbacks a content (*2) \\
266 e & extracts a file from a content (*2) \\
267 C-c C-p & prints a content (*2) \\ \hline
274 \newcounter{asteriskcount}
275 \noindent{\bf
\e$B!N
\e(BNote
\e$B!O
\e(B}
277 {\list{(*\arabic{asteriskcount})}{\usecounter{asteriskcount}\leftmargin=8ex}
278 \item Not return to the Summary mode unless tm-view has been setup using
279 tm-mh-e, tm-gnus, tm-rmail etc.
280 \item Actual playback/extract/print will be performed by a method.
284 \section{Customizing tm-gnus}
286 \subsection{saving articles without decoding}
288 By default, The articles will be saved as they appear in the buffer
291 You can save the articles always without decoding by setting a
292 tm-gnus/set-mime-header-decoding-mode variable to nil then call a
293 function which saves the articles.
295 The following example shows how you can save an article without
296 decoding, preserving the current MIME header decoding mode.
299 (let ((mm mime/header-decoding-mode))
300 (tm-gnus/set-mime-header-decoding-mode nil)
301 (article save function)
302 (tm-gnus/set-mime-header-decoding-mode mm)
306 The following is an example that saves the articles to a folder
310 (add-hook 'gnus-Startup-hook
313 (setq gnus-default-article-saver
317 (let ((mm mime/header-decoding-mode))
318 (tm-gnus/set-mime-header-decoding-mode nil)
319 (gnus-Subject-save-in-folder)
320 (tm-gnus/set-mime-header-decoding-mode mm)
322 (add-hook 'gnus-startup-hook
325 (setq gnus-default-article-saver
329 (let ((mm mime/header-decoding-mode))
330 (tm-gnus/set-mime-header-decoding-mode nil)
331 (gnus-summary-save-in-folder)
332 (tm-gnus/set-mime-header-decoding-mode mm)
336 \subsection{replying with encoded subject to an article with encoded subject}
338 When you reply to an article, you may want to encode the Subject field only
339 when the original article has an encoded Subject. It can be done by
340 defining a hook as shown below.
343 (add-hook 'gnus-article-prepare-hook
346 (if (mime/exist-encoded-word-in-subject)
347 (setq mime/no-encoding-header-fields '("X-Nsubject"))
348 (setq mime/no-encoding-header-fields '("X-Nsubject" "Subject"))
355 tm-view is a module which is used to examine the MIME messages.
356 It provides a mime/viewer-mode for that purpose.
358 Regarding the functions of mime/viewer-mode, refer to
359 \ref{sec:mime/viewer-mode} section.
361 \section{Defining Conditions of Decoding}
363 A mime/content-decoding-condition variable is used to define the methods
364 which will be called at decoding. It replaces a
365 mime/content-decoding-method-alist variable of tm-view version 4.x.
367 A mime/content-decoding-method-alist only allowed you to define a
368 method used for each content-type/subtype. Now a
369 mime/content-decoding-condition variable allows you to write more
370 complicated statements to describe the more detailed conditions to determine
371 which method is to be use.
373 A mime/content-decoding-condition variable is defined as a list with the
377 (condition_1 \;\; condition_2 \;\; ...)
380 \noindent Each condition is an association list with the following
384 ((field-type_1 \; . \; value_1) \;\;
385 (field-type_2 \; . \; value_2) \;\; ...)
390 For example, if you want to call the external method named tm-plain
391 to decode every text/plain type content, you can define the condition like
394 ((type . "text/plain")
395 (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
398 \noindent As you notice, now you can define the arguments to pass to a
399 external method. Refer to \ref{sec:method-arguments} section for more
402 This condition definition will match all contents whose types are text/plain.
403 Here is an another example.
406 ((type . "text/plain")
407 (method "tm-plain" nil 'file 'type 'encoding 'mode 'name)
411 \noindent This will match the content whose type is text/plain and
416 ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file)
420 \noindent This will match all contents which have a mode of play.
422 The conditions defined in a mime/content-decoding-condition variable
423 are examined from top to bottom. The first matching condition
424 becomes valid and the method specified in that condition definition
428 \subsection{arguments of method}
429 \label{sec:method-arguments}
431 You can specify the method field of the condition definition in two
435 (method \; . \; SYMBOL)
441 (method \; STRING \; FLAG \; ARGUMENT_1 \; ARGUMENT_2 \; ...)
444 \noindent can be accepted.
446 When a symbol is specified in the method field, it will be called as
449 When a list is specified in the method field, it will be called as an
450 external method. The list below shows the meaning of the parameters
451 when the external method is specified in the method field.
454 \item [STRING] name of an external method
455 \item [FLAG] if t, both the content header and the content body are
456 passed to an external method. if nil, only the content body is
457 passed to an external method.
458 \item [ARGUMENT$_x$] list of arguments passed to an external method
461 An argument passed to an external method can be in one of the following
466 STRING&:&string itself \\
467 'SYMBOL&:&value gotten using SYMBOL as a key (see below) \\
468 'STRING&:&value gotten using STRING as a key (see below)
472 'SYMBOL can be one of the following.
476 'file&:&name of a file holding the original content \\
477 'type&:&content-type/sub-type \\
478 'encoding&:&content-transfer-encoding \\
479 'mode&:&decoding mode \\
480 'name&:&name of a file created by decode operation
484 \noindent 'STRING is used to search a parameter of the Content-Type
485 field whose name matches with it, and pass the value of that parameter
486 to the external method.
489 \subsection{examples}
491 The default definition of a mime/content-decoding-condition variable is
495 (defvar mime/content-decoding-condition
496 '(((type . "text/plain")
497 (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
498 ((type . "text/x-latex")
499 (method "tm-latex" nil 'file 'type 'encoding 'mode 'name))
500 ((type . "audio/basic")
501 (method "tm-au" nil 'file 'type 'encoding 'mode 'name))
502 ((type . "image/gif")
503 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
504 ((type . "image/jpeg")
505 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
506 ((type . "image/tiff")
507 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
508 ((type . "image/x-tiff")
509 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
510 ((type . "image/x-xbm")
511 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
512 ((type . "image/x-pic")
513 (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
514 ((type . "video/mpeg")`
515 (method "tm-mpeg" nil 'file 'type 'encoding 'mode 'name))
516 ((type . "application/octet-stream")
517 (method "tm-file" nil 'file 'type 'encoding 'mode 'name))
518 ((type . "message/partial")
519 (method . mime/decode-message/partial-region))
520 ((method "metamail" t
521 "-m" "tm" "-x" "-d" "-z" "-e" 'file)(mode . "play"))
525 For example, if you want to use metamail to decode any contents,
528 (setq mime/content-decoding-condition
530 ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file))
536 A mime/content-decoding-condition variable provides you of very flexible
537 way to define the conditions of decoding. It can be simple if you only
538 need the a few decoding methods, while it can be very complicated if you
539 want to use the separate decoding method for each type/mode combination.
542 \section{Method Script}
545 The methods are written in shell script. The arguments passed from tm-view.el
546 to each method can be customized using mime/content-decoding-condition
547 variable. If you use the tm-provided setting of
548 mime/content-decoding-condition variable, the following arguments are
549 passed to the method.
553 \begin{tabular}{|c|l|} \hline
554 argument & \multicolumn{1}{|c|}{ meaning }\\ \hline
555 \$1 & file name before decoded \\
556 \$2 & Content-Type (type/sub-type) \\
558 \{7bit / quoted-printable / base64 / 8bit / binary / ...\}\\
559 \$4 & decoding-mode \{play / extract / print\} \\
560 \$5 & file name after decoded \\ \hline
565 Exceptionally, no method is used to restore message/partial messages
566 into one message. It is done by tm-view.el itself.
569 \section{Changing Appearance}
571 Each content in the preview buffer is shown in the following format.
579 \noindent tm-view shows one content in three separate portions.
582 \item content subject
590 \subsection{content subject}
592 A content subject indicates the beginning of a content in the preview
593 buffer. By default, it will be shown as below.
599 \noindent The cid field shows the position of a content in the message.
600 It can be considered as the chapter number in the message. The title
601 field is composed of the text string from the Subject and the
602 Content-Description field. The type field is a copy of a
603 text string specified in the type/subtype field of the content.
605 You can customize how the content subject appears in the preview
606 buffer by modifying a definition of mime/make-content-subject-function
607 variable. The tm-view provides a following definition as a default.
610 (defvar mime/make-content-subject-function
612 (lambda (cid subj ctype)
614 (format "[%s %s (%s)]\n"
618 (format "%s" (+ num 1))
626 \noindent The following is an example of the customization.
629 (setq mime/make-content-subject-function
631 (lambda (cid subj ctype)
632 (if (not (member (car ctype) mime/default-showing-Content-Type-list))
634 (format "[%s %s (%s)]\n"
638 (format "%s" (+ num 1))
646 \noindent This will show the content subjects only for the contents whose body
647 portions are to be hidden.
650 \subsection{content header}
652 A content header shows the header portion of a content in the preview
653 buffer. The default setup will show no content headers.
655 You can customize how the content header appears in the preview
656 buffer by modifying a definition of mime/make-content-header-filter
657 variable. The tm-view provides a following default definition.
661 (defvar mime/make-content-header-filter
665 (delete-region (goto-char (point-min))
666 (or (and (re-search-forward "^$" nil t)
674 \noindent The default setting removes all content headers
675 until it detects a blank line delimiting the headers and the body.
676 If you change a mime/make-content-header-filter variable like
679 (setq mime/make-content-header-filter
685 \noindent you will see all headers in the content header portion.
688 \subsection{content body}
690 According to the type of content, the body portion of the content
691 is managed by tm-view using
698 \noindent techniques before it is put in the preview buffer.
700 'Hide' is performed to prevent showing the non-text type content body
701 in the preview buffer. A mime/default-showing-Content-Type-list
702 variable defines which type of contents will NOT be hidden. It has
703 the following default value.
706 (defvar mime/default-showing-Content-Type-list
707 '("text/plain" "text/richtext" "text/enriched" "text/x-latex" nil))
710 \noindent All contents are hidden except text/plain, text/richtext,
711 text/enriched, text/x-latex, and non-MIME contents.
713 A content body which was not "hidden" is then "processed". A list
714 in a mime/content-filter-alist variable will be searched looking up
715 an entry which matches with the content-type of a content. If a matching
716 entry is found, the function defined in that entry will be called
717 to "process" a content body.
719 A mime/content-filter-alist variable has nil as a default value. It
720 will have non-nil after loading tm-rich.el which contains the following
724 (aput 'mime/content-filter-alist
725 "text/enriched" (function mime/decode-text/enriched-body))
728 \noindent This is defining a process to be done to the text/enriched
729 type content body. A function mime/decode-text/enriched-body will
730 be called if a text/enriched body need to be "processed".
733 \section{Restrictions}
735 A decode-b.c file in the tm package is the source of the BASE64
736 decoder. As it was not thoroughly tested, it may not work for you.
737 But at least you can see what it wants to do so that you can correct
738 errors in the source code. (\verb+^+\_\verb+^+;
740 Or you can use mmencode in the metamail package to decode the BASE64
743 Use mmencode to decode the Quoted-Printable messages. The tm package
744 does not include the decoder for Quoted-Printable.
749 tiny-mime is a multi-lingual MIME style message header
750 encoder/decoder based on RFC 1522 for Mule, NEmacs, and NEpoch. It
751 is based on Mr. Enami's ISO-2022-JP Base64 MIME header decoder which
752 could decode only ISO-2022-JP Base64-encoded headers. The following list
753 shows some of the functional enhancemets I made in tiny-mime.
756 \item unfolding at decoding
757 \item encoding/decoding multilingual character sets, such as,
758 ISO-2022-JP, ISO-2022-JP-2, ISO-2022-CN, ISO-2022-KR, ISO-8859-*,
761 \item compliance with RFC 1522
766 tiny-mime is a MIME headers encoder/decoder in the tm package and used
767 by tm-view and tm-MUAs.
770 \section{mime/decode-message-header}
772 {\tt mime/decode-message-header} is a command to decode the MIME headers.
773 You need to load tiny-mime before you can use this command.
775 {\list{}{\leftmargin=8ex}\item[]
777 M-x {\tt mime/decode-message-header}
780 \noindent will decode the MIME headers in the current buffer.
782 tm-MUAs and tm-view use this command to decode the MIME headers.
783 Therefore, it may not be required to explicitly execute this command if
787 \section{mime/decode-region}
789 You can decode the MIME messages within the specified region by executing
791 {\list{}{\leftmargin=8ex}\item[]
793 M-x {\tt mime/decode-region}
796 \noindent This is useful when you want to decode the MIME headers
797 which are yanked from the referenced article.
800 \chapter{Reporting Bugs}
802 Please report tm bugs you find to fj.editor.emacs or send a mail to
803 tm ML, $<$tm@@chamonix.jaist.ac.jp$>$.
805 Via tm ML, You can report bugs of tm, obtain the latest release of tm
806 package, and discuss the future enhancements to tm. To join tm ML,
810 tm-admin@@chamonix.jaist.ac.jp
813 \noindent Since the user registration is manually done, please write
814 the mail body in human-recognizable language (\verb+^+\_\verb+^+).
822 @*** empty log message ***
827 \date{\verb$Id: tm-eng.tex,v 5.2 1994/10/11 17:17:05 morioka Exp $}