tm 6.70

[elisp/tm.git] / doc / tm-view_en.texi

\input texinfo.tex
@c{-*-tm manual-*-}
@setfilename tm-view_en.info
@settitle{tm-view manual}

@titlepage
@title tm-view Manual (English Version)
@author by MORIOKA Tomohiko
@code{$Id: tm-view_en.texi,v 3.0 1995/08/01 18:49:44 morioka Exp $}
@end titlepage


@node Top, Mechanism, (dir), (dir)
@comment  node-name,  next,  previous,  up
@chapter{tm-view}
@cindex{tm-view}

The tm-view is a general MIME viewer running on GNU Emacs.

tm-view provides the major-mode called @code{mime/viewer-mode} to read
MIME message for MUA. MUA implementer can use it to add MIME function.



@menu
* Mechanism::      Mechanism of mime/viewer-mode.
* How to run::     How to run mime/viewer-mode.
* How to use::     Commands of mime/viewer-mode.
* Preview Buffer:: Screen design of preview buffer.
* Decoding::       Mechanism of decoding operations for contents.

Preview buffer
* Preview Buffer:: Screen design of preview buffer.
* content-subject::
* content-header::
* content-body::
* content-separator::

Decoding
* Decoding:: Mechanism of decoding operations for contents.
* decoding-condition:: Setting of content decoding condition.
* Format of method value:: Format of method value part.
* Example of decoding-condition:: Examples of decoding-condition.

Indexes
* Concept Index::
* Command Index::
* Variable Index::
@end menu


@node Mechanism, How to run, Top, Top
@comment  node-name,  next,  previous,  up
@chapter{Mechanism}
@cindex{Mechanism}

tm-view managements two buffers, one is for raw message called
@strong{article buffer}, another one is to preview for user called
@strong{preview buffer}.

When called @code{mime/viewer-mode}, tm-view analyzes article buffer,
and sets its result to the variable @code{mime::article/content-info}.

After that, tm-view create a preview buffer corresponded to the
article buffer. As this time, tm-view modifies header and body of each
contents of the message. It is done by definition for Content-Types.

On the preview buffer created by tm-view, user can manipulate a
message to decode, such as run external vewer, extract files, or
print.

Notice: In this document, I call @strong{content-type} as
content-type/subtype of Content-Type field.


@node How to run, How to use, Mechanism, Top
@comment  node-name,  next,  previous,  up
@chapter{How to run mime/viewer-mode}
@cindex{How to run mime/viewer-mode}

@deffn{Command} mime/viewer-mode &optional mother ctl encoding

Parse current-buffer as a MIME message, and create preview buffer to
display to user, then enter @code{mime/viewer-mode}.

@var{mother} is used to specify original article buffer. It may be
useful when an article buffer is assembled from message/partial.

@var{ctl} is used to specify Content-Type field information. Its
format is output format of @code{mime/Content-Type}. When @var{ctl} is 
specified, tm-view uses it instead of Content-Type field of the
article buffer.

@var{encoding} is used to specify field-body of
Content-Transfer-Encoding field. When is is specified, tm-view uses it
instead of Content-Type field of the article buffer.
@end deffn


@node How to use, Preview Buffer, How to run, Top
@comment  node-name,  next,  previous,  up
@chapter{Commands of mime/viewer-mode}
@cindex{Commands of mime/viewer-mode}

@code{mime/viewer-mode} has following functions:

@table @kbd 
@item u
        goes to the upper content (returns to the Summary mode if the
        cursor is sitting on the top content (*1))
@item p
        goes to the previous content
@item n
        goes to the next content
@item @key{SPC}
        scrolls up
@item @key{M-SPC}
        scrolls down
@item @key{DEL}
        scrolls down
@item @key{RET}
        goes to the next line
@item @key{M-RET}
        goes to the previous line
@item v
        playbacks a content            (*2)
@item e
        extracts a file from a content (*2)
@item C-c C-p
        prints a content               (*2)
@end table

@b{[Notice]}
@enumerate
@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.
@end enumerate


