1 \input texinfo.tex @c -*- texinfo -*-
7 @dircategory Emacs/MIME
9 * EMY: (emy). User guide for EMY.
12 @settitle EMY @value{VERSION}
15 This file describes how to use EMY, MIME user interface which
18 Copyright (C) 1993, 94, 95, 96, 97, 98, 99 Free Software Foundation, Inc.
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.
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).
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.
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.
44 @subtitle MIME User Interface implements SEMI API
45 @author Yoshiki Hayashi
47 @vskip 0pt plus 1filll
48 Copyright @copyright{} 1993, 94, 95, 96, 97, 98, 99 Free Software
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.
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.
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.
68 @top EMY: An Introduction
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}.
74 This manual corresponds to EMY version @value{VERSION}.
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.
85 @chapter Overview of MIME
87 MIME stands for Multipurpose Internet Mail Extensions.
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.
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.
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.
108 * Text:: What you normally do.
109 * Content-Types:: You can create messages other than text/plain.
113 @section Writing text
115 (I'll write this sections later).
118 @section Types of message you can use
121 * Content-Type:: Details of interpreting Content-Type.
125 @subsection How things are interpreted with each types
128 @chapter Some basic things about EMY
133 * Customize:: How to customize EMY.
137 @section What you should care about
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.
143 (Not yet fully documented.)
146 @c @vindex mime-setup-enable-inline-image
147 @item mime-setup-enable-inline-image
149 @item mime-setup-enable-inline-html
151 @item mime-setup-enable-pgp
153 @item mime-setup-use-signature
155 @c before signature.el is loaded.
156 @item mime-setup-default-signature-key
157 @item mime-setup-signature-key-alist
161 @chapter Viewing MIME messages
163 Right now, only differences between SEMI and EMY are documented.
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.
172 @node Manipulating an Entity
173 @section Playing with an entity
175 You can change the representation of given part in the preview buffer.
176 Following commands are available in preview buffer.
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}).
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}).
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}).
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}).
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.
214 @kindex b (MIME-View)
215 @findex mime-preview-buttonize
216 Buttonize article (@code{mime-preview-buttonize}).
219 @kindex B (MIME-View)
220 @findex mime-preview-unbuttonize
221 Unbuttonize article (@code{mime-preview-unbuttonize}).
228 @kindex C-c C-t C-h (MIME-View)
229 @findex mime-preview-toggle-header
231 Toggle display of entity header.
234 @kindex C-c C-t C-c (MIME-View)
235 @findex mime-preview-toggle-content
237 Toggle display of entity body.
241 @node Changing Entity Buttons
242 @section How buttons look like
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}
249 A button is a place where information about a given part is displayed.
250 Its contents is already defined.
252 [You should be able to customize button with format string.
253 This might be implemented in later versions. If you
257 @section Add button before, after or around an entity
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.
265 Three valid keywords are:
269 Add button before given types.
272 Add button when another part follows that type.
275 Do both @code{before} and @code{after}.
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.
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.
300 (application . before)
301 (multipart/alternative . around))
304 This means you will have buttons around message/* and
305 multipart/alternative, and before application/*.
307 @node How to deal with broken MUA
308 @section Invalid MIME messages
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
315 Some MUAs localized to Japanese sends these strings as a filename
316 parameter of Content-Disposition.
319 =?ISO-2022-JP?B?GyRCRnxLXDhsGyhC?=
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
331 (method . mime-save-content-for-broken-message)))
334 Unfortunately, there's no easy way to customize looking of buttons.
335 It's on EMY's TODO list.
337 If you are desperate, you can redefine
338 @code{mime-view-insert-entity-button}.
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))))
348 (let ((access-type (assoc "access-type" params))
349 (num (or (cdr (assoc "x-part-number" params))
350 (if (consp entity-node-id)
353 (format "%s" (1+ num))))
354 (reverse entity-node-id) ".")
357 (let ((server (assoc "server" params)))
358 (setq access-type (cdr access-type))
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))))
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))))))
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)))
378 (format " <%s/%s%s%s>"
379 media-type media-subtype
381 (concat "; " charset)
384 (concat " (" encoding ")")
386 (if (>= (+ (current-column)(length rest))(window-width))
389 (if body-is-invisible
392 (function mime-preview-play-current-entity))))
395 @strong{Note:} These settings are unsupported until a better way is
399 @chapter Composing MIME messages
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.
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.
411 If you want insert application/* and message/rfc822 at the end,
412 you can do like this:
415 (setq mime-edit-attach-at-end-types
416 '(application message/rfc822))