(displayed-month, displayed-year): Define for compiler.
[emacs.git] / man / emacs-mime.texi
blobab47e5a900ae9a38cbab4211508d5c6dc355dbf1
1 \input texinfo                  @c -*-mode: texinfo; coding: latin-1 -*-
3 @setfilename ../info/emacs-mime
4 @settitle Emacs MIME Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
9 @copying
10 This file documents the Emacs MIME interface functionality.
12 Copyright (C) 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
14 @quotation
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.1 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with the Front-Cover texts being ``A GNU
19 Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the
20 license is included in the section entitled ``GNU Free Documentation
21 License'' in the Emacs manual.
23 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
24 this GNU Manual, like GNU software.  Copies published by the Free
25 Software Foundation raise funds for GNU development.''
27 This document is part of a collection distributed under the GNU Free
28 Documentation License.  If you want to distribute this document
29 separately from the collection, you can do so by adding a copy of the
30 license to the document, as described in section 6 of the license.
31 @end quotation
32 @end copying
34 @dircategory Emacs
35 @direntry
36 * MIME: (emacs-mime).   Emacs MIME de/composition library.
37 @end direntry
38 @iftex
39 @finalout
40 @end iftex
41 @setchapternewpage odd
43 @titlepage
44 @title Emacs MIME Manual
46 @author by Lars Magne Ingebrigtsen
47 @page
48 @vskip 0pt plus 1filll
49 @insertcopying
50 @end titlepage
53 @node Top
54 @top Emacs MIME
56 This manual documents the libraries used to compose and display
57 @sc{mime} messages.
59 This is not a manual meant for users; it's a manual directed at people
60 who want to write functions and commands that manipulate @sc{mime}
61 elements.
63 @sc{mime} is short for @dfn{Multipurpose Internet Mail Extensions}.
64 This standard is documented in a number of RFCs; mainly RFC2045 (Format
65 of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
66 Header Extensions for Non-ASCII Text), RFC2048 (Registration
67 Procedures), RFC2049 (Conformance Criteria and Examples).  It is highly
68 recommended that anyone who intends writing @sc{mime}-compliant software
69 read at least RFC2045 and RFC2047.
71 @menu
72 * Interface Functions::   An abstraction over the basic functions.
73 * Basic Functions::       Utility and basic parsing functions.
74 * Decoding and Viewing::  A framework for decoding and viewing.
75 * Composing::             MML; a language for describing MIME parts.
76 * Standards::             A summary of RFCs and working documents used.
77 * Index::                 Function and variable index.
78 @end menu
81 @node Interface Functions
82 @chapter Interface Functions
83 @cindex interface functions
84 @cindex mail-parse
86 The @code{mail-parse} library is an abstraction over the actual
87 low-level libraries that are described in the next chapter.
89 Standards change, and so programs have to change to fit in the new
90 mold.  For instance, RFC2045 describes a syntax for the
91 @code{Content-Type} header that only allows @sc{ascii} characters in the
92 parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
93 for continuation headers and non-@sc{ascii} characters.
95 The traditional way to deal with this is just to update the library
96 functions to parse the new syntax.  However, this is sometimes the wrong
97 thing to do.  In some instances it may be vital to be able to understand
98 both the old syntax as well as the new syntax, and if there is only one
99 library, one must choose between the old version of the library and the
100 new version of the library.
102 The Emacs MIME library takes a different tack.  It defines a series of
103 low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} and so on)
104 that parses strictly according to the corresponding standard.  However,
105 normal programs would not use the functions provided by these libraries
106 directly, but instead use the functions provided by the
107 @code{mail-parse} library.  The functions in this library are just
108 aliases to the corresponding functions in the latest low-level
109 libraries.  Using this scheme, programs get a consistent interface they
110 can use, and library developers are free to create write code that
111 handles new standards.
113 The following functions are defined by this library:
115 @defun mail-header-parse-content-type string
116 Parse @var{string}, a @code{Content-Type} header, and return a
117 content-type list in the following format:
119 @lisp
120 ("type/subtype"
121  (attribute1 . value1)
122  (attribute2 . value2)
123  @dots{})
124 @end lisp
126 Here's an example:
128 @example
129 (mail-header-parse-content-type
130  "image/gif; name=\"b980912.gif\"")
131 @result{} ("image/gif" (name . "b980912.gif"))
132 @end example
133 @end defun
135 @defun mail-header-parse-content-disposition string
136 Parse @var{string}, a @code{Content-Disposition} header, and return a
137 content-type list in the format above.
138 @end defun
140 @defun mail-content-type-get ct attribute
141 @findex mail-content-type-get
142 Returns the value of the given @var{attribute} from the content-type
143 list @var{ct}.
145 @example
146 (mail-content-type-get
147  '("image/gif" (name . "b980912.gif")) 'name)
148 @result{} "b980912.gif"
149 @end example
150 @end defun
152 @defun mail-header-encode-parameter param value
153 Takes a parameter string @samp{@var{param}=@var{value}} and returns an
154 encoded version of it.  This is used for parameters in headers like
155 @samp{Content-Type} and @samp{Content-Disposition}.
156 @end defun
158 @defun mail-header-remove-comments string
159 Return a comment-free version of @var{string}.
161 @example
162 (mail-header-remove-comments
163  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
164 @result{} "Gnus/5.070027  "
165 @end example
166 @end defun
168 @defun mail-header-remove-whitespace string
169 Remove linear white space from @var{string}.  Space inside quoted
170 strings and comments is preserved.
172 @example
173 (mail-header-remove-whitespace
174  "image/gif; name=\"Name with spaces\"")
175 @result{} "image/gif;name=\"Name with spaces\""
176 @end example
177 @end defun
179 @defun mail-header-get-comment string
180 Return the last comment in @var{string}.
182 @example
183 (mail-header-get-comment
184  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
185 @result{} "Finnish Landrace"
186 @end example
187 @end defun
190 @defun mail-header-parse-address string
191 Parse an address string @var{string} and return a list containing the
192 mailbox and the plaintext name.
194 @example
195 (mail-header-parse-address
196  "Hrvoje Niksic <hniksic@@srce.hr>")
197 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
198 @end example
199 @end defun
201 @defun mail-header-parse-addresses string
202 Parse @var{string} as a list of addresses and return a list of elements
203 like the one described above.
205 @example
206 (mail-header-parse-addresses
207  "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
208 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
209      ("sb@@metis.no" . "Steinar Bang"))
210 @end example
211 @end defun
213 @defun mail-header-parse-date string
214 Parse a date @var{string} and return an Emacs time structure.
215 @end defun
217 @defun mail-narrow-to-head
218 Narrow the buffer to the header section of the buffer.  Point is placed
219 at the beginning of the narrowed buffer.
220 @end defun
222 @defun mail-header-narrow-to-field
223 Narrow the buffer to the header under point.
224 @end defun
226 @defun mail-encode-encoded-word-region start end
227 Encode the non-@sc{ascii} words in the region @var{start}to @var{end}.  For
228 instance, @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
229 @end defun
231 @defun mail-encode-encoded-word-buffer
232 Encode the non-@sc{ascii} words in the current buffer.  This function is
233 meant to be called with the buffer narrowed to the headers of a message.
234 @end defun
236 @defun mail-encode-encoded-word-string string
237 Encode the words that need encoding in @var{string}, and return the
238 result.
240 @example
241 (mail-encode-encoded-word-string
242  "This is naïve, baby")
243 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
244 @end example
245 @end defun
247 @defun mail-decode-encoded-word-region start end
248 Decode the encoded words in the region @var{start}to @var{end}.
249 @end defun
251 @defun mail-decode-encoded-word-string string
252 Decode the encoded words in @var{string} and return the result.
254 @example
255 (mail-decode-encoded-word-string
256  "This is =?iso-8859-1?q?na=EFve,?= baby")
257 @result{} "This is naïve, baby"
258 @end example
259 @end defun
261 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
262 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}.  These are documented
263 in the subsequent sections.
267 @node Basic Functions
268 @chapter Basic Functions
270 This chapter describes the basic, ground-level functions for parsing and
271 handling.  Covered here is parsing @code{From} lines, removing comments
272 from header lines, decoding encoded words, parsing date headers and so
273 on.  High-level functionality is dealt with in the next chapter
274 (@pxref{Decoding and Viewing}).
276 @menu
277 * rfc2045::      Encoding @code{Content-Type} headers.
278 * rfc2231::      Parsing @code{Content-Type} headers.
279 * ietf-drums::   Handling mail headers defined by RFC822bis.
280 * rfc2047::      En/decoding encoded words in headers.
281 * time-date::    Functions for parsing dates and manipulating time.
282 * qp::           Quoted-Printable en/decoding.
283 * base64::       Base64 en/decoding.
284 * binhex::       Binhex decoding.
285 * uudecode::     Uuencode decoding.
286 * rfc1843::      Decoding HZ-encoded text.
287 * mailcap::      How parts are displayed is specified by mailcap files
288 @end menu
291 @node rfc2045
292 @section rfc2045
294 RFC2045 is the ``main'' @sc{mime} document, and as such, one would
295 imagine that there would be a lot to implement.  But there isn't, since
296 most of the implementation details are delegated to the subsequent
297 RFCs.
299 So @file{rfc2045.el} has only a single function:
301 @defun rfc2045-encode-string parameter value
302 @findex rfc2045-encode-string
303 Takes a @var{parameter} and a @var{value} and returns a
304 @samp{@var{param}=@var{value}} string.  @var{value} will be quoted if
305 there are non-safe characters in it.
306 @end defun
309 @node rfc2231
310 @section rfc2231
312 RFC2231 defines a syntax for the @samp{Content-Type} and
313 @samp{Content-Disposition} headers.  Its snappy name is @dfn{MIME
314 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
315 and Continuations}.
317 In short, these headers look something like this:
319 @example
320 Content-Type: application/x-stuff;
321  title*0*=us-ascii'en'This%20is%20even%20more%20;
322  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
323  title*2="isn't it!"
324 @end example
326 They usually aren't this bad, though.
328 The following functions are defined by this library:
330 @defun rfc2231-parse-string string
331 Parse a @samp{Content-Type} header @var{string} and return a list
332 describing its elements.
334 @example
335 (rfc2231-parse-string
336  "application/x-stuff;
337  title*0*=us-ascii'en'This%20is%20even%20more%20;
338  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
339  title*2=\"isn't it!\"")
340 @result{} ("application/x-stuff"
341     (title . "This is even more ***fun*** isn't it!"))
342 @end example
343 @end defun
345 @defun rfc2231-get-value ct attribute
346 Takes a list @var{ct} of the format above and returns the value of the
347 specified @var{attribute}.
348 @end defun
350 @defun rfc2231-encode-string parameter value
351 Encode the string @samp{@var{parameter}=@var{value}} for inclusion in
352 headers likes @samp{Content-Type} and @samp{Content-Disposition}.
353 @end defun
355 @node ietf-drums
356 @section ietf-drums
358 @dfn{drums} is an IETF working group that is working on the replacement
359 for RFC822.
361 The functions provided by this library include:
363 @defun ietf-drums-remove-comments string
364 Remove the comments from @var{string} and return the result.
365 @end defun
367 @defun ietf-drums-remove-whitespace string
368 Remove linear white space from @var{string} and return the result.
369 Spaces inside quoted strings and comments are left untouched.
370 @end defun
372 @defun ietf-drums-get-comment string
373 Return the last most comment from @var{string}.
374 @end defun
376 @defun ietf-drums-parse-address string
377 Parse an address @var{string} and return a list of the mailbox and the
378 plain text name.
379 @end defun
381 @defun ietf-drums-parse-addresses string
382 Parse @var{string}, containing any number of comma-separated addresses,
383 and return a list of mailbox/plain text pairs.
384 @end defun
386 @defun ietf-drums-parse-date string
387 Parse the date @var{string} and return an Emacs time structure.
388 @end defun
390 @defun ietf-drums-narrow-to-header
391 Narrow the buffer to the header section of the current buffer.
392 @end defun
395 @node rfc2047
396 @section rfc2047
398 RFC2047 (Message Header Extensions for Non-ASCII Text) specifies how
399 non-@sc{ascii} text in headers are to be encoded.  This is actually rather
400 complicated, so a number of variables are necessary to tweak what this
401 library does.
403 The following variables are tweakable:
405 @defvar rfc2047-default-charset
406 Characters in this charset should not be decoded by this library.
407 This defaults to @samp{iso-8859-1}.
408 @end defvar
410 @defvar rfc2047-header-encoding-list
411 This is an alist of header / encoding-type pairs.  Its main purpose is
412 to prevent encoding of certain headers.
413 @end defvar
415 The keys can either be header regexps, or @code{t}.
417 The values can be either @code{nil}, in which case the header(s) in
418 question won't be encoded, or @code{mime}, which means that they will be
419 encoded.
421 @defvar rfc2047-charset-encoding-alist
422 RFC2047 specifies two forms of encoding---@code{Q} (a
423 Quoted-Printable-like encoding) and @code{B} (base64).  This alist
424 specifies which charset should use which encoding.
425 @end defvar
427 @defvar rfc2047-encoding-function-alist
428 This is an alist of encoding / function pairs.  The encodings are
429 @code{Q}, @code{B} and @code{nil}.
430 @end defvar
432 @defvar rfc2047-q-encoding-alist
433 The @code{Q} encoding isn't quite the same for all headers.  Some
434 headers allow a narrower range of characters, and that is what this
435 variable is for.  It's an alist of header regexps and allowable character
436 ranges.
437 @end defvar
439 @defvar rfc2047-encoded-word-regexp
440 When decoding words, this library looks for matches to this regexp.
441 @end defvar
443 Those were the variables, and these are the functions:
445 @defun rfc2047-narrow-to-field
446 Narrow the buffer to the header on the current line.
447 @end defun
449 @defun rfc2047-encode-message-header
450 Should be called narrowed to the header of a message.  Encodes according
451 to @code{rfc2047-header-encoding-alist}.
452 @end defun
454 @defun rfc2047-encode-region start end
455 Encodes all encodable words in the region @var{start} to @var{end}.
456 @end defun
458 @defun rfc2047-encode-string string
459 Encode @var{string} and return the result.
460 @end defun
462 @defun rfc2047-decode-region start end
463 Decode the encoded words in the region @var{start} to @var{end}.
464 @end defun
466 @defun rfc2047-decode-string string
467 Decode @var{string} and return the result.
468 @end defun
472 @node time-date
473 @section time-date
475 While not really a part of the @sc{mime} library, it is convenient to
476 document this library here.  It deals with parsing @samp{Date} headers
477 and manipulating time.  (Not by using tesseracts, though, I'm sorry to
478 say.)
480 These functions convert between five formats: a date string, an Emacs
481 time structure, a decoded time list, a number of seconds, and a day number.
483 The functions have quite self-explanatory names, so the following just
484 gives an overview of which functions are available.
486 @findex parse-time-string
487 @findex date-to-time
488 @findex time-to-seconds
489 @findex seconds-to-time
490 @findex time-to-day
491 @findex days-to-time
492 @findex time-since
493 @findex time-less-p
494 @findex subtract-time
495 @findex days-between
496 @findex date-leap-year-p
497 @findex time-to-day-in-year
498 @example
499 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
500 @result{} (54 21 12 12 9 1998 6 nil 7200)
502 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
503 @result{} (13818 19266)
505 (time-to-seconds '(13818 19266))
506 @result{} 905595714.0
508 (seconds-to-time 905595714.0)
509 @result{} (13818 19266 0)
511 (time-to-day '(13818 19266))
512 @result{} 729644
514 (days-to-time 729644)
515 @result{} (961933 65536)
517 (time-since '(13818 19266))
518 @result{} (0 430)
520 (time-less-p '(13818 19266) '(13818 19145))
521 @result{} nil
523 (subtract-time '(13818 19266) '(13818 19145))
524 @result{} (0 121)
526 (days-between "Sat Sep 12 12:21:54 1998 +0200"
527               "Sat Sep 07 12:21:54 1998 +0200")
528 @result{} 5
530 (date-leap-year-p 2000)
531 @result{} t
533 (time-to-day-in-year '(13818 19266))
534 @result{} 255
535 @end example
537 @findex safe-date-to-time
538 And finally, we have @code{safe-date-to-time}, which does the same as
539 @code{date-to-time}, but returns a zero time if the date is
540 syntactically malformed.
544 @node qp
545 @section qp
547 This library deals with decoding and encoding Quoted-Printable text.
549 Very briefly explained, QP encoding means translating all 8-bit
550 characters (and lots of control characters) into things that look like
551 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
552 string.  It is defined in RFC 2045.
554 The following functions are defined by the library:
556 @deffn Command quoted-printable-decode-region @var{from} @var{to} &optional @var{coding-system}
557 QP-decode all the encoded text in the region.  If @var{coding-system}
558 is non-nil, decode bytes into characters with that coding-system.  It
559 is probably better not to use @var{coding-system}; instead decode into
560 a unibyte buffer, decode that appropriately and then interpret it as
561 multibyte.
562 @end deffn
564 @defun quoted-printable-decode-string @var{string} &optional @var{coding-system}
565 Return a QP-encoded copy of @var{string}.  If @var{coding-system} is
566 non-nil, decode bytes into characters with that coding-system.
567 @end defun
569 @deffn Command quoted-printable-encode-region @var{from} @var{to} &optional @var{fold} @var{class}
570 QP-encode all the region.  If @var{fold} is non-@var{nil}, fold lines
571 at 76 characters, as required by the RFC.  If @var{class} is
572 non-@code{nil}, translate the characters not matched by that regexp
573 class, which should be in the form expected by
574 @var{skip-chars-forward} and should probably not contain literal
575 eight-bit characters.  Specifying @var{class} makes sense to do extra
576 encoding in header fields.
578 If variable @var{mm-use-ultra-safe-encoding} is defined and
579 non-@code{nil}, fold lines unconditionally and encode @samp{From } and
580 @samp{-} at the start of lines..
581 @end deffn
583 @defun quoted-printable-encode-string string
584 Return a QP-encoded copy of @var{string}.
585 @end defun
587 @node base64
588 @section base64
589 @cindex base64
591 Base64 is an encoding that encodes three bytes into four characters,
592 thereby increasing the size by about 33%.  The alphabet used for
593 encoding is very resistant to mangling during transit.  @xref{Base
594 64,,Base 64 Encoding, elisp, The Emacs Lisp Reference Manual}.
596 @node binhex
597 @section binhex
598 @cindex binhex
599 @cindex Apple
600 @cindex Macintosh
602 Binhex is an encoding that originated in Macintosh environments.
603 The following function is supplied to deal with these:
605 @defun binhex-decode-region start end &optional header-only
606 Decode the encoded text in the region @var{start} to @var{end}.  If
607 @var{header-only} is non-@code{nil}, only decode the @samp{binhex}
608 header and return the file name.
609 @end defun
612 @node uudecode
613 @section uudecode
614 @cindex uuencode
615 @cindex uudecode
617 Uuencoding is probably still the most popular encoding of binaries
618 used on Usenet, although Base64 rules the mail world.
620 The following function is supplied by this package:
622 @defun uudecode-decode-region start end &optional file-name
623 Decode the text in the region @var{start} to @var{end}.  If
624 @var{file-name} is non-@code{nil}, save the result to @var{file-name}.
625 @end defun
628 @node rfc1843
629 @section rfc1843
630 @cindex rfc1843
631 @cindex HZ
632 @cindex Chinese
634 RFC1843 deals with mixing Chinese and @sc{ascii} characters in messages.  In
635 essence, RFC1843 switches between @sc{ascii} and Chinese by doing this:
637 @example
638 This sentence is in ASCII.
639 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
640 @end example
642 Simple enough, and widely used in China.
644 The following functions are available to handle this encoding:
646 @defun rfc1843-decode-region start end
647 Decode HZ-encoded text in the region @var{start} to @var{end}.
648 @end defun
650 @defun rfc1843-decode-string string
651 Decode the HZ-encoded @var{string} and return the result.
652 @end defun
655 @node mailcap
656 @section mailcap
658 As specified by RFC 1524, @sc{mime}-aware message handlers parse
659 @dfn{mailcap} files from a default list, which can be overridden by the
660 @code{MAILCAP} environment variable.  These describe how elements are
661 supposed to be displayed.  Here's an example file:
663 @example
664 image/*; gimp -8 %s
665 audio/wav; wavplayer %s
666 @end example
668 This says that all image files should be displayed with @command{gimp},
669 and that WAVE audio files should be played by @code{wavplayer}.
671 The @code{mailcap} library parses such files, and provides functions for
672 matching types.
674 @defvar mailcap-mime-data
675 This variable is an alist of alists containing backup viewing rules for
676 @sc{mime} types.  These are overridden by rules for a type found in
677 mailcap files.  The outer alist is keyed on the major content-type and
678 the inner alists are keyed on the minor content-type (which can be a
679 regular expression).
681 @c Fixme: document this properly!
682 For example:
683 @example
684 (("application"
685   ("octet-stream"
686    (viewer . mailcap-save-binary-file)
687    (non-viewer . t)
688    (type . "application/octet-stream"))
689   ("plain"
690    (viewer . view-mode)
691    (test fboundp 'view-mode)
692    (type . "text/plain")))
693 @end example
694 @end defvar
696 @defopt mailcap-default-mime-data
697 This variable is the default value of @code{mailcap-mime-data}.  It
698 exists to allow setting the value using Custom.  It is merged with
699 values from mailcap files by @code{mailcap-parse-mailcaps}.
700 @end defopt
702 Although it is not specified by the RFC, @sc{mime} tools normally use a
703 common means of associating file extensions with defualt @sc{mime} types
704 in the absence of other information about the type of a file.  The
705 information is found in per-user files @file{~/.mime.types} and system
706 @file{mime.types} files found in quasi-standard places.  Here is an
707 example:
709 @example
710 application/x-dvi       dvi
711 audio/mpeg              mpga mpega mp2 mp3
712 image/jpeg              jpeg jpg jpe
713 @end example
716 @defvar mailcap-mime-extensions
717 This variable is an alist @sc{mime} types keyed by file extensions.
718 This is overridden by entries found in @file{mime.types} files.
719 @end defvar
721 @defopt mailcap-default-mime-extensions
722 This variable is the default value of @code{mailcap-mime-extensions}.
723 It exists to allow setting the value using Custom.  It is merged with
724 values from mailcap files by @code{mailcap-parse-mimetypes}.
725 @end defopt
727 Interface functions:
729 @defun mailcap-parse-mailcaps &optional path force
730 Parse all the mailcap files specified in a path string @var{path} and
731 merge them with the values from @code{mailcap-mime-data}.  Components of
732 @var{path} are separated by the @code{path-separator} character
733 appropriate for the system.  If @var{force} is non-@code{nil}, the files
734 are re-parsed even if they have been parsed already.  If @var{path} is
735 omitted, use the value of environment variable @code{MAILCAPS} if it is
736 set; otherwise (on GNU and Unix) use the path defined in RFC 1524, plus
737 @file{/usr/local/etc/mailcap}.
738 @end defun
740 @defun mailcap-parse-mimetypes &optional path force
741 Parse all the mimetypes specified in a path string @var{path}
742 and merge them with the values from @code{mailcap-mime-extensions}.
743 Components of @var{path} are separated by the @code{path-separator}
744 character appropriate for the system.  If @var{path} is omitted, use the
745 value of environment variable @code{MIMETYPES} if set; otherwise use a
746 default path consistent with that used by @code{mailcap-parse-mailcaps}.
747 If @var{force} is non-@code{nil}, the files are re-parsed even if they
748 have been parsed already.
749 @end defun
751 @defun mailcap-mime-info string &optional request
752 Gets the viewer command for content-type @var{string}.  @code{nil} is
753 returned if none is found.  Expects @var{string} to be a complete
754 content-type header line.
756 If @var{request} is non-@code{nil} it specifies what information to
757 return.  If it is nil or the empty string, the viewer (second field of
758 the mailcap entry) will be returned.  If it is a string, then the
759 mailcap field corresponding to that string will be returned
760 (@samp{print}, @samp{description}, whatever).  If it is a number, all
761 the information for this viewer is returned.  If it is @code{all}, then
762 all possible viewers for this type is returned.
763 @end defun
765 @defun mailcap-mime-types
766 This function returns a list of all the defined media types.
767 @end defun
769 @defun mailcap-extension-to-mime extension
770 This function returns the content type defined for a file with the given
771 @var{extension}.
772 @end defun
775 @node Decoding and Viewing
776 @chapter Decoding and Viewing
778 This chapter deals with decoding and viewing @sc{mime} messages on a
779 higher level.
781 The main idea is to first analyze a @sc{mime} article, and then allow
782 other programs to do things based on the list of @dfn{handles} that are
783 returned as a result of this analysis.
785 @menu
786 * Dissection::     Analyzing a @sc{mime} message.
787 * Handles::        Handle manipulations.
788 * Display::        Displaying handles.
789 * Customization::  Variables that affect display.
790 * New Viewers::    How to write your own viewers.
791 @end menu
794 @node Dissection
795 @section Dissection
797 The @code{mm-dissect-buffer} is the function responsible for dissecting
798 a @sc{mime} article.  If given a multipart message, it will recursively
799 descend the message, following the structure, and return a tree of
800 @sc{mime} handles that describes the structure of the message.
803 @node Handles
804 @section Handles
806 A @sc{mime} handle is a list that fully describes a @sc{mime} component.
808 The following macros can be used to access elements from the
809 @var{handle} argument:
811 @defmac mm-handle-buffer handle
812 Return the buffer that holds the contents of the undecoded @sc{mime}
813 part.
814 @end defmac
816 @defmac mm-handle-type handle
817 Return the parsed @samp{Content-Type} of the part.
818 @end defmac
820 @defmac mm-handle-encoding handle
821 Return the @samp{Content-Transfer-Encoding} of the part.
822 @end defmac
824 @defmac mm-handle-undisplayer handle
825 Return the function that can be used to remove the displayed part (if it
826 has been displayed).
827 @end defmac
829 @defmac mm-handle-set-undisplayer handle function
830 Set the undisplayer function for the part to function.
831 @end defmac
833 @defmac mm-handle-disposition
834 Return the parsed @samp{Content-Disposition} of the part.
835 @end defmac
837 @defmac mm-handle-disposition
838 Return the description of the part.
839 @end defmac
841 @defmac mm-get-content-id id
842 Returns the handle(s) referred to by @var{id}, the @samp{Content-ID} of
843 the part.
844 @end defmac
847 @node Display
848 @section Display
850 Functions for displaying, removing and saving.  In the descriptions
851 below, `the part' means the @sc{mime} part represented by the
852 @var{handle} argument.
854 @defun mm-display-part handle &optional no-default
855 Display the part.  Return @code{nil} if the part is removed,
856 @code{inline} if it is displayed inline or @code{external} if it is
857 displayed externally.  If @var{no-default} is non-@code{nil}, the part
858 is not displayed unless the @sc{mime} type of @var{handle} is defined to
859 be displayed inline or there is an display method defined for it; i.e.@:
860 no default external method will be used.
861 @end defun
863 @defun mm-remove-part handle
864 Remove the part if it has been displayed.
865 @end defun
867 @defun mm-inlinable-p handle
868 Return non-@code{nil} if the part can be displayed inline.
869 @end defun
871 @defun mm-automatic-display-p handle
872 Return non-@code{nil} if the user has requested automatic display of the
873 @sc{mime} type of the part.
874 @end defun
876 @defun mm-destroy-part handle
877 Free all the resources used by the part.
878 @end defun
880 @defun mm-save-part handle
881 Save the part to a file.  The user is prompted for a file name to use.
882 @end defun
884 @defun mm-pipe-part handle
885 Pipe the part through a shell command.  The user is prompted for the
886 command to use.
887 @end defun
889 @defun mm-interactively-view-part handle
890 Prompt for a mailcap method to use to view the part and display it
891 externally using that method.
892 @end defun
895 @node Customization
896 @section Customization
898 The display of @sc{mime} types may be customized with the following
899 options.
901 @defopt mm-inline-media-tests
902 This is an alist where the key is a @sc{mime} type, the second element
903 is a function to display the part @dfn{inline} (i.e., inside Emacs), and
904 the third element is a form to be @code{eval}ed to say whether the part
905 can be displayed inline.
907 This variable specifies whether a part @emph{can} be displayed inline,
908 and, if so, how to do it.  It does not say whether parts are
909 @emph{actually} displayed inline.
910 @end defopt
912 @defopt mm-inlined-types
913 This, on the other hand, says what types are to be displayed inline, if
914 they satisfy the conditions set by the variable above.  It's a list of
915 @sc{mime} media types.
916 @end defopt
918 @defopt mm-automatic-display
919 This is a list of types that are to be displayed ``automatically'', but
920 only if the above variable allows it.  That is, only inlinable parts can
921 be displayed automatically.
922 @end defopt
924 @defopt mm-attachment-override-types
925 Some @sc{mime} agents create parts that have a content-disposition of
926 @samp{attachment}.  This variable allows overriding that disposition and
927 displaying the part inline.  (Note that the disposition is only
928 overridden if we are able to, and want to, display the part inline.)
929 @end defopt
931 @defopt mm-discouraged-alternatives
932 List of @sc{mime} types that are discouraged when viewing
933 @samp{multipart/alternative}.  Viewing agents are supposed to view the
934 last possible part of a message, as that is supposed to be the richest.
935 However, users may prefer other types instead, and this list says what
936 types are most unwanted.  If, for instance, @samp{text/html} parts are
937 very unwanted, and @samp{text/richtech} parts are somewhat unwanted,
938 then the value of this variable should be set to:
940 @lisp
941 ("text/html" "text/richtext")
942 @end lisp
943 @end defopt
945 @defopt mm-inline-large-images-p
946 When displaying inline images that are larger than the window, XEmacs
947 does not enable scrolling, which means that you cannot see the whole
948 image.  To prevent this, the library tries to determine the image size
949 before displaying it inline, and if it doesn't fit the window, the
950 library will display it externally (e.g. with @samp{ImageMagick} or
951 @samp{xv}).  Setting this variable to @code{t} disables this check and
952 makes the library display all inline images as inline, regardless of
953 their size.
954 @end defopt
956 @defopt mm-inline-override-p
957 @code{mm-inlined-types} may include regular expressions, for example to
958 specify that all @samp{text/.*} parts be displayed inline.  If a user
959 prefers to have a type that matches such a regular expression be treated
960 as an attachment, that can be accomplished by setting this variable to a
961 list containing that type.  For example assuming @code{mm-inlined-types}
962 includes @samp{text/.*}, then including @samp{text/html} in this
963 variable will cause @samp{text/html} parts to be treated as attachments.
964 @end defopt
967 @node New Viewers
968 @section New Viewers
970 Here's an example viewer for displaying @samp{text/enriched} inline:
972 @lisp
973 (defun mm-display-enriched-inline (handle)
974   (let (text)
975     (with-temp-buffer
976       (mm-insert-part handle)
977       (save-window-excursion
978         (enriched-decode (point-min) (point-max))
979         (setq text (buffer-string))))
980     (mm-insert-inline handle text)))
981 @end lisp
983 We see that the function takes a @sc{mime} handle as its parameter.  It
984 then goes to a temporary buffer, inserts the text of the part, does some
985 work on the text, stores the result, goes back to the buffer it was
986 called from and inserts the result.
988 The two important helper functions here are @code{mm-insert-part} and
989 @code{mm-insert-inline}.  The first function inserts the text of the
990 handle in the current buffer.  It handles charset and/or content
991 transfer decoding.  The second function just inserts whatever text you
992 tell it to insert, but it also sets things up so that the text can be
993 ``undisplayed' in a convenient manner.
996 @node Composing
997 @chapter Composing
998 @cindex Composing
999 @cindex MIME Composing
1000 @cindex MML
1001 @cindex MIME Meta Language
1003 Creating a @sc{mime} message is boring and non-trivial.  Therefore, a
1004 library called @code{mml} has been defined that parses a language called
1005 MML (@sc{mime} Meta Language) and generates @sc{mime} messages.
1007 @findex mml-generate-mime
1008 The main interface function is @code{mml-generate-mime}.  It will
1009 examine the contents of the current (narrowed-to) buffer and return a
1010 string containing the @sc{mime} message.
1012 @menu
1013 * Simple MML Example::             An example MML document.
1014 * MML Definition::                 All valid MML elements.
1015 * Advanced MML Example::           Another example MML document.
1016 * Charset Translation::            How charsets are mapped from Mule to MIME.
1017 * Conversion::                     Going from @sc{mime} to MML and vice versa.
1018 @end menu
1021 @node Simple MML Example
1022 @section Simple MML Example
1024 Here's a simple @samp{multipart/alternative}:
1026 @example
1027 <#multipart type=alternative>
1028 This is a plain text part.
1029 <#part type=text/enriched>
1030 <center>This is a centered enriched part</center>
1031 <#/multipart>
1032 @end example
1034 After running this through @code{mml-generate-mime}, we get this:
1036 @example
1037 Content-Type: multipart/alternative; boundary="=-=-="
1040 --=-=-=
1043 This is a plain text part.
1045 --=-=-=
1046 Content-Type: text/enriched
1049 <center>This is a centered enriched part</center>
1051 --=-=-=--
1052 @end example
1055 @node MML Definition
1056 @section MML Definition
1058 The MML language is very simple.  It looks a bit like an SGML
1059 application, but it's not.
1061 The main concept of MML is the @dfn{part}.  Each part can be of a
1062 different type or use a different charset.  The way to delineate a part
1063 is with a @samp{<#part ...>} tag.  Multipart parts can be introduced
1064 with the @samp{<#multipart ...>} tag.  Parts are ended by the
1065 @samp{<#/part>} or @samp{<#/multipart>} tags.  Parts started with the
1066 @samp{<#part ...>} tags are also closed by the next open tag.
1068 There's also the @samp{<#external ...>} tag.  These introduce
1069 @samp{external/message-body} parts.
1071 Each tag can contain zero or more parameters on the form
1072 @samp{parameter=value}.  The values may be enclosed in quotation marks,
1073 but that's not necessary unless the value contains white space.  So
1074 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
1076 The following parameters have meaning in MML; parameters that have no
1077 meaning are ignored.  The MML parameter names are the same as the
1078 @sc{mime} parameter names; the things in the parentheses say which
1079 header it will be used in.
1081 @table @samp
1082 @item type
1083 The @sc{mime} type of the part (@samp{Content-Type}).
1085 @item filename
1086 Use the contents of the file in the body of the part
1087 (@samp{Content-Disposition}).
1089 @item charset
1090 The contents of the body of the part are to be encoded in the character
1091 set specified (@samp{Content-Type}).
1093 @item name
1094 Might be used to suggest a file name if the part is to be saved
1095 to a file (@samp{Content-Type}).
1097 @item disposition
1098 Valid values are @samp{inline} and @samp{attachment}
1099 (@samp{Content-Disposition}).
1101 @item encoding
1102 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
1103 @samp{base64} (@samp{Content-Transfer-Encoding}).
1105 @item description
1106 A description of the part (@samp{Content-Description}).
1108 @item creation-date
1109 RFC822 date when the part was created (@samp{Content-Disposition}).
1111 @item modification-date
1112 RFC822 date when the part was modified (@samp{Content-Disposition}).
1114 @item read-date
1115 RFC822 date when the part was read (@samp{Content-Disposition}).
1117 @item size
1118 The size (in octets) of the part (@samp{Content-Disposition}).
1120 @end table
1122 Parameters for @samp{application/octet-stream}:
1124 @table @samp
1125 @item type
1126 Type of the part; informal---meant for human readers
1127 (@samp{Content-Type}).
1128 @end table
1130 Parameters for @samp{message/external-body}:
1132 @table @samp
1133 @item access-type
1134 A word indicating the supported access mechanism by which the file may
1135 be obtained.  Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
1136 @samp{localfile}, and @samp{mailserver}.  (@samp{Content-Type}.)
1138 @item expiration
1139 The RFC822 date after which the file may no longer be fetched.
1140 (@samp{Content-Type}.)
1142 @item size
1143 The size (in octets) of the file.  (@samp{Content-Type}.)
1145 @item permission
1146 Valid values are @samp{read} and @samp{read-write}
1147 (@samp{Content-Type}).
1149 @end table
1152 @node Advanced MML Example
1153 @section Advanced MML Example
1155 Here's a complex multipart message.  It's a @samp{multipart/mixed} that
1156 contains many parts, one of which is a @samp{multipart/alternative}.
1158 @example
1159 <#multipart type=mixed>
1160 <#part type=image/jpeg filename=~/rms.jpg disposition=inline>
1161 <#multipart type=alternative>
1162 This is a plain text part.
1163 <#part type=text/enriched name=enriched.txt>
1164 <center>This is a centered enriched part</center>
1165 <#/multipart>
1166 This is a new plain text part.
1167 <#part disposition=attachment>
1168 This plain text part is an attachment.
1169 <#/multipart>
1170 @end example
1172 And this is the resulting @sc{mime} message:
1174 @example
1175 Content-Type: multipart/mixed; boundary="=-=-="
1178 --=-=-=
1182 --=-=-=
1183 Content-Type: image/jpeg;
1184  filename="~/rms.jpg"
1185 Content-Disposition: inline;
1186  filename="~/rms.jpg"
1187 Content-Transfer-Encoding: base64
1189 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
1190 Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
1191 AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
1192 BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
1193 RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
1194 qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
1195 AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
1196 AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
1197 sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
1198 2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
1199 5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
1200 L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
1201 34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
1202 tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
1203 7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
1204 pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
1205 jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
1207 --=-=-=
1208 Content-Type: multipart/alternative; boundary="==-=-="
1211 --==-=-=
1214 This is a plain text part.
1216 --==-=-=
1217 Content-Type: text/enriched;
1218  name="enriched.txt"
1221 <center>This is a centered enriched part</center>
1223 --==-=-=--
1225 --=-=-=
1227 This is a new plain text part.
1229 --=-=-=
1230 Content-Disposition: attachment
1233 This plain text part is an attachment.
1235 --=-=-=--
1236 @end example
1238 @node Charset Translation
1239 @section Charset Translation
1240 @cindex charsets
1242 During translation from MML to @sc{mime}, for each @sc{mime} part which
1243 has been composed inside Emacs, an appropriate @sc{mime} charset has to
1244 be chosen.
1246 @vindex mail-parse-charset
1247 @cindex unibyte Emacs
1248 If you are running a non-Mule XEmacs, or Emacs in unibyte
1249 mode@footnote{Deprecated!}, this process is simple: if the part
1250 contains any non-@sc{ascii} (8-bit) characters, the @sc{mime} charset
1251 given by @code{mail-parse-charset} (a symbol) is used.  (Never set this
1252 variable directly, though.  If you want to change the default charset,
1253 please consult the documentation of the package which you use to process
1254 @sc{mime} messages.  @xref{Various Message Variables, , Various Message
1255 Variables, message, Message Manual}, for example.)  If there are only
1256 @sc{ascii} characters, the @sc{mime} charset @samp{US-ASCII} is used, of
1257 course.
1259 @cindex multibyte Emacs
1260 @cindex @code{mime-charset} property
1261 In a normal (multibyte) Emacs session, a list of coding systems is
1262 derived that can encode the message part's content and correspond to
1263 MIME charsets (according to their @code{mime-charset} property).  This
1264 list is according to the normal priority rules and the highest priority
1265 one is chosen to encode the part.  If no such coding system can encode
1266 the part's contents, they are split into several parts such that each
1267 can be encoded with an appropriate coding system/@sc{mime}
1268 charset.@footnote{The part can only be split at line boundaries,
1269 though---if more than one @sc{mime} charset is required to encode a
1270 single line, it is not possible to encode the part.}  Note that this
1271 procedure works with any correctly-defined coding systems, not just
1272 built-in ones.  Given a suitably-defined UTF-8 coding system---one
1273 capable of encoding the Emacs charsets you use---it is not normally
1274 necessary to split a part by charset.
1276 @vindex mm-mime-mule-charset-alist
1277 @cindex XEmacs/Mule
1278 It isn't possible to do this properly in XEmacs/Mule.  Instead, a list
1279 of the Mule charsets used in the part is obtained, and the
1280 corresponding @sc{mime} charsets are determined by lookup in
1281 @code{mm-mime-mule-charset-alist}.  If the list elements all
1282 correspond to a single @sc{mime} charset, that is used to encode the
1283 part.  Otherwise, the part is split as above.
1285 @node Conversion
1286 @section Conversion
1288 @findex mime-to-mml
1289 A (multipart) @sc{mime} message can be converted to MML with the
1290 @code{mime-to-mml} function.  It works on the message in the current
1291 buffer, and substitutes MML markup for @sc{mime} boundaries.
1292 Non-textual parts do not have their contents in the buffer, but instead
1293 have the contents in separate buffers that are referred to from the MML
1294 tags.
1296 @findex mml-to-mime
1297 An MML message can be converted back to @sc{mime} by the
1298 @code{mml-to-mime} function.
1300 These functions are in certain senses ``lossy''---you will not get back
1301 an identical message if you run @sc{mime-to-mml} and then
1302 @sc{mml-to-mime}.  Not only will trivial things like the order of the
1303 headers differ, but the contents of the headers may also be different.
1304 For instance, the original message may use base64 encoding on text,
1305 while @sc{mml-to-mime} may decide to use quoted-printable encoding, and
1306 so on.
1308 In essence, however, these two functions should be the inverse of each
1309 other.  The resulting contents of the message should remain equivalent,
1310 if not identical.
1313 @node Standards
1314 @chapter Standards
1316 The Emacs @sc{mime} library implements handling of various elements
1317 according to a (somewhat) large number of RFCs, drafts and standards
1318 documents.  This chapter lists the relevant ones.  They can all be
1319 fetched from @samp{http://quimby.gnus.org/notes/}.
1321 @table @dfn
1322 @item RFC822
1323 @itemx STD11
1324 Standard for the Format of ARPA Internet Text Messages.
1326 @item RFC1036
1327 Standard for Interchange of USENET Messages
1329 @item RFC1524
1330 A User Agent Configuration Mechanism For Multimedia Mail Format
1331 Information
1333 @item RFC2045
1334 Format of Internet Message Bodies
1336 @item RFC2046
1337 Media Types
1339 @item RFC2047
1340 Message Header Extensions for Non-ASCII Text
1342 @item RFC2048
1343 Registration Procedures
1345 @item RFC2049
1346 Conformance Criteria and Examples
1348 @item RFC2231
1349 MIME Parameter Value and Encoded Word Extensions: Character Sets,
1350 Languages, and Continuations
1352 @item RFC1843
1353 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1354 ASCII characters
1356 @item draft-ietf-drums-msg-fmt-05.txt
1357 Draft for the successor of RFC822
1359 @item RFC2112
1360 The MIME Multipart/Related Content-type
1362 @item RFC1892
1363 The Multipart/Report Content Type for the Reporting of Mail System
1364 Administrative Messages
1366 @item RFC2183
1367 Communicating Presentation Information in Internet Messages: The
1368 Content-Disposition Header Field
1370 @end table
1373 @node Index
1374 @chapter Index
1375 @printindex cp
1376 @printindex fn
1378 @summarycontents
1379 @contents
1380 @bye
1382 @c End: