head 5.4; access; symbols; locks; strict; comment @% @; 5.4 date 94.10.17.03.05.02; author morioka; state Exp; branches; next 5.2; 5.2 date 94.10.17.02.55.02; author morioka; state Exp; branches; next ; desc @@ 5.4 log @I added description for vm. @ text @\documentstyle{report} \title{tm Reference Manual (English Edition)} \author{{\Large Morioka Tomohiko} \\ {\normalsize $<$morioka@@jaist.ac.jp$>$}\\ \\ {\large translated by \Large Ueno Hiroshi} \\ {\normalsize $<$jl07715@@yamato.ibm.co.jp$>$} } \date{\verb$Id: tm-eng.tex,v 5.2 1994/10/17 02:55:02 morioka Exp morioka $} \begin{document} \maketitle \tableofcontents \chapter{Overview} The tm package is a set of modules to enjoy MIME on GNU Emacs. Using tm, you can \begin{itemize} \item playback or view the MIME messages using new mime/viewer-mode \item encode and decode the multi-lingual headers \item use the enhanced MIME functions with mh-e, GNUS, and RMAIL \end{itemize} \noindent and more. \section{Module List} The tm package includes the modules listed below. \begin{itemize} \item {\bf tiny-mime} : MIME header encoder/decoder \item {\bf tm-view} : MIME message viewer \item {\bf tm-misc} : common part of tm-MUAs \item {\bf tm-MUAs} : MIME function enhancer for MUAs \begin{itemize} \item {\bf tm-mh-e} : tm-MUA for mh-e \item {\bf tm-gnus} : tm-MUA for GNUS \item {\bf tm-rmail} : tm-MUA for RMAIL \item {\bf tm-vm} : tm-MUA for vm \end{itemize} \item {\bf tm-setup} tm-MUA setup module \item {\bf mime-setup} MIME setup module \end{itemize} \chapter{Considerations for Each Version of Emacs} \section{Emacs (original)} A single character set can be used if you use the original Emacs. \section{NEmacs, NEpoch} ISO-2022-JP and US-ASCII can be used if you use NEmacs. \section{Mule} Mule can handle the multi-lingual text. With Mule, tiny-mime supports ISO-2022-JP, ISO-2022-JP-2, US-ASCII, ISO-8859-1..9, ISO-2022-CN, ISO-2022-KR, EUC-KR, etc. You can also add or change encoding/decoding for character sets by mime/set-charset-and-encoding function. \chapter{Installation and Setup} \section{Installation} You can install tm by following the procedures below. \begin{enumerate} \item modify bindir definition in Makefile according to your build environment. \item modify the method scripts in methods/ directory so that it can work in your environment. Refer to \ref{sec:method} section for how you can suit the method scripts to your environment. \item make all \item make install \item copy all files with .el suffix into the directory pointed by Emacs load-path variable. \end{enumerate} \noindent{\bf [Notes]} \begin{itemize} \item Make sure mh-e version 3.x has been loaded before byte-compiling tm-mh-e3.el. \item Make sure GNUS 3 has been loaded before byte-compiling tm-gnus3.el. \item Use Emacs 18 when you byte-compile tl-18.el. \item Use the original Emacs when you byte-compile tl-orig.el. \item Use NEmacs when you byte-compile tl-nemacs.el. \item Use Mule when you byte-compile tl-mule.el. \item Modules byte-compiled by Emacs 19 do not work with Emacs 18. \end{itemize} \section{Setup} In the tm package, two files, mime-setup.el and tm-setup.el, are provided to ease the setup. A mime-setup.el is used for the whole MIME related setup including MIME encoding, while tm-setup is used to set up tm-MUA only. \subsection{mime-setup} \begin{verbatim} (load "mime-setup") \end{verbatim} \noindent will perform various settings of MIME. As mime-setup loads tm-setup, you do not need to load tm-setup when you use mime-setup. You can also set up the "automatic signature selection tool" using mime-setup. If you want to automatically select the signature file depending on how the message headers show, add lines like shown below to your .emacs (Refer to the reference manual of signature.el for more details). \begin{verbatim} (setq signature-file-alist '((("Newsgroups" . "jokes") . "~/.signature-jokes") (("Newsgroups" . ("zxr" "nzr")) . "~/.signature-sun") (("To" . ("ishimaru" "z-suzuki")) . "~/.signature-sun") (("To" . "tea") . "~/.signature-jokes") (("To" . ("sim" "oku" "takuo")) . "~/.signature-formal") )) \end{verbatim} mime-setup requires mime.el. if you set up SuperCite via mime-setup, you need the SuperCite package also. \subsection{tm-setup} tm-setup only sets up tm-MUAs. You do not need to explicitly load tm-setup if you are using mime-setup for your setup. tm-setup is useful when you do not want to use mime-setup but want to set up tm-MUAs. \begin{verbatim} (load "tm-setup") \end{verbatim} \subsection{vm} If you want use vm, please insert following in .vm or .emacs: \begin{verbatim} (load "tm-vm") \end{verbatim} \subsection{setting up without loading provided setup files} You may find the valuable hints in tm-setup.el if you want to set up MIME environment without loading the tm-provided setup files. \subsection{setting up MH} If you are using MH-6.8JP2, add the following lines to your .mh\_profile. \begin{verbatim} scan: -form scan.mime inc: -form inc.mime repl: -form replcomps.mime showproc: mhl \end{verbatim} \noindent Emacs will handle the most part of MH processing. You should not specify further options in your MH profile to avoid any possible conflict between MH and Emacs. \chapter{tm-MUA} ``tm-MUA'' is a generic name of the modules which enhance the MIME functions of MUA like mh-e, GNUS, and RMAIL etc. The current version of tm provides the following tm-MUA. \begin{itemize} \item {\bf tm-mh-e} : tm-MUA for mh-e \item {\bf tm-gnus} : tm-MUA for GNUS \item {\bf tm-rmail} : tm-MUA for RAMIL \end{itemize} \noindent You can find the detailed explanations of these modules in the following sections. \section{Summary Mode} If you are using tm-MUA, the following functions are added to the Summary mode of the MUA. \medskip \begin{center} \begin{tabular}{|l|l|}\hline key & function \\ \hline M-t & toggles decoding of MIME headers \\ v & enters mime/view-mode \\ \hline \end{tabular} \end{center} \medskip \section{mime/viewer-mode} \label{sec:mime/viewer-mode} If you are using tm-MUA, mime/viewer-mode becomes active by pressing {\bf v} key in the Summary mode. In mime/viewer-mode, you can manipulate the MIME messages by the simple key operations. The following list shows the functions and their key bindings which can be used in mime/viewer-mode. \medskip \begin{center} \begin{tabular}{|l|l|}\hline key & function \\ \hline u & goes to the upper content \\ & returns to the Summary mode if the cursor is sitting on the top content (*1) \\ p & goes to the previous content \\ n & goes to the next content \\ SPC & scrolls up \\ M-SPC & scrolls down \\ DEL & scrolls down \\ RET & goes to the next line \\ M-RET & goes to the previous line \\ v & playbacks a content (*2) \\ e & extracts a file from a content (*2) \\ C-c C-p & prints a content (*2) \\ \hline \end{tabular} \end{center} \medskip \bigskip \newcounter{asteriskcount} \noindent{\bf ［Note］} \vspace{-1ex} {\list{(*\arabic{asteriskcount})}{\usecounter{asteriskcount}\leftmargin=8ex} \item Not return to the Summary mode unless tm-view has been setup using tm-mh-e, tm-gnus, tm-rmail etc. \item Actual playback/extract/print will be performed by a method. \endlist} \section{Customizing tm-gnus} \subsection{saving articles without decoding} By default, The articles will be saved as they appear in the buffer at that time. You can save the articles always without decoding by setting a tm-gnus/set-mime-header-decoding-mode variable to nil then call a function which saves the articles. The following example shows how you can save an article without decoding, preserving the current MIME header decoding mode. \begin{verbatim} (let ((mm mime/header-decoding-mode)) (tm-gnus/set-mime-header-decoding-mode nil) (article save function) (tm-gnus/set-mime-header-decoding-mode mm) ) \end{verbatim} The following is an example that saves the articles to a folder of mh-e. \begin{verbatim} (add-hook 'gnus-Startup-hook (function (lambda () (setq gnus-default-article-saver (function (lambda () (interactive) (let ((mm mime/header-decoding-mode)) (tm-gnus/set-mime-header-decoding-mode nil) (gnus-Subject-save-in-folder) (tm-gnus/set-mime-header-decoding-mode mm) ))))))) (add-hook 'gnus-startup-hook (function (lambda () (setq gnus-default-article-saver (function (lambda () (interactive) (let ((mm mime/header-decoding-mode)) (tm-gnus/set-mime-header-decoding-mode nil) (gnus-summary-save-in-folder) (tm-gnus/set-mime-header-decoding-mode mm) ))))))) \end{verbatim} \subsection{replying with encoded subject to an article with encoded subject} When you reply to an article, you may want to encode the Subject field only when the original article has an encoded Subject. It can be done by defining a hook as shown below. \begin{verbatim} (add-hook 'gnus-article-prepare-hook (function (lambda () (if (mime/exist-encoded-word-in-subject) (setq mime/no-encoding-header-fields '("X-Nsubject")) (setq mime/no-encoding-header-fields '("X-Nsubject" "Subject")) )))) \end{verbatim} \chapter{tm-view} tm-view is a module which is used to examine the MIME messages. It provides a mime/viewer-mode for that purpose. Regarding the functions of mime/viewer-mode, refer to \ref{sec:mime/viewer-mode} section. \section{Defining Conditions of Decoding} A mime/content-decoding-condition variable is used to define the methods which will be called at decoding. It replaces a mime/content-decoding-method-alist variable of tm-view version 4.x. A mime/content-decoding-method-alist only allowed you to define a method used for each content-type/subtype. Now a mime/content-decoding-condition variable allows you to write more complicated statements to describe the more detailed conditions to determine which method is to be use. A mime/content-decoding-condition variable is defined as a list with the following syntax. \begin{eqnarray*} (condition_1 \;\; condition_2 \;\; ...) \end{eqnarray*} \noindent Each condition is an association list with the following syntax. \begin{eqnarray*} ((field-type_1 \; . \; value_1) \;\; (field-type_2 \; . \; value_2) \;\; ...) \end{eqnarray*} \noindent 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 \begin{quote} ((type . "text/plain") (method "tm-plain" nil 'file 'type 'encoding 'mode 'name)) \end{quote} \noindent As you notice, now you can define the arguments to pass to a external method. Refer to \ref{sec:method-arguments} section for more explanation. This condition definition will match all contents whose types are text/plain. Here is an another example. \begin{quote} ((type . "text/plain") (method "tm-plain" nil 'file 'type 'encoding 'mode 'name) (mode . "play")) \end{quote} \noindent This will match the content whose type is text/plain and the mode is play. \begin{quote} ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file) (mode . "play")) \end{quote} \noindent 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. \subsection{arguments of method} \label{sec:method-arguments} You can specify the method field of the condition definition in two different ways. \begin{eqnarray*} (method \; . \; SYMBOL) \end{eqnarray*} \noindent or \begin{eqnarray*} (method \; STRING \; FLAG \; ARGUMENT_1 \; ARGUMENT_2 \; ...) \end{eqnarray*} \noindent can be accepted. When a symbol is specified in the method field, it 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. \begin{description} \item [STRING] name of an external method \item [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. \item [ARGUMENT$_x$] list of arguments passed to an external method \end{description} An argument passed to an external method can be in one of the following formats. \begin{quote} \begin{tabular}{lcl} STRING&:&string itself \\ 'SYMBOL&:&value gotten using SYMBOL as a key (see below) \\ 'STRING&:&value gotten using STRING as a key (see below) \end{tabular} \end{quote} 'SYMBOL can be one of the following. \begin{quote} \begin{tabular}{lcl} 'file&:&name of a file holding the original content \\ 'type&:&content-type/sub-type \\ 'encoding&:&content-transfer-encoding \\ 'mode&:&decoding mode \\ 'name&:&name of a file created by decode operation \end{tabular} \end{quote} \noindent '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. \subsection{examples} The default definition of a mime/content-decoding-condition variable is shown below. \begin{verbatim} (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")) )) \end{verbatim} For example, if you want to use metamail to decode any contents, \begin{verbatim} (setq mime/content-decoding-condition '( ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file)) )) \end{verbatim} \noindent 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. \section{Method Script} \label{sec:method} The methods are written in shell script. The arguments passed from tm-view.el to each method can be customized using mime/content-decoding-condition variable. If you use the tm-provided setting of mime/content-decoding-condition variable, the following arguments are passed to the method. \medskip \begin{center} \begin{tabular}{|c|l|} \hline argument & \multicolumn{1}{|c|}{ meaning }\\ \hline \$1 & file name before decoded \\ \$2 & Content-Type (type/sub-type) \\ \$3 & encoding \{7bit / quoted-printable / base64 / 8bit / binary / ...\}\\ \$4 & decoding-mode \{play / extract / print\} \\ \$5 & file name after decoded \\ \hline \end{tabular} \end{center} \medskip Exceptionally, no method is used to restore message/partial messages into one message. It is done by tm-view.el itself. \section{Changing Appearance} Each content in the preview buffer is shown in the following format. \begin{verbatim} [1 (text/plain)] body \end{verbatim} \noindent tm-view shows one content in three separate portions. \begin{itemize} \item content subject \item content header \item content body \end{itemize} \noindent \subsection{content subject} A content subject indicates the beginning of a content in the preview buffer. By default, it will be shown as below. \begin{quote} [cid title (type)] \end{quote} \noindent The cid field shows the position of a content in the message. It can be considered as the chapter number in the message. The title field is composed of the text string from the Subject and the Content-Description field. The type field is a copy of a text string specified in the type/subtype field of the content. You can customize how the content subject appears in the preview buffer by modifying a definition of mime/make-content-subject-function variable. The tm-view provides a following definition as a default. \begin{verbatim} (defvar mime/make-content-subject-function (function (lambda (cid subj ctype) (insert (format "[%s %s (%s)]\n" (if (listp cid) (mapconcat (function (lambda (num) (format "%s" (+ num 1)) )) cid ".") "0") subj (car ctype))) ))) \end{verbatim} \noindent The following is an example of the customization. \begin{verbatim} (setq mime/make-content-subject-function (function (lambda (cid subj ctype) (if (not (member (car ctype) mime/default-showing-Content-Type-list)) (insert (format "[%s %s (%s)]\n" (if (listp cid) (mapconcat (function (lambda (num) (format "%s" (+ num 1)) )) cid ".") "0") subj (car ctype)))) ))) \end{verbatim} \noindent This will show the content subjects only for the contents whose body portions are to be hidden. \subsection{content header} A content header shows the header portion of a content in the preview buffer. The default setup will show no content headers. You can customize how the content header appears in the preview buffer by modifying a definition of mime/make-content-header-filter variable. The tm-view provides a following default definition. \begin{verbatim} (defvar mime/make-content-header-filter (function (lambda (cid) (if (listp cid) (delete-region (goto-char (point-min)) (or (and (re-search-forward "^$" nil t) (match-end 0)) (point-max)) ) ) ))) \end{verbatim} \noindent The default setting removes all content headers until it detects a blank line delimiting the headers and the body. If you change a mime/make-content-header-filter variable like \begin{verbatim} (setq mime/make-content-header-filter (function (lambda (cid) ))) \end{verbatim} \noindent you will see all headers in the content header portion. \subsection{content body} According to the type of content, the body portion of the content is managed by tm-view using \begin{enumerate} \item Hide \item Process \end{enumerate} \noindent techniques before it is put in the preview buffer. 'Hide' is performed to prevent showing the non-text type content body in the preview buffer. A mime/default-showing-Content-Type-list variable defines which type of contents will NOT be hidden. It has the following default value. \begin{verbatim} (defvar mime/default-showing-Content-Type-list '("text/plain" "text/richtext" "text/enriched" "text/x-latex" nil)) \end{verbatim} \noindent All contents are hidden except text/plain, text/richtext, text/enriched, text/x-latex, and non-MIME contents. A content body which was not "hidden" is then "processed". A list in a mime/content-filter-alist variable will be searched looking up an entry which matches with the content-type of a content. If a matching entry is found, the function defined in that entry will be called to "process" a content body. A mime/content-filter-alist variable has nil as a default value. It will have non-nil after loading tm-rich.el which contains the following lines. \begin{verbatim} (aput 'mime/content-filter-alist "text/enriched" (function mime/decode-text/enriched-body)) \end{verbatim} \noindent This is defining a process to be done to the text/enriched type content body. A function mime/decode-text/enriched-body will be called if a text/enriched body need to be "processed". \section{Restrictions} A decode-b.c file in the tm package is the source of the BASE64 decoder. As it was not thoroughly tested, it may not work for you. But at least you can see what it wants to do so that you can correct errors in the source code. (\verb+^+\_\verb+^+; Or you can use mmencode in the metamail package to decode the BASE64 encoded messages. Use mmencode to decode the Quoted-Printable messages. The tm package does not include the decoder for Quoted-Printable. \chapter{tiny-mime} tiny-mime is a multi-lingual MIME style message header encoder/decoder based on RFC 1522 for Mule, NEmacs, and NEpoch. It is based on Mr. Enami's ISO-2022-JP Base64 MIME header decoder which could decode only ISO-2022-JP Base64-encoded headers. The following list shows some of the functional enhancemets I made in tiny-mime. \begin{itemize} \item unfolding at decoding \item encoding/decoding multilingual character sets, such as, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-CN, ISO-2022-KR, ISO-8859-*, US-ASCII, EUC-KR \item Q-encoding \item compliance with RFC 1522 \end{itemize} \noindent and more. tiny-mime is a MIME headers encoder/decoder in the tm package and used by tm-view and tm-MUAs. \section{mime/decode-message-header} {\tt mime/decode-message-header} is a command to decode the MIME headers. You need to load tiny-mime before you can use this command. {\list{}{\leftmargin=8ex}\item[] \par M-x {\tt mime/decode-message-header} \endlist} \noindent will decode the MIME headers in the current buffer. tm-MUAs and tm-view use this command to decode the MIME headers. Therefore, it may not be required to explicitly execute this command if you are using them. \section{mime/decode-region} You can decode the MIME messages within the specified region by executing {\list{}{\leftmargin=8ex}\item[] \par M-x {\tt mime/decode-region} \endlist} \noindent This is useful when you want to decode the MIME headers which are yanked from the referenced article. \chapter{Reporting Bugs} Please report tm bugs you find to fj.editor.emacs or send a mail to tm ML, $<$tm@@chamonix.jaist.ac.jp$>$. Via tm ML, You can report bugs of tm, obtain the latest release of tm package, and discuss the future enhancements to tm. To join tm ML, send a mail to \begin{center} tm-admin@@chamonix.jaist.ac.jp \end{center} \noindent Since the user registration is manually done, please write the mail body in human-recognizable language (\verb+^+\_\verb+^+). \end{document} @ 5.2 log @*** empty log message *** @ text @d10 1 a10 1 \date{\verb$Id: tm-eng.tex,v 5.2 1994/10/11 17:17:05 morioka Exp $} d44 1 d147 9 @