@node Preview Buffer, content-subject, how-to-use, Top
@comment  node-name,  next,  previous,  up
@chapter{Screen design of preview buffer}
@cindex{Screen design of preview buffer}

In preview buffer, following are displayed for each content:

@example
        [content-subject]
        (content-header)
        
        (content-body)
        (content-separator)
@end example

You can change design or stop to display if you specify for each
content-types.

Example:

@example
From: MORIOKA Tomohiko <morioka@@jaist.ac.jp>
Newsgroups: zxr.comp.emacs.tm-english
Subject: tm6.63.tar.gz
Date: Mon, 26 Jun 1995 17:39:50 JST
Organization: Chamonix, JAIST, Tatsunokuchi, Ishikawa, Japan
Reply-To: tm-eng@@chamonix.jaist.ac.jp
To: tm-eng@@chamonix.jaist.ac.jp
In-Reply-To: Your message of "Sun, 25 Jun 1995 23:20:49 MST"
X-Mua: mh-e 4.1 + tm 6.63 / Mule 2.2 (WAKAMURASAKI) PL02
X-Mime-Composer: mime.el + tiny-mime 5.12
X-Ml-Count: 32

[1  (text/plain)]
  I put tm6.63.tar.gz in ftp.jaist.ac.jp.

  In this version, tm-view uses new MIME encoding/decoding engine
