3 @setfilename emacs-mime
4 @settitle Emacs MIME Manual
10 This file documents the Emacs MIME interface functionality.
12 Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
13 2006, 2007 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.2 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover texts being ``A GNU
20 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
21 license is included in the section entitled ``GNU Free Documentation
22 License'' in the Emacs manual.
24 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
25 this GNU Manual, like GNU software. Copies published by the Free
26 Software Foundation raise funds for GNU development.''
28 This document is part of a collection distributed under the GNU Free
29 Documentation License. If you want to distribute this document
30 separately from the collection, you can do so by adding a copy of the
31 license to the document, as described in section 6 of the license.
35 @c Node ``Interface Functions'' uses Latin-1 characters
36 @documentencoding ISO-8859-1
40 * Emacs MIME: (emacs-mime). Emacs MIME de/composition library.
45 @setchapternewpage odd
48 @title Emacs MIME Manual
50 @author by Lars Magne Ingebrigtsen
52 @vskip 0pt plus 1filll
59 This manual documents the libraries used to compose and display
60 @acronym{MIME} messages.
62 This manual is directed at users who want to modify the behavior of
63 the @acronym{MIME} encoding/decoding process or want a more detailed
64 picture of how the Emacs @acronym{MIME} library works, and people who want
65 to write functions and commands that manipulate @acronym{MIME} elements.
67 @acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}.
68 This standard is documented in a number of RFCs; mainly RFC2045 (Format
69 of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
70 Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration
71 Procedures), RFC2049 (Conformance Criteria and Examples). It is highly
72 recommended that anyone who intends writing @acronym{MIME}-compliant software
73 read at least RFC2045 and RFC2047.
76 * Decoding and Viewing:: A framework for decoding and viewing.
77 * Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts.
78 * Interface Functions:: An abstraction over the basic functions.
79 * Basic Functions:: Utility and basic parsing functions.
80 * Standards:: A summary of RFCs and working documents used.
81 * GNU Free Documentation License:: The license for this documentation.
82 * Index:: Function and variable index.
86 @node Decoding and Viewing
87 @chapter Decoding and Viewing
89 This chapter deals with decoding and viewing @acronym{MIME} messages on a
92 The main idea is to first analyze a @acronym{MIME} article, and then allow
93 other programs to do things based on the list of @dfn{handles} that are
94 returned as a result of this analysis.
97 * Dissection:: Analyzing a @acronym{MIME} message.
98 * Non-MIME:: Analyzing a non-@acronym{MIME} message.
99 * Handles:: Handle manipulations.
100 * Display:: Displaying handles.
101 * Display Customization:: Variables that affect display.
102 * Files and Directories:: Saving and naming attachments.
103 * New Viewers:: How to write your own viewers.
110 The @code{mm-dissect-buffer} is the function responsible for dissecting
111 a @acronym{MIME} article. If given a multipart message, it will recursively
112 descend the message, following the structure, and return a tree of
113 @acronym{MIME} handles that describes the structure of the message.
117 @vindex mm-uu-configure-list
119 Gnus also understands some non-@acronym{MIME} attachments, such as
120 postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp,
121 diff. Each of these features can be disabled by add an item into
122 @code{mm-uu-configure-list}. For example,
126 (add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
152 Non-@acronym{MIME} forwarded message.
160 @acronym{PGP} signed clear text.
163 @findex pgp-encrypted
164 @acronym{PGP} encrypted clear text.
168 @acronym{PGP} public keys.
171 @findex emacs-sources
172 @vindex mm-uu-emacs-sources-regexp
173 Emacs source code. This item works only in the groups matching
174 @code{mm-uu-emacs-sources-regexp}.
178 @vindex mm-uu-diff-groups-regexp
179 Patches. This is intended for groups where diffs of committed files
180 are automatically sent to. It only works in groups matching
181 @code{mm-uu-diff-groups-regexp}.
184 @cindex verbatim-marks
185 Slrn-style verbatim marks.
189 LaTeX documents. It only works in groups matching
190 @code{mm-uu-tex-groups-regexp}.
194 @cindex text/x-verbatim
195 @c Is @vindex suitable for a face?
196 @vindex mm-uu-extract
197 Some inlined non-@acronym{MIME} attachments are displayed using the face
198 @code{mm-uu-extract}. By default, no @acronym{MIME} button for these
199 parts is displayed. You can force displaying a button using @kbd{K b}
200 (@code{gnus-summary-display-buttonized}) or add @code{text/x-verbatim}
201 to @code{gnus-buttonized-mime-types}, @xref{MIME Commands, ,MIME
202 Commands, gnus, Gnus Manual}.
207 A @acronym{MIME} handle is a list that fully describes a @acronym{MIME}
210 The following macros can be used to access elements in a handle:
213 @item mm-handle-buffer
214 @findex mm-handle-buffer
215 Return the buffer that holds the contents of the undecoded @acronym{MIME}
219 @findex mm-handle-type
220 Return the parsed @code{Content-Type} of the part.
222 @item mm-handle-encoding
223 @findex mm-handle-encoding
224 Return the @code{Content-Transfer-Encoding} of the part.
226 @item mm-handle-undisplayer
227 @findex mm-handle-undisplayer
228 Return the object that can be used to remove the displayed part (if it
231 @item mm-handle-set-undisplayer
232 @findex mm-handle-set-undisplayer
233 Set the undisplayer object.
235 @item mm-handle-disposition
236 @findex mm-handle-disposition
237 Return the parsed @code{Content-Disposition} of the part.
239 @item mm-get-content-id
240 Returns the handle(s) referred to by @code{Content-ID}.
248 Functions for displaying, removing and saving.
251 @item mm-display-part
252 @findex mm-display-part
256 @findex mm-remove-part
257 Remove the part (if it has been displayed).
260 @findex mm-inlinable-p
261 Say whether a @acronym{MIME} type can be displayed inline.
263 @item mm-automatic-display-p
264 @findex mm-automatic-display-p
265 Say whether a @acronym{MIME} type should be displayed automatically.
267 @item mm-destroy-part
268 @findex mm-destroy-part
269 Free all resources occupied by a part.
273 Offer to save the part in a file.
277 Offer to pipe the part to some process.
279 @item mm-interactively-view-part
280 @findex mm-interactively-view-part
281 Prompt for a mailcap method to use to view the part.
286 @node Display Customization
287 @section Display Customization
291 @item mm-inline-media-tests
292 @vindex mm-inline-media-tests
293 This is an alist where the key is a @acronym{MIME} type, the second element
294 is a function to display the part @dfn{inline} (i.e., inside Emacs), and
295 the third element is a form to be @code{eval}ed to say whether the part
296 can be displayed inline.
298 This variable specifies whether a part @emph{can} be displayed inline,
299 and, if so, how to do it. It does not say whether parts are
300 @emph{actually} displayed inline.
302 @item mm-inlined-types
303 @vindex mm-inlined-types
304 This, on the other hand, says what types are to be displayed inline, if
305 they satisfy the conditions set by the variable above. It's a list of
306 @acronym{MIME} media types.
308 @item mm-automatic-display
309 @vindex mm-automatic-display
310 This is a list of types that are to be displayed ``automatically'', but
311 only if the above variable allows it. That is, only inlinable parts can
312 be displayed automatically.
314 @item mm-automatic-external-display
315 @vindex mm-automatic-external-display
316 This is a list of types that will be displayed automatically in an
319 @item mm-keep-viewer-alive-types
320 @vindex mm-keep-viewer-alive-types
321 This is a list of media types for which the external viewer will not
322 be killed when selecting a different article.
324 @item mm-attachment-override-types
325 @vindex mm-attachment-override-types
326 Some @acronym{MIME} agents create parts that have a content-disposition of
327 @samp{attachment}. This variable allows overriding that disposition and
328 displaying the part inline. (Note that the disposition is only
329 overridden if we are able to, and want to, display the part inline.)
331 @item mm-discouraged-alternatives
332 @vindex mm-discouraged-alternatives
333 List of @acronym{MIME} types that are discouraged when viewing
334 @samp{multipart/alternative}. Viewing agents are supposed to view the
335 last possible part of a message, as that is supposed to be the richest.
336 However, users may prefer other types instead, and this list says what
337 types are most unwanted. If, for instance, @samp{text/html} parts are
338 very unwanted, and @samp{text/richtext} parts are somewhat unwanted,
339 you could say something like:
342 (setq mm-discouraged-alternatives
343 '("text/html" "text/richtext")
345 (remove "text/html" mm-automatic-display))
348 Adding @code{"image/.*"} might also be useful. Spammers use images as
349 the preferred part of @samp{multipart/alternative} messages, so you might
350 not notice there are other parts. See also
351 @code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands,
352 gnus, Gnus Manual}. After adding @code{"multipart/alternative"} to
353 @code{gnus-buttonized-mime-types} you can choose manually which
354 alternative you'd like to view. For example, you can set those
358 (setq gnus-buttonized-mime-types
359 '("multipart/alternative" "multipart/signed")
360 mm-discouraged-alternatives
361 '("text/html" "image/.*"))
364 In this case, Gnus will display radio buttons for such a kind of spam
368 1. (*) multipart/alternative ( ) image/gif
370 2. (*) text/plain ( ) text/html
373 @item mm-inline-large-images
374 @vindex mm-inline-large-images
375 When displaying inline images that are larger than the window, Emacs
376 does not enable scrolling, which means that you cannot see the whole
377 image. To prevent this, the library tries to determine the image size
378 before displaying it inline, and if it doesn't fit the window, the
379 library will display it externally (e.g. with @samp{ImageMagick} or
380 @samp{xv}). Setting this variable to @code{t} disables this check and
381 makes the library display all inline images as inline, regardless of
384 @item mm-inline-override-types
385 @vindex mm-inline-override-types
386 @code{mm-inlined-types} may include regular expressions, for example to
387 specify that all @samp{text/.*} parts be displayed inline. If a user
388 prefers to have a type that matches such a regular expression be treated
389 as an attachment, that can be accomplished by setting this variable to a
390 list containing that type. For example assuming @code{mm-inlined-types}
391 includes @samp{text/.*}, then including @samp{text/html} in this
392 variable will cause @samp{text/html} parts to be treated as attachments.
394 @item mm-text-html-renderer
395 @vindex mm-text-html-renderer
396 This selects the function used to render @acronym{HTML}. The predefined
397 renderers are selected by the symbols @code{w3},
398 @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more
399 information about emacs-w3m}, @code{links}, @code{lynx},
400 @code{w3m-standalone} or @code{html2text}. If @code{nil} use an
401 external viewer. You can also specify a function, which will be
402 called with a @acronym{MIME} handle as the argument.
404 @item mm-inline-text-html-with-images
405 @vindex mm-inline-text-html-with-images
406 Some @acronym{HTML} mails might have the trick of spammers using
407 @samp{<img>} tags. It is likely to be intended to verify whether you
408 have read the mail. You can prevent your personal informations from
409 leaking by setting this option to @code{nil} (which is the default).
410 It is currently ignored by Emacs/w3. For emacs-w3m, you may use the
411 command @kbd{t} on the image anchor to show an image even if it is
412 @code{nil}.@footnote{The command @kbd{T} will load all images. If you
413 have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i}
416 @item mm-w3m-safe-url-regexp
417 @vindex mm-w3m-safe-url-regexp
418 A regular expression that matches safe URL names, i.e. URLs that are
419 unlikely to leak personal information when rendering @acronym{HTML}
420 email (the default value is @samp{\\`cid:}). If @code{nil} consider
423 @item mm-inline-text-html-with-w3m-keymap
424 @vindex mm-inline-text-html-with-w3m-keymap
425 You can use emacs-w3m command keys in the inlined text/html part by
426 setting this option to non-@code{nil}. The default value is @code{t}.
428 @item mm-external-terminal-program
429 @vindex mm-external-terminal-program
430 The program used to start an external terminal.
432 @item mm-enable-external
433 @vindex mm-enable-external
434 Indicate whether external @acronym{MIME} handlers should be used.
436 If @code{t}, all defined external @acronym{MIME} handlers are used. If
437 @code{nil}, files are saved to disk (@code{mailcap-save-binary-file}).
438 If it is the symbol @code{ask}, you are prompted before the external
439 @acronym{MIME} handler is invoked.
441 When you launch an attachment through mailcap (@pxref{mailcap}) an
442 attempt is made to use a safe viewer with the safest options---this isn't
443 the case if you save it to disk and launch it in a different way
444 (command line or double-clicking). Anyhow, if you want to be sure not
445 to launch any external programs, set this variable to @code{nil} or
450 @node Files and Directories
451 @section Files and Directories
455 @item mm-default-directory
456 @vindex mm-default-directory
457 The default directory for saving attachments. If @code{nil} use
458 @code{default-directory}.
460 @item mm-tmp-directory
461 @vindex mm-tmp-directory
462 Directory for storing temporary files.
464 @item mm-file-name-rewrite-functions
465 @vindex mm-file-name-rewrite-functions
466 A list of functions used for rewriting file names of @acronym{MIME}
467 parts. Each function is applied successively to the file name.
468 Ready-made functions include
471 @item mm-file-name-delete-control
472 @findex mm-file-name-delete-control
473 Delete all control characters.
475 @item mm-file-name-delete-gotchas
476 @findex mm-file-name-delete-gotchas
477 Delete characters that could have unintended consequences when used
478 with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and
479 @samp{-}, @samp{.} as the first character.
481 @item mm-file-name-delete-whitespace
482 @findex mm-file-name-delete-whitespace
483 Remove all whitespace.
485 @item mm-file-name-trim-whitespace
486 @findex mm-file-name-trim-whitespace