[README for tm (English Version)]
by MORIOKA Tomohiko <morioka@jaist.ac.jp>
and KOBAYASHI Shuhei <shuhei-k@jaist.ac.jp>
$Id: README.en,v 7.32 1997/02/03 06:53:15 morioka Exp $

1 What's tm?

  tm is a MIME package for GNU Emacs. tm has following functions:

	- MIME style multilingual header
	- MIME message viewer (mime/viewer-mode)
	- MIME message composer (mime/editor-mode)
	- MIME extenders for mh-e, GNUS, Gnus, RMAIL and VM


2 Documents

  This package includes the following documents.

(1) English edition

- SGML (sinfo)
  - tm/doc/tm-en.sgml		: tm Reference Manual
  - tm/doc/tm-view-en.sgml	: tm-view Reference Manual
  - tm/doc/tm-edit-en.sgml	: tm-edit Reference Manual
  - tm-mh-e/tm-mh-e-en.sgml	: tm-mh-e Reference Manual
  - gnus-mime/gnus-mime-en.sgml	: gnus-mime Reference Manual

- Texinfo
  - tm/doc/tm-en.texi		: tm Reference Manual
  - tm/doc/tm-view-en.texi	: tm-view Reference Manual
  - tm/doc/tm-edit-en.texi	: tm-edit Reference Manual
  - tm-mh-e/tm-mh-e-en.texi	: tm-mh-e Reference Manual
  - gnus-mime/gnus-mime-en.texi	: gnus-mime Reference Manual
  - tm-vm/tm-vm-en.texi		: tm-vm Reference Manual

- info
  - tm/doc/tm-en.info		: tm Reference Manual
  - tm/doc/tm-view-en.info	: tm-view Reference Manual
  - tm/doc/tm-edit-en.info	: tm-edit Reference Manual
  - tm-mh-e/tm-mh-e-en.info	: tm-mh-e Reference Manual
  - gnus-mime/gnus-mime-en.info	: gnus-mime Reference Manual
  - tm-vm/tm-vm-en.info		: tm-vm Reference Manual

(2) Japanese edition

- SGML (sinfo)
  - tm/doc/tm-ja.sgml		: tm Reference Manual
  - tm/doc/tm-view-ja.sgml	: tm-view Reference Manual
  - tm/doc/tm-edit-ja.sgml	: tm-edit Reference Manual
  - tm-mh-e/tm-mh-e-ja.sgml	: tm-mh-e Reference Manual
  - gnus-mime/gnus-mime-ja.sgml	: gnus-mime Reference Manual

- Texinfo
  - tm/doc/tm-ja.texi		: tm Reference Manual
  - tm/doc/tm-view-ja.texi	: tm-view Reference Manual
  - tm/doc/tm-edit-ja.texi	: tm-edit Reference Manual
  - tm-mh-e/tm-mh-e-ja.texi	: tm-mh-e Reference Manual
  - gnus-mime/gnus-mime-ja.texi	: gnus-mime Reference Manual

- info
  - tm/doc/tm-ja.info		: tm Reference Manual
  - tm/doc/tm-view-ja.info	: tm-view Reference Manual
  - tm/doc/tm-edit-ja.info	: tm-edit Reference Manual
  - tm-mh-e/tm-mh-e-ja.info	: tm-mh-e Reference Manual
  - gnus-mime/gnus-mime-ja.info	: gnus-mime Reference Manual

- other format
  - tm/doc/signature-jp.ol : signature.el Reference Manual (Emacs Outline)
  - tm/doc/signature-jp.tex: signature.el Reference Manual (LaTeX)
  - tm/doc/tm-charset_ja.ol: How to use character codes in tm (Emacs Outline)
  - tm/doc/tm-charset_ja.tex: How to use character codes in tm (LaTeX)