``mel (MIME encoding library''. This library has internal/external
encoding/decoding engine. If data is smaller than a limit, tm-view
uses internal decoder, otherwise external decoder.

[2 tm6.63.tar.gz ([anon-ftp] ftp.jaist.ac.jp:/pub/GNU/elisp/mime/alpha)]

[3  (text/plain)]
----
MORIOKA, Tomohiko <morioka@@jaist.ac.jp>
@end example


@menu
* content-subject::
* content-header::
* content-body::
* content-separator::
@end menu


@node content-subject, content-header, Preview Buffer, Preview Buffer
@comment  node-name,  next,  previous,  up
@section{content-subject}
@cindex{content-subject}

content-subject is a part to display abstract for the content. It is
placed in top of content.

In default, it is displayed following design:

@example
        [1.3 test (text/plain)]
@end example

First number field represents position of a content in the message. It
is called `content-number'. It can be considered as the chapter number
in the message.

Second string part represents title. It is created by following:

@itemize
@item name paramater or x-name parameter in Content-Type field
@item Content-Description field or Subject field
@item filename of uuencode
@end itemize

If they are not exists, space is displayed.

Third parenthesis part represents content-type/subtype of the
content. If it is non-MIME part, @code{nil} is displayed.

Content-subject is used like icon when content-header and content-body
are hidden. For example,

@example
        [2  (image/gif)]
@end example

if you press `v' key, GIF image is displayed.


@defvr{Variable} mime-viewer/content-subject-omitting-Content-Type-list

List of content-type. If content-type of a content is a member of this 
list, its content-subject is not displayed.

This variable is referenced by function
@code{mime-viewer/default-content-subject-function}.
@end defvr


@deffn{Function} mime-viewer/default-content-subject-function cnum cinfo ctype params subj

Default value of the variable
@code{mime-viewer/content-subject-function}.
It refers variable
@code{mime-viewer/content-subject-omitting-Content-Type-list}.
@end deffn


@defvar mime-viewer/content-subject-function cnum cinfo ctype params subj

Variable to specify content-subject display function. Default value is
the function @code{mime-viewer/default-content-subject-function}.
@end defvar


@node content-header, content-body, content-subject, Preview Buffer
@comment  node-name,  next,  previous,  up
@section{content-header}
@cindex{content-header}

A content header shows the header portion of a content in the preview
buffer.

When the function @code{mime-viewer/header-visible-p} returns @code{t}
for content-number of a content, content-header is displayed. This
judge function returns @code{t} when a content is root or content-type
of its parent is a member of the variable
@code{mime-viewer/childrens-header-showing-Content-Type-list}.

If you want to change this condition, please redefine it.

When content-header is displayed, content-header are formated by
content-header-filter. Content-header-filter is searched from variable 
@code{mime-viewer/content-header-filter-alist}. Its key is major-mode
of the article buffer. If not found, function
@code{mime-viewer/default-content-header-filter} is called.


@defvar mime-viewer/childrens-header-showing-Content-Type-list

List of content-type. If content-type of parent of a content is a
member of this variable, its content-header is displayed.
Default value is "message/rfc822".

This variable is referred by the function
@code{mime-viewer/header-visible-p}.
@end defvar


@deffn{Function} mime-viewer/header-visible-p cnum cinfo &optional ctype

Returns @code{t} if a content is displayed.

@var{cnum} is content-number. @var{cinfo} is content-info. If you know 
content-type, you can specify by @var{ctype}.
@end deffn


@defvar mime-viewer/content-header-filter-alist

Association-list whose key is major-mode of a article buffer, value is
content-header-filter.
@end defvar


@deffn{Function} mime-viewer/default-content-header-filter

It is called when content-header-filter is not found in variable
@code{mime-viewer/content-header-filter-alist}.
@end deffn


@node content-body, content-separator, content-header, Preview Buffer
@comment  node-name,  next,  previous,  up
@section{content-body}
@cindex{content-body}

Content-body represents content of the message. tm-view does not
display raw content body. For example, if a content has binary, it is
hidden. If a content has richtext, it is formated. Namely content body
is hidden or formated.

Function @code{mime-viewer/body-visible-p} is a judge function whether
content-body of a content is displayed. If it returns @code{nil},
content-body is hidden. In default, it returns non-@code{nil} when
content-type of a content is a member of variable
@code{mime-viewer/default-showing-Content-Type-list}.

When content-body of a content is displayed, content-body is formated
by content-filter. Content-filter is searched from variable
@code{mime-viewer/content-filter-alist}. At this time, major-mode of
the article buffer is used as the key.

If it is not found, function @code{mime-viewer/default-content-filter}
is called.


@defvar mime-viewer/default-showing-Content-Type-list

List of content-type. If content-type of a content is a member of this 
variable, its body is displayed.
@end defvar


@deffn{Function} mime-viewer/body-visible-p cnum cinfo &optional ctype

Return non-@code{nil}, if content-type of a content is displayed.
@var{cnum} is content-number of a content. @var{cinfo} is content-info
of the message. If you know content-type of a content, you can specify
it as argument @var{ctype}.
@end deffn


@defvar mime-viewer/content-filter-alist

Association-list whose key is major-mode of a article buffer, value is
content-filter.
@end defvar


@deffn{Function} mime-viewer/default-content-filter cnum cinfo ctype params subj

It is called when content-body of a content should be displayed and
content-filter is not found in
@code{mime-viewer/content-filter-alist}.

In default, it does nothing.
@end deffn


@node content-separator, Decoding, content-body, Preview Buffer
@comment  node-name,  next,  previous,  up
@section{content-separator}
@cindex{content-separator}

Content-separator is displayed to represent boundary of contents.

Content-separator is displayed by function
@code{mime-viewer/default-content-separator}. In default, it displays
line-break when content-header and content-body are not displayed.

If you want to change this condition, please redefine this function.


@deffn{Function} mime-viewer/default-content-separator cnum cinfo ctype params subj

Display content-separator. @var{cnum} is content-number of a
content. @var{cinfo} is content-info of the message. @var{ctype} is
content-type of a content. @var{params} is Content-Type field
parameters of a content. @var{subj} is subject.

In default, it displays line-break when content-header and
content-body are not displayed.
@end deffn


@node Decoding, decoding-condition, Preview Buffer, Top
@comment  node-name,  next,  previous,  up
@chapter{Decoding}
@cindex{Decoding}

In @code{mime/viewer-mode}, you can do play (@key{v}), extract
(@key{e}), or print (@key{C-c C-p}) for each content. These operations
are called ``decoding operation(s) (for a content)''. And kind of
decoding operations are called @strong{decoding-mode}.

When decoding operation is driven, tm-view calls a procedure matched
for the condition, such as content-type. This procedure is called
@strong{method}.

There are two kinds of method. One is Emacs Lisp function, called
@strong{internal method}. Another one is external program, called
@strong{external method}.

Internal method operates in Emacs, so it can do carefully.

External method is called as asynchronous process, so Emacs does not
wait while method is running. So it is good for big data, such as
audio, image or video.

@menu
* decoding-condition:: Setting of content decoding condition.
* Format of method value:: Format of method value part.
* Example of decoding-condition:: Examples of decoding-condition.
@end menu


@node decoding-condition, Format of method value, Decoding, Decoding
@comment  node-name,  next,  previous,  up
@section{Setting of content decoding condition}
@cindex{Setting of content decoding condition}

When decoding operation is driven, tm-view calls a method matched for
the condition searched from the variable
@code{mime/content-decoding-condition}.

Variable @code{mime/content-decoding-condition} is defined as a list
with the following syntax:

@lisp
        (condition1 condition2 ...)
@end lisp

Each condition are association-list with the following syntax:

@lisp
        ((field-type_1 . value_1)
         (field-type_2 . value_2)
         ...)
@end lisp

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

@lisp
        ((type . "text/plain")
         (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
@end lisp

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:

@lisp
        ((type . "text/plain")
         (method "tm-plain" nil 'file 'type 'encoding 'mode 'name)
         (mode . "play"))
@end lisp

This will match the content whose type is text/plain and the mode is
play.

@lisp
        ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file)
         (mode . "play"))
@end lisp

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.


@node Format of method value, Example of decoding-condition, decoding-condition, Decoding
@comment  node-name,  next,  previous,  up
@section{Format of method value part}
@cindex{Format of method value part}

You can specify the method field of the decoding-condition definition
in two different ways,

@lisp
        (method . SYMBOL)
@end lisp

or

@lisp
        (method  STRING  FLAG  ARGUMENT1  ARGUMENT2  ...)
@end lisp

can be accepted.

When a symbol is specified in the method field, a function whose name
is SYMBOL 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.

@table @samp
@item STRING
        name of an external method
@item FLAG
        If @code{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 ARGUMENTs
        list of arguments passed to an external method
@end table

An argument passed to an external method can be in one of the
following formats:

@table @samp
@item STRING
        string itself
@item 'SYMBOL
        value gotten using SYMBOL as a key (see below)
@item 'STRING
        value gotten using STRING as a key (see below)
@end table

'SYMBOL can be one of the following:

@table @samp
@item 'file
        name of a file holding the original content
@item 'type
        content-type/sub-type of Content-Type field
@item 'encoding
        field body of Content-Transfer-Encoding field
@item 'mode
        decoding-mode
@item 'name
        name of a file created by decode operation
@end table

'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.


@node Example of decoding-condition, Concept Index, Format of method value, Decoding
@comment  node-name,  next,  previous,  up
@section{Examples of decoding-condition}
@cindex{Examples of decoding-condition}

The default definition of a mime/content-decoding-condition variable
is shown below.

@lisp
(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 lisp

For example, if you want to use metamail to decode any contents,

@lisp
(setq mime/content-decoding-condition
      '(
        ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file))
       ))
@end lisp

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.


Following function may be useful to set decoding-condition. It is a
function of tl-atype.el.


@deffn{Function} set-atype symbol alist

Add condition @var{alist} to symbol @var{symbol}.

Example:

@lisp
(set-atype 'mime/content-decoding-condition
           '((type . "message/external-body")
             ("access-type" . "anon-ftp")
             (method . mime/decode-message/external-ftp)
             ))
@end lisp
@end deffn


@node Concept Index, Command Index, Decoding, Top
@unnumbered Concept Index

@printindex cp


@node Command Index, Variable Index, Concept Index, Top
@unnumbered Command and Function Index

@printindex fn


@node Variable Index,  , Command Index, Top
@unnumbered Variable Index

@printindex vr

@bye