3 @setfilename emacs-mime
4 @settitle Emacs MIME Manual
10 * Emacs MIME: (emacs-mime). The MIME de/composition library.
15 @setchapternewpage odd
19 This file documents the Emacs MIME interface functionality.
21 Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
23 Permission is granted to copy, distribute and/or modify this document
24 under the terms of the GNU Free Documentation License, Version 1.1 or
25 any later version published by the Free Software Foundation; with no
26 Invariant Sections, with the Front-Cover texts being ``A GNU
27 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
28 license is included in the section entitled ``GNU Free Documentation
29 License'' in the Emacs manual.
31 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
32 this GNU Manual, like GNU software. Copies published by the Free
33 Software Foundation raise funds for GNU development.''
35 This document is part of a collection distributed under the GNU Free
36 Documentation License. If you want to distribute this document
37 separately from the collection, you can do so by adding a copy of the
38 license to the document, as described in section 6 of the license.
44 @title Emacs MIME Manual
46 @author by Lars Magne Ingebrigtsen
49 @vskip 0pt plus 1filll
50 Copyright @copyright{} 1998, 1999, 2000 Free Software Foundation, Inc.
52 Permission is granted to copy, distribute and/or modify this document
53 under the terms of the GNU Free Documentation License, Version 1.1 or
54 any later version published by the Free Software Foundation; with the
55 Invariant Sections being none, with the Front-Cover texts being ``A GNU
56 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
57 license is included in the section entitled ``GNU Free Documentation
58 License'' in the Emacs manual.
60 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
61 this GNU Manual, like GNU software. Copies published by the Free
62 Software Foundation raise funds for GNU development.''
64 This document is part of a collection distributed under the GNU Free
65 Documentation License. If you want to distribute this document
66 separately from the collection, you can do so by adding a copy of the
67 license to the document, as described in section 6 of the license.
76 This manual documents the libraries used to compose and display
79 This is not a manual meant for users; it's a manual directed at people
80 who want to write functions and commands that manipulate @sc{mime}
83 @sc{mime} is short for @dfn{Multipurpose Internet Mail Extensions}.
84 This standard is documented in a number of RFCs; mainly RFC2045 (Format
85 of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
86 Header Extensions for Non-ASCII Text), RFC2048 (Registration
87 Procedures), RFC2049 (Conformance Criteria and Examples). It is highly
88 recommended that anyone who intends writing @sc{mime}-compliant software
89 read at least RFC2045 and RFC2047.
92 * Interface Functions:: An abstraction over the basic functions.
93 * Basic Functions:: Utility and basic parsing functions.
94 * Decoding and Viewing:: A framework for decoding and viewing.
95 * Composing:: MML; a language for describing MIME parts.
96 * Standards:: A summary of RFCs and working documents used.
97 * Index:: Function and variable index.
101 @node Interface Functions
102 @chapter Interface Functions
103 @cindex interface functions
106 The @code{mail-parse} library is an abstraction over the actual
107 low-level libraries that are described in the next chapter.
109 Standards change, and so programs have to change to fit in the new
110 mold. For instance, RFC2045 describes a syntax for the
111 @code{Content-Type} header that only allows ASCII characters in the
112 parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme
113 for continuation headers and non-ASCII characters.
115 The traditional way to deal with this is just to update the library
116 functions to parse the new syntax. However, this is sometimes the wrong
117 thing to do. In some instances it may be vital to be able to understand
118 both the old syntax as well as the new syntax, and if there is only one
119 library, one must choose between the old version of the library and the
120 new version of the library.
122 The Emacs MIME library takes a different tack. It defines a series of
123 low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} and so on)
124 that parses strictly according to the corresponding standard. However,
125 normal programs would not use the functions provided by these libraries
126 directly, but instead use the functions provided by the
127 @code{mail-parse} library. The functions in this library are just
128 aliases to the corresponding functions in the latest low-level
129 libraries. Using this scheme, programs get a consistent interface they
130 can use, and library developers are free to create write code that
131 handles new standards.
133 The following functions are defined by this library:
136 @item mail-header-parse-content-type
137 @findex mail-header-parse-content-type
138 Parse a @code{Content-Type} header and return a list on the following
143 (attribute1 . value1)
144 (attribute2 . value2)
151 (mail-header-parse-content-type
152 "image/gif; name=\"b980912.gif\"")
153 @result{} ("image/gif" (name . "b980912.gif"))
156 @item mail-header-parse-content-disposition
157 @findex mail-header-parse-content-disposition
158 Parse a @code{Content-Disposition} header and return a list on the same
159 format as the function above.
161 @item mail-content-type-get
162 @findex mail-content-type-get
163 Takes two parameters---a list on the format above, and an attribute.
164 Returns the value of the attribute.
167 (mail-content-type-get
168 '("image/gif" (name . "b980912.gif")) 'name)
169 @result{} "b980912.gif"
172 @item mail-header-encode-parameter
173 @findex mail-header-encode-parameter
174 Takes a parameter string and returns an encoded version of the string.
175 This is used for parameters in headers like @code{Content-Type} and
176 @code{Content-Disposition}.
178 @item mail-header-remove-comments
179 @findex mail-header-remove-comments
180 Return a comment-free version of a header.
183 (mail-header-remove-comments
184 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
185 @result{} "Gnus/5.070027 "
188 @item mail-header-remove-whitespace
189 @findex mail-header-remove-whitespace
190 Remove linear white space from a header. Space inside quoted strings
191 and comments is preserved.
194 (mail-header-remove-whitespace
195 "image/gif; name=\"Name with spaces\"")
196 @result{} "image/gif;name=\"Name with spaces\""
199 @item mail-header-get-comment
200 @findex mail-header-get-comment
201 Return the last comment in a header.
204 (mail-header-get-comment
205 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
206 @result{} "Finnish Landrace"
209 @item mail-header-parse-address
210 @findex mail-header-parse-address
211 Parse an address and return a list containing the mailbox and the
215 (mail-header-parse-address
216 "Hrvoje Niksic <hniksic@@srce.hr>")
217 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
220 @item mail-header-parse-addresses
221 @findex mail-header-parse-addresses
222 Parse a string with list of addresses and return a list of elements like
223 the one described above.
226 (mail-header-parse-addresses
227 "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
228 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
229 ("sb@@metis.no" . "Steinar Bang"))
232 @item mail-header-parse-date
233 @findex mail-header-parse-date
234 Parse a date string and return an Emacs time structure.
236 @item mail-narrow-to-head
237 @findex mail-narrow-to-head
238 Narrow the buffer to the header section of the buffer. Point is placed
239 at the beginning of the narrowed buffer.
241 @item mail-header-narrow-to-field
242 @findex mail-header-narrow-to-field
243 Narrow the buffer to the header under point. Understands continuation
246 @item mail-header-fold-field
247 @findex mail-header-fold-field
248 Fold the header under point.
250 @item mail-header-unfold-field
251 @findex mail-header-unfold-field
252 Unfold the header under point.
254 @item mail-header-field-value
255 @findex mail-header-field-value
256 Return the value of the field under point.
258 @item mail-encode-encoded-word-region
259 @findex mail-encode-encoded-word-region
260 Encode the non-ASCII words in the region. For instance,
261 @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
263 @item mail-encode-encoded-word-buffer
264 @findex mail-encode-encoded-word-buffer
265 Encode the non-ASCII words in the current buffer. This function is
266 meant to be called narrowed to the headers of a message.
268 @item mail-encode-encoded-word-string
269 @findex mail-encode-encoded-word-string
270 Encode the words that need encoding in a string, and return the result.
273 (mail-encode-encoded-word-string
274 "This is naïve, baby")
275 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
278 @item mail-decode-encoded-word-region
279 @findex mail-decode-encoded-word-region
280 Decode the encoded words in the region.
282 @item mail-decode-encoded-word-string
283 @findex mail-decode-encoded-word-string
284 Decode the encoded words in the string and return the result.
287 (mail-decode-encoded-word-string
288 "This is =?iso-8859-1?q?na=EFve,?= baby")
289 @result{} "This is naïve, baby"
294 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
295 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented
296 in the subsequent sections.
300 @node Basic Functions
301 @chapter Basic Functions
303 This chapter describes the basic, ground-level functions for parsing and
304 handling. Covered here is parsing @code{From} lines, removing comments
305 from header lines, decoding encoded words, parsing date headers and so
306 on. High-level functionality is dealt with in the next chapter
307 (@pxref{Decoding and Viewing}).
310 * rfc2045:: Encoding @code{Content-Type} headers.
311 * rfc2231:: Parsing @code{Content-Type} headers.
312 * ietf-drums:: Handling mail headers defined by RFC822bis.
313 * rfc2047:: En/decoding encoded words in headers.
314 * time-date:: Functions for parsing dates and manipulating time.
315 * qp:: Quoted-Printable en/decoding.
316 * base64:: Base64 en/decoding.
317 * binhex:: Binhex decoding.
318 * uudecode:: Uuencode decoding.
319 * rfc1843:: Decoding HZ-encoded text.
320 * mailcap:: How parts are displayed is specified by the @file{.mailcap} file
327 RFC2045 is the ``main'' @sc{mime} document, and as such, one would
328 imagine that there would be a lot to implement. But there isn't, since
329 most of the implementation details are delegated to the subsequent
332 So @file{rfc2045.el} has only a single function:
335 @item rfc2045-encode-string
336 @findex rfc2045-encode-string
337 Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
338 @var{value} will be quoted if there are non-safe characters in it.
345 RFC2231 defines a syntax for the @code{Content-Type} and
346 @code{Content-Disposition} headers. Its snappy name is @dfn{MIME
347 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
350 In short, these headers look something like this:
353 Content-Type: application/x-stuff;
354 title*0*=us-ascii'en'This%20is%20even%20more%20;
355 title*1*=%2A%2A%2Afun%2A%2A%2A%20;
359 They usually aren't this bad, though.
361 The following functions are defined by this library:
364 @item rfc2231-parse-string
365 @findex rfc2231-parse-string
366 Parse a @code{Content-Type} header and return a list describing its
370 (rfc2231-parse-string
371 "application/x-stuff;
372 title*0*=us-ascii'en'This%20is%20even%20more%20;
373 title*1*=%2A%2A%2Afun%2A%2A%2A%20;
374 title*2=\"isn't it!\"")
375 @result{} ("application/x-stuff"
376 (title . "This is even more ***fun*** isn't it!"))
379 @item rfc2231-get-value
380 @findex rfc2231-get-value
381 Takes one of the lists on the format above and returns
382 the value of the specified attribute.
384 @item rfc2231-encode-string
385 @findex rfc2231-encode-string
386 Encode a parameter in headers likes @code{Content-Type} and
387 @code{Content-Disposition}.
395 @dfn{drums} is an IETF working group that is working on the replacement
398 The functions provided by this library include:
401 @item ietf-drums-remove-comments
402 @findex ietf-drums-remove-comments
403 Remove the comments from the argument and return the results.
405 @item ietf-drums-remove-whitespace
406 @findex ietf-drums-remove-whitespace
407 Remove linear white space from the string and return the results.
408 Spaces inside quoted strings and comments are left untouched.
410 @item ietf-drums-get-comment
411 @findex ietf-drums-get-comment
412 Return the last most comment from the string.
414 @item ietf-drums-parse-address
415 @findex ietf-drums-parse-address
416 Parse an address string and return a list that contains the mailbox and
419 @item ietf-drums-parse-addresses
420 @findex ietf-drums-parse-addresses
421 Parse a string that contains any number of comma-separated addresses and
422 return a list that contains mailbox/plain text pairs.
424 @item ietf-drums-parse-date
425 @findex ietf-drums-parse-date
426 Parse a date string and return an Emacs time structure.
428 @item ietf-drums-narrow-to-header
429 @findex ietf-drums-narrow-to-header
430 Narrow the buffer to the header section of the current buffer.
438 RFC2047 (Message Header Extensions for Non-ASCII Text) specifies how
439 non-ASCII text in headers are to be encoded. This is actually rather
440 complicated, so a number of variables are necessary to tweak what this
443 The following variables are tweakable:
446 @item rfc2047-default-charset
447 @vindex rfc2047-default-charset
448 Characters in this charset should not be decoded by this library.
449 This defaults to @code{iso-8859-1}.
451 @item rfc2047-header-encoding-list
452 @vindex rfc2047-header-encoding-list
453 This is an alist of header / encoding-type pairs. Its main purpose is
454 to prevent encoding of certain headers.
456 The keys can either be header regexps, or @code{t}.
458 The values can be either @code{nil}, in which case the header(s) in
459 question won't be encoded, or @code{mime}, which means that they will be
462 @item rfc2047-charset-encoding-alist
463 @vindex rfc2047-charset-encoding-alist
464 RFC2047 specifies two forms of encoding---@code{Q} (a
465 Quoted-Printable-like encoding) and @code{B} (base64). This alist
466 specifies which charset should use which encoding.
468 @item rfc2047-encoding-function-alist
469 @vindex rfc2047-encoding-function-alist
470 This is an alist of encoding / function pairs. The encodings are
471 @code{Q}, @code{B} and @code{nil}.
473 @item rfc2047-q-encoding-alist
474 @vindex rfc2047-q-encoding-alist
475 The @code{Q} encoding isn't quite the same for all headers. Some
476 headers allow a narrower range of characters, and that is what this
477 variable is for. It's an alist of header regexps / allowable character
480 @item rfc2047-encoded-word-regexp
481 @vindex rfc2047-encoded-word-regexp
482 When decoding words, this library looks for matches to this regexp.
486 Those were the variables, and these are this functions:
489 @item rfc2047-narrow-to-field
490 @findex rfc2047-narrow-to-field
491 Narrow the buffer to the header on the current line.
493 @item rfc2047-encode-message-header
494 @findex rfc2047-encode-message-header
495 Should be called narrowed to the header of a message. Encodes according
496 to @code{rfc2047-header-encoding-alist}.
498 @item rfc2047-encode-region
499 @findex rfc2047-encode-region
500 Encodes all encodable words in the region specified.
502 @item rfc2047-encode-string
503 @findex rfc2047-encode-string
504 Encode a string and return the results.
506 @item rfc2047-decode-region
507 @findex rfc2047-decode-region
508 Decode the encoded words in the region.
510 @item rfc2047-decode-string
511 @findex rfc2047-decode-string
512 Decode a string and return the results.
520 While not really a part of the @sc{mime} library, it is convenient to
521 document this library here. It deals with parsing @code{Date} headers
522 and manipulating time. (Not by using tesseracts, though, I'm sorry to
525 These functions convert between five formats: A date string, an Emacs
526 time structure, a decoded time list, a second number, and a day number.
528 Here's a bunch of time/date/second/day examples:
531 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
532 @result{} (54 21 12 12 9 1998 6 nil 7200)
534 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
535 @result{} (13818 19266)
537 (time-to-seconds '(13818 19266))
538 @result{} 905595714.0
540 (seconds-to-time 905595714.0)
541 @result{} (13818 19266 0)
543 (time-to-days '(13818 19266))
546 (days-to-time 729644)
547 @result{} (961933 65536)
549 (time-since '(13818 19266))
552 (time-less-p '(13818 19266) '(13818 19145))
555 (subtract-time '(13818 19266) '(13818 19145))
558 (days-between "Sat Sep 12 12:21:54 1998 +0200"
559 "Sat Sep 07 12:21:54 1998 +0200")
562 (date-leap-year-p 2000)
565 (time-to-day-in-year '(13818 19266))
568 (time-to-number-of-days
570 (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
571 @result{} 4.146122685185185
574 And finally, we have @code{safe-date-to-time}, which does the same as
575 @code{date-to-time}, but returns a zero time if the date is
576 syntactically malformed.
578 The five data representations used are the following:
582 An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12
583 12:21:54 1998 +0200"}.
586 An internal Emacs time. For instance: @code{(13818 26466)}.
589 A floating point representation of the internal Emacs time. For
590 instance: @code{905595714.0}.
593 An integer number representing the number of days since 00000101. For
594 instance: @code{729644}.
597 A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t
601 All the examples above represent the same moment.
603 These are the functions available:
607 Take a date and return a time.
609 @item time-to-seconds
610 Take a time and return seconds.
612 @item seconds-to-time
613 Take seconds and return a time.
616 Take a time and return days.
619 Take days and return a time.
622 Take a date and return days.
624 @item time-to-number-of-days
625 Take a time and return the number of days that represents.
627 @item safe-date-to-time
628 Take a date and return a time. If the date is not syntactically valid,
629 return a "zero" date.
632 Take two times and say whether the first time is less (i. e., earlier)
633 than the second time.
636 Take a time and return a time saying how long it was since that time.
639 Take two times and subtract the second from the first. I. e., return
640 the time between the two times.
643 Take two days and return the number of days between those two days.
645 @item date-leap-year-p
646 Take a year number and say whether it's a leap year.
648 @item time-to-day-in-year
649 Take a time and return the day number within the year that the time is
658 This library deals with decoding and encoding Quoted-Printable text.
660 Very briefly explained, qp encoding means translating all 8-bit
661 characters (and lots of control characters) into things that look like
662 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
665 The following functions are defined by the library:
668 @item quoted-printable-decode-region
669 @findex quoted-printable-decode-region
670 QP-decode all the encoded text in the specified region.
672 @item quoted-printable-decode-string
673 @findex quoted-printable-decode-string
674 Decode the QP-encoded text in a string and return the results.
676 @item quoted-printable-encode-region
677 @findex quoted-printable-encode-region
678 QP-encode all the encodable characters in the specified region. The third
679 optional parameter @var{fold} specifies whether to fold long lines.
680 (Long here means 72.)
682 @item quoted-printable-encode-string
683 @findex quoted-printable-encode-string
684 QP-encode all the encodable characters in a string and return the
694 Base64 is an encoding that encodes three bytes into four characters,
695 thereby increasing the size by about 33%. The alphabet used for
696 encoding is very resistant to mangling during transit.
698 The following functions are defined by this library:
701 @item base64-encode-region
702 @findex base64-encode-region
703 base64 encode the selected region. Return the length of the encoded
704 text. Optional third argument @var{no-line-break} means do not break
705 long lines into shorter lines.
707 @item base64-encode-string
708 @findex base64-encode-string
709 base64 encode a string and return the result.
711 @item base64-decode-region
712 @findex base64-decode-region
713 base64 decode the selected region. Return the length of the decoded
714 text. If the region can't be decoded, return @code{nil} and don't
717 @item base64-decode-string
718 @findex base64-decode-string
719 base64 decode a string and return the result. If the string can't be
720 decoded, @code{nil} is returned.
731 @code{binhex} is an encoding that originated in Macintosh environments.
732 The following function is supplied to deal with these:
735 @item binhex-decode-region
736 @findex binhex-decode-region
737 Decode the encoded text in the region. If given a third parameter, only
738 decode the @code{binhex} header and return the filename.
748 @code{uuencode} is probably still the most popular encoding of binaries
749 used on Usenet, although @code{base64} rules the mail world.
751 The following function is supplied by this package:
754 @item uudecode-decode-region
755 @findex uudecode-decode-region
756 Decode the text in the region.
766 RFC1843 deals with mixing Chinese and ASCII characters in messages. In
767 essence, RFC1843 switches between ASCII and Chinese by doing this:
770 This sentence is in ASCII.
771 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
774 Simple enough, and widely used in China.
776 The following functions are available to handle this encoding:
779 @item rfc1843-decode-region
780 Decode HZ-encoded text in the region.
782 @item rfc1843-decode-string
783 Decode a HZ-encoded string and return the result.
791 The @file{~/.mailcap} file is parsed by most @sc{mime}-aware message
792 handlers and describes how elements are supposed to be displayed.
793 Here's an example file:
797 audio/wav; wavplayer %s
800 This says that all image files should be displayed with @code{gimp}, and
801 that WAVE audio files should be played by @code{wavplayer}.
803 The @code{mailcap} library parses this file, and provides functions for
807 @item mailcap-mime-data
808 @vindex mailcap-mime-data
809 This variable is an alist of alists containing backup viewing rules.
816 @item mailcap-parse-mailcaps
817 @findex mailcap-parse-mailcaps
818 Parse the @code{~/.mailcap} file.
820 @item mailcap-mime-info
821 Takes a @sc{mime} type as its argument and returns the matching viewer.
828 @node Decoding and Viewing
829 @chapter Decoding and Viewing
831 This chapter deals with decoding and viewing @sc{mime} messages on a
834 The main idea is to first analyze a @sc{mime} article, and then allow
835 other programs to do things based on the list of @dfn{handles} that are
836 returned as a result of this analysis.
839 * Dissection:: Analyzing a @sc{mime} message.
840 * Non-MIME:: Analyzing a non-@sc{mime} message.
841 * Handles:: Handle manipulations.
842 * Display:: Displaying handles.
843 * Customization:: Variables that affect display.
844 * New Viewers:: How to write your own viewers.
851 The @code{mm-dissect-buffer} is the function responsible for dissecting
852 a @sc{mime} article. If given a multipart message, it will recursively
853 descend the message, following the structure, and return a tree of
854 @sc{mime} handles that describes the structure of the message.
859 Gnus also understands some non-MIME attachments, such as postscript,
860 uuencode, binhex, shar, forward, gnatsweb, pgp. Each of these features
861 can be disabled by add an item into @code{mm-uu-configure-list}.
866 (add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
888 Non-@sc{mime} forwarded message.
896 PGP signed clear text.
899 @findex pgp-encrypted
900 PGP encrypted clear text.
907 @findex emacs-sources
908 Emacs source code. This item works only in the groups matching
909 @code{mm-uu-emacs-sources-regexp}.
916 A @sc{mime} handle is a list that fully describes a @sc{mime}
919 The following macros can be used to access elements in a handle:
922 @item mm-handle-buffer
923 @findex mm-handle-buffer
924 Return the buffer that holds the contents of the undecoded @sc{mime}
928 @findex mm-handle-type
929 Return the parsed @code{Content-Type} of the part.
931 @item mm-handle-encoding
932 @findex mm-handle-encoding
933 Return the @code{Content-Transfer-Encoding} of the part.
935 @item mm-handle-undisplayer
936 @findex mm-handle-undisplayer
937 Return the object that can be used to remove the displayed part (if it
940 @item mm-handle-set-undisplayer
941 @findex mm-handle-set-undisplayer
942 Set the undisplayer object.
944 @item mm-handle-disposition
945 @findex mm-handle-disposition
946 Return the parsed @code{Content-Disposition} of the part.
948 @item mm-handle-disposition
949 @findex mm-handle-disposition
950 Return the description of the part.
952 @item mm-get-content-id
953 Returns the handle(s) referred to by @code{Content-ID}.
961 Functions for displaying, removing and saving.
964 @item mm-display-part
965 @findex mm-display-part
969 @findex mm-remove-part
970 Remove the part (if it has been displayed).
973 @findex mm-inlinable-p
974 Say whether a @sc{mime} type can be displayed inline.
976 @item mm-automatic-display-p
977 @findex mm-automatic-display-p
978 Say whether a @sc{mime} type should be displayed automatically.
980 @item mm-destroy-part
981 @findex mm-destroy-part
982 Free all resources occupied by a part.
986 Offer to save the part in a file.
990 Offer to pipe the part to some process.
992 @item mm-interactively-view-part
993 @findex mm-interactively-view-part
994 Prompt for a mailcap method to use to view the part.
1000 @section Customization
1004 @item mm-inline-media-tests
1005 This is an alist where the key is a @sc{mime} type, the second element
1006 is a function to display the part @dfn{inline} (i.e., inside Emacs), and
1007 the third element is a form to be @code{eval}ed to say whether the part
1008 can be displayed inline.
1010 This variable specifies whether a part @emph{can} be displayed inline,
1011 and, if so, how to do it. It does not say whether parts are
1012 @emph{actually} displayed inline.
1014 @item mm-inlined-types
1015 This, on the other hand, says what types are to be displayed inline, if
1016 they satisfy the conditions set by the variable above. It's a list of
1017 @sc{mime} media types.
1019 @item mm-automatic-display
1020 This is a list of types that are to be displayed ``automatically'', but
1021 only if the above variable allows it. That is, only inlinable parts can
1022 be displayed automatically.
1024 @item mm-attachment-override-types
1025 Some @sc{mime} agents create parts that have a content-disposition of
1026 @samp{attachment}. This variable allows overriding that disposition and
1027 displaying the part inline. (Note that the disposition is only
1028 overridden if we are able to, and want to, display the part inline.)
1030 @item mm-discouraged-alternatives
1031 List of @sc{mime} types that are discouraged when viewing
1032 @samp{multipart/alternative}. Viewing agents are supposed to view the
1033 last possible part of a message, as that is supposed to be the richest.
1034 However, users may prefer other types instead, and this list says what
1035 types are most unwanted. If, for instance, @samp{text/html} parts are
1036 very unwanted, and @samp{text/richtech} parts are somewhat unwanted,
1037 you could say something like:
1040 (setq mm-discouraged-alternatives
1041 '("text/html" "text/richtext")
1042 mm-automatic-display
1043 (remove "text/html" mm-automatic-display))
1046 @item mm-inline-large-images-p
1047 When displaying inline images that are larger than the window, XEmacs
1048 does not enable scrolling, which means that you cannot see the whole
1049 image. To prevent this, the library tries to determine the image size
1050 before displaying it inline, and if it doesn't fit the window, the
1051 library will display it externally (e.g. with @samp{ImageMagick} or
1052 @samp{xv}). Setting this variable to @code{t} disables this check and
1053 makes the library display all inline images as inline, regardless of
1056 @item mm-inline-override-type
1057 @code{mm-inlined-types} may include regular expressions, for example to
1058 specify that all @samp{text/.*} parts be displayed inline. If a user
1059 prefers to have a type that matches such a regular expression be treated
1060 as an attachment, that can be accomplished by setting this variable to a
1061 list containing that type. For example assuming @code{mm-inlined-types}
1062 includes @samp{text/.*}, then including @samp{text/html} in this
1063 variable will cause @samp{text/html} parts to be treated as attachments.
1065 @item mm-inline-text-html-renderer
1066 @findex mm-inline-text-html-render-with-w3
1067 @findex mm-inline-text-html-render-with-w3m
1068 This function will be used to convert the HTML to the text. There are
1069 two pre-defined functions: @code{mm-inline-text-html-render-with-w3},
1070 which uses Emacs/w3; and @code{mm-inline-text-html-render-with-w3m},
1071 which uses emacs-w3m (see @uref{http://emacs-w3m.namazu.org/} for more
1072 information about emacs-w3m). The function will be called with a MIME
1073 handle as the argument.
1075 @item mm-inline-text-html-with-images
1076 Some HTML mails might have the trick of spammers using @samp{<img>} tags.
1077 It is likely to be intended to verify whether you have read the mail.
1078 You can prevent your personal informations from leaking by setting this
1079 option to @code{nil} (which is the default). It is currently ignored by
1080 Emacs/w3. For emacs-w3m, you may use the command @kbd{t} on the image
1081 anchor to show an image (or @kbd{T} for loading all images) even if it
1084 @item mm-inline-text-html-with-w3m-keymap
1085 You can use emacs-w3m command keys in the inlined text/html part by
1086 setting this option to non-@code{nil}. The default value is @code{t}.
1092 @section New Viewers
1094 Here's an example viewer for displaying @code{text/enriched} inline:
1097 (defun mm-display-enriched-inline (handle)
1100 (mm-insert-part handle)
1101 (save-window-excursion
1102 (enriched-decode (point-min) (point-max))
1103 (setq text (buffer-string))))
1104 (mm-insert-inline handle text)))
1107 We see that the function takes a @sc{mime} handle as its parameter. It
1108 then goes to a temporary buffer, inserts the text of the part, does some
1109 work on the text, stores the result, goes back to the buffer it was
1110 called from and inserts the result.
1112 The two important helper functions here are @code{mm-insert-part} and
1113 @code{mm-insert-inline}. The first function inserts the text of the
1114 handle in the current buffer. It handles charset and/or content
1115 transfer decoding. The second function just inserts whatever text you
1116 tell it to insert, but it also sets things up so that the text can be
1117 ``undisplayed' in a convenient manner.
1123 @cindex MIME Composing
1125 @cindex MIME Meta Language
1127 Creating a @sc{mime} message is boring and non-trivial. Therefore, a
1128 library called @code{mml} has been defined that parses a language called
1129 MML (@sc{mime} Meta Language) and generates @sc{mime} messages.
1131 @findex mml-generate-mime
1132 The main interface function is @code{mml-generate-mime}. It will
1133 examine the contents of the current (narrowed-to) buffer and return a
1134 string containing the @sc{mime} message.
1137 * Simple MML Example:: An example MML document.
1138 * MML Definition:: All valid MML elements.
1139 * Advanced MML Example:: Another example MML document.
1140 * Charset Translation:: How charsets are mapped from @sc{mule} to MIME.
1141 * Conversion:: Going from @sc{mime} to MML and vice versa.
1142 * Flowed text:: Soft and hard newlines.
1146 @node Simple MML Example
1147 @section Simple MML Example
1149 Here's a simple @samp{multipart/alternative}:
1152 <#multipart type=alternative>
1153 This is a plain text part.
1154 <#part type=text/enriched>
1155 <center>This is a centered enriched part</center>
1159 After running this through @code{mml-generate-mime}, we get this:
1162 Content-Type: multipart/alternative; boundary="=-=-="
1168 This is a plain text part.
1171 Content-Type: text/enriched
1174 <center>This is a centered enriched part</center>
1180 @node MML Definition
1181 @section MML Definition
1183 The MML language is very simple. It looks a bit like an SGML
1184 application, but it's not.
1186 The main concept of MML is the @dfn{part}. Each part can be of a
1187 different type or use a different charset. The way to delineate a part
1188 is with a @samp{<#part ...>} tag. Multipart parts can be introduced
1189 with the @samp{<#multipart ...>} tag. Parts are ended by the
1190 @samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the
1191 @samp{<#part ...>} tags are also closed by the next open tag.
1193 There's also the @samp{<#external ...>} tag. These introduce
1194 @samp{external/message-body} parts.
1196 Each tag can contain zero or more parameters on the form
1197 @samp{parameter=value}. The values may be enclosed in quotation marks,
1198 but that's not necessary unless the value contains white space. So
1199 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
1201 The following parameters have meaning in MML; parameters that have no
1202 meaning are ignored. The MML parameter names are the same as the
1203 @sc{mime} parameter names; the things in the parentheses say which
1204 header it will be used in.
1208 The @sc{mime} type of the part (@code{Content-Type}).
1211 Use the contents of the file in the body of the part
1212 (@code{Content-Disposition}).
1215 The contents of the body of the part are to be encoded in the character
1216 set speficied (@code{Content-Type}).
1219 Might be used to suggest a file name if the part is to be saved
1220 to a file (@code{Content-Type}).
1223 Valid values are @samp{inline} and @samp{attachment}
1224 (@code{Content-Disposition}).
1227 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
1228 @samp{base64} (@code{Content-Transfer-Encoding}).
1231 A description of the part (@code{Content-Description}).
1234 RFC822 date when the part was created (@code{Content-Disposition}).
1236 @item modification-date
1237 RFC822 date when the part was modified (@code{Content-Disposition}).
1240 RFC822 date when the part was read (@code{Content-Disposition}).
1243 Who to encrypt/sign the part to. This field is used to override any
1244 auto-detection based on the To/CC headers.
1247 The size (in octets) of the part (@code{Content-Disposition}).
1250 What technology to sign this MML part with (@code{smime}, @code{pgp}
1254 What technology to encrypt this MML part with (@code{smime},
1255 @code{pgp} or @code{pgpmime})
1259 Parameters for @samp{application/octet-stream}:
1263 Type of the part; informal---meant for human readers
1264 (@code{Content-Type}).
1267 Parameters for @samp{message/external-body}:
1271 A word indicating the supported access mechanism by which the file may
1272 be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
1273 @samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.)
1276 The RFC822 date after which the file may no longer be fetched.
1277 (@code{Content-Type}.)
1280 The size (in octets) of the file. (@code{Content-Type}.)
1283 Valid values are @samp{read} and @samp{read-write}
1284 (@code{Content-Type}).
1288 Parameters for @samp{sign=smime}:
1293 File containing key and certificate for signer.
1297 Parameters for @samp{encrypt=smime}:
1302 File containing certificate for recipient.
1307 @node Advanced MML Example
1308 @section Advanced MML Example
1310 Here's a complex multipart message. It's a @samp{multipart/mixed} that
1311 contains many parts, one of which is a @samp{multipart/alternative}.
1314 <#multipart type=mixed>
1315 <#part type=image/jpeg filename=~/rms.jpg disposition=inline>
1316 <#multipart type=alternative>
1317 This is a plain text part.
1318 <#part type=text/enriched name=enriched.txt>
1319 <center>This is a centered enriched part</center>
1321 This is a new plain text part.
1322 <#part disposition=attachment>
1323 This plain text part is an attachment.
1327 And this is the resulting @sc{mime} message:
1330 Content-Type: multipart/mixed; boundary="=-=-="
1338 Content-Type: image/jpeg;
1339 filename="~/rms.jpg"
1340 Content-Disposition: inline;
1341 filename="~/rms.jpg"
1342 Content-Transfer-Encoding: base64
1344 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
1345 Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
1346 AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
1347 BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
1348 RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
1349 qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
1350 AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
1351 AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
1352 sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
1353 2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
1354 5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
1355 L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
1356 34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
1357 tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
1358 7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
1359 pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
1360 jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
1363 Content-Type: multipart/alternative; boundary="==-=-="
1369 This is a plain text part.
1372 Content-Type: text/enriched;
1376 <center>This is a centered enriched part</center>
1382 This is a new plain text part.
1385 Content-Disposition: attachment
1388 This plain text part is an attachment.
1393 @node Charset Translation
1394 @section Charset Translation
1397 During translation from MML to @sc{mime}, for each @sc{mime} part which
1398 has been composed inside Emacs, an appropriate charset has to be chosen.
1400 @vindex mail-parse-charset
1401 If you are running a non-@sc{mule} Emacs, this process is simple: If the
1402 part contains any non-ASCII (8-bit) characters, the @sc{mime} charset
1403 given by @code{mail-parse-charset} (a symbol) is used. (Never set this
1404 variable directly, though. If you want to change the default charset,
1405 please consult the documentation of the package which you use to process
1407 @xref{Various Message Variables, , Various Message Variables, message,
1408 Message Manual}, for example.)
1409 If there are only ASCII characters, the @sc{mime} charset US-ASCII is
1415 @vindex mm-mime-mule-charset-alist
1416 Things are slightly more complicated when running Emacs with @sc{mule}
1417 support. In this case, a list of the @sc{mule} charsets used in the
1418 part is obtained, and the @sc{mule} charsets are translated to @sc{mime}
1419 charsets by consulting the variable @code{mm-mime-mule-charset-alist}.
1420 If this results in a single @sc{mime} charset, this is used to encode
1421 the part. But if the resulting list of @sc{mime} charsets contains more
1422 than one element, two things can happen: If it is possible to encode the
1423 part via UTF-8, this charset is used. (For this, Emacs must support
1424 the @code{utf-8} coding system, and the part must consist entirely of
1425 characters which have Unicode counterparts.) If UTF-8 is not available
1426 for some reason, the part is split into several ones, so that each one
1427 can be encoded with a single @sc{mime} charset. The part can only be
1428 split at line boundaries, though---if more than one @sc{mime} charset is
1429 required to encode a single line, it is not possible to encode the part.
1435 A (multipart) @sc{mime} message can be converted to MML with the
1436 @code{mime-to-mml} function. It works on the message in the current
1437 buffer, and substitutes MML markup for @sc{mime} boundaries.
1438 Non-textual parts do not have their contents in the buffer, but instead
1439 have the contents in separate buffers that are referred to from the MML
1443 An MML message can be converted back to @sc{mime} by the
1444 @code{mml-to-mime} function.
1446 These functions are in certain senses ``lossy''---you will not get back
1447 an identical message if you run @sc{mime-to-mml} and then
1448 @sc{mml-to-mime}. Not only will trivial things like the order of the
1449 headers differ, but the contents of the headers may also be different.
1450 For instance, the original message may use base64 encoding on text,
1451 while @sc{mml-to-mime} may decide to use quoted-printable encoding, and
1454 In essence, however, these two functions should be the inverse of each
1455 other. The resulting contents of the message should remain equivalent,
1460 @section Flowed text
1461 @cindex format=flowed
1463 The Emacs @sc{mime} library will respect the @code{use-hard-newlines}
1464 variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines,
1465 emacs, Emacs Manual}) when encoding a message, and the
1466 ``format=flowed'' Content-Type parameter when decoding a message.
1468 On encoding text, lines terminated by soft newline characters are
1469 filled together and wrapped after the column decided by
1470 @code{fill-flowed-encode-column}. This variable controls how the text
1471 will look in a client that does not support flowed text, the default
1472 is to wrap after 66 characters. If hard newline characters are not
1473 present in the buffer, no flow encoding occurs.
1475 On decoding flowed text, lines with soft newline characters are filled
1476 together and wrapped after the column decided by
1477 @code{fill-flowed-display-column}. The default is to wrap after
1483 The Emacs @sc{mime} library implements handling of various elements
1484 according to a (somewhat) large number of RFCs, drafts and standards
1485 documents. This chapter lists the relevant ones. They can all be
1486 fetched from @uref{http://quimby.gnus.org/notes/}.
1491 Standard for the Format of ARPA Internet Text Messages.
1494 Standard for Interchange of USENET Messages
1497 Format of Internet Message Bodies
1503 Message Header Extensions for Non-ASCII Text
1506 Registration Procedures
1509 Conformance Criteria and Examples
1512 MIME Parameter Value and Encoded Word Extensions: Character Sets,
1513 Languages, and Continuations
1516 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1519 @item draft-ietf-drums-msg-fmt-05.txt
1520 Draft for the successor of RFC822
1523 The MIME Multipart/Related Content-type
1526 The Multipart/Report Content Type for the Reporting of Mail System
1527 Administrative Messages
1530 Communicating Presentation Information in Internet Messages: The
1531 Content-Disposition Header Field
1534 Documentation of the text/plain format parameter for flowed text.
1550 @c coding: iso-8859-1