3 Modules

  tm has following modules:

	- tm-view : MIME viewer
		- tm-parse.el : MIME message parser
		- tm-play.el  : MIME content player
		- tm-ew-d.el : MIME encoded-word decoder
	- preview filter for tm-view
		- tm-text    : for text/*
		- tm-image   : for image/* and X-Face
	- internal methods for tm-view
		- tm-partial : automatic assembler for message/partial
		- tm-ftp     : for anonymous ftp
		- tm-file    : for file extraction
		- tm-tar     : for tar content
		- tm-latex   : for LaTeX
		- tm-html    : for text/html
		- tm-pgp     : for PGP
	- tm-edit : MIME composer (mime.el and tm-comp.el were merged)
		- tm-ew-e.el : MIME encoded-word encoder
		- tm-edit-mc.el : tm-edit interface for Mailcrypt
		- tm-edit-tipgp.el : tm-edit interface for TinyPgp.el
	- tm-def  : definition module for tm
	- tm-MUAs : MIME extender for MUAs
		- tm-mh-e   : tm-MUA for mh-e
		- gnus-mime : tm-MUA for Gnus
		- tm-gnus   : tm-MUA for GNUS
		- tm-rmail  : tm-MUA for RMAIL
		- tm-vm     : tm-MUA for vm
		- tm-mail   : tm-MUA library module for mail-mode
	- mime-setup: set up module for MIME
		- tm-setup: set up only reading


4 Install

4.1 edit tm/TM-CFG (optional)

  You can edit tm/TM-CFG file.

  By default, tm is installed into /usr/local/. If you want to change this,
please modify the variables `PREFIX' and `EXEC_PREFIX'.


4.2 edit external methods (optional)

  You can edit external methods in `tm/methods/' directory for your
environment.

	tm/methods/tm-au	for audio
	tm/methods/tm-file	for file extraction
	tm/methods/tm-image	for image
	tm/methods/tm-mpeg	for MPEG
	tm/methods/tm-plain	for plain text
	tm/methods/tm-html	for HTML
	tm/methods/tmdecode	decoder

  By default, tmdecode uses the `mmencode' command, which is part of
the metamail package (available by anonymous ftp from
ftp://thumper.bellcore.com/pub/nsb).  If you don't have the metamail
package, please modify tmdecode to use decode-b instead of mmencode.


4.3 make

  Run `make all'.

  You can specify the Emacs command name, for example if you want to use
`mule' as the Emacs command:

	% make all EMACS=mule


4.4 install

  Run `make install'.

  You can specify the Emacs command name, for example if you want to use
`xemacs' as the Emacs command:

	% make install EMACS=xemacs


6 .emacs

  Please insert `(load "mime-setup")' in ~/.emacs.


6.1 gnus-mime

  gnus-mime provides automatic MIME preview feature for Gnus.

  If you don't want to use automatic MIME preview feature, please
insert in ~/.emacs:

	(setq gnus-show-mime nil)

  In addition, Gnus 5.2 is designed to support automatic MIME preview
feature.  Of course, gnus-mime provides this feature for Gnus 5.0.*
and Gnus 5.1.*, but it is unnatural.

  When automatic MIME preview mode, Gnus do MIME processing if a
message has a Mime-Version field.  If it does not have one, Gnus does
not do MIME processing, in default.

  Gnus 5.0.*, 5.1 and Gnus 5.2 have a variable `gnus-strict-mime'.  If
you insert

	(setq gnus-strict-mime nil)

Gnus does MIME processing even if a message does not have a
Mime-Version field.

  In Gnus 5.2, if `gnus-strict-mime' is not nil, variable
`gnus-decode-encoded-word-method' is called.  gnus-mime uses it to
decode RFC 2047 encoded-words.  So it is not necessary to reset
`gnus-strict-mime'.


6.2 tm-gnus

  tm-gnus provides automatic MIME preview feature for GNUS 3.15 or
later.

  If you don't want to use automatic MIME preview feature, please
insert in ~/.emacs:

	(setq tm-gnus/automatic-mime-preview nil)


6.3 VM

  If you use vm, please insert `(require 'tm-vm)' in ~/.vm.

  tm works well with BBDB: If you use VM, please insert
(require 'tm-vm) *after* (bbdb-insinuate-vm).

  Important changes have been made to the VM interface in TM v7.102,
users upgrading from an earlier version should read the documentation
of tm-vm (`News' section) for details.


6.4 PGP

  If you have the PGP and Mailcrypt packages, you can use PGP with
MIME. Currently, PGP/MIME (RFC 2015) and draft-kazu-pgp-mime-00.txt
are proposed, so tm provides both ways.

  For decoding, please insert the following into ~/.emacs:

======================================================================
(call-after-loaded
 'tm-view
 (function
  (lambda ()
    (require 'tm-pgp)
    )))
======================================================================

tm-pgp.el is an internal method module to support PGP.

  For encoding, tm-edit provides 2 mechanisms. One is for signing or
encrypting for message as application/pgp. There are two commands,
`mime-editor/set-sign' and `mime-editor/set-encrypt'. They set a
message as signed, encrypted or not.

  Another one is for content. There are 2 kinds of enclosures for PGP:
``signed'' and ``encrypted''. Their enclosure are bound to key and
menu. If you use this mechanism, please specify 2 variables:
`mime-editor/signing-type' and `mime-editor/encrypting-type'. They
requires following values:

	pgp-elkins	processed as PGP/MIME (RFC 2015)
	pgp-kazu	processed as draft-kazu-pgp-mime-00.txt
	nil		not processed

If you use ``signed'' and ``encrypted'' as PGP/MIME, please insert
into ~/.emacs:

======================================================================
(setq mime-editor/signing-type    'pgp-elkins)
(setq mime-editor/encrypting-type 'pgp-elkins)
======================================================================

If you use ``signed'' and ``encrypted'' as draft-kazu-pgp-mime-00.txt,
please insert into ~/.emacs:

======================================================================
(setq mime-editor/signing-type    'pgp-kazu)
(setq mime-editor/encrypting-type 'pgp-kazu)
======================================================================


6.5 code sample for hilit19

======================================================================
(cond (window-system
       (require 'hilit19)
       (let* ((csubject-patterns '(("^\\[.+\\]$" nil msg-subject)))
	      (header-patterns '(("^Subject:.*$" nil msg-subject)
				 ("^From:.*$" nil msg-from)
				 ("^--text follows this line--$"
				  nil msg-separator)
				 ("^[A-Za-z][A-Za-z0-9-]+:" nil msg-header)
				 ))
	      (body-patterns '(("^\\(In article\\|[ \t]*\\w*[]<>}|]\\).*$"
				nil msg-quote)))
	      (message-patterns (append ;;csubject-patterns
				 header-patterns
				 body-patterns))
	      )
	 (hilit-set-mode-patterns 'msg-header header-patterns)
	 (hilit-set-mode-patterns 'msg-body body-patterns)
	 (hilit-set-mode-patterns 'mime/viewer-mode
				  message-patterns
				  'hilit-rehighlight-message)
	 )
       (add-hook 'mime-viewer/content-header-filter-hook
		 (lambda ()
		   (if (not (eq mime::preview/original-major-mode
				'gnus-original-article-mode))
		       (hilit-rehighlight-buffer-quietly)
		     )))
       (add-hook 'mime-viewer/plain-text-preview-hook
		 (lambda ()
		   (if (not (eq mime::preview/original-major-mode
				'gnus-original-article-mode))
		       (hilit-rehighlight-buffer-quietly)
		     )))
       ))
======================================================================


6.6 code sample for browse-url

  If you have browse-url.el (included in Gnus 5.*, September Gnus and
Emacs 19.30 or later), you can use URL button in
mime/viewer-mode. Sample code follows:

======================================================================
(setq browse-url-browser-function
      (if (eq window-system 'x)
	  'browse-url-netscape
	'browse-url-w3))
(autoload browse-url-browser-function "browse-url"
  "Ask a WWW browser to show a URL." t)
======================================================================


7 How to use mime/viewer-mode

In tm-MUAs, you can use mime/viewer-mode if you press the `v' key (in
VM, `Z' key) in Summary mode. Or automatic MIME previewed buffer's
major-mode is mime/viewer-mode. mime/viewer-mode has following
functions (these key bindings are prefixed with C-c in VM):

	q		quit from mime/viewer-mode
	u		move to upper content
	p or M-TAB	move to previous content
	n or TAB	move to next content
	SPC		scroll up or move to next content
	M-SPC or DEL	scroll down or move to previous content
	RET		move to next line
	M-RET		move to previous line
	<		move to beginning of message
	>		move to end of message
	v		play current content
	e		extract as file current content
	C-c C-p		print current content
	f		display X-Face in current message
	button-2	play current content or browse URL


8 Bug report

If you write bug-reports and/or propositions for improvement, please
send to tm ML:

	bug-tm-en@chamonix.jaist.ac.jp	(English)
	bug-tm-ja@chamonix.jaist.ac.jp	(Japanese)

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

	tm-ja-admin@chamonix.jaist.ac.jp	(Japanese)
	tm-en-admin@chamonix.jaist.ac.jp	(English)

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


9 How to get the latest version

tm is available from following anonymous ftp site:

	ftp://ftp.jaist.ac.jp/pub/GNU/elisp/mime/	(Japan)

and its mirrors:

	ftp://ftp.nis.co.jp/pub/gnu/emacs-lisp/tm/	(Japan)
	ftp://ftp.nisiq.net/pub/gnu/emacs-lisp/tm/	(US)


10 PROBLEMS

- Automatic combining method for message/partial is not implemented
  for RMAIL.
- answer method is not implemented for RMAIL, Gnus and GNUS.


11 TODO

- better method selecting system as successor of atype system
- development of internal method for message/external-body based on
  tm-ftp
- better automatic MIME preview support
- etc.
