README.en

   1 [README for tm (English Version)]
   2 by MORIOKA Tomohiko <tomo@m17n.org>
   3 and KOBAYASHI Shuhei <shuhei@aqua.ocn.ne.jp>
   4
   5 What's tm?
   6 ==========
   7
   8   tm is a MIME package for GNU Emacs. tm has following functions:
   9
  10         - MIME style multilingual header
  11         - MIME message viewer (mime/viewer-mode)
  12         - MIME message composer (mime/editor-mode)
  13         - MIME extenders for mh-e, GNUS, Gnus, RMAIL and VM
  14
  15
  16 2 Documents
  17
  18   This package includes the following documents.
  19
  20 (1) English edition
  21
  22 - SGML (sinfo)
  23   - tm/doc/tm-en.sgml           : tm Reference Manual
  24   - tm/doc/tm-view-en.sgml      : tm-view Reference Manual
  25   - tm/doc/tm-edit-en.sgml      : tm-edit Reference Manual
  26   - tm-mh-e/tm-mh-e-en.sgml     : tm-mh-e Reference Manual
  27   - gnus-mime/gnus-mime-en.sgml : gnus-mime Reference Manual
  28
  29 - Texinfo
  30   - tm/doc/tm-en.texi           : tm Reference Manual
  31   - tm/doc/tm-view-en.texi      : tm-view Reference Manual
  32   - tm/doc/tm-edit-en.texi      : tm-edit Reference Manual
  33   - tm-mh-e/tm-mh-e-en.texi     : tm-mh-e Reference Manual
  34   - gnus-mime/gnus-mime-en.texi : gnus-mime Reference Manual
  35   - tm-vm/tm-vm-en.texi         : tm-vm Reference Manual
  36
  37 - info
  38   - tm/doc/tm-en.info           : tm Reference Manual
  39   - tm/doc/tm-view-en.info      : tm-view Reference Manual
  40   - tm/doc/tm-edit-en.info      : tm-edit Reference Manual
  41   - tm-mh-e/tm-mh-e-en.info     : tm-mh-e Reference Manual
  42   - gnus-mime/gnus-mime-en.info : gnus-mime Reference Manual
  43   - tm-vm/tm-vm-en.info         : tm-vm Reference Manual
  44
  45 (2) Japanese edition
  46
  47 - SGML (sinfo)
  48   - tm/doc/tm-ja.sgml           : tm Reference Manual
  49   - tm/doc/tm-view-ja.sgml      : tm-view Reference Manual
  50   - tm/doc/tm-edit-ja.sgml      : tm-edit Reference Manual
  51   - tm-mh-e/tm-mh-e-ja.sgml     : tm-mh-e Reference Manual
  52   - gnus-mime/gnus-mime-ja.sgml : gnus-mime Reference Manual
  53
  54 - Texinfo
  55   - tm/doc/tm-ja.texi           : tm Reference Manual
  56   - tm/doc/tm-view-ja.texi      : tm-view Reference Manual
  57   - tm/doc/tm-edit-ja.texi      : tm-edit Reference Manual
  58   - tm-mh-e/tm-mh-e-ja.texi     : tm-mh-e Reference Manual
  59   - gnus-mime/gnus-mime-ja.texi : gnus-mime Reference Manual
  60
  61 - info
  62   - tm/doc/tm-ja.info           : tm Reference Manual
  63   - tm/doc/tm-view-ja.info      : tm-view Reference Manual
  64   - tm/doc/tm-edit-ja.info      : tm-edit Reference Manual
  65   - tm-mh-e/tm-mh-e-ja.info     : tm-mh-e Reference Manual
  66   - gnus-mime/gnus-mime-ja.info : gnus-mime Reference Manual
  67
  68 - other format
  69   - tm/doc/signature-jp.ol : signature.el Reference Manual (Emacs Outline)
  70   - tm/doc/signature-jp.tex: signature.el Reference Manual (LaTeX)
  71   - tm/doc/tm-charset_ja.ol: How to use character codes in tm (Emacs Outline)
  72   - tm/doc/tm-charset_ja.tex: How to use character codes in tm (LaTeX)
  73
  74
  75 3 Modules
  76
  77   tm has following modules:
  78
  79         - tm-view : MIME viewer
  80                 - tm-parse.el : MIME message parser
  81                 - tm-play.el  : MIME content player
  82         - preview filter for tm-view
  83                 - tm-text    : for text/*
  84                 - tm-image   : for image/* and X-Face
  85         - internal methods for tm-view
  86                 - tm-partial : automatic assembler for message/partial
  87                 - tm-ftp     : for anonymous ftp
  88                 - tm-file    : for file extraction
  89                 - tm-tar     : for tar content
  90                 - tm-latex   : for LaTeX
  91                 - tm-html    : for text/html
  92                 - tm-pgp     : for PGP
  93         - tm-edit : MIME composer (mime.el and tm-comp.el were merged)
  94                 - tm-edit-mc.el : tm-edit interface for Mailcrypt
  95                 - tm-edit-tipgp.el : tm-edit interface for TinyPgp.el
  96         - tm-def  : definition module for tm
  97         - tm-MUAs : MIME extender for MUAs
  98                 - tm-mh-e   : tm-MUA for mh-e
  99                 - gnus-mime : tm-MUA for Gnus
 100                 - tm-gnus   : tm-MUA for GNUS
 101                 - tm-rmail  : tm-MUA for RMAIL
 102                 - tm-vm     : tm-MUA for vm
 103                 - tm-mail   : tm-MUA library module for mail-mode
 104         - mime-setup: set up module for MIME
 105                 - tm-setup: set up only reading
 106
 107
 108 4 Install
 109
 110 4.1 edit tm/TM-CFG (optional)
 111
 112   You can edit tm/TM-CFG file.
 113
 114   By default, tm is installed into /usr/local/. If you want to change this,
 115 please modify the variables `PREFIX' and `EXEC_PREFIX'.
 116
 117
 118 4.2 edit external methods (optional)
 119
 120   You can edit external methods in `tm/methods/' directory for your
 121 environment.
 122
 123         tm/methods/tm-au        for audio
 124         tm/methods/tm-file      for file extraction
 125         tm/methods/tm-image     for image
 126         tm/methods/tm-mpeg      for MPEG
 127         tm/methods/tm-plain     for plain text
 128         tm/methods/tm-html      for HTML
 129         tm/methods/tmdecode     decoder
 130
 131   By default, tmdecode uses the `mmencode' command, which is part of
 132 the metamail package (available by anonymous ftp from
 133 ftp://thumper.bellcore.com/pub/nsb).  If you don't have the metamail
 134 package, please modify tmdecode to use decode-b instead of mmencode.
 135
 136
 137 4.3 make
 138
 139   Run `make all'.
 140
 141   You can specify the Emacs command name, for example if you want to use
 142 `mule' as the Emacs command:
 143
 144         % make all EMACS=mule
 145
 146
 147 4.4 install
 148
 149   Run `make install'.
 150
 151   You can specify the Emacs command name, for example if you want to use
 152 `xemacs' as the Emacs command:
 153
 154         % make install EMACS=xemacs
 155
 156
 157 6 .emacs
 158
 159   Please insert `(load "mime-setup")' in ~/.emacs.
 160
 161
 162 6.1 gnus-mime
 163
 164   gnus-mime provides automatic MIME preview feature for Gnus.
 165
 166   If you don't want to use automatic MIME preview feature, please
 167 insert in ~/.emacs:
 168
 169         (setq gnus-show-mime nil)
 170
 171   In addition, Gnus 5.2 is designed to support automatic MIME preview
 172 feature.  Of course, gnus-mime provides this feature for Gnus 5.0.*
 173 and Gnus 5.1.*, but it is unnatural.
 174
 175   When automatic MIME preview mode, Gnus do MIME processing if a
 176 message has a Mime-Version field.  If it does not have one, Gnus does
 177 not do MIME processing, in default.
 178
 179   Gnus 5.0.*, 5.1 and Gnus 5.2 have a variable `gnus-strict-mime'.  If
 180 you insert
 181
 182         (setq gnus-strict-mime nil)
 183
 184 Gnus does MIME processing even if a message does not have a
 185 Mime-Version field.
 186
 187   In Gnus 5.2, if `gnus-strict-mime' is not nil, variable
 188 `gnus-decode-encoded-word-method' is called.  gnus-mime uses it to
 189 decode RFC 2047 encoded-words.  So it is not necessary to reset
 190 `gnus-strict-mime'.
 191
 192
 193 6.2 tm-gnus
 194
 195   tm-gnus provides automatic MIME preview feature for GNUS 3.15 or
 196 later.
 197
 198   If you don't want to use automatic MIME preview feature, please
 199 insert in ~/.emacs:
 200
 201         (setq tm-gnus/automatic-mime-preview nil)
 202
 203
 204 6.3 VM
 205
 206   If you use vm, please insert `(require 'tm-vm)' in ~/.vm.
 207
 208   tm works well with BBDB: If you use VM, please insert
 209 (require 'tm-vm) *after* (bbdb-insinuate-vm).
 210
 211   Important changes have been made to the VM interface in TM v7.102,
 212 users upgrading from an earlier version should read the documentation
 213 of tm-vm (`News' section) for details.
 214
 215
 216 6.4 PGP
 217
 218   If you have the PGP and Mailcrypt packages, you can use PGP with
 219 MIME. Currently, PGP/MIME (RFC 2015) and draft-kazu-pgp-mime-00.txt
 220 are proposed, so tm provides both ways.
 221
 222   For decoding, please insert the following into ~/.emacs:
 223
 224 ======================================================================
 225 (call-after-loaded
 226  'tm-view
 227  (function
 228   (lambda ()
 229     (require 'tm-pgp)
 230     )))
 231 ======================================================================
 232
 233 tm-pgp.el is an internal method module to support PGP.
 234
 235   For encoding, tm-edit provides 2 mechanisms. One is for signing or
 236 encrypting for message as application/pgp. There are two commands,
 237 `mime-editor/set-sign' and `mime-editor/set-encrypt'. They set a
 238 message as signed, encrypted or not.
 239
 240   Another one is for content. There are 2 kinds of enclosures for PGP:
 241 ``signed'' and ``encrypted''. Their enclosure are bound to key and
 242 menu. If you use this mechanism, please specify 2 variables:
 243 `mime-editor/signing-type' and `mime-editor/encrypting-type'. They
 244 requires following values:
 245
 246         pgp-elkins      processed as PGP/MIME (RFC 2015)
 247         pgp-kazu        processed as draft-kazu-pgp-mime-00.txt
 248         nil             not processed
 249
 250 If you use ``signed'' and ``encrypted'' as PGP/MIME, please insert
 251 into ~/.emacs:
 252
 253 ======================================================================
 254 (setq mime-editor/signing-type    'pgp-elkins)
 255 (setq mime-editor/encrypting-type 'pgp-elkins)
 256 ======================================================================
 257
 258 If you use ``signed'' and ``encrypted'' as draft-kazu-pgp-mime-00.txt,
 259 please insert into ~/.emacs:
 260
 261 ======================================================================
 262 (setq mime-editor/signing-type    'pgp-kazu)
 263 (setq mime-editor/encrypting-type 'pgp-kazu)
 264 ======================================================================
 265
 266
 267 6.5 code sample for hilit19
 268
 269 ======================================================================
 270 (cond (window-system
 271        (require 'hilit19)
 272        (let* ((csubject-patterns '(("^\\[.+\\]$" nil msg-subject)))
 273               (header-patterns '(("^Subject:.*$" nil msg-subject)
 274                                  ("^From:.*$" nil msg-from)
 275                                  ("^--text follows this line--$"
 276                                   nil msg-separator)
 277                                  ("^[A-Za-z][A-Za-z0-9-]+:" nil msg-header)
 278                                  ))
 279               (body-patterns '(("^\\(In article\\|[ \t]*\\w*[]<>}|]\\).*$"
 280                                 nil msg-quote)))
 281               (message-patterns (append ;;csubject-patterns
 282                                  header-patterns
 283                                  body-patterns))
 284               )
 285          (hilit-set-mode-patterns 'msg-header header-patterns)
 286          (hilit-set-mode-patterns 'msg-body body-patterns)
 287          (hilit-set-mode-patterns 'mime/viewer-mode
 288                                   message-patterns
 289                                   'hilit-rehighlight-message)
 290          )
 291        (add-hook 'mime-viewer/content-header-filter-hook
 292                  (lambda ()
 293                    (if (not (eq mime::preview/original-major-mode
 294                                 'gnus-original-article-mode))
 295                        (hilit-rehighlight-buffer-quietly)
 296                      )))
 297        (add-hook 'mime-viewer/plain-text-preview-hook
 298                  (lambda ()
 299                    (if (not (eq mime::preview/original-major-mode
 300                                 'gnus-original-article-mode))
 301                        (hilit-rehighlight-buffer-quietly)
 302                      )))
 303        ))
 304 ======================================================================
 305
 306
 307 6.6 code sample for browse-url
 308
 309   If you have browse-url.el (included in Gnus 5.*, September Gnus and
 310 Emacs 19.30 or later), you can use URL button in
 311 mime/viewer-mode. Sample code follows:
 312
 313 ======================================================================
 314 (setq browse-url-browser-function
 315       (if (eq window-system 'x)
 316           'browse-url-netscape
 317         'browse-url-w3))
 318 (autoload browse-url-browser-function "browse-url"
 319   "Ask a WWW browser to show a URL." t)
 320 ======================================================================
 321
 322
 323 7 How to use mime/viewer-mode
 324
 325 In tm-MUAs, you can use mime/viewer-mode if you press the `v' key (in
 326 VM, `Z' key) in Summary mode. Or automatic MIME previewed buffer's
 327 major-mode is mime/viewer-mode. mime/viewer-mode has following
 328 functions (these key bindings are prefixed with C-c in VM):
 329
 330         q               quit from mime/viewer-mode
 331         u               move to upper content
 332         p or M-TAB      move to previous content
 333         n or TAB        move to next content
 334         SPC             scroll up or move to next content
 335         M-SPC or DEL    scroll down or move to previous content
 336         RET             move to next line
 337         M-RET           move to previous line
 338         <               move to beginning of message
 339         >               move to end of message
 340         v               play current content
 341         e               extract as file current content
 342         C-c C-p         print current content
 343         f               display X-Face in current message
 344         button-2        play current content or browse URL
 345
 346
 347 8 Bug report
 348
 349 If you write bug-reports and/or propositions for improvement, please
 350 send to the EMACS-MIME Mailing List:
 351
 352         emacs-mime-en@m17n.org  (English)
 353         emacs-mime-ja@m17n.org  (Japanese)
 354
 355 Via the EMACS-MIME ML, you can report tm bugs, obtain the latest
 356 release of tm package, and discuss the future enhancements to tm.  To
 357 join the EMACS-MIME ML, send an empty e-mail to
 358
 359         emacs-mime-ja-ctl@m17n.org      (Japanese)
 360         emacs-mime-en-ctl@m17n.org      (English)
 361
 362
 363 10 PROBLEMS
 364
 365 - Automatic combining method for message/partial is not implemented
 366   for RMAIL.
 367 - answer method is not implemented for RMAIL, Gnus and GNUS.
 368
 369
 370 11 TODO
 371
 372 - better method selecting system as successor of atype system
 373 - development of internal method for message/external-body based on
 374   tm-ftp
 375 - better automatic MIME preview support
 376 - etc.