emy.texi

   1 \input texinfo.tex              @c -*- texinfo -*-
   2
   3 @setfilename emy.info
   4
   5 @set VERSION 1.13
   6
   7 @dircategory Emacs/MIME
   8 @direntry
   9 * EMY: (emy).   User guide for EMY.
  10 @end direntry
  11
  12 @settitle EMY @value{VERSION}
  13
  14 @ifinfo
  15 This file describes how to use EMY, MIME user interface which
  16 implements SEMI API.
  17
  18 Copyright (C) 1993, 94, 95, 96, 97, 98, 99 Free Software Foundation, Inc.
  19
  20 Permission is granted to make and distribute verbatim copies of
  21 this manual provided the copyright notice and this permission notice
  22 are preserved on all copies.
  23
  24 @ignore
  25 Permission is granted to process this file through TeX and print the
  26 results, provided the printed document carries copying permission
  27 notice identical to this one except for the removal of this paragraph
  28 (this paragraph not being relevant to the printed manual).
  29
  30 @end ignore
  31 Permission is granted to copy and distribute modified versions of this
  32 manual under the conditions for verbatim copying, provided that the entire
  33 resulting derived work is distributed under the terms of a permission
  34 notice identical to this one.
  35
  36 Permission is granted to copy and distribute translations of this manual
  37 into another language, under the above conditions for modified versions,
  38 except that this permission notice may be stated in a translation approved
  39 by the Free Software Foundation.
  40 @end ifinfo
  41
  42 @titlepage
  43 @title EMY
  44 @subtitle MIME User Interface implements SEMI API
  45 @author Yoshiki Hayashi
  46 @page
  47 @vskip 0pt plus 1filll
  48 Copyright @copyright{} 1993, 94, 95, 96, 97, 98, 99 Free Software
  49 Foundation, Inc.
  50
  51 Permission is granted to make and distribute verbatim copies of
  52 this manual provided the copyright notice and this permission notice
  53 are preserved on all copies.
  54
  55 Permission is granted to copy and distribute modified versions of this
  56 manual under the conditions for verbatim copying, provided that the entire
  57 resulting derived work is distributed under the terms of a permission
  58 notice identical to this one.
  59
  60 Permission is granted to copy and distribute translations of this manual
  61 into another language, under the above conditions for modified versions,
  62 except that this permission notice may be stated in a translation approved
  63 by the Free Software Foundation.
  64 @end titlepage
  65
  66 @ifnottex
  67 @node Top
  68 @top EMY: An Introduction
  69
  70 EMY is a MIME interface for Emacs. EMY provides SEMI API, which
  71 is specified in a separate document.
  72 @c @xref{(semi-api)Top}.
  73
  74 This manual corresponds to EMY version @value{VERSION}.
  75 @end ifnottex
  76
  77 @menu
  78 * MIME::                Overview of MIME.
  79 * Overview::            What EMY does and doesn't.
  80 * MIME-View::           How to View MIME messages.
  81 * MIME-Edit::           How to compose MIME messages.
  82 @end menu
  83
  84 @node MIME
  85 @chapter Overview of MIME
  86
  87 MIME stands for Multipurpose Internet Mail Extensions.
  88
  89 MIME is built on top of STD11.  MIME enhances semantics of STD11 so that
  90 you can send messages other than text/plain and US-ASCII.  MIME does not
  91 prohibit use of local conventions.  However, its use is discouraged.
  92 It would be nice if all MUA uses MIME to specify character set etc.
  93 Then you don't have to be aware of all local conventions in the world.
  94
  95 Don't assume every MUA can handle MIME correctly.  They might even don't
  96 understand MIME.  EMY takes interoperability the first priority.  You
  97 must be carefull to choose format that is easy to understand for
  98 everyone.  But you don't have to be afraid.  MIME is written in such a
  99 way that it can be viewed with non-MIME MUA if its well written.
 100
 101 EMY is here to make your life easier.  It provides some way to ignore
 102 standards to cooperate with broken world.  However, it doesn't allow
 103 you to send broken MIME messages.  If you want to same brokenness like
 104 them, EMY is not a candidate.  If you really thinks it's needed, you can
 105 try persuading me.  Warning: `It's de facto standard' is not enough.
 106
 107 @menu
 108 * Text::                What you normally do.
 109 * Content-Types::       You can create messages other than text/plain.
 110 @end menu
 111
 112 @node Text
 113 @section Writing text
 114
 115 (I'll write this sections later).
 116
 117 @node Content-Types
 118 @section Types of message you can use
 119
 120 @menu
 121 * Content-Type::        Details of interpreting Content-Type.
 122 @end menu
 123
 124 @node Content-Type
 125 @subsection How things are interpreted with each types
 126
 127 @node Overview
 128 @chapter Some basic things about EMY
 129
 130 (Not yet written).
 131
 132 @menu
 133 * Customize::           How to customize EMY.
 134 @end menu
 135
 136 @node Customize
 137 @section What you should care about
 138
 139 You can change how EMY works by setting various variables.  Normally you
 140 should change values after EMY is loaded.  However, there are some
 141 varaibles which should be set before anything has done.
 142
 143 (Not yet fully documented.)
 144
 145 @table @code
 146 @c @vindex mime-setup-enable-inline-image
 147 @item mime-setup-enable-inline-image
 148
 149 @item mime-setup-enable-inline-html
 150
 151 @item mime-setup-enable-pgp
 152
 153 @item mime-setup-use-signature
 154
 155 @c before signature.el is loaded.
 156 @item mime-setup-default-signature-key
 157 @item mime-setup-signature-key-alist
 158 @end table
 159
 160 @node MIME-View
 161 @chapter Viewing MIME messages
 162
 163 Right now, only differences between SEMI and EMY are documented.
 164
 165 @menu
 166 * Manipulating an Entity::      Changing representation of a part.
 167 * Changing Entity Buttons::     Where to add button indicating that entity.
 168 * Adding Buttons::              Where you want to see buttons.
 169 * How to deal with broken MUA:: Some MUA sends totally broken messages.
 170 @end menu
 171
 172 @node Manipulating an Entity
 173 @section Playing with an entity
 174
 175 You can change the representation of given part in the preview buffer.
 176 Following commands are available in preview buffer.
 177
 178 @table @code
 179
 180 @item c
 181 @kindex c (MIME-View)
 182 @findex mime-preview-text
 183 Display the part as text/plain with automatic MIME charset
 184 detection.  You can specify coding-system if you give a numerical
 185 prefix (@code{mime-preview-text}).
 186
 187 @item i
 188 @kindex i (MIME-View)
 189 @findex mime-preview-inline
 190 Show the contents of the part without code-conversion.  @code{C-u c
 191 binary RET} does the same thing (@code{mime-preview-inline}).
 192
 193 @item t
 194 @kindex t (MIME-View)
 195 @findex mime-preview-type
 196 Represent the part using the method specified by
 197 @code{mime-preview-condition}.  When there's no presentation method for
 198 given part, nothing is performed (@code{mime-preview-type}).
 199
 200 @item e
 201 @kindex e (MIME-View)
 202 @findex mime-preview-extract-current-entity
 203 Save content of the part to a file.  It will prompt for you to enter
 204 file name (@code{mime-preview-extract-current-entity}).
 205
 206 @item v
 207 @kindex v (MIME-View)
 208 @findex mime-preview-play-current-entity
 209 Pass the entity to an external program specified by mailcap file
 210 (@code{mime-preview-play-current-entity}).
 211 @c Need more documentation about mailcap.
 212
 213 @item b
 214 @kindex b (MIME-View)
 215 @findex mime-preview-buttonize
 216 Buttonize article (@code{mime-preview-buttonize}).
 217
 218 @item B
 219 @kindex B (MIME-View)
 220 @findex mime-preview-unbuttonize
 221 Unbuttonize article (@code{mime-preview-unbuttonize}).
 222
 223 @end table
 224
 225 @table @code
 226
 227 @item C-c C-t C-h
 228 @kindex C-c C-t C-h (MIME-View)
 229 @findex mime-preview-toggle-header
 230
 231 Toggle display of entity header.
 232
 233 @item C-c C-t C-c
 234 @kindex C-c C-t C-c (MIME-View)
 235 @findex mime-preview-toggle-content
 236
 237 Toggle display of entity body.
 238
 239 @end table
 240
 241 @node Changing Entity Buttons
 242 @section How buttons look like
 243
 244 @vindex mime-use-widget
 245 Before EMY 1.13.6, you need W- variants of SEMI to show wigdet buttons
 246 From now on, you only need to set @code{mime-use-widget}
 247 to @code{t}.
 248
 249 A button is a place where information about a given part is displayed.
 250 Its contents is already defined.
 251
 252 [You should be able to customize button with format string.
 253  This might be implemented in later versions.  If you
 254  want it, speak up!]
 255
 256 @node Adding Buttons
 257 @section Add button before, after or around an entity
 258
 259 @vindex mime-view-button-place-alist
 260 You can customize where to add buttons and where to not with
 261 @code{mime-view-button-place-alist}.  Unfortunately, there's no variable
 262 to change content of the button. It must be an alist of type or
 263 type/subtype vs. keywords.
 264
 265 Three valid keywords are:
 266
 267 @table @code
 268 @item before
 269 Add button before given types.
 270
 271 @item after
 272 Add button when another part follows that type.
 273
 274 @item around
 275 Do both @code{before} and @code{after}.
 276
 277 @end table
 278
 279 Notice when deciding whether inserting button or not, an entity of same
 280 level is consulted as a previous entity.  Let's say a message has
 281 following structure and nothing is specified for text/xml.
 282
 283 @example
 284 message/rfc822
 285   multipart/mixed
 286     text/plain
 287     image/jpeg
 288   text/xml
 289 @end example
 290
 291 When MIME-View decides text/xml part should have button or not, it
 292 checks multipart/mixed has @code{after} or @code{around}, not
 293 image/jpeg. This behaviour may be confusing.  In the future version, the
 294 very last part's value will be used as well.
 295
 296 Default value is:
 297
 298 @lisp
 299 ((message . around)
 300  (application . before)
 301  (multipart/alternative . around))
 302 @end lisp
 303
 304 This means you will have buttons around message/* and
 305 multipart/alternative, and before application/*.
 306
 307 @node How to deal with broken MUA
 308 @section Invalid MIME messages
 309
 310 Some MUAs send totally broken MIME messages.  According to the standard,
 311 it's perfectly fine for EMY not to grok those message.  However, EMY
 312 tries to extract as much information as possible.  Here's some functions
 313 that might help you.
 314
 315 Some MUAs localized to Japanese sends these strings as a filename
 316 parameter of Content-Disposition.
 317
 318 @example
 319 =?ISO-2022-JP?B?GyRCRnxLXDhsGyhC?=
 320 @end example
 321
 322 It looks like encoded-words. This usage is strictly prohibited by RFC
 323 2047.  Instead, you should use mechanism described in RFC 2231.
 324 If you really want to ``decode'' it when saving it to file, you can use
 325 something like this.
 326
 327 @lisp
 328 (mime-add-condition
 329  'action
 330  '((mode . "extract")
 331    (method . mime-save-content-for-broken-message)))
 332 @end lisp
 333
 334 Unfortunately, there's no easy way to customize looking of buttons.
 335 It's on EMY's TODO list.
 336
 337 If you are desperate, you can redefine
 338 @code{mime-view-insert-entity-button}.
 339
 340 @lisp
 341 (defun mime-view-insert-entity-button (entity &optional body-is-invisible)
 342   "Insert entity-button of ENTITY."
 343   (let ((entity-node-id (mime-entity-node-id entity))
 344         (params (mime-entity-parameters entity))
 345         (subject (eword-decode-string (mime-view-entity-title entity))))
 346     (mime-insert-button
 347      (concat
 348       (let ((access-type (assoc "access-type" params))
 349             (num (or (cdr (assoc "x-part-number" params))
 350                      (if (consp entity-node-id)
 351                          (mapconcat (function
 352                                      (lambda (num)
 353                                        (format "%s" (1+ num))))
 354                                     (reverse entity-node-id) ".")
 355                        "0"))))
 356         (cond (access-type
 357                (let ((server (assoc "server" params)))
 358                  (setq access-type (cdr access-type))
 359                  (if server
 360                      (format "%s %s ([%s] %s)"
 361                              num subject access-type (cdr server))
 362                    (let ((site (cdr (assoc "site" params)))
 363                          (dir (cdr (assoc "directory" params)))
 364                          (url (cdr (assoc "url" params))))
 365                      (if url
 366                          (format "%s %s ([%s] %s)"
 367                                  num subject access-type url)
 368                        (format "%s %s ([%s] %s:%s)"
 369                                num subject access-type site dir))))))
 370               (t
 371                (let ((media-type (mime-entity-media-type entity))
 372                      (media-subtype (mime-entity-media-subtype entity))
 373                      (charset (cdr (assoc "charset" params)))
 374                      (encoding (mime-entity-encoding entity)))
 375                  (concat
 376                   num " " subject
 377                   (let ((rest
 378                          (format " <%s/%s%s%s>"
 379                                  media-type media-subtype
 380                                  (if charset
 381                                      (concat "; " charset)
 382                                    "")
 383                                  (if encoding
 384                                      (concat " (" encoding ")")
 385                                    ""))))
 386                     (if (>= (+ (current-column)(length rest))(window-width))
 387                         "\n\t")
 388                     rest))))))
 389       (if body-is-invisible
 390           " ..."
 391         ""))
 392      (function mime-preview-play-current-entity))))
 393 @end lisp
 394
 395 @strong{Note:} These settings are unsupported until a better way is
 396 implemented.
 397
 398 @node MIME-Edit
 399 @chapter Composing MIME messages
 400
 401 @vindex mime-edit-attach-at-end-type (MIME-Edit)
 402 When you are editing MIME message, you might want to insert some part at
 403 the end of your message.  Some MUA are known to have some problems when
 404 last part is not an attachment.
 405
 406 If you want to do this, @code{mime-edit-attach-at-end-type} is your
 407 friend. This variable is list of MIME types or type/subtypes inserted
 408 at the last part. When only type is specified, it will affect all
 409 subtypes of that type.
 410
 411 If you want insert application/* and message/rfc822 at the end,
 412 you can do like this:
 413
 414 @lisp
 415 (setq mime-edit-attach-at-end-types
 416       '(application message/rfc822))
 417 @end lisp
 418
 419 @bye