1 \input texinfo @c -*-texinfo-*-
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,99 Free Software Foundation, Inc.
23 Permission is granted to make and distribute verbatim copies of
24 this manual provided the copyright notice and this permission notice
25 are preserved on all copies.
28 Permission is granted to process this file through Tex and print the
29 results, provided the printed document carries copying permission
30 notice identical to this one except for the removal of this paragraph
31 (this paragraph not being relevant to the printed manual).
34 Permission is granted to copy and distribute modified versions of this
35 manual under the conditions for verbatim copying, provided also that the
36 entire resulting derived work is distributed under the terms of a
37 permission notice identical to this one.
39 Permission is granted to copy and distribute translations of this manual
40 into another language, under the above conditions for modified versions.
46 @title Emacs MIME Manual
48 @author by Lars Magne Ingebrigtsen
51 @vskip 0pt plus 1filll
52 Copyright @copyright{} 1998,99 Free Software Foundation, Inc.
54 Permission is granted to make and distribute verbatim copies of
55 this manual provided the copyright notice and this permission notice
56 are preserved on all copies.
58 Permission is granted to copy and distribute modified versions of this
59 manual under the conditions for verbatim copying, provided that the
60 entire resulting derived work is distributed under the terms of a
61 permission notice identical to this one.
63 Permission is granted to copy and distribute translations of this manual
64 into another language, under the above conditions for modified versions.
74 This manual documents the libraries used to compose and display
77 This is not a manual meant for users; it's a manual directed at people
78 who want to write functions and commands that manipulate @sc{mime}
81 @sc{mime} is short for @dfn{Multipurpose Internet Mail Extensions}.
82 This standard is documented in a number of RFCs; mainly RFC2045 (Format
83 of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
84 Header Extensions for Non-ASCII Text), RFC2048 (Registration
85 Procedures), RFC2049 (Conformance Criteria and Examples). It is highly
86 recommended that anyone who intends writing @sc{mime}-compliant software
87 read at least RFC2045 and RFC2047.
90 * Interface Functions:: An abstraction over the basic functions.
91 * Basic Functions:: Utility and basic parsing functions.
92 * Decoding and Viewing:: A framework for decoding and viewing.
93 * Composing:: MML; a language for describing MIME parts.
94 * Standards:: A summary of RFCs and working documents used.
95 * Index:: Function and variable index.
99 @node Interface Functions
100 @chapter Interface Functions
101 @cindex interface functions
104 The @code{mail-parse} library is an abstraction over the actual
105 low-level libraries that are described in the next chapter.
107 Standards change, and so programs have to change to fit in the new
108 mold. For instance, RFC2045 describes a syntax for the
109 @code{Content-Type} header that only allows ASCII characters in the
110 parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme
111 for continuation headers and non-ASCII characters.
113 The traditional way to deal with this is just to update the library
114 functions to parse the new syntax. However, this is sometimes the wrong
115 thing to do. In some instances it may be vital to be able to understand
116 both the old syntax as well as the new syntax, and if there is only one
117 library, one must choose between the old version of the library and the
118 new version of the library.
120 The Emacs MIME library takes a different tack. It defines a series of
121 low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} and so on)
122 that parses strictly according to the corresponding standard. However,
123 normal programs would not use the functions provided by these libraries
124 directly, but instead use the functions provided by the
125 @code{mail-parse} library. The functions in this library are just
126 aliases to the corresponding functions in the latest low-level
127 libraries. Using this scheme, programs get a consistent interface they
128 can use, and library developers are free to create write code that
129 handles new standards.
131 The following functions are defined by this library:
134 @item mail-header-parse-content-type
135 @findex mail-header-parse-content-type
136 Parse a @code{Content-Type} header and return a list on the following
141 (attribute1 . value1)
142 (attribute2 . value2)
149 (mail-header-parse-content-type
150 "image/gif; name=\"b980912.gif\"")
151 @result{} ("image/gif" (name . "b980912.gif"))
154 @item mail-header-parse-content-disposition
155 @findex mail-header-parse-content-disposition
156 Parse a @code{Content-Disposition} header and return a list on the same
157 format as the function above.
159 @item mail-content-type-get
160 @findex mail-content-type-get
161 Takes two parameters---a list on the format above, and an attribute.
162 Returns the value of the attribute.
165 (mail-content-type-get
166 '("image/gif" (name . "b980912.gif")) 'name)
167 @result{} "b980912.gif"
170 @item mail-header-encode-parameter
171 @findex mail-header-encode-parameter
172 Takes a parameter string and returns an encoded version of the string.
173 This is used for parameters in headers like @code{Content-Type} and
174 @code{Content-Disposition}.
176 @item mail-header-remove-comments
177 @findex mail-header-remove-comments
178 Return a comment-free version of a header.
181 (mail-header-remove-comments
182 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
183 @result{} "Gnus/5.070027 "
186 @item mail-header-remove-whitespace
187 @findex mail-header-remove-whitespace
188 Remove linear white space from a header. Space inside quoted strings
189 and comments is preserved.
192 (mail-header-remove-whitespace
193 "image/gif; name=\"Name with spaces\"")
194 @result{} "image/gif;name=\"Name with spaces\""
197 @item mail-header-get-comment
198 @findex mail-header-get-comment
199 Return the last comment in a header.
202 (mail-header-get-comment
203 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
204 @result{} "Finnish Landrace"
207 @item mail-header-parse-address
208 @findex mail-header-parse-address
209 Parse an address and return a list containing the mailbox and the
213 (mail-header-parse-address
214 "Hrvoje Niksic <hniksic@@srce.hr>")
215 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
218 @item mail-header-parse-addresses
219 @findex mail-header-parse-addresses
220 Parse a string with list of addresses and return a list of elements like
221 the one described above.
224 (mail-header-parse-addresses
225 "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
226 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
227 ("sb@@metis.no" . "Steinar Bang"))
230 @item mail-header-parse-date
231 @findex mail-header-parse-date
232 Parse a date string and return an Emacs time structure.
234 @item mail-narrow-to-head
235 @findex mail-narrow-to-head
236 Narrow the buffer to the header section of the buffer. Point is placed
237 at the beginning of the narrowed buffer.
239 @item mail-header-narrow-to-field
240 @findex mail-header-narrow-to-field
241 Narrow the buffer to the header under point.
243 @item mail-encode-encoded-word-region
244 @findex mail-encode-encoded-word-region
245 Encode the non-ASCII words in the region. For instance,
246 @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
248 @item mail-encode-encoded-word-buffer
249 @findex mail-encode-encoded-word-buffer
250 Encode the non-ASCII words in the current buffer. This function is
251 meant to be called narrowed to the headers of a message.
253 @item mail-encode-encoded-word-string
254 @findex mail-encode-encoded-word-string
255 Encode the words that need encoding in a string, and return the result.
258 (mail-encode-encoded-word-string
259 "This is naïve, baby")
260 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
263 @item mail-decode-encoded-word-region
264 @findex mail-decode-encoded-word-region
265 Decode the encoded words in the region.
267 @item mail-decode-encoded-word-string
268 @findex mail-decode-encoded-word-string
269 Decode the encoded words in the string and return the result.
272 (mail-decode-encoded-word-string
273 "This is =?iso-8859-1?q?na=EFve,?= baby")
274 @result{} "This is naïve, baby"
279 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
280 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented
281 in the subsequent sections.
285 @node Basic Functions
286 @chapter Basic Functions
288 This chapter describes the basic, ground-level functions for parsing and
289 handling. Covered here is parsing @code{From} lines, removing comments
290 from header lines, decoding encoded words, parsing date headers and so
291 on. High-level functionality is dealt with in the next chapter
292 (@pxref{Decoding and Viewing}).
295 * rfc2045:: Encoding @code{Content-Type} headers.
296 * rfc2231:: Parsing @code{Content-Type} headers.
297 * ietf-drums:: Handling mail headers defined by RFC822bis.
298 * rfc2047:: En/decoding encoded words in headers.
299 * time-date:: Functions for parsing dates and manipulating time.
300 * qp:: Quoted-Printable en/decoding.
301 * base64:: Base64 en/decoding.
302 * binhex:: Binhex decoding.
303 * uudecode:: Uuencode decoding.
304 * rfc1843:: Decoding HZ-encoded text.
305 * mailcap:: How parts are displayed is specified by the @file{.mailcap} file
312 RFC2045 is the ``main'' @sc{mime} document, and as such, one would
313 imagine that there would be a lot to implement. But there isn't, since
314 most of the implementation details are delegated to the subsequent
317 So @file{rfc2045.el} has only a single function:
320 @item rfc2045-encode-string
321 @findex rfc2045-encode-string
322 Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
323 @var{value} will be quoted if there are non-safe characters in it.
330 RFC2231 defines a syntax for the @code{Content-Type} and
331 @code{Content-Disposition} headers. Its snappy name is @dfn{MIME
332 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
335 In short, these headers look something like this:
338 Content-Type: application/x-stuff;
339 title*0*=us-ascii'en'This%20is%20even%20more%20;
340 title*1*=%2A%2A%2Afun%2A%2A%2A%20;
344 They usually aren't this bad, though.
346 The following functions are defined by this library:
349 @item rfc2231-parse-string
350 @findex rfc2231-parse-string
351 Parse a @code{Content-Type} header and return a list describing its
355 (rfc2231-parse-string
356 "application/x-stuff;
357 title*0*=us-ascii'en'This%20is%20even%20more%20;
358 title*1*=%2A%2A%2Afun%2A%2A%2A%20;
359 title*2=\"isn't it!\"")
360 @result{} ("application/x-stuff"
361 (title . "This is even more ***fun*** isn't it!"))
364 @item rfc2231-get-value
365 @findex rfc2231-get-value
366 Takes one of the lists on the format above and returns
367 the value of the specified attribute.
369 @item rfc2231-encode-string
370 @findex rfc2231-encode-string
371 Encode a parameter in headers likes @code{Content-Type} and
372 @code{Content-Disposition}.
380 @dfn{drums} is an IETF working group that is working on the replacement
383 The functions provided by this library include:
386 @item ietf-drums-remove-comments
387 @findex ietf-drums-remove-comments
388 Remove the comments from the argument and return the results.
390 @item ietf-drums-remove-whitespace
391 @findex ietf-drums-remove-whitespace
392 Remove linear white space from the string and return the results.
393 Spaces inside quoted strings and comments are left untouched.
395 @item ietf-drums-get-comment
396 @findex ietf-drums-get-comment
397 Return the last most comment from the string.
399 @item ietf-drums-parse-address
400 @findex ietf-drums-parse-address
401 Parse an address string and return a list that contains the mailbox and
404 @item ietf-drums-parse-addresses
405 @findex ietf-drums-parse-addresses
406 Parse a string that contains any number of comma-separated addresses and
407 return a list that contains mailbox/plain text pairs.
409 @item ietf-drums-parse-date
410 @findex ietf-drums-parse-date
411 Parse a date string and return an Emacs time structure.
413 @item ietf-drums-narrow-to-header
414 @findex ietf-drums-narrow-to-header
415 Narrow the buffer to the header section of the current buffer.
423 RFC2047 (Message Header Extensions for Non-ASCII Text) specifies how
424 non-ASCII text in headers are to be encoded. This is actually rather
425 complicated, so a number of variables are necessary to tweak what this
428 The following variables are tweakable:
431 @item rfc2047-default-charset
432 @vindex rfc2047-default-charset
433 Characters in this charset should not be decoded by this library.
434 This defaults to @code{iso-8859-1}.
436 @item rfc2047-header-encoding-list
437 @vindex rfc2047-header-encoding-list
438 This is an alist of header / encoding-type pairs. Its main purpose is
439 to prevent encoding of certain headers.
441 The keys can either be header regexps, or @code{t}.
443 The values can be either @code{nil}, in which case the header(s) in
444 question won't be encoded, or @code{mime}, which means that they will be
447 @item rfc2047-charset-encoding-alist
448 @vindex rfc2047-charset-encoding-alist
449 RFC2047 specifies two forms of encoding---@code{Q} (a
450 Quoted-Printable-like encoding) and @code{B} (base64). This alist
451 specifies which charset should use which encoding.
453 @item rfc2047-encoding-function-alist
454 @vindex rfc2047-encoding-function-alist
455 This is an alist of encoding / function pairs. The encodings are
456 @code{Q}, @code{B} and @code{nil}.
458 @item rfc2047-q-encoding-alist
459 @vindex rfc2047-q-encoding-alist
460 The @code{Q} encoding isn't quite the same for all headers. Some
461 headers allow a narrower range of characters, and that is what this
462 variable is for. It's an alist of header regexps / allowable character
465 @item rfc2047-encoded-word-regexp
466 @vindex rfc2047-encoded-word-regexp
467 When decoding words, this library looks for matches to this regexp.
471 Those were the variables, and these are this functions:
474 @item rfc2047-narrow-to-field
475 @findex rfc2047-narrow-to-field
476 Narrow the buffer to the header on the current line.
478 @item rfc2047-encode-message-header
479 @findex rfc2047-encode-message-header
480 Should be called narrowed to the header of a message. Encodes according
481 to @code{rfc2047-header-encoding-alist}.
483 @item rfc2047-encode-region
484 @findex rfc2047-encode-region
485 Encodes all encodable words in the region specified.
487 @item rfc2047-encode-string
488 @findex rfc2047-encode-string
489 Encode a string and return the results.
491 @item rfc2047-decode-region
492 @findex rfc2047-decode-region
493 Decode the encoded words in the region.
495 @item rfc2047-decode-string
496 @findex rfc2047-decode-string
497 Decode a string and return the results.
505 While not really a part of the @sc{mime} library, it is convenient to
506 document this library here. It deals with parsing @code{Date} headers
507 and manipulating time. (Not by using tesseracts, though, I'm sorry to
510 These functions convert between five formats: A date string, an Emacs
511 time structure, a decoded time list, a second number, and a day number.
513 The functions have quite self-explanatory names, so the following just
514 gives an overview of which functions are available.
517 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
518 @result{} (54 21 12 12 9 1998 6 nil 7200)
520 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
521 @result{} (13818 19266)
523 (time-to-seconds '(13818 19266))
524 @result{} 905595714.0
526 (seconds-to-time 905595714.0)
527 @result{} (13818 19266 0)
529 (time-to-day '(13818 19266))
532 (days-to-time 729644)
533 @result{} (961933 65536)
535 (time-since '(13818 19266))
538 (time-less-p '(13818 19266) '(13818 19145))
541 (subtract-time '(13818 19266) '(13818 19145))
544 (days-between "Sat Sep 12 12:21:54 1998 +0200"
545 "Sat Sep 07 12:21:54 1998 +0200")
548 (date-leap-year-p 2000)
551 (time-to-day-in-year '(13818 19266))
556 And finally, we have @code{safe-date-to-time}, which does the same as
557 @code{date-to-time}, but returns a zero time if the date is
558 syntactically malformed.
565 This library deals with decoding and encoding Quoted-Printable text.
567 Very briefly explained, qp encoding means translating all 8-bit
568 characters (and lots of control characters) into things that look like
569 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
572 The following functions are defined by the library:
575 @item quoted-printable-decode-region
576 @findex quoted-printable-decode-region
577 QP-decode all the encoded text in the specified region.
579 @item quoted-printable-decode-string
580 @findex quoted-printable-decode-string
581 Decode the QP-encoded text in a string and return the results.
583 @item quoted-printable-encode-region
584 @findex quoted-printable-encode-region
585 QP-encode all the encodable characters in the specified region. The third
586 optional parameter @var{fold} specifies whether to fold long lines.
587 (Long here means 72.)
589 @item quoted-printable-encode-string
590 @findex quoted-printable-encode-string
591 QP-encode all the encodable characters in a string and return the
601 Base64 is an encoding that encodes three bytes into four characters,
602 thereby increasing the size by about 33%. The alphabet used for
603 encoding is very resistant to mangling during transit.
605 The following functions are defined by this library:
608 @item base64-encode-region
609 @findex base64-encode-region
610 base64 encode the selected region. Return the length of the encoded
611 text. Optional third argument @var{no-line-break} means do not break
612 long lines into shorter lines.
614 @item base64-encode-string
615 @findex base64-encode-string
616 base64 encode a string and return the result.
618 @item base64-decode-region
619 @findex base64-decode-region
620 base64 decode the selected region. Return the length of the decoded
621 text. If the region can't be decoded, return @code{nil} and don't
624 @item base64-decode-string
625 @findex base64-decode-string
626 base64 decode a string and return the result. If the string can't be
627 decoded, @code{nil} is returned.
638 @code{binhex} is an encoding that originated in Macintosh environments.
639 The following function is supplied to deal with these:
642 @item binhex-decode-region
643 @findex binhex-decode-region
644 Decode the encoded text in the region. If given a third parameter, only
645 decode the @code{binhex} header and return the filename.
655 @code{uuencode} is probably still the most popular encoding of binaries
656 used on Usenet, although @code{base64} rules the mail world.
658 The following function is supplied by this package:
661 @item uudecode-decode-region
662 @findex uudecode-decode-region
663 Decode the text in the region.
673 RFC1843 deals with mixing Chinese and ASCII characters in messages. In
674 essence, RFC1843 switches between ASCII and Chinese by doing this:
677 This sentence is in ASCII.
678 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
681 Simple enough, and widely used in China.
683 The following functions are available to handle this encoding:
686 @item rfc1843-decode-region
687 Decode HZ-encoded text in the region.
689 @item rfc1843-decode-string
690 Decode a HZ-encoded string and return the result.
698 The @file{~/.mailcap} file is parsed by most @sc{mime}-aware message
699 handlers and describes how elements are supposed to be displayed.
700 Here's an example file:
704 audio/wav; wavplayer %s
707 This says that all image files should be displayed with @samp{xv}, and
708 that realaudio files should be played by @samp{rvplayer}.
710 The @code{mailcap} library parses this file, and provides functions for
714 @item mailcap-mime-data
715 @vindex mailcap-mime-data
716 This variable is an alist of alists containing backup viewing rules.
723 @item mailcap-parse-mailcaps
724 @findex mailcap-parse-mailcaps
725 Parse the @code{~/.mailcap} file.
727 @item mailcap-mime-info
728 Takes a @sc{mime} type as its argument and returns the matching viewer.
735 @node Decoding and Viewing
736 @chapter Decoding and Viewing
738 This chapter deals with decoding and viewing @sc{mime} messages on a
741 The main idea is to first analyze a @sc{mime} article, and then allow
742 other programs to do things based on the list of @dfn{handles} that are
743 returned as a result of this analysis.
746 * Dissection:: Analyzing a @sc{mime} message.
747 * Handles:: Handle manipulations.
748 * Display:: Displaying handles.
749 * Customization:: Variables that affect display.
750 * New Viewers:: How to write your own viewers.
757 The @code{mm-dissect-buffer} is the function responsible for dissecting
758 a @sc{mime} article. If given a multipart message, it will recursively
759 descend the message, following the structure, and return a tree of
760 @sc{mime} handles that describes the structure of the message.
766 A @sc{mime} handle is a list that fully describes a @sc{mime}
769 The following macros can be used to access elements in a handle:
772 @item mm-handle-buffer
773 @findex mm-handle-buffer
774 Return the buffer that holds the contents of the undecoded @sc{mime}
778 @findex mm-handle-type
779 Return the parsed @code{Content-Type} of the part.
781 @item mm-handle-encoding
782 @findex mm-handle-encoding
783 Return the @code{Content-Transfer-Encoding} of the part.
785 @item mm-handle-undisplayer
786 @findex mm-handle-undisplayer
787 Return the object that can be used to remove the displayed part (if it
790 @item mm-handle-set-undisplayer
791 @findex mm-handle-set-undisplayer
792 Set the undisplayer object.
794 @item mm-handle-disposition
795 @findex mm-handle-disposition
796 Return the parsed @code{Content-Disposition} of the part.
798 @item mm-handle-disposition
799 @findex mm-handle-disposition
800 Return the description of the part.
802 @item mm-get-content-id
803 Returns the handle(s) referred to by @code{Content-ID}.
811 Functions for displaying, removing and saving.
814 @item mm-display-part
815 @findex mm-display-part
819 @findex mm-remove-part
820 Remove the part (if it has been displayed).
823 @findex mm-inlinable-p
824 Say whether a @sc{mime} type can be displayed inline.
826 @item mm-automatic-display-p
827 @findex mm-automatic-display-p
828 Say whether a @sc{mime} type should be displayed automatically.
830 @item mm-destroy-part
831 @findex mm-destroy-part
832 Free all resources occupied by a part.
836 Offer to save the part in a file.
840 Offer to pipe the part to some process.
842 @item mm-interactively-view-part
843 @findex mm-interactively-view-part
844 Prompt for a mailcap method to use to view the part.
850 @section Customization
854 @item mm-inline-media-tests
855 This is an alist where the key is a @sc{mime} type, the second element
856 is a function to display the part @dfn{inline} (i.e., inside Emacs), and
857 the third element is a form to be @code{eval}ed to say whether the part
858 can be displayed inline.
860 This variable specifies whether a part @emph{can} be displayed inline,
861 and, if so, how to do it. It does not say whether parts are
862 @emph{actually} displayed inline.
864 @item mm-inlined-types
865 This, on the other hand, says what types are to be displayed inline, if
866 they satisfy the conditions set by the variable above. It's a list of
867 @sc{mime} media types.
869 @item mm-automatic-display
870 This is a list of types that are to be displayed ``automatically'', but
871 only if the above variable allows it. That is, only inlinable parts can
872 be displayed automatically.
874 @item mm-attachment-override-types
875 Some @sc{mime} agents create parts that have a content-disposition of
876 @samp{attachment}. This variable allows overriding that disposition and
877 displaying the part inline. (Note that the disposition is only
878 overridden if we are able to, and want to, display the part inline.)
880 @item mm-discouraged-alternatives
881 List of @sc{mime} types that are discouraged when viewing
882 @samp{multipart/alternative}. Viewing agents are supposed to view the
883 last possible part of a message, as that is supposed to be the richest.
884 However, users may prefer other types instead, and this list says what
885 types are most unwanted. If, for instance, @samp{text/html} parts are
886 very unwanted, and @samp{text/richtech} parts are somewhat unwanted,
887 then the value of this variable should be set to:
890 ("text/html" "text/richtext")
893 @item mm-inline-large-images-p
894 When displaying inline images that are larger than the window, XEmacs
895 does not enable scrolling, which means that you cannot see the whole
896 image. To prevent this, the library tries to determine the image size
897 before displaying it inline, and if it doesn't fit the window, the
898 library will display it externally (e.g. with @samp{ImageMagick} or
899 @samp{xv}). Setting this variable to @code{t} disables this check and
900 makes the library display all inline images as inline, regardless of
903 @item mm-inline-override-p
904 @code{mm-inlined-types} may include regular expressions, for example to
905 specify that all @samp{text/.*} parts be displayed inline. If a user
906 prefers to have a type that matches such a regular expression be treated
907 as an attachment, that can be accomplished by setting this variable to a
908 list containing that type. For example assuming @code{mm-inlined-types}
909 includes @samp{text/.*}, then including @samp{text/html} in this
910 variable will cause @samp{text/html} parts to be treated as attachments.
918 Here's an example viewer for displaying @code{text/enriched} inline:
921 (defun mm-display-enriched-inline (handle)
924 (mm-insert-part handle)
925 (save-window-excursion
926 (enriched-decode (point-min) (point-max))
927 (setq text (buffer-string))))
928 (mm-insert-inline handle text)))
931 We see that the function takes a @sc{mime} handle as its parameter. It
932 then goes to a temporary buffer, inserts the text of the part, does some
933 work on the text, stores the result, goes back to the buffer it was
934 called from and inserts the result.
936 The two important helper functions here are @code{mm-insert-part} and
937 @code{mm-insert-inline}. The first function inserts the text of the
938 handle in the current buffer. It handles charset and/or content
939 transfer decoding. The second function just inserts whatever text you
940 tell it to insert, but it also sets things up so that the text can be
941 ``undisplayed' in a convenient manner.
947 @cindex MIME Composing
949 @cindex MIME Meta Language
951 Creating a @sc{mime} message is boring and non-trivial. Therefore, a
952 library called @code{mml} has been defined that parses a language called
953 MML (@sc{mime} Meta Language) and generates @sc{mime} messages.
955 @findex mml-generate-mime
956 The main interface function is @code{mml-generate-mime}. It will
957 examine the contents of the current (narrowed-to) buffer and return a
958 string containing the @sc{mime} message.
961 * Simple MML Example:: An example MML document.
962 * MML Definition:: All valid MML elements.
963 * Advanced MML Example:: Another example MML document.
964 * Charset Translation:: How charsets are mapped from @sc{mule} to MIME.
965 * Conversion:: Going from @sc{mime} to MML and vice versa.
969 @node Simple MML Example
970 @section Simple MML Example
972 Here's a simple @samp{multipart/alternative}:
975 <#multipart type=alternative>
976 This is a plain text part.
977 <#part type=text/enriched>
978 <center>This is a centered enriched part</center>
982 After running this through @code{mml-generate-mime}, we get this:
985 Content-Type: multipart/alternative; boundary="=-=-="
991 This is a plain text part.
994 Content-Type: text/enriched
997 <center>This is a centered enriched part</center>
1003 @node MML Definition
1004 @section MML Definition
1006 The MML language is very simple. It looks a bit like an SGML
1007 application, but it's not.
1009 The main concept of MML is the @dfn{part}. Each part can be of a
1010 different type or use a different charset. The way to delineate a part
1011 is with a @samp{<#part ...>} tag. Multipart parts can be introduced
1012 with the @samp{<#multipart ...>} tag. Parts are ended by the
1013 @samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the
1014 @samp{<#part ...>} tags are also closed by the next open tag.
1016 There's also the @samp{<#external ...>} tag. These introduce
1017 @samp{external/message-body} parts.
1019 Each tag can contain zero or more parameters on the form
1020 @samp{parameter=value}. The values may be enclosed in quotation marks,
1021 but that's not necessary unless the value contains white space. So
1022 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
1024 The following parameters have meaning in MML; parameters that have no
1025 meaning are ignored. The MML parameter names are the same as the
1026 @sc{mime} parameter names; the things in the parentheses say which
1027 header it will be used in.
1031 The @sc{mime} type of the part (@code{Content-Type}).
1034 Use the contents of the file in the body of the part
1035 (@code{Content-Disposition}).
1038 The contents of the body of the part are to be encoded in the character
1039 set speficied (@code{Content-Type}).
1042 Might be used to suggest a file name if the part is to be saved
1043 to a file (@code{Content-Type}).
1046 Valid values are @samp{inline} and @samp{attachment}
1047 (@code{Content-Disposition}).
1050 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
1051 @samp{base64} (@code{Content-Transfer-Encoding}).
1054 A description of the part (@code{Content-Description}).
1057 RFC822 date when the part was created (@code{Content-Disposition}).
1059 @item modification-date
1060 RFC822 date when the part was modified (@code{Content-Disposition}).
1063 RFC822 date when the part was read (@code{Content-Disposition}).
1066 The size (in octets) of the part (@code{Content-Disposition}).
1070 Parameters for @samp{application/octet-stream}:
1074 Type of the part; informal---meant for human readers
1075 (@code{Content-Type}).
1078 Parameters for @samp{message/external-body}:
1082 A word indicating the supported access mechanism by which the file may
1083 be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
1084 @samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.)
1087 The RFC822 date after which the file may no longer be fetched.
1088 (@code{Content-Type}.)
1091 The size (in octets) of the file. (@code{Content-Type}.)
1094 Valid values are @samp{read} and @samp{read-write}
1095 (@code{Content-Type}).
1100 @node Advanced MML Example
1101 @section Advanced MML Example
1103 Here's a complex multipart message. It's a @samp{multipart/mixed} that
1104 contains many parts, one of which is a @samp{multipart/alternative}.
1107 <#multipart type=mixed>
1108 <#part type=image/jpeg filename=~/rms.jpg disposition=inline>
1109 <#multipart type=alternative>
1110 This is a plain text part.
1111 <#part type=text/enriched name=enriched.txt>
1112 <center>This is a centered enriched part</center>
1114 This is a new plain text part.
1115 <#part disposition=attachment>
1116 This plain text part is an attachment.
1120 And this is the resulting @sc{mime} message:
1123 Content-Type: multipart/mixed; boundary="=-=-="
1131 Content-Type: image/jpeg;
1132 filename="~/rms.jpg"
1133 Content-Disposition: inline;
1134 filename="~/rms.jpg"
1135 Content-Transfer-Encoding: base64
1137 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
1138 Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
1139 AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
1140 BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
1141 RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
1142 qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
1143 AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
1144 AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
1145 sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
1146 2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
1147 5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
1148 L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
1149 34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
1150 tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
1151 7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
1152 pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
1153 jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
1156 Content-Type: multipart/alternative; boundary="==-=-="
1162 This is a plain text part.
1165 Content-Type: text/enriched;
1169 <center>This is a centered enriched part</center>
1175 This is a new plain text part.
1178 Content-Disposition: attachment
1181 This plain text part is an attachment.
1186 @node Charset Translation
1187 @section Charset Translation
1190 During translation from MML to @sc{mime}, for each @sc{mime} part which
1191 has been composed inside Emacs, an appropriate charset has to be chosen.
1193 @vindex mail-parse-charset
1194 If you are running a non-@sc{mule} Emacs, this process is simple: If the
1195 part contains any non-ASCII (8-bit) characters, the @sc{mime} charset
1196 given by @code{mail-parse-charset} (a symbol) is used. (Never set this
1197 variable directly, though. If you want to change the default charset,
1198 please consult the documentation of the package which you use to process
1200 @xref{Various Message Variables, , Various Message Variables, message,
1201 Message Manual}, for example.)
1202 If there are only ASCII characters, the @sc{mime} charset US-ASCII is
1208 @vindex mm-mime-mule-charset-alist
1209 Things are slightly more complicated when running Emacs with @sc{mule}
1210 support. In this case, a list of the @sc{mule} charsets used in the
1211 part is obtained, and the @sc{mule} charsets are translated to @sc{mime}
1212 charsets by consulting the variable @code{mm-mime-mule-charset-alist}.
1213 If this results in a single @sc{mime} charset, this is used to encode
1214 the part. But if the resulting list of @sc{mime} charsets contains more
1215 than one element, two things can happen: If it is possible to encode the
1216 part via UTF-8, this charset is used. (For this, Emacs must support
1217 the @code{utf-8} coding system, and the part must consist entirely of
1218 characters which have Unicode counterparts.) If UTF-8 is not available
1219 for some reason, the part is split into several ones, so that each one
1220 can be encoded with a single @sc{mime} charset. The part can only be
1221 split at line boundaries, though---if more than one @sc{mime} charset is
1222 required to encode a single line, it is not possible to encode the part.
1228 A (multipart) @sc{mime} message can be converted to MML with the
1229 @code{mime-to-mml} function. It works on the message in the current
1230 buffer, and substitutes MML markup for @sc{mime} boundaries.
1231 Non-textual parts do not have their contents in the buffer, but instead
1232 have the contents in separate buffers that are referred to from the MML
1236 An MML message can be converted back to @sc{mime} by the
1237 @code{mml-to-mime} function.
1239 These functions are in certain senses ``lossy''---you will not get back
1240 an identical message if you run @sc{mime-to-mml} and then
1241 @sc{mml-to-mime}. Not only will trivial things like the order of the
1242 headers differ, but the contents of the headers may also be different.
1243 For instance, the original message may use base64 encoding on text,
1244 while @sc{mml-to-mime} may decide to use quoted-printable encoding, and
1247 In essence, however, these two functions should be the inverse of each
1248 other. The resulting contents of the message should remain equivalent,
1255 The Emacs @sc{mime} library implements handling of various elements
1256 according to a (somewhat) large number of RFCs, drafts and standards
1257 documents. This chapter lists the relevant ones. They can all be
1258 fetched from @samp{http://quimby.gnus.org/notes/}.
1263 Standard for the Format of ARPA Internet Text Messages.
1266 Standard for Interchange of USENET Messages
1269 Format of Internet Message Bodies
1275 Message Header Extensions for Non-ASCII Text
1278 Registration Procedures
1281 Conformance Criteria and Examples
1284 MIME Parameter Value and Encoded Word Extensions: Character Sets,
1285 Languages, and Continuations
1288 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1291 @item draft-ietf-drums-msg-fmt-05.txt
1292 Draft for the successor of RFC822
1295 The MIME Multipart/Related Content-type
1298 The Multipart/Report Content Type for the Reporting of Mail System
1299 Administrative Messages
1302 Communicating Presentation Information in Internet Messages: The
1303 Content-Disposition Header Field