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.
37 * Emacs MIME: (emacs-mime). Emacs MIME de/composition library.
42 @setchapternewpage odd
45 @title Emacs MIME Manual
47 @author by Lars Magne Ingebrigtsen
49 @vskip 0pt plus 1filll
56 This manual documents the libraries used to compose and display
57 @acronym{MIME} messages.
59 This manual is directed at users who want to modify the behavior of
60 the @acronym{MIME} encoding/decoding process or want a more detailed
61 picture of how the Emacs @acronym{MIME} library works, and people who want
62 to write functions and commands that manipulate @acronym{MIME} elements.
64 @acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}.
65 This standard is documented in a number of RFCs; mainly RFC2045 (Format
66 of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
67 Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration
68 Procedures), RFC2049 (Conformance Criteria and Examples). It is highly
69 recommended that anyone who intends writing @acronym{MIME}-compliant software
70 read at least RFC2045 and RFC2047.
73 * Decoding and Viewing:: A framework for decoding and viewing.
74 * Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts.
75 * Interface Functions:: An abstraction over the basic functions.
76 * Basic Functions:: Utility and basic parsing functions.
77 * Standards:: A summary of RFCs and working documents used.
78 * GNU Free Documentation License:: The license for this documentation.
79 * Index:: Function and variable index.
83 @node Decoding and Viewing
84 @chapter Decoding and Viewing
86 This chapter deals with decoding and viewing @acronym{MIME} messages on a
89 The main idea is to first analyze a @acronym{MIME} article, and then allow
90 other programs to do things based on the list of @dfn{handles} that are
91 returned as a result of this analysis.
94 * Dissection:: Analyzing a @acronym{MIME} message.
95 * Non-MIME:: Analyzing a non-@acronym{MIME} message.
96 * Handles:: Handle manipulations.
97 * Display:: Displaying handles.
98 * Display Customization:: Variables that affect display.
99 * Files and Directories:: Saving and naming attachments.
100 * New Viewers:: How to write your own viewers.
107 The @code{mm-dissect-buffer} is the function responsible for dissecting
108 a @acronym{MIME} article. If given a multipart message, it will recursively
109 descend the message, following the structure, and return a tree of
110 @acronym{MIME} handles that describes the structure of the message.
114 @vindex mm-uu-configure-list
116 Gnus also understands some non-@acronym{MIME} attachments, such as
117 postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp,
118 diff. Each of these features can be disabled by add an item into
119 @code{mm-uu-configure-list}. For example,
123 (add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
149 Non-@acronym{MIME} forwarded message.
157 @acronym{PGP} signed clear text.
160 @findex pgp-encrypted
161 @acronym{PGP} encrypted clear text.
165 @acronym{PGP} public keys.
168 @findex emacs-sources
169 @vindex mm-uu-emacs-sources-regexp
170 Emacs source code. This item works only in the groups matching
171 @code{mm-uu-emacs-sources-regexp}.
175 @vindex mm-uu-diff-groups-regexp
176 Patches. This is intended for groups where diffs of committed files
177 are automatically sent to. It only works in groups matching
178 @code{mm-uu-diff-groups-regexp}.
181 @cindex verbatim-marks
182 Slrn-style verbatim marks.
186 LaTeX documents. It only works in groups matching
187 @code{mm-uu-tex-groups-regexp}.
191 @cindex text/x-verbatim
192 @c Is @vindex suitable for a face?
193 @vindex mm-uu-extract
194 Some inlined non-@acronym{MIME} attachments are displayed using the face
195 @code{mm-uu-extract}. By default, no @acronym{MIME} button for these
196 parts is displayed. You can force displaying a button using @kbd{K b}
197 (@code{gnus-summary-display-buttonized}) or add @code{text/x-verbatim}
198 to @code{gnus-buttonized-mime-types}, @xref{MIME Commands, ,MIME
199 Commands, gnus, Gnus Manual}.
204 A @acronym{MIME} handle is a list that fully describes a @acronym{MIME}
207 The following macros can be used to access elements in a handle:
210 @item mm-handle-buffer
211 @findex mm-handle-buffer
212 Return the buffer that holds the contents of the undecoded @acronym{MIME}
216 @findex mm-handle-type
217 Return the parsed @code{Content-Type} of the part.
219 @item mm-handle-encoding
220 @findex mm-handle-encoding
221 Return the @code{Content-Transfer-Encoding} of the part.
223 @item mm-handle-undisplayer
224 @findex mm-handle-undisplayer
225 Return the object that can be used to remove the displayed part (if it
228 @item mm-handle-set-undisplayer
229 @findex mm-handle-set-undisplayer
230 Set the undisplayer object.
232 @item mm-handle-disposition
233 @findex mm-handle-disposition
234 Return the parsed @code{Content-Disposition} of the part.
236 @item mm-get-content-id
237 Returns the handle(s) referred to by @code{Content-ID}.
245 Functions for displaying, removing and saving.
248 @item mm-display-part
249 @findex mm-display-part
253 @findex mm-remove-part
254 Remove the part (if it has been displayed).
257 @findex mm-inlinable-p
258 Say whether a @acronym{MIME} type can be displayed inline.
260 @item mm-automatic-display-p
261 @findex mm-automatic-display-p
262 Say whether a @acronym{MIME} type should be displayed automatically.
264 @item mm-destroy-part
265 @findex mm-destroy-part
266 Free all resources occupied by a part.
270 Offer to save the part in a file.
274 Offer to pipe the part to some process.
276 @item mm-interactively-view-part
277 @findex mm-interactively-view-part
278 Prompt for a mailcap method to use to view the part.
283 @node Display Customization
284 @section Display Customization
288 @item mm-inline-media-tests
289 @vindex mm-inline-media-tests
290 This is an alist where the key is a @acronym{MIME} type, the second element
291 is a function to display the part @dfn{inline} (i.e., inside Emacs), and
292 the third element is a form to be @code{eval}ed to say whether the part
293 can be displayed inline.
295 This variable specifies whether a part @emph{can} be displayed inline,
296 and, if so, how to do it. It does not say whether parts are
297 @emph{actually} displayed inline.
299 @item mm-inlined-types
300 @vindex mm-inlined-types
301 This, on the other hand, says what types are to be displayed inline, if
302 they satisfy the conditions set by the variable above. It's a list of
303 @acronym{MIME} media types.
305 @item mm-automatic-display
306 @vindex mm-automatic-display
307 This is a list of types that are to be displayed ``automatically'', but
308 only if the above variable allows it. That is, only inlinable parts can
309 be displayed automatically.
311 @item mm-automatic-external-display
312 @vindex mm-automatic-external-display
313 This is a list of types that will be displayed automatically in an
316 @item mm-keep-viewer-alive-types
317 @vindex mm-keep-viewer-alive-types
318 This is a list of media types for which the external viewer will not
319 be killed when selecting a different article.
321 @item mm-attachment-override-types
322 @vindex mm-attachment-override-types
323 Some @acronym{MIME} agents create parts that have a content-disposition of
324 @samp{attachment}. This variable allows overriding that disposition and
325 displaying the part inline. (Note that the disposition is only
326 overridden if we are able to, and want to, display the part inline.)
328 @item mm-discouraged-alternatives
329 @vindex mm-discouraged-alternatives
330 List of @acronym{MIME} types that are discouraged when viewing
331 @samp{multipart/alternative}. Viewing agents are supposed to view the
332 last possible part of a message, as that is supposed to be the richest.
333 However, users may prefer other types instead, and this list says what
334 types are most unwanted. If, for instance, @samp{text/html} parts are
335 very unwanted, and @samp{text/richtext} parts are somewhat unwanted,
336 you could say something like:
339 (setq mm-discouraged-alternatives
340 '("text/html" "text/richtext")
342 (remove "text/html" mm-automatic-display))
345 Adding @code{"image/.*"} might also be useful. Spammers use images as
346 the preferred part of @samp{multipart/alternative} messages, so you might
347 not notice there are other parts. See also
348 @code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands,
349 gnus, Gnus Manual}. After adding @code{"multipart/alternative"} to
350 @code{gnus-buttonized-mime-types} you can choose manually which
351 alternative you'd like to view. For example, you can set those
355 (setq gnus-buttonized-mime-types
356 '("multipart/alternative" "multipart/signed")
357 mm-discouraged-alternatives
358 '("text/html" "image/.*"))
361 In this case, Gnus will display radio buttons for such a kind of spam
365 1. (*) multipart/alternative ( ) image/gif
367 2. (*) text/plain ( ) text/html
370 @item mm-inline-large-images
371 @vindex mm-inline-large-images
372 When displaying inline images that are larger than the window, Emacs
373 does not enable scrolling, which means that you cannot see the whole
374 image. To prevent this, the library tries to determine the image size
375 before displaying it inline, and if it doesn't fit the window, the
376 library will display it externally (e.g. with @samp{ImageMagick} or
377 @samp{xv}). Setting this variable to @code{t} disables this check and
378 makes the library display all inline images as inline, regardless of
381 @item mm-inline-override-types
382 @vindex mm-inline-override-types
383 @code{mm-inlined-types} may include regular expressions, for example to
384 specify that all @samp{text/.*} parts be displayed inline. If a user
385 prefers to have a type that matches such a regular expression be treated
386 as an attachment, that can be accomplished by setting this variable to a
387 list containing that type. For example assuming @code{mm-inlined-types}
388 includes @samp{text/.*}, then including @samp{text/html} in this
389 variable will cause @samp{text/html} parts to be treated as attachments.
391 @item mm-text-html-renderer
392 @vindex mm-text-html-renderer
393 This selects the function used to render @acronym{HTML}. The predefined
394 renderers are selected by the symbols @code{w3},
395 @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more
396 information about emacs-w3m}, @code{links}, @code{lynx},
397 @code{w3m-standalone} or @code{html2text}. If @code{nil} use an
398 external viewer. You can also specify a function, which will be
399 called with a @acronym{MIME} handle as the argument.
401 @item mm-inline-text-html-with-images
402 @vindex mm-inline-text-html-with-images
403 Some @acronym{HTML} mails might have the trick of spammers using
404 @samp{<img>} tags. It is likely to be intended to verify whether you
405 have read the mail. You can prevent your personal informations from
406 leaking by setting this option to @code{nil} (which is the default).
407 It is currently ignored by Emacs/w3. For emacs-w3m, you may use the
408 command @kbd{t} on the image anchor to show an image even if it is
409 @code{nil}.@footnote{The command @kbd{T} will load all images. If you
410 have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i}
413 @item mm-w3m-safe-url-regexp
414 @vindex mm-w3m-safe-url-regexp
415 A regular expression that matches safe URL names, i.e. URLs that are
416 unlikely to leak personal information when rendering @acronym{HTML}
417 email (the default value is @samp{\\`cid:}). If @code{nil} consider
420 @item mm-inline-text-html-with-w3m-keymap
421 @vindex mm-inline-text-html-with-w3m-keymap
422 You can use emacs-w3m command keys in the inlined text/html part by
423 setting this option to non-@code{nil}. The default value is @code{t}.
425 @item mm-external-terminal-program
426 @vindex mm-external-terminal-program
427 The program used to start an external terminal.
429 @item mm-enable-external
430 @vindex mm-enable-external
431 Indicate whether external @acronym{MIME} handlers should be used.
433 If @code{t}, all defined external @acronym{MIME} handlers are used. If
434 @code{nil}, files are saved to disk (@code{mailcap-save-binary-file}).
435 If it is the symbol @code{ask}, you are prompted before the external
436 @acronym{MIME} handler is invoked.
438 When you launch an attachment through mailcap (@pxref{mailcap}) an
439 attempt is made to use a safe viewer with the safest options---this isn't
440 the case if you save it to disk and launch it in a different way
441 (command line or double-clicking). Anyhow, if you want to be sure not
442 to launch any external programs, set this variable to @code{nil} or
447 @node Files and Directories
448 @section Files and Directories
452 @item mm-default-directory
453 @vindex mm-default-directory
454 The default directory for saving attachments. If @code{nil} use
455 @code{default-directory}.
457 @item mm-tmp-directory
458 @vindex mm-tmp-directory
459 Directory for storing temporary files.
461 @item mm-file-name-rewrite-functions
462 @vindex mm-file-name-rewrite-functions
463 A list of functions used for rewriting file names of @acronym{MIME}
464 parts. Each function is applied successively to the file name.
465 Ready-made functions include
468 @item mm-file-name-delete-control
469 @findex mm-file-name-delete-control
470 Delete all control characters.
472 @item mm-file-name-delete-gotchas
473 @findex mm-file-name-delete-gotchas
474 Delete characters that could have unintended consequences when used
475 with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and
476 @samp{-}, @samp{.} as the first character.
478 @item mm-file-name-delete-whitespace
479 @findex mm-file-name-delete-whitespace
480 Remove all whitespace.
482 @item mm-file-name-trim-whitespace
483 @findex mm-file-name-trim-whitespace
484 Remove leading and trailing whitespace.
486 @item mm-file-name-collapse-whitespace
487 @findex mm-file-name-collapse-whitespace
488 Collapse multiple whitespace characters.
490 @item mm-file-name-replace-whitespace
491 @findex mm-file-name-replace-whitespace
492 @vindex mm-file-name-replace-whitespace
493 Replace whitespace with underscores. Set the variable
494 @code{mm-file-name-replace-whitespace} to any other string if you do
495 not like underscores.
498 The standard Emacs functions @code{capitalize}, @code{downcase},
499 @code{upcase} and @code{upcase-initials} might also prove useful.
501 @item mm-path-name-rewrite-functions
502 @vindex mm-path-name-rewrite-functions
503 List of functions used for rewriting the full file names of @acronym{MIME}
504 parts. This is used when viewing parts externally, and is meant for
505 transforming the absolute name so that non-compliant programs can find
506 the file where it's saved.
513 Here's an example viewer for displaying @code{text/enriched} inline:
516 (defun mm-display-enriched-inline (handle)
519 (mm-insert-part handle)
520 (save-window-excursion
521 (enriched-decode (point-min) (point-max))
522 (setq text (buffer-string))))
523 (mm-insert-inline handle text)))
526 We see that the function takes a @acronym{MIME} handle as its parameter. It
527 then goes to a temporary buffer, inserts the text of the part, does some
528 work on the text, stores the result, goes back to the buffer it was
529 called from and inserts the result.
531 The two important helper functions here are @code{mm-insert-part} and
532 @code{mm-insert-inline}. The first function inserts the text of the
533 handle in the current buffer. It handles charset and/or content
534 transfer decoding. The second function just inserts whatever text you
535 tell it to insert, but it also sets things up so that the text can be
536 ``undisplayed'' in a convenient manner.
542 @cindex MIME Composing
544 @cindex MIME Meta Language
546 Creating a @acronym{MIME} message is boring and non-trivial. Therefore,
547 a library called @code{mml} has been defined that parses a language
548 called @acronym{MML} (@acronym{MIME} Meta Language) and generates
549 @acronym{MIME} messages.
551 @findex mml-generate-mime
552 The main interface function is @code{mml-generate-mime}. It will
553 examine the contents of the current (narrowed-to) buffer and return a
554 string containing the @acronym{MIME} message.
557 * Simple MML Example:: An example @acronym{MML} document.
558 * MML Definition:: All valid @acronym{MML} elements.
559 * Advanced MML Example:: Another example @acronym{MML} document.
560 * Encoding Customization:: Variables that affect encoding.
561 * Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}.
562 * Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa.
563 * Flowed text:: Soft and hard newlines.
567 @node Simple MML Example
568 @section Simple MML Example
570 Here's a simple @samp{multipart/alternative}:
573 <#multipart type=alternative>
574 This is a plain text part.
575 <#part type=text/enriched>
576 <center>This is a centered enriched part</center>
580 After running this through @code{mml-generate-mime}, we get this:
583 Content-Type: multipart/alternative; boundary="=-=-="
589 This is a plain text part.
592 Content-Type: text/enriched
595 <center>This is a centered enriched part</center>
602 @section MML Definition
604 The @acronym{MML} language is very simple. It looks a bit like an SGML
605 application, but it's not.
607 The main concept of @acronym{MML} is the @dfn{part}. Each part can be of a
608 different type or use a different charset. The way to delineate a part
609 is with a @samp{<#part ...>} tag. Multipart parts can be introduced
610 with the @samp{<#multipart ...>} tag. Parts are ended by the
611 @samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the
612 @samp{<#part ...>} tags are also closed by the next open tag.
614 There's also the @samp{<#external ...>} tag. These introduce
615 @samp{external/message-body} parts.
617 Each tag can contain zero or more parameters on the form
618 @samp{parameter=value}. The values may be enclosed in quotation marks,
619 but that's not necessary unless the value contains white space. So
620 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
622 The following parameters have meaning in @acronym{MML}; parameters that have no
623 meaning are ignored. The @acronym{MML} parameter names are the same as the
624 @acronym{MIME} parameter names; the things in the parentheses say which
625 header it will be used in.
629 The @acronym{MIME} type of the part (@code{Content-Type}).
632 Use the contents of the file in the body of the part
633 (@code{Content-Disposition}).
636 The contents of the body of the part are to be encoded in the character
637 set specified (@code{Content-Type}). @xref{Charset Translation}.
640 Might be used to suggest a file name if the part is to be saved
641 to a file (@code{Content-Type}).
644 Valid values are @samp{inline} and @samp{attachment}
645 (@code{Content-Disposition}).