\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.7 1995/06/26 06:03:21 morioka Exp $}

\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)}

US-ASCII and ISO-8859-1 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:
\begin{center}
  \begin{tabular}{ll}
    tm@chamonix.jaist.ac.jp     & (Japanese or English) \\
    tm-eng@chamonix.jaist.ac.jp & (English)
  \end{tabular}
\end{center}

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}
  \begin{tabular}{ll}
    tm-admin@chamonix.jaist.ac.jp     & (Japanese or English) \\
    tm-eng-admin@chamonix.jaist.ac.jp & (English)
  \end{tabular}
\end{center}

\noindent Since the user registration is manually done, please write
the mail body in human-recognizable language (\verb+^+\_\verb+^+).

\end{document}
