1 \input texinfo @c -*-texinfo-*-
4 @settitle Emacs MIME Manual
9 @c * Emacs MIME: (emacs-mime). The MIME de/composition library.
14 @setchapternewpage odd
18 This file documents the Emacs MIME interface functionality.
20 Copyright (C) 1996 Free Software Foundation, Inc.
22 Permission is granted to make and distribute verbatim copies of
23 this manual provided the copyright notice and this permission notice
24 are preserved on all copies.
27 Permission is granted to process this file through Tex and print the
28 results, provided the printed document carries copying permission
29 notice identical to this one except for the removal of this paragraph
30 (this paragraph not being relevant to the printed manual).
33 Permission is granted to copy and distribute modified versions of this
34 manual under the conditions for verbatim copying, provided also that the
35 entire resulting derived work is distributed under the terms of a
36 permission notice identical to this one.
38 Permission is granted to copy and distribute translations of this manual
39 into another language, under the above conditions for modified versions.
45 @title Emacs MIME Manual
47 @author by Lars Magne Ingebrigtsen
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 1998 Free Software Foundation, Inc.
53 Permission is granted to make and distribute verbatim copies of
54 this manual provided the copyright notice and this permission notice
55 are preserved on all copies.
57 Permission is granted to copy and distribute modified versions of this
58 manual under the conditions for verbatim copying, provided that the
59 entire resulting derived work is distributed under the terms of a
60 permission notice identical to this one.
62 Permission is granted to copy and distribute translations of this manual
63 into another language, under the above conditions for modified versions.
73 This manual documents the libraries used to compose and display
76 This is not a manual meant for users; it's a manual directed at people
77 who want to write functions and commands that manipulate @sc{mime}
80 @sc{mime} is short for @dfn{Multipurpose Internet Mail Extensions}.
81 This standard is documented in a number of RFCs; mainly RFC2045 (Format
82 of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
83 Header Extensions for Non-ASCII Text), RFC2048 (Registration
84 Procedures), RFC2049 (Conformance Criteria and Examples). It is highly
85 recommended that anyone who intends writing @sc{mime}-compliant software
86 read at least RFC2045 and RFC2047.
89 * Basic Functions:: Utility and basic parsing functions.
90 * Decoding and Viewing:: A framework for decoding and viewing.
91 * Index:: Function and variable index.
96 @chapter Basic Functions
98 This chapter describes the basic, ground-level functions for parsing and
99 handling. Covered here is parsing @code{From} lines, removing comments
100 from header lines, decoding encoded words, parsing date headers and so
101 on. High-level functionality is dealt with in the next chapter
102 (@pxref{Decoding and Viewing}).
105 * mail-parse:: The generalized @sc{mime} and mail interface.
106 * rfc2231:: Parsing @code{Content-Type} headers.
107 * drums:: Handling mail headers defined by RFC822bis.
108 * rfc2047:: En/decoding encoded words in headers.
109 * time-date:: Functions for parsing dates and manipulating time.
110 * qp:: Quoted-Printable en/decoding.
111 * base64:: Base64 en/decoding.
112 * mailcap:: How parts are displayed is specified by the @file{.mailcap} file
119 It is perhaps misleading to place the @code{mail-parse} library in this
120 chapter. It is not a basic low-level library---rather, it is an
121 abstraction over the actual low-level libraries that are described in the
124 Standards change, and so programs have to change to fit in the new
125 mold. For instance, RFC2045 describes a syntax for the
126 @code{Content-Type} header that only allows ASCII characters in the
127 parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme
128 for continuation headers and non-ASCII characters.
130 The traditional way to deal with this is just to update the library
131 functions to parse the new syntax. However, this is sometimes the wrong
132 thing to do. In some instances it may be vital to be able to understand
133 both the old syntax as well as the new syntax, and if there is only one
134 library, one must choose between the old version of the library and the
135 new version of the library.
137 The Emacs MIME library takes a different tack. It defines a series of
138 low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} and so on)
139 that parses strictly according to the corresponding standard. However,
140 normal programs would not use the functions provided by these libraries
141 directly, but instead use the functions provided by the
142 @code{mail-parse} library. The functions in this library are just
143 aliases to the corresponding functions in the latest low-level
144 libraries. Using this scheme, programs get a consistent interface they
145 can use, and library developers are free to create write code that
146 handles new standards.
148 The following functions are defined by this library:
151 @item mail-header-parse-content-type
152 @findex mail-header-parse-content-type
153 Parse a @code{Content-Type} header and return a list on the following
158 (attribute1 . value1)
159 (attribute2 . value2)
166 (mail-header-parse-content-type
167 "image/gif; name=\"b980912.gif\"")
168 => ("image/gif" (name . "b980912.gif"))
171 @item mail-header-parse-content-disposition
172 @findex mail-header-parse-content-disposition
173 Parse a @code{Content-Disposition} header and return a list on the same
174 format as the function above.
176 @item mail-content-type-get
177 @findex mail-content-type-get
178 Takes two parameters---a list on the format above, and an attribute.
179 Returns the value of the attribute.
182 (mail-content-type-get
183 '("image/gif" (name . "b980912.gif")) 'name)
187 @item mail-header-remove-comments
188 @findex mail-header-remove-comments
189 Return a comment-free version of a header.
192 (mail-header-remove-comments
193 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
197 @item mail-header-remove-whitespace
198 @findex mail-header-remove-whitespace
199 Remove linear white space from a header. Space inside quoted strings
200 and comments is preserved.
203 (mail-header-remove-whitespace
204 "image/gif; name=\"Name with spaces\"")
205 => "image/gif;name=\"Name with spaces\""
208 @item mail-header-get-comment
209 @findex mail-header-get-comment
210 Return the last comment in a header.
213 (mail-header-get-comment
214 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
215 => "Finnish Landrace"
218 @item mail-header-parse-address
219 @findex mail-header-parse-address
220 Parse an address and return a list containing the mailbox and the
224 (mail-header-parse-address
225 "Hrvoje Niksic <hniksic@@srce.hr>")
226 => ("hniksic@@srce.hr" . "Hrvoje Niksic")
229 @item mail-header-parse-addresses
230 @findex mail-header-parse-addresses
231 Parse a string with list of addresses and return a list of elements like
232 the one described above.
235 (mail-header-parse-addresses
236 "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
237 => (("hniksic@@srce.hr" . "Hrvoje Niksic")
238 ("sb@@metis.no" . "Steinar Bang"))
241 @item mail-header-parse-date
242 @findex mail-header-parse-date
243 Parse a date string and return an Emacs time structure.
245 @item mail-narrow-to-head
246 @findex mail-narrow-to-head
247 Narrow the buffer to the header section of the buffer. Point is placed
248 at the beginning of the narrowed buffer.
250 @item mail-header-narrow-to-field
251 @findex mail-header-narrow-to-field
252 Narrow the buffer to the header under point.
254 @item mail-encode-encoded-word-region
255 @findex mail-encode-encoded-word-region
256 Encode the non-ASCII words in the region. For instance,
257 @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
259 @item mail-encode-encoded-word-buffer
260 @findex mail-encode-encoded-word-buffer
261 Encode the non-ASCII words in the current buffer. This function is
262 meant to be called narrowed to the headers of a message.
264 @item mail-encode-encoded-word-string
265 @findex mail-encode-encoded-word-string
266 Encode the words that need encoding in a string, and return the result.
269 (mail-encode-encoded-word-string
270 "This is naïve, baby")
271 => "This is =?iso-8859-1?q?na=EFve,?= baby"
274 @item mail-decode-encoded-word-region
275 @findex mail-decode-encoded-word-region
276 Decode the encoded words in the region.
278 @item mail-decode-encoded-word-string
279 @findex mail-decode-encoded-word-string
280 Decode the encoded words in the string and return the result.
283 (mail-decode-encoded-word-string
284 "This is =?iso-8859-1?q?na=EFve,?= baby")
285 => "This is naïve, baby"
290 Currently, @code{mail-parse} is an abstraction over @code{drums},
291 @code{rfc2047} and @code{rfc2231}. These are documented in the
298 RFC2231 defines a syntax for the @code{Content-Type} and
299 @code{Content-Disposition} headers. Its snappy name is @dfn{MIME
300 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
303 In short, these headers look something like this:
306 Content-Type: application/x-stuff;
307 title*0*=us-ascii'en'This%20is%20even%20more%20;
308 title*1*=%2A%2A%2Afun%2A%2A%2A%20;
312 They usually aren't this bad, though.
314 The following functions are defined by this library:
317 @item rfc2231-parse-string
318 @findex rfc2231-parse-string
319 Parse a @code{Content-Type} header and return a list describing its
323 (rfc2231-parse-string
324 "application/x-stuff;
325 title*0*=us-ascii'en'This%20is%20even%20more%20;
326 title*1*=%2A%2A%2Afun%2A%2A%2A%20;
327 title*2=\"isn't it!\"")
328 => ("application/x-stuff"
329 (title . "This is even more ***fun*** isn't it!"))
332 @item rfc2231-get-value
333 @findex rfc2231-get-value
334 Takes one of the lists on the format above and return
335 the value of the specified attribute.
343 @dfn{drums} is an IETF working group that is working on the replacement
346 The functions provided by this library include:
349 @item drums-remove-comments
350 @findex drums-remove-comments
351 Remove the comments from the argument and return the results.
353 @item drums-remove-whitespace
354 @findex drums-remove-whitespace
355 Remove linear white space from the string and return the results.
356 Spaces inside quoted strings and comments are left untouched.
358 @item drums-get-comment
359 @findex drums-get-comment
360 Return the last most comment from the string.
362 @item drums-parse-address
363 @findex drums-parse-address
364 Parse an address string and return a list that contains the mailbox and
367 @item drums-parse-addresses
368 @findex drums-parse-addresses
369 Parse a string that contains any number of comma-separated addresses and
370 return a list that contains mailbox/plain text pairs.
372 @item drums-parse-date
373 @findex drums-parse-date
374 Parse a date string and return an Emacs time structure.
376 @item drums-narrow-to-header
377 @findex drums-narrow-to-header
378 Narrow the buffer to the header section of the current buffer.
386 RFC2047 (Message Header Extensions for Non-ASCII Text) specifies how
387 non-ASCII text in headers are to be encoded. This is actually rather
388 complicated, so a number of variables are necessary to tweak what this
391 The following variables are tweakable:
394 @item rfc2047-default-charset
395 @vindex rfc2047-default-charset
396 Characters in this charset should not be decoded by this library.
397 This defaults to @code{iso-8859-1}.
399 @item rfc2047-header-encoding-list
400 @vindex rfc2047-header-encoding-list
401 This is an alist of header / encoding-type pairs. Its main purpose is
402 to prevent encoding of certain headers.
404 The keys can either be header regexps, or @code{t}.
406 The values can be either @code{nil}, in which case the header(s) in
407 question won't be encoded, or @code{mime}, which means that they will be
410 @item rfc2047-charset-encoding-alist
411 @vindex rfc2047-charset-encoding-alist
412 RFC2047 specifies two forms of encoding---@code{Q} (a
413 Quoted-Printable-like encoding) and @code{B} (base64). This alist
414 specifies which charset should use which encoding.
416 @item rfc2047-encoding-function-alist
417 @vindex rfc2047-encoding-function-alist
418 This is an alist of encoding / function pairs. The encodings are
419 @code{Q}, @code{B} and @code{nil}.
421 @item rfc2047-q-encoding-alist
422 @vindex rfc2047-q-encoding-alist
423 The @code{Q} encoding isn't quite the same for all headers. Some
424 headers allow a narrower range of characters, and that is what this
425 variable is for. It's an alist of header regexps / allowable character
428 @item rfc2047-encoded-word-regexp
429 @vindex rfc2047-encoded-word-regexp
430 When decoding words, this library looks for matches to this regexp.
434 Those were the variables, and these are this functions:
437 @item rfc2047-narrow-to-field
438 @findex rfc2047-narrow-to-field
439 Narrow the buffer to the header on the current line.
441 @item rfc2047-encode-message-header
442 @findex rfc2047-encode-message-header
443 Should be called narrowed to the header of a message. Encodes according
444 to @code{rfc2047-header-encoding-alist}.
446 @item rfc2047-encode-region
447 @findex rfc2047-encode-region
448 Encodes all encodable words in the region specified.
450 @item rfc2047-encode-string
451 @findex rfc2047-encode-string
452 Encode a string and return the results.
454 @item rfc2047-decode-region
455 @findex rfc2047-decode-region
456 Decode the encoded words in the region.
458 @item rfc2047-decode-string
459 @findex rfc2047-decode-string
460 Decode a string and return the results.
468 While not really a part of the @sc{mime} library, it is convenient to
469 document this library here. It deals with parsing @code{Date} headers
470 and manipulating time. (Not by using tesseracts, though, I'm sorry to
473 These functions converts between five formats: A date string, an Emacs
474 time structure, a decoded time list, a second number, and a day number.
476 The functions have quite self-explanatory names, so the following just
477 gives an overview of which functions are available.
480 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
481 => (54 21 12 12 9 1998 6 nil 7200)
483 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
486 (time-to-seconds '(13818 19266))
489 (seconds-to-time 905595714.0)
492 (time-to-day '(13818 19266))
495 (days-to-time 729644)
498 (time-since '(13818 19266))
501 (time-less-p '(13818 19266) '(13818 19145))
504 (subtract-time '(13818 19266) '(13818 19145))
507 (days-between "Sat Sep 12 12:21:54 1998 +0200"
508 "Sat Sep 07 12:21:54 1998 +0200")
511 (date-leap-year-p 2000)
514 (time-to-day-in-year '(13818 19266))
519 And finally, we have @code{safe-date-to-time}, which does the same as
520 @code{date-to-time}, but returns a zero time if the date is
521 syntactically malformed.
528 This library deals with decoding and encoding Quoted-Printable text.
530 Very briefly explained, qp encoding means translating all 8-bit
531 characters (and lots of control characters) into things that look like
532 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
535 The following functions are defined by the library:
538 @item quoted-printable-decode-region
539 @findex quoted-printable-decode-region
540 QP-decode all the encoded text in the specified region.
542 @item quoted-printable-decode-string
543 @findex quoted-printable-decode-string
544 Decode the QP-encoded text in a string and return the results.
546 @item quoted-printable-encode-region
547 @findex quoted-printable-encode-region
548 QP-encode all the encodable characters in the specified region. The third
549 optional parameter @var{fold} specifies whether to fold long lines.
550 (Long here means 72.)
552 @item quoted-printable-encode-string
553 @findex quoted-printable-encode-string
554 QP-encode all the encodable characters in a string and return the
563 Base64 is an encoding that encodes three bytes into four characters,
564 thereby increasing the size by about 33%. The alphabet used for
565 encoding is very resistant to mangling during transit.
567 The following functions are defined by this library:
570 @item base64-encode-region
571 @findex base64-encode-region
572 base64 encode the selected region. Return the length of the encoded
573 text. Optional third argument @var{no-line-break} means do not break
574 long lines into shorter lines.
576 @item base64-encode-string
577 @findex base64-encode-string
578 base64 encode a string and return the result.
580 @item base64-decode-region
581 @findex base64-decode-region
582 base64 decode the selected region. Return the length of the decoded
583 text. If the region can't be decoded, return @code{nil} and don't
586 @item base64-decode-string
587 @findex base64-decode-string
588 base64 decode a string and return the result. If the string can't be
589 decoded, @code{nil} is returned.
597 The @file{~/.mailcap} file is parsed by most @sc{mime}-aware message
598 handlers and describes how elements are supposed to be displayed.
599 Here's an example file:
603 audio/x-pn-realaudio; rvplayer %s
606 This says that all image files should be displayed with @samp{xv}, and
607 that realaudio files should be played by @samp{rvplayer}.
609 The @code{mailcap} library parses this file, and provides functions for
613 @item mailcap-mime-data
614 @vindex mailcap-mime-data
615 This variable is an alist of alists containing backup viewing rules.
622 @item mailcap-parse-mailcaps
623 @findex mailcap-parse-mailcaps
624 Parse the @code{~/.mailcap} file.
626 @item mailcap-mime-info
627 Takes a @sc{mime} type as its argument and returns the matching viewer.
634 @node Decoding and Viewing
635 @chapter Decoding and Viewing
637 This chapter deals with decoding and viewing @sc{mime} messages on a
640 The main idea is to first analyze a @sc{mime} article, and then allow
641 other programs to do things based on the list of @dfn{handles} that are
642 returned as a result of this analyzation.
645 * Dissection:: Analyzing a @sc{mime} message.
646 * Handles:: Handle manipulations.
647 * Display:: Displaying handles.
654 The @code{mm-dissect-buffer} is the function responsible for dissecting
655 a @sc{mime} article. If given a multipart message, it will recursively
656 descend the message, following the structure, and return a tree of
657 @sc{mime} handles that describes the structure of the message.
663 A @sc{mime} handle is a list that fully describes a @sc{mime}
666 The following macros can be used to access elements in a handle:
669 @item mm-handle-buffer
670 @findex mm-handle-buffer
671 Return the buffer that holds the contents of the undecoded @sc{mime}
675 @findex mm-handle-type
676 Return the parsed @code{Content-Type} of the part.
678 @item mm-handle-encoding
679 @findex mm-handle-encoding
680 Return the @code{Content-Transfer-Encoding} of the part.
682 @item mm-handle-undisplayer
683 @findex mm-handle-undisplayer
684 Return the object that can be used to remove the displayed part (if it
687 @item mm-handle-set-undisplayer
688 @findex mm-handle-set-undisplayer
689 Set the undisplayer object.
691 @item mm-handle-disposition
692 @findex mm-handle-disposition
693 Return the parsed @code{Content-Disposition} of the part.
695 @item mm-handle-disposition
696 @findex mm-handle-disposition
697 Return the description of the part.
699 @item mm-get-content-id
700 Returns the handle(s) referred to by @code{Content-ID}.
708 Functions for displaying, removing and saving.
711 @item mm-display-part
712 @findex mm-display-part
716 @findex mm-remove-part
717 Remove the part (if it has been displayed).
720 @findex mm-inlinable-p
721 Say whether a @sc{mime} type can be displayed inline.
723 @item mm-automatic-display-p
724 @findex mm-automatic-display-p
725 Say whether a @sc{mime} type should be displayed automatically.
727 @item mm-destroy-part
728 @findex mm-destroy-part
729 Free all resources occupied by a part.
733 Offer to save the part in a file.
737 Offer to pipe the part to some process.
739 @item mm-interactively-view-part
740 @findex mm-interactively-view-part
741 Prompt for a mailcap method to use to view the part.