Sync up with Pterodactyl Gnus v0.92.
[elisp/gnus.git-] / texi / emacs-mime.texi
1 \input texinfo                  @c -*-texinfo-*-
2
3 @setfilename emacs-mime
4 @settitle Emacs MIME Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
8 @c @direntry
9 @c * Emacs MIME: (emacs-mime).   The MIME de/composition library.
10 @c @end direntry
11 @iftex
12 @finalout
13 @end iftex
14 @setchapternewpage odd
15
16 @ifinfo
17
18 This file documents the Emacs MIME interface functionality.
19
20 Copyright (C) 1998,99 Free Software Foundation, Inc.
21
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.
25
26 @ignore
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).
31
32 @end ignore
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.
37
38 Permission is granted to copy and distribute translations of this manual
39 into another language, under the above conditions for modified versions.
40 @end ifinfo
41
42 @tex
43
44 @titlepage
45 @title Emacs MIME Manual
46
47 @author by Lars Magne Ingebrigtsen
48 @page
49
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 1998,99 Free Software Foundation, Inc.
52
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.
56
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.
61
62 Permission is granted to copy and distribute translations of this manual
63 into another language, under the above conditions for modified versions.
64
65 @end titlepage
66 @page
67
68 @end tex
69
70 @node Top
71 @top Emacs MIME
72
73 This manual documents the libraries used to compose and display
74 @sc{mime} messages.
75
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}
78 elements.
79
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.
87
88 @menu
89 * Interface Functions::   An abstraction over the basic functions.
90 * Basic Functions::       Utility and basic parsing functions.
91 * Decoding and Viewing::  A framework for decoding and viewing.
92 * Composing::             MML; a language for describing MIME parts.
93 * Standards::             A summary of RFCs and working documents used.
94 * Index::                 Function and variable index.
95 @end menu
96
97
98 @node Interface Functions
99 @chapter Interface Functions
100 @cindex interface functions
101 @cindex mail-parse
102
103 The @code{mail-parse} library is an abstraction over the actual
104 low-level libraries that are described in the next chapter.
105
106 Standards change, and so programs have to change to fit in the new
107 mold.  For instance, RFC2045 describes a syntax for the
108 @code{Content-Type} header that only allows ASCII characters in the
109 parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
110 for continuation headers and non-ASCII characters.
111
112 The traditional way to deal with this is just to update the library
113 functions to parse the new syntax.  However, this is sometimes the wrong
114 thing to do.  In some instances it may be vital to be able to understand
115 both the old syntax as well as the new syntax, and if there is only one
116 library, one must choose between the old version of the library and the
117 new version of the library.
118
119 The Emacs MIME library takes a different tack.  It defines a series of
120 low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} and so on)
121 that parses strictly according to the corresponding standard.  However,
122 normal programs would not use the functions provided by these libraries
123 directly, but instead use the functions provided by the
124 @code{mail-parse} library.  The functions in this library are just
125 aliases to the corresponding functions in the latest low-level
126 libraries.  Using this scheme, programs get a consistent interface they
127 can use, and library developers are free to create write code that
128 handles new standards.
129
130 The following functions are defined by this library:
131
132 @table @code
133 @item mail-header-parse-content-type
134 @findex mail-header-parse-content-type
135 Parse a @code{Content-Type} header and return a list on the following
136 format:
137
138 @lisp
139 ("type/subtype"
140  (attribute1 . value1)
141  (attribute2 . value2)
142  ...)
143 @end lisp
144
145 Here's an example:
146
147 @example
148 (mail-header-parse-content-type
149  "image/gif; name=\"b980912.gif\"")
150 @result{} ("image/gif" (name . "b980912.gif"))
151 @end example
152
153 @item mail-header-parse-content-disposition
154 @findex mail-header-parse-content-disposition
155 Parse a @code{Content-Disposition} header and return a list on the same
156 format as the function above.
157
158 @item mail-content-type-get
159 @findex mail-content-type-get
160 Takes two parameters---a list on the format above, and an attribute.
161 Returns the value of the attribute.
162
163 @example
164 (mail-content-type-get
165  '("image/gif" (name . "b980912.gif")) 'name)
166 @result{} "b980912.gif"
167 @end example
168
169 @item mail-header-encode-parameter
170 @findex mail-header-encode-parameter
171 Takes a parameter string and returns an encoded version of the string.
172 This is used for parameters in headers like @code{Content-Type} and
173 @code{Content-Disposition}.
174
175 @item mail-header-remove-comments
176 @findex mail-header-remove-comments
177 Return a comment-free version of a header.
178
179 @example
180 (mail-header-remove-comments
181  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
182 @result{} "Gnus/5.070027  "
183 @end example
184
185 @item mail-header-remove-whitespace
186 @findex mail-header-remove-whitespace
187 Remove linear white space from a header.  Space inside quoted strings
188 and comments is preserved.
189
190 @example
191 (mail-header-remove-whitespace
192  "image/gif; name=\"Name with spaces\"")
193 @result{} "image/gif;name=\"Name with spaces\""
194 @end example
195
196 @item mail-header-get-comment
197 @findex mail-header-get-comment
198 Return the last comment in a header.
199
200 @example
201 (mail-header-get-comment
202  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
203 @result{} "Finnish Landrace"
204 @end example
205
206 @item mail-header-parse-address
207 @findex mail-header-parse-address
208 Parse an address and return a list containing the mailbox and the
209 plaintext name.
210
211 @example
212 (mail-header-parse-address
213  "Hrvoje Niksic <hniksic@@srce.hr>")
214 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
215 @end example
216
217 @item mail-header-parse-addresses
218 @findex mail-header-parse-addresses
219 Parse a string with list of addresses and return a list of elements like
220 the one described above.
221
222 @example
223 (mail-header-parse-addresses
224  "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
225 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
226      ("sb@@metis.no" . "Steinar Bang"))
227 @end example
228
229 @item mail-header-parse-date
230 @findex mail-header-parse-date
231 Parse a date string and return an Emacs time structure.
232
233 @item mail-narrow-to-head
234 @findex mail-narrow-to-head
235 Narrow the buffer to the header section of the buffer.  Point is placed
236 at the beginning of the narrowed buffer.
237
238 @item mail-header-narrow-to-field
239 @findex mail-header-narrow-to-field
240 Narrow the buffer to the header under point.
241
242 @item mail-encode-encoded-word-region
243 @findex mail-encode-encoded-word-region
244 Encode the non-ASCII words in the region.  For instance,
245 @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
246
247 @item mail-encode-encoded-word-buffer
248 @findex mail-encode-encoded-word-buffer
249 Encode the non-ASCII words in the current buffer.  This function is
250 meant to be called narrowed to the headers of a message.
251
252 @item mail-encode-encoded-word-string
253 @findex mail-encode-encoded-word-string
254 Encode the words that need encoding in a string, and return the result.
255
256 @example
257 (mail-encode-encoded-word-string
258  "This is naïve, baby")
259 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
260 @end example
261
262 @item mail-decode-encoded-word-region
263 @findex mail-decode-encoded-word-region
264 Decode the encoded words in the region.
265
266 @item mail-decode-encoded-word-string
267 @findex mail-decode-encoded-word-string
268 Decode the encoded words in the string and return the result.
269
270 @example
271 (mail-decode-encoded-word-string
272  "This is =?iso-8859-1?q?na=EFve,?= baby")
273 @result{} "This is naïve, baby"
274 @end example
275
276 @end table
277
278 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
279 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}.  These are documented
280 in the subsequent sections.
281
282
283
284 @node Basic Functions
285 @chapter Basic Functions
286
287 This chapter describes the basic, ground-level functions for parsing and
288 handling.  Covered here is parsing @code{From} lines, removing comments
289 from header lines, decoding encoded words, parsing date headers and so
290 on.  High-level functionality is dealt with in the next chapter
291 (@pxref{Decoding and Viewing}).
292
293 @menu
294 * rfc2045::      Encoding @code{Content-Type} headers.
295 * rfc2231::      Parsing @code{Content-Type} headers.
296 * ietf-drums::   Handling mail headers defined by RFC822bis.
297 * rfc2047::      En/decoding encoded words in headers.
298 * time-date::    Functions for parsing dates and manipulating time.
299 * qp::           Quoted-Printable en/decoding.
300 * base64::       Base64 en/decoding.
301 * binhex::       Binhex decoding.
302 * uudecode::     Uuencode decoding.
303 * rfc1843::      Decoding HZ-encoded text.
304 * mailcap::      How parts are displayed is specified by the @file{.mailcap} file
305 @end menu
306
307
308 @node rfc2045
309 @section rfc2045
310
311 RFC2045 is the ``main'' @sc{mime} document, and as such, one would
312 imagine that there would be a lot to implement.  But there isn't, since
313 most of the implementation details are delegated to the subsequent
314 RFCs.
315
316 So @file{rfc2045.el} has only a single function:
317
318 @table @code
319 @item rfc2045-encode-string
320 @findex rfc2045-encode-string
321 Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
322 @var{value} will be quoted if there are non-safe characters in it.
323 @end table
324
325
326 @node rfc2231
327 @section rfc2231
328
329 RFC2231 defines a syntax for the @code{Content-Type} and
330 @code{Content-Disposition} headers.  Its snappy name is @dfn{MIME
331 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
332 and Continuations}.
333
334 In short, these headers look something like this:
335
336 @example
337 Content-Type: application/x-stuff;
338  title*0*=us-ascii'en'This%20is%20even%20more%20;
339  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
340  title*2="isn't it!"
341 @end example
342
343 They usually aren't this bad, though.
344
345 The following functions are defined by this library:
346
347 @table @code
348 @item rfc2231-parse-string
349 @findex rfc2231-parse-string
350 Parse a @code{Content-Type} header and return a list describing its
351 elements.
352
353 @example
354 (rfc2231-parse-string
355  "application/x-stuff;
356  title*0*=us-ascii'en'This%20is%20even%20more%20;
357  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
358  title*2=\"isn't it!\"")
359 @result{} ("application/x-stuff"
360     (title . "This is even more ***fun*** isn't it!"))
361 @end example
362
363 @item rfc2231-get-value
364 @findex rfc2231-get-value
365 Takes one of the lists on the format above and returns
366 the value of the specified attribute.
367
368 @item rfc2231-encode-string
369 @findex rfc2231-encode-string
370 Encode a parameter in headers likes @code{Content-Type} and
371 @code{Content-Disposition}.
372
373 @end table
374
375
376 @node ietf-drums
377 @section ietf-drums
378
379 @dfn{drums} is an IETF working group that is working on the replacement
380 for RFC822.
381
382 The functions provided by this library include:
383
384 @table @code
385 @item ietf-drums-remove-comments
386 @findex ietf-drums-remove-comments
387 Remove the comments from the argument and return the results.
388
389 @item ietf-drums-remove-whitespace
390 @findex ietf-drums-remove-whitespace
391 Remove linear white space from the string and return the results.
392 Spaces inside quoted strings and comments are left untouched.
393
394 @item ietf-drums-get-comment
395 @findex ietf-drums-get-comment
396 Return the last most comment from the string.
397
398 @item ietf-drums-parse-address
399 @findex ietf-drums-parse-address
400 Parse an address string and return a list that contains the mailbox and
401 the plain text name.
402
403 @item ietf-drums-parse-addresses
404 @findex ietf-drums-parse-addresses
405 Parse a string that contains any number of comma-separated addresses and
406 return a list that contains mailbox/plain text pairs.
407
408 @item ietf-drums-parse-date
409 @findex ietf-drums-parse-date
410 Parse a date string and return an Emacs time structure.
411
412 @item ietf-drums-narrow-to-header
413 @findex ietf-drums-narrow-to-header
414 Narrow the buffer to the header section of the current buffer.
415
416 @end table
417
418
419 @node rfc2047
420 @section rfc2047
421
422 RFC2047 (Message Header Extensions for Non-ASCII Text) specifies how
423 non-ASCII text in headers are to be encoded.  This is actually rather
424 complicated, so a number of variables are necessary to tweak what this
425 library does.
426
427 The following variables are tweakable:
428
429 @table @code
430 @item rfc2047-default-charset
431 @vindex rfc2047-default-charset
432 Characters in this charset should not be decoded by this library.
433 This defaults to @code{iso-8859-1}.
434
435 @item rfc2047-header-encoding-list
436 @vindex rfc2047-header-encoding-list
437 This is an alist of header / encoding-type pairs.  Its main purpose is
438 to prevent encoding of certain headers.
439
440 The keys can either be header regexps, or @code{t}.
441
442 The values can be either @code{nil}, in which case the header(s) in
443 question won't be encoded, or @code{mime}, which means that they will be
444 encoded.
445
446 @item rfc2047-charset-encoding-alist
447 @vindex rfc2047-charset-encoding-alist
448 RFC2047 specifies two forms of encoding---@code{Q} (a
449 Quoted-Printable-like encoding) and @code{B} (base64).  This alist
450 specifies which charset should use which encoding.
451
452 @item rfc2047-encoding-function-alist
453 @vindex rfc2047-encoding-function-alist
454 This is an alist of encoding / function pairs.  The encodings are
455 @code{Q}, @code{B} and @code{nil}.
456
457 @item rfc2047-q-encoding-alist
458 @vindex rfc2047-q-encoding-alist
459 The @code{Q} encoding isn't quite the same for all headers.  Some
460 headers allow a narrower range of characters, and that is what this
461 variable is for.  It's an alist of header regexps / allowable character
462 ranges.
463
464 @item rfc2047-encoded-word-regexp
465 @vindex rfc2047-encoded-word-regexp
466 When decoding words, this library looks for matches to this regexp.
467
468 @end table
469
470 Those were the variables, and these are this functions:
471
472 @table @code
473 @item rfc2047-narrow-to-field
474 @findex rfc2047-narrow-to-field
475 Narrow the buffer to the header on the current line.
476
477 @item rfc2047-encode-message-header
478 @findex rfc2047-encode-message-header
479 Should be called narrowed to the header of a message.  Encodes according
480 to @code{rfc2047-header-encoding-alist}.
481
482 @item rfc2047-encode-region
483 @findex rfc2047-encode-region
484 Encodes all encodable words in the region specified.
485
486 @item rfc2047-encode-string
487 @findex rfc2047-encode-string
488 Encode a string and return the results.
489
490 @item rfc2047-decode-region
491 @findex rfc2047-decode-region
492 Decode the encoded words in the region.
493
494 @item rfc2047-decode-string
495 @findex rfc2047-decode-string
496 Decode a string and return the results.
497
498 @end table
499
500
501 @node time-date
502 @section time-date
503
504 While not really a part of the @sc{mime} library, it is convenient to
505 document this library here.  It deals with parsing @code{Date} headers
506 and manipulating time.  (Not by using tesseracts, though, I'm sorry to
507 say.)
508
509 These functions convert between five formats: A date string, an Emacs
510 time structure, a decoded time list, a second number, and a day number.
511
512 The functions have quite self-explanatory names, so the following just
513 gives an overview of which functions are available.
514
515 @example
516 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
517 @result{} (54 21 12 12 9 1998 6 nil 7200)
518
519 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
520 @result{} (13818 19266)
521
522 (time-to-seconds '(13818 19266))
523 @result{} 905595714.0
524
525 (seconds-to-time 905595714.0)
526 @result{} (13818 19266 0)
527
528 (time-to-day '(13818 19266))
529 @result{} 729644
530
531 (days-to-time 729644)
532 @result{} (961933 65536)
533
534 (time-since '(13818 19266))
535 @result{} (0 430)
536
537 (time-less-p '(13818 19266) '(13818 19145))
538 @result{} nil
539
540 (subtract-time '(13818 19266) '(13818 19145))
541 @result{} (0 121)
542
543 (days-between "Sat Sep 12 12:21:54 1998 +0200"
544               "Sat Sep 07 12:21:54 1998 +0200")
545 @result{} 5
546
547 (date-leap-year-p 2000)
548 @result{} t
549
550 (time-to-day-in-year '(13818 19266))
551 @result{} 255
552
553 @end example
554
555 And finally, we have @code{safe-date-to-time}, which does the same as
556 @code{date-to-time}, but returns a zero time if the date is
557 syntactically malformed.
558
559
560
561 @node qp
562 @section qp
563
564 This library deals with decoding and encoding Quoted-Printable text.
565
566 Very briefly explained, qp encoding means translating all 8-bit
567 characters (and lots of control characters) into things that look like
568 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
569 string.
570
571 The following functions are defined by the library:
572
573 @table @code
574 @item quoted-printable-decode-region
575 @findex quoted-printable-decode-region
576 QP-decode all the encoded text in the specified region.
577
578 @item quoted-printable-decode-string
579 @findex quoted-printable-decode-string
580 Decode the QP-encoded text in a string and return the results.
581
582 @item quoted-printable-encode-region
583 @findex quoted-printable-encode-region
584 QP-encode all the encodable characters in the specified region.  The third
585 optional parameter @var{fold} specifies whether to fold long lines.
586 (Long here means 72.)
587
588 @item quoted-printable-encode-string
589 @findex quoted-printable-encode-string
590 QP-encode all the encodable characters in a string and return the
591 results.
592
593 @end table
594
595
596 @node base64
597 @section base64
598 @cindex base64
599
600 Base64 is an encoding that encodes three bytes into four characters,
601 thereby increasing the size by about 33%.  The alphabet used for
602 encoding is very resistant to mangling during transit.
603
604 The following functions are defined by this library:
605
606 @table @code
607 @item base64-encode-region
608 @findex base64-encode-region
609 base64 encode the selected region.  Return the length of the encoded
610 text.  Optional third argument @var{no-line-break} means do not break
611 long lines into shorter lines.
612
613 @item base64-encode-string
614 @findex base64-encode-string
615 base64 encode a string and return the result.
616
617 @item base64-decode-region
618 @findex base64-decode-region
619 base64 decode the selected region.  Return the length of the decoded
620 text.  If the region can't be decoded, return @code{nil} and don't
621 modify the buffer.
622
623 @item base64-decode-string
624 @findex base64-decode-string
625 base64 decode a string and return the result.  If the string can't be
626 decoded, @code{nil} is returned.
627
628 @end table
629
630
631 @node binhex
632 @section binhex
633 @cindex binhex
634 @cindex Apple
635 @cindex Macintosh
636
637 @code{binhex} is an encoding that originated in Macintosh environments.
638 The following function is supplied to deal with these:
639
640 @table @code
641 @item binhex-decode-region
642 @findex binhex-decode-region
643 Decode the encoded text in the region.  If given a third parameter, only
644 decode the @code{binhex} header and return the filename.
645
646 @end table
647
648
649 @node uudecode
650 @section uudecode
651 @cindex uuencode
652 @cindex uudecode
653
654 @code{uuencode} is probably still the most popular encoding of binaries
655 used on Usenet, although @code{base64} rules the mail world.
656
657 The following function is supplied by this package:
658
659 @table @code
660 @item uudecode-decode-region
661 @findex uudecode-decode-region
662 Decode the text in the region.
663 @end table
664
665
666 @node rfc1843
667 @section rfc1843
668 @cindex rfc1843
669 @cindex HZ
670 @cindex Chinese
671
672 RFC1843 deals with mixing Chinese and ASCII characters in messages.  In
673 essence, RFC1843 switches between ASCII and Chinese by doing this:
674
675 @example
676 This sentence is in ASCII.
677 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
678 @end example
679
680 Simple enough, and widely used in China.
681
682 The following functions are available to handle this encoding:
683
684 @table @code
685 @item rfc1843-decode-region
686 Decode HZ-encoded text in the region.
687
688 @item rfc1843-decode-string
689 Decode a HZ-encoded string and return the result.
690
691 @end table
692
693
694 @node mailcap
695 @section mailcap
696
697 The @file{~/.mailcap} file is parsed by most @sc{mime}-aware message
698 handlers and describes how elements are supposed to be displayed.
699 Here's an example file:
700
701 @example
702 image/*; gimp -8 %s
703 audio/wav; wavplayer %s
704 @end example
705
706 This says that all image files should be displayed with @samp{xv}, and
707 that realaudio files should be played by @samp{rvplayer}.
708
709 The @code{mailcap} library parses this file, and provides functions for
710 matching types.
711
712 @table @code
713 @item mailcap-mime-data
714 @vindex mailcap-mime-data
715 This variable is an alist of alists containing backup viewing rules.
716
717 @end table
718
719 Interface functions:
720
721 @table @code
722 @item mailcap-parse-mailcaps
723 @findex mailcap-parse-mailcaps
724 Parse the @code{~/.mailcap} file.
725
726 @item mailcap-mime-info
727 Takes a @sc{mime} type as its argument and returns the matching viewer.
728
729 @end table
730
731
732
733
734 @node Decoding and Viewing
735 @chapter Decoding and Viewing
736
737 This chapter deals with decoding and viewing @sc{mime} messages on a
738 higher level.
739
740 The main idea is to first analyze a @sc{mime} article, and then allow
741 other programs to do things based on the list of @dfn{handles} that are
742 returned as a result of this analysis.
743
744 @menu
745 * Dissection::     Analyzing a @sc{mime} message.
746 * Handles::        Handle manipulations.
747 * Display::        Displaying handles.
748 * Customization::  Variables that affect display.
749 @end menu
750
751
752 @node Dissection
753 @section Dissection
754
755 The @code{mm-dissect-buffer} is the function responsible for dissecting
756 a @sc{mime} article.  If given a multipart message, it will recursively
757 descend the message, following the structure, and return a tree of
758 @sc{mime} handles that describes the structure of the message.
759
760
761 @node Handles
762 @section Handles
763
764 A @sc{mime} handle is a list that fully describes a @sc{mime}
765 component.
766
767 The following macros can be used to access elements in a handle:
768
769 @table @code
770 @item mm-handle-buffer
771 @findex mm-handle-buffer
772 Return the buffer that holds the contents of the undecoded @sc{mime}
773 part.
774
775 @item mm-handle-type
776 @findex mm-handle-type
777 Return the parsed @code{Content-Type} of the part.
778
779 @item mm-handle-encoding
780 @findex mm-handle-encoding
781 Return the @code{Content-Transfer-Encoding} of the part.
782
783 @item mm-handle-undisplayer
784 @findex mm-handle-undisplayer
785 Return the object that can be used to remove the displayed part (if it
786 has been displayed).
787
788 @item mm-handle-set-undisplayer
789 @findex mm-handle-set-undisplayer
790 Set the undisplayer object.
791
792 @item mm-handle-disposition
793 @findex mm-handle-disposition
794 Return the parsed @code{Content-Disposition} of the part.
795
796 @item mm-handle-disposition
797 @findex mm-handle-disposition
798 Return the description of the part.
799
800 @item mm-get-content-id
801 Returns the handle(s) referred to by @code{Content-ID}.
802
803 @end table
804
805
806 @node Display
807 @section Display
808
809 Functions for displaying, removing and saving.
810
811 @table @code
812 @item mm-display-part
813 @findex mm-display-part
814 Display the part.
815
816 @item mm-remove-part
817 @findex mm-remove-part
818 Remove the part (if it has been displayed).
819
820 @item mm-inlinable-p
821 @findex mm-inlinable-p
822 Say whether a @sc{mime} type can be displayed inline.
823
824 @item mm-automatic-display-p
825 @findex mm-automatic-display-p
826 Say whether a @sc{mime} type should be displayed automatically.
827
828 @item mm-destroy-part
829 @findex mm-destroy-part
830 Free all resources occupied by a part.
831
832 @item mm-save-part
833 @findex mm-save-part
834 Offer to save the part in a file.
835
836 @item mm-pipe-part
837 @findex mm-pipe-part
838 Offer to pipe the part to some process.
839
840 @item mm-interactively-view-part
841 @findex mm-interactively-view-part
842 Prompt for a mailcap method to use to view the part.
843
844 @end table
845
846
847 @node Customization
848 @section Customization
849
850 @table @code
851
852 @item mm-inline-media-tests
853 This is an alist where the key is a @sc{mime} type, the second element
854 is a function to display the part @dfn{inline} (i.e., inside Emacs), and 
855 the third element is a form to be @code{eval}ed to say whether the part
856 can be displayed inline.
857
858 This variable specifies whether a part @emph{can} be displayed inline,
859 and, if so, how to do it.  It does not say whether parts are
860 @emph{actually} displayed inline.
861
862 @item mm-inlined-types
863 This, on the other hand, says what types are to be displayed inline, if
864 they satisfy the conditions set by the variable above.  It's a list of
865 @sc{mime} media types.
866
867 @item mm-automatic-display
868 This is a list of types that are to be displayed ``automatically'', but
869 only if the above variable allows it.  That is, only inlinable parts can
870 be displayed automatically.
871
872 @item mm-attachment-override-types
873 Some @sc{mime} agents create parts that have a content-disposition of
874 @samp{attachment}.  This variable allows overriding that disposition and 
875 displaying the part inline.  (Note that the disposition is only
876 overridden if we are able to, and want to, display the part inline.)
877
878 @item mm-discouraged-alternatives
879 List of @sc{mime} types that are discouraged when viewing
880 @samp{multipart/alternative}.  Viewing agents are supposed to view the
881 last possible part of a message, as that is supposed to be the richest.
882 However, users may prefer other types instead, and this list says what
883 types are most unwanted.  If, for instance, @samp{text/html} parts are
884 very unwanted, and @samp{text/richtech} parts are somewhat unwanted,
885 then the value of this variable should be set to:
886
887 @lisp
888 ("text/html" "text/richtext")
889 @end lisp
890
891 @item mm-inline-large-images-p
892 When displaying inline images that are larger than the window, XEmacs
893 does not enable scrolling, which means that you cannot see the whole
894 image.  To prevent this, the library tries to determine the image size
895 before displaying it inline, and if it doesn't fit the window, the
896 library will display it externally (e.g. with @samp{ImageMagick} or
897 @samp{xv}).  Setting this variable to @code{t} disables this check and
898 makes the library display all inline images as inline, regardless of
899 their size.
900
901
902 @end table
903
904
905
906 @node Composing
907 @chapter Composing
908 @cindex Composing
909 @cindex MIME Composing
910 @cindex MML
911 @cindex MIME Meta Language
912
913 Creating a @sc{mime} message is boring and non-trivial.  Therefore, a
914 library called @code{mml} has been defined that parses a language called
915 MML (@sc{mime} Meta Language) and generates @sc{mime} messages.
916
917 @findex mml-generate-mime
918 The main interface function is @code{mml-generate-mime}.  It will
919 examine the contents of the current (narrowed-to) buffer and return a
920 string containing the @sc{mime} message.
921
922 @menu
923 * Simple MML Example::             An example MML document.
924 * MML Definition::                 All valid MML elements.
925 * Advanced MML Example::           Another example MML document.
926 * Conversion::                     Going from @sc{mime} to MML and vice versa.
927 @end menu
928
929
930 @node Simple MML Example
931 @section Simple MML Example
932
933 Here's a simple @samp{multipart/alternative}:
934
935 @example
936 <#multipart type=alternative>
937 This is a plain text part.
938 <#part type=text/enriched>
939 <center>This is a centered enriched part</center>
940 <#/multipart>
941 @end example
942
943 After running this through @code{mml-generate-mime}, we get this:
944
945 @example
946 Content-Type: multipart/alternative; boundary="=-=-="
947
948
949 --=-=-=
950
951
952 This is a plain text part.
953
954 --=-=-=
955 Content-Type: text/enriched
956
957
958 <center>This is a centered enriched part</center>
959
960 --=-=-=--
961 @end example
962
963
964 @node MML Definition
965 @section MML Definition
966
967 The MML language is very simple.  It looks a bit like an SGML
968 application, but it's not.
969
970 The main concept of MML is the @dfn{part}.  Each part can be of a
971 different type or use a different charset.  The way to delineate a part
972 is with a @samp{<#part ...>} tag.  Multipart parts can be introduced
973 with the @samp{<#multipart ...>} tag.  Parts are ended by the
974 @samp{<#/part>} or @samp{<#/multipart>} tags.  Parts started with the
975 @samp{<#part ...>} tags are also closed by the next open tag.
976
977 There's also the @samp{<#external ...>} tag.  These introduce
978 @samp{external/message-body} parts.
979
980 Each tag can contain zero or more parameters on the form
981 @samp{parameter=value}.  The values may be enclosed in quotation marks,
982 but that's not necessary unless the value contains white space.  So
983 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
984
985 The following parameters have meaning in MML; parameters that have no
986 meaning are ignored.  The MML parameter names are the same as the
987 @sc{mime} parameter names; the things in the parentheses say which
988 header it will be used in.
989
990 @table @samp
991 @item type
992 The @sc{mime} type of the part (@code{Content-Type}).
993
994 @item filename
995 Use the contents of the file in the body of the part
996 (@code{Content-Disposition}).
997
998 @item charset
999 The contents of the body of the part are to be encoded in the character
1000 set speficied (@code{Content-Type}).
1001
1002 @item name
1003 Might be used to suggest a file name if the part is to be saved
1004 to a file (@code{Content-Type}).
1005
1006 @item disposition
1007 Valid values are @samp{inline} and @samp{attachment}
1008 (@code{Content-Disposition}).
1009
1010 @item encoding
1011 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
1012 @samp{base64} (@code{Content-Transfer-Encoding}).
1013
1014 @item description
1015 A description of the part (@code{Content-Description}).
1016
1017 @item creation-date
1018 RFC822 date when the part was created (@code{Content-Disposition}).
1019
1020 @item modification-date
1021 RFC822 date when the part was modified (@code{Content-Disposition}).
1022
1023 @item read-date
1024 RFC822 date when the part was read (@code{Content-Disposition}).
1025
1026 @item size
1027 The size (in octets) of the part (@code{Content-Disposition}).
1028
1029 @end table
1030
1031 Parameters for @samp{application/octet-stream}:
1032
1033 @table @samp
1034 @item type
1035 Type of the part; informal---meant for human readers
1036 (@code{Content-Type}).
1037 @end table
1038
1039 Parameters for @samp{message/external-body}:
1040
1041 @table @samp
1042 @item access-type
1043 A word indicating the supported access mechanism by which the file may
1044 be obtained.  Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
1045 @samp{localfile}, and @samp{mailserver}.  (@code{Content-Type}.)
1046
1047 @item expiration
1048 The RFC822 date after which the file may no longer be fetched.
1049 (@code{Content-Type}.)
1050
1051 @item size
1052 The size (in octets) of the file.  (@code{Content-Type}.)
1053
1054 @item permission
1055 Valid values are @samp{read} and @samp{read-write}
1056 (@code{Content-Type}).
1057
1058 @end table
1059
1060
1061 @node Advanced MML Example
1062 @section Advanced MML Example
1063
1064 Here's a complex multipart message.  It's a @samp{multipart/mixed} that
1065 contains many parts, one of which is a @samp{multipart/alternative}.
1066
1067 @example
1068 <#multipart type=mixed>
1069 <#part type=image/jpeg filename=~/rms.jpg disposition=inline>
1070 <#multipart type=alternative>
1071 This is a plain text part.
1072 <#part type=text/enriched name=enriched.txt>
1073 <center>This is a centered enriched part</center>
1074 <#/multipart>
1075 This is a new plain text part.
1076 <#part disposition=attachment>
1077 This plain text part is an attachment.
1078 <#/multipart>
1079 @end example
1080
1081 And this is the resulting @sc{mime} message:
1082
1083 @example
1084 Content-Type: multipart/mixed; boundary="=-=-="
1085
1086
1087 --=-=-=
1088
1089
1090
1091 --=-=-=
1092 Content-Type: image/jpeg;
1093  filename="~/rms.jpg"
1094 Content-Disposition: inline;
1095  filename="~/rms.jpg"
1096 Content-Transfer-Encoding: base64
1097
1098 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
1099 Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
1100 AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
1101 BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
1102 RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
1103 qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
1104 AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
1105 AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
1106 sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
1107 2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
1108 5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
1109 L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
1110 34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
1111 tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
1112 7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
1113 pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
1114 jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
1115
1116 --=-=-=
1117 Content-Type: multipart/alternative; boundary="==-=-="
1118
1119
1120 --==-=-=
1121
1122
1123 This is a plain text part.
1124
1125 --==-=-=
1126 Content-Type: text/enriched;
1127  name="enriched.txt"
1128
1129
1130 <center>This is a centered enriched part</center>
1131
1132 --==-=-=--
1133
1134 --=-=-=
1135
1136 This is a new plain text part.
1137
1138 --=-=-=
1139 Content-Disposition: attachment
1140
1141
1142 This plain text part is an attachment.
1143
1144 --=-=-=--
1145 @end example
1146
1147
1148 @node Conversion
1149 @section Conversion
1150
1151 @findex mime-to-mml
1152 A (multipart) @sc{mime} message can be converted to MML with the
1153 @code{mime-to-mml} function.  It works on the message in the current
1154 buffer, and substitutes MML markup for @sc{mime} boundaries.
1155 Non-textual parts do not have their contents in the buffer, but instead
1156 have the contents in separate buffers that are referred to from the MML
1157 tags.
1158
1159 @findex mml-to-mime
1160 An MML message can be converted back to @sc{mime} by the
1161 @code{mml-to-mime} function.
1162
1163 These functions are in certain senses ``lossy''---you will not get back
1164 an identical message if you run @sc{mime-to-mml} and then
1165 @sc{mml-to-mime}.  Not only will trivial things like the order of the
1166 headers differ, but the contents of the headers may also be different.
1167 For instance, the original message may use base64 encoding on text,
1168 while @sc{mml-to-mime} may decide to use quoted-printable encoding, and
1169 so on.
1170
1171 In essence, however, these two functions should be the inverse of each
1172 other.  The resulting contents of the message should remain equivalent,
1173 if not identical.
1174
1175
1176 @node Standards
1177 @chapter Standards
1178
1179 The Emacs @sc{mime} library implements handling of various elements
1180 according to a (somewhat) large number of RFCs, drafts and standards
1181 documents.  This chapter lists the relevant ones.  They can all be
1182 fetched from @samp{http://www.stud.ifi.uio.no/~larsi/notes/}.
1183
1184 @table @dfn
1185 @item RFC822
1186 @itemx STD11
1187 Standard for the Format of ARPA Internet Text Messages.
1188
1189 @item RFC1036
1190 Standard for Interchange of USENET Messages
1191
1192 @item RFC2045
1193 Format of Internet Message Bodies
1194
1195 @item RFC2046
1196 Media Types
1197
1198 @item RFC2047
1199 Message Header Extensions for Non-ASCII Text
1200
1201 @item RFC2048
1202 Registration Procedures
1203
1204 @item RFC2049
1205 Conformance Criteria and Examples
1206
1207 @item RFC2231
1208 MIME Parameter Value and Encoded Word Extensions: Character Sets,
1209 Languages, and Continuations
1210
1211 @item RFC1843
1212 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1213 ASCII characters
1214
1215 @item draft-ietf-drums-msg-fmt-05.txt
1216 Draft for the successor of RFC822
1217
1218 @item RFC2112
1219 The MIME Multipart/Related Content-type
1220
1221 @item RFC1892
1222 The Multipart/Report Content Type for the Reporting of Mail System
1223 Administrative Messages
1224
1225 @item RFC2183
1226 Communicating Presentation Information in Internet Messages: The
1227 Content-Disposition Header Field
1228
1229 @end table
1230
1231
1232 @node Index
1233 @chapter Index
1234 @printindex cp
1235
1236 @summarycontents
1237 @contents
1238 @bye
1239
1240 @c End: