3 @setfilename emacs-mime
4 @settitle Emacs MIME Manual
10 This file documents the Emacs MIME interface functionality.
12 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
13 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.2 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover texts being ``A GNU
20 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
21 license is included in the section entitled ``GNU Free Documentation
22 License'' in the Emacs manual.
24 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
25 this GNU Manual, like GNU software. Copies published by the Free
26 Software Foundation raise funds for GNU development.''
28 This document is part of a collection distributed under the GNU Free
29 Documentation License. If you want to distribute this document
30 separately from the collection, you can do so by adding a copy of the
31 license to the document, as described in section 6 of the license.
37 * Emacs MIME: (emacs-mime). Emacs MIME de/composition library.
42 @setchapternewpage odd
45 @title Emacs MIME Manual
47 @author by Lars Magne Ingebrigtsen
49 @vskip 0pt plus 1filll
56 This manual documents the libraries used to compose and display
57 @acronym{MIME} messages.
59 This manual is directed at users who want to modify the behavior of
60 the @acronym{MIME} encoding/decoding process or want a more detailed
61 picture of how the Emacs @acronym{MIME} library works, and people who want
62 to write functions and commands that manipulate @acronym{MIME} elements.
64 @acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}.
65 This standard is documented in a number of RFCs; mainly RFC2045 (Format
66 of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
67 Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration
68 Procedures), RFC2049 (Conformance Criteria and Examples). It is highly
69 recommended that anyone who intends writing @acronym{MIME}-compliant software
70 read at least RFC2045 and RFC2047.
73 * Decoding and Viewing:: A framework for decoding and viewing.
74 * Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts.
75 * Interface Functions:: An abstraction over the basic functions.
76 * Basic Functions:: Utility and basic parsing functions.
77 * Standards:: A summary of RFCs and working documents used.
78 * Index:: Function and variable index.
82 @node Decoding and Viewing
83 @chapter Decoding and Viewing
85 This chapter deals with decoding and viewing @acronym{MIME} messages on a
88 The main idea is to first analyze a @acronym{MIME} article, and then allow
89 other programs to do things based on the list of @dfn{handles} that are
90 returned as a result of this analysis.
93 * Dissection:: Analyzing a @acronym{MIME} message.
94 * Non-MIME:: Analyzing a non-@acronym{MIME} message.
95 * Handles:: Handle manipulations.
96 * Display:: Displaying handles.
97 * Display Customization:: Variables that affect display.
98 * Files and Directories:: Saving and naming attachments.
99 * New Viewers:: How to write your own viewers.
106 The @code{mm-dissect-buffer} is the function responsible for dissecting
107 a @acronym{MIME} article. If given a multipart message, it will recursively
108 descend the message, following the structure, and return a tree of
109 @acronym{MIME} handles that describes the structure of the message.
113 @vindex mm-uu-configure-list
115 Gnus also understands some non-@acronym{MIME} attachments, such as
116 postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp,
117 diff. Each of these features can be disabled by add an item into
118 @code{mm-uu-configure-list}. For example,
122 (add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
148 Non-@acronym{MIME} forwarded message.
156 @acronym{PGP} signed clear text.
159 @findex pgp-encrypted
160 @acronym{PGP} encrypted clear text.
164 @acronym{PGP} public keys.
167 @findex emacs-sources
168 @vindex mm-uu-emacs-sources-regexp
169 Emacs source code. This item works only in the groups matching
170 @code{mm-uu-emacs-sources-regexp}.
174 @vindex mm-uu-diff-groups-regexp
175 Patches. This is intended for groups where diffs of committed files
176 are automatically sent to. It only works in groups matching
177 @code{mm-uu-diff-groups-regexp}.
184 A @acronym{MIME} handle is a list that fully describes a @acronym{MIME}
187 The following macros can be used to access elements in a handle:
190 @item mm-handle-buffer
191 @findex mm-handle-buffer
192 Return the buffer that holds the contents of the undecoded @acronym{MIME}
196 @findex mm-handle-type
197 Return the parsed @code{Content-Type} of the part.
199 @item mm-handle-encoding
200 @findex mm-handle-encoding
201 Return the @code{Content-Transfer-Encoding} of the part.
203 @item mm-handle-undisplayer
204 @findex mm-handle-undisplayer
205 Return the object that can be used to remove the displayed part (if it
208 @item mm-handle-set-undisplayer
209 @findex mm-handle-set-undisplayer
210 Set the undisplayer object.
212 @item mm-handle-disposition
213 @findex mm-handle-disposition
214 Return the parsed @code{Content-Disposition} of the part.
216 @item mm-get-content-id
217 Returns the handle(s) referred to by @code{Content-ID}.
225 Functions for displaying, removing and saving.
228 @item mm-display-part
229 @findex mm-display-part
233 @findex mm-remove-part
234 Remove the part (if it has been displayed).
237 @findex mm-inlinable-p
238 Say whether a @acronym{MIME} type can be displayed inline.
240 @item mm-automatic-display-p
241 @findex mm-automatic-display-p
242 Say whether a @acronym{MIME} type should be displayed automatically.
244 @item mm-destroy-part
245 @findex mm-destroy-part
246 Free all resources occupied by a part.
250 Offer to save the part in a file.
254 Offer to pipe the part to some process.
256 @item mm-interactively-view-part
257 @findex mm-interactively-view-part
258 Prompt for a mailcap method to use to view the part.
263 @node Display Customization
264 @section Display Customization
268 @item mm-inline-media-tests
269 @vindex mm-inline-media-tests
270 This is an alist where the key is a @acronym{MIME} type, the second element
271 is a function to display the part @dfn{inline} (i.e., inside Emacs), and
272 the third element is a form to be @code{eval}ed to say whether the part
273 can be displayed inline.
275 This variable specifies whether a part @emph{can} be displayed inline,
276 and, if so, how to do it. It does not say whether parts are
277 @emph{actually} displayed inline.
279 @item mm-inlined-types
280 @vindex mm-inlined-types
281 This, on the other hand, says what types are to be displayed inline, if
282 they satisfy the conditions set by the variable above. It's a list of
283 @acronym{MIME} media types.
285 @item mm-automatic-display
286 @vindex mm-automatic-display
287 This is a list of types that are to be displayed ``automatically'', but
288 only if the above variable allows it. That is, only inlinable parts can
289 be displayed automatically.
291 @item mm-automatic-external-display
292 @vindex mm-automatic-external-display
293 This is a list of types that will be displayed automatically in an
296 @item mm-keep-viewer-alive-types
297 @vindex mm-keep-viewer-alive-types
298 This is a list of media types for which the external viewer will not
299 be killed when selecting a different article.
301 @item mm-attachment-override-types
302 @vindex mm-attachment-override-types
303 Some @acronym{MIME} agents create parts that have a content-disposition of
304 @samp{attachment}. This variable allows overriding that disposition and
305 displaying the part inline. (Note that the disposition is only
306 overridden if we are able to, and want to, display the part inline.)
308 @item mm-discouraged-alternatives
309 @vindex mm-discouraged-alternatives
310 List of @acronym{MIME} types that are discouraged when viewing
311 @samp{multipart/alternative}. Viewing agents are supposed to view the
312 last possible part of a message, as that is supposed to be the richest.
313 However, users may prefer other types instead, and this list says what
314 types are most unwanted. If, for instance, @samp{text/html} parts are
315 very unwanted, and @samp{text/richtext} parts are somewhat unwanted,
316 you could say something like:
319 (setq mm-discouraged-alternatives
320 '("text/html" "text/richtext")
322 (remove "text/html" mm-automatic-display))
325 @item mm-inline-large-images
326 @vindex mm-inline-large-images
327 When displaying inline images that are larger than the window, Emacs
328 does not enable scrolling, which means that you cannot see the whole
329 image. To prevent this, the library tries to determine the image size
330 before displaying it inline, and if it doesn't fit the window, the
331 library will display it externally (e.g. with @samp{ImageMagick} or
332 @samp{xv}). Setting this variable to @code{t} disables this check and
333 makes the library display all inline images as inline, regardless of
336 @item mm-inline-override-types
337 @vindex mm-inline-override-types
338 @code{mm-inlined-types} may include regular expressions, for example to
339 specify that all @samp{text/.*} parts be displayed inline. If a user
340 prefers to have a type that matches such a regular expression be treated
341 as an attachment, that can be accomplished by setting this variable to a
342 list containing that type. For example assuming @code{mm-inlined-types}
343 includes @samp{text/.*}, then including @samp{text/html} in this
344 variable will cause @samp{text/html} parts to be treated as attachments.
346 @item mm-text-html-renderer
347 @vindex mm-text-html-renderer
348 This selects the function used to render @acronym{HTML}. The predefined
349 renderers are selected by the symbols @code{w3},
350 @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more
351 information about emacs-w3m}, @code{links}, @code{lynx},
352 @code{w3m-standalone} or @code{html2text}. If @code{nil} use an
353 external viewer. You can also specify a function, which will be
354 called with a @acronym{MIME} handle as the argument.
356 @item mm-inline-text-html-with-images
357 @vindex mm-inline-text-html-with-images
358 Some @acronym{HTML} mails might have the trick of spammers using
359 @samp{<img>} tags. It is likely to be intended to verify whether you
360 have read the mail. You can prevent your personal informations from
361 leaking by setting this option to @code{nil} (which is the default).
362 It is currently ignored by Emacs/w3. For emacs-w3m, you may use the
363 command @kbd{t} on the image anchor to show an image even if it is
364 @code{nil}.@footnote{The command @kbd{T} will load all images. If you
365 have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i}
368 @item mm-w3m-safe-url-regexp
369 @vindex mm-w3m-safe-url-regexp
370 A regular expression that matches safe URL names, i.e. URLs that are
371 unlikely to leak personal information when rendering @acronym{HTML}
372 email (the default value is @samp{\\`cid:}). If @code{nil} consider
375 @item mm-inline-text-html-with-w3m-keymap
376 @vindex mm-inline-text-html-with-w3m-keymap
377 You can use emacs-w3m command keys in the inlined text/html part by
378 setting this option to non-@code{nil}. The default value is @code{t}.
380 @item mm-external-terminal-program
381 @vindex mm-external-terminal-program
382 The program used to start an external terminal.
384 @item mm-enable-external
385 @vindex mm-enable-external
386 Indicate whether external @acronym{MIME} handlers should be used.
388 If @code{t}, all defined external @acronym{MIME} handlers are used. If
389 @code{nil}, files are saved to disk (@code{mailcap-save-binary-file}).
390 If it is the symbol @code{ask}, you are prompted before the external
391 @acronym{MIME} handler is invoked.
393 When you launch an attachment through mailcap (@pxref{mailcap}) an
394 attempt is made to use a safe viewer with the safest options---this isn't
395 the case if you save it to disk and launch it in a different way
396 (command line or double-clicking). Anyhow, if you want to be sure not
397 to launch any external programs, set this variable to @code{nil} or
402 @node Files and Directories
403 @section Files and Directories
407 @item mm-default-directory
408 @vindex mm-default-directory
409 The default directory for saving attachments. If @code{nil} use
410 @code{default-directory}.
412 @item mm-tmp-directory
413 @vindex mm-tmp-directory
414 Directory for storing temporary files.
416 @item mm-file-name-rewrite-functions
417 @vindex mm-file-name-rewrite-functions
418 A list of functions used for rewriting file names of @acronym{MIME}
419 parts. Each function is applied successively to the file name.
420 Ready-made functions include
423 @item mm-file-name-delete-control
424 @findex mm-file-name-delete-control
425 Delete all control characters.
427 @item mm-file-name-delete-gotchas
428 @findex mm-file-name-delete-gotchas
429 Delete characters that could have unintended consequences when used
430 with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and
431 @samp{-}, @samp{.} as the first character.
433 @item mm-file-name-delete-whitespace
434 @findex mm-file-name-delete-whitespace
435 Remove all whitespace.
437 @item mm-file-name-trim-whitespace
438 @findex mm-file-name-trim-whitespace
439 Remove leading and trailing whitespace.
441 @item mm-file-name-collapse-whitespace
442 @findex mm-file-name-collapse-whitespace
443 Collapse multiple whitespace characters.
445 @item mm-file-name-replace-whitespace
446 @findex mm-file-name-replace-whitespace
447 @vindex mm-file-name-replace-whitespace
448 Replace whitespace with underscores. Set the variable
449 @code{mm-file-name-replace-whitespace} to any other string if you do
450 not like underscores.
453 The standard Emacs functions @code{capitalize}, @code{downcase},
454 @code{upcase} and @code{upcase-initials} might also prove useful.
456 @item mm-path-name-rewrite-functions
457 @vindex mm-path-name-rewrite-functions
458 List of functions used for rewriting the full file names of @acronym{MIME}
459 parts. This is used when viewing parts externally, and is meant for
460 transforming the absolute name so that non-compliant programs can find
461 the file where it's saved.
468 Here's an example viewer for displaying @code{text/enriched} inline:
471 (defun mm-display-enriched-inline (handle)
474 (mm-insert-part handle)
475 (save-window-excursion
476 (enriched-decode (point-min) (point-max))
477 (setq text (buffer-string))))
478 (mm-insert-inline handle text)))
481 We see that the function takes a @acronym{MIME} handle as its parameter. It
482 then goes to a temporary buffer, inserts the text of the part, does some
483 work on the text, stores the result, goes back to the buffer it was
484 called from and inserts the result.
486 The two important helper functions here are @code{mm-insert-part} and
487 @code{mm-insert-inline}. The first function inserts the text of the
488 handle in the current buffer. It handles charset and/or content
489 transfer decoding. The second function just inserts whatever text you
490 tell it to insert, but it also sets things up so that the text can be
491 ``undisplayed'' in a convenient manner.
497 @cindex MIME Composing
499 @cindex MIME Meta Language
501 Creating a @acronym{MIME} message is boring and non-trivial. Therefore,
502 a library called @code{mml} has been defined that parses a language
503 called @acronym{MML} (@acronym{MIME} Meta Language) and generates
504 @acronym{MIME} messages.
506 @findex mml-generate-mime
507 The main interface function is @code{mml-generate-mime}. It will
508 examine the contents of the current (narrowed-to) buffer and return a
509 string containing the @acronym{MIME} message.
512 * Simple MML Example:: An example @acronym{MML} document.
513 * MML Definition:: All valid @acronym{MML} elements.
514 * Advanced MML Example:: Another example @acronym{MML} document.
515 * Encoding Customization:: Variables that affect encoding.
516 * Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}.
517 * Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa.
518 * Flowed text:: Soft and hard newlines.
522 @node Simple MML Example
523 @section Simple MML Example
525 Here's a simple @samp{multipart/alternative}:
528 <#multipart type=alternative>
529 This is a plain text part.
530 <#part type=text/enriched>
531 <center>This is a centered enriched part</center>
535 After running this through @code{mml-generate-mime}, we get this:
538 Content-Type: multipart/alternative; boundary="=-=-="
544 This is a plain text part.
547 Content-Type: text/enriched
550 <center>This is a centered enriched part</center>
557 @section MML Definition
559 The @acronym{MML} language is very simple. It looks a bit like an SGML
560 application, but it's not.
562 The main concept of @acronym{MML} is the @dfn{part}. Each part can be of a
563 different type or use a different charset. The way to delineate a part
564 is with a @samp{<#part ...>} tag. Multipart parts can be introduced
565 with the @samp{<#multipart ...>} tag. Parts are ended by the
566 @samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the
567 @samp{<#part ...>} tags are also closed by the next open tag.
569 There's also the @samp{<#external ...>} tag. These introduce
570 @samp{external/message-body} parts.
572 Each tag can contain zero or more parameters on the form
573 @samp{parameter=value}. The values may be enclosed in quotation marks,
574 but that's not necessary unless the value contains white space. So
575 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
577 The following parameters have meaning in @acronym{MML}; parameters that have no
578 meaning are ignored. The @acronym{MML} parameter names are the same as the
579 @acronym{MIME} parameter names; the things in the parentheses say which
580 header it will be used in.
584 The @acronym{MIME} type of the part (@code{Content-Type}).
587 Use the contents of the file in the body of the part
588 (@code{Content-Disposition}).
591 The contents of the body of the part are to be encoded in the character
592 set specified (@code{Content-Type}). @xref{Charset Translation}.
595 Might be used to suggest a file name if the part is to be saved
596 to a file (@code{Content-Type}).
599 Valid values are @samp{inline} and @samp{attachment}
600 (@code{Content-Disposition}).
603 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
604 @samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset
608 A description of the part (@code{Content-Description}).
611 RFC822 date when the part was created (@code{Content-Disposition}).
613 @item modification-date
614 RFC822 date when the part was modified (@code{Content-Disposition}).
617 RFC822 date when the part was read (@code{Content-Disposition}).
620 Who to encrypt/sign the part to. This field is used to override any
621 auto-detection based on the To/CC headers.
624 Identity used to sign the part. This field is used to override the
628 The size (in octets) of the part (@code{Content-Disposition}).
631 What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp}
635 What technology to encrypt this @acronym{MML} part with (@code{smime},
636 @code{pgp} or @code{pgpmime})
640 Parameters for @samp{text/plain}:
644 Formatting parameter for the text, valid values include @samp{fixed}
645 (the default) and @samp{flowed}. Normally you do not specify this
646 manually, since it requires the textual body to be formatted in a
647 special way described in RFC 2646. @xref{Flowed text}.
650 Parameters for @samp{application/octet-stream}:
654 Type of the part; informal---meant for human readers
655 (@code{Content-Type}).
658 Parameters for @samp{message/external-body}:
662 A word indicating the supported access mechanism by which the file may
663 be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
664 @samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.)
667 The RFC822 date after which the file may no longer be fetched.
668 (@code{Content-Type}.)
671 The size (in octets) of the file. (@code{Content-Type}.)
674 Valid values are @samp{read} and @samp{read-write}
675 (@code{Content-Type}).
679 Parameters for @samp{sign=smime}:
684 File containing key and certificate for signer.
688 Parameters for @samp{encrypt=smime}:
693 File containing certificate for recipient.
698 @node Advanced MML Example
699 @section Advanced MML Example
701 Here's a complex multipart message. It's a @samp{multipart/mixed} that
702 contains many parts, one of which is a @samp{multipart/alternative}.
705 <#multipart type=mixed>
706 <#part type=image/jpeg filename=~/rms.jpg disposition=inline>
707 <#multipart type=alternative>
708 This is a plain text part.
709 <#part type=text/enriched name=enriched.txt>
710 <center>This is a centered enriched part</center>
712 This is a new plain text part.
713 <#part disposition=attachment>
714 This plain text part is an attachment.
718 And this is the resulting @acronym{MIME} message:
721 Content-Type: multipart/mixed; boundary="=-=-="
729 Content-Type: image/jpeg;
731 Content-Disposition: inline;
733 Content-Transfer-Encoding: base64
735 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
736 Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
737 AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
738 BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
739 RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
740 qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
741 AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
742 AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
743 sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
744 2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
745 5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
746 L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
747 34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
748 tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
749 7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
750 pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
751 jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
754 Content-Type: multipart/alternative; boundary="==-=-="
760 This is a plain text part.
763 Content-Type: text/enriched;
767 <center>This is a centered enriched part</center>
773 This is a new plain text part.
776 Content-Disposition: attachment
779 This plain text part is an attachment.
784 @node Encoding Customization
785 @section Encoding Customization
789 @item mm-body-charset-encoding-alist
790 @vindex mm-body-charset-encoding-alist
791 Mapping from @acronym{MIME} charset to encoding to use. This variable is
792 usually used except, e.g., when other requirements force a specific
793 encoding (digitally signed messages require 7bit encodings). The
797 ((iso-2022-jp . 7bit)
798 (iso-2022-jp-2 . 7bit)
804 As an example, if you do not want to have ISO-8859-1 characters
805 quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to
806 this variable. You can override this setting on a per-message basis
807 by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}).
809 @item mm-coding-system-priorities
810 @vindex mm-coding-system-priorities
811 Prioritize coding systems to use for outgoing messages. The default
812 is @code{nil}, which means to use the defaults in Emacs, but is
813 @code{(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8)} when
814 running Emacs in the Japanese language environment. It is a list of
815 coding system symbols (aliases of coding systems are also allowed, use
816 @kbd{M-x describe-coding-system} to make sure you are specifying correct
817 coding system names). For example, if you have configured Emacs
818 to prefer UTF-8, but wish that outgoing messages should be sent in
819 ISO-8859-1 if possible, you can set this variable to
820 @code{(iso-8859-1)}. You can override this setting on a per-message
821 basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}).
823 @item mm-content-transfer-encoding-defaults
824 @vindex mm-content-transfer-encoding-defaults
825 Mapping from @acronym{MIME} types to encoding to use. This variable is usually
826 used except, e.g., when other requirements force a safer encoding
827 (digitally signed messages require 7bit encoding). Besides the normal
828 @acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for
829 each case the most efficient of quoted-printable and base64 should be
832 @code{qp-or-base64} has another effect. It will fold long lines so that
833 MIME parts may not be broken by MTA. So do @code{quoted-printable} and
836 Note that it affects body encoding only when a part is a raw forwarded
837 message (which will be made by @code{gnus-summary-mail-forward} with the
838 arg 2 for example) or is neither the @samp{text/*} type nor the
839 @samp{message/*} type. Even though in those cases, you can override
840 this setting on a per-message basis by using the @code{encoding}
841 @acronym{MML} tag (@pxref{MML Definition}).
843 @item mm-use-ultra-safe-encoding
844 @vindex mm-use-ultra-safe-encoding
845 When this is non-@code{nil}, it means that textual parts are encoded as
846 quoted-printable if they contain lines longer than 76 characters or
847 starting with "From " in the body. Non-7bit encodings (8bit, binary)
848 are generally disallowed. This reduce the probability that a non-8bit
849 clean MTA or MDA changes the message. This should never be set
850 directly, but bound by other functions when necessary (e.g., when
851 encoding messages that are to be digitally signed).
855 @node Charset Translation
856 @section Charset Translation
859 During translation from @acronym{MML} to @acronym{MIME}, for each
860 @acronym{MIME} part which has been composed inside Emacs, an appropriate
861 charset has to be chosen.
863 @vindex mail-parse-charset
864 If you are running a non-@sc{mule} Emacs, this process is simple: If the
865 part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset
866 given by @code{mail-parse-charset} (a symbol) is used. (Never set this
867 variable directly, though. If you want to change the default charset,
868 please consult the documentation of the package which you use to process
869 @acronym{MIME} messages.
870 @xref{Various Message Variables, , Various Message Variables, message,
871 Message Manual}, for example.)
872 If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is
878 @vindex mm-mime-mule-charset-alist
879 Things are slightly more complicated when running Emacs with @sc{mule}
880 support. In this case, a list of the @sc{mule} charsets used in the
881 part is obtained, and the @sc{mule} charsets are translated to
882 @acronym{MIME} charsets by consulting the table provided by Emacs itself
883 or the variable @code{mm-mime-mule-charset-alist} for XEmacs.
884 If this results in a single @acronym{MIME} charset, this is used to encode
885 the part. But if the resulting list of @acronym{MIME} charsets contains more
886 than one element, two things can happen: If it is possible to encode the
887 part via UTF-8, this charset is used. (For this, Emacs must support
888 the @code{utf-8} coding system, and the part must consist entirely of
889 characters which have Unicode counterparts.) If UTF-8 is not available
890 for some reason, the part is split into several ones, so that each one
891 can be encoded with a single @acronym{MIME} charset. The part can only be
892 split at line boundaries, though---if more than one @acronym{MIME} charset is
893 required to encode a single line, it is not possible to encode the part.
895 When running Emacs with @sc{mule} support, the preferences for which
896 coding system to use is inherited from Emacs itself. This means that
897 if Emacs is set up to prefer UTF-8, it will be used when encoding
898 messages. You can modify this by altering the
899 @code{mm-coding-system-priorities} variable though (@pxref{Encoding
902 The charset to be used can be overridden by setting the @code{charset}
903 @acronym{MML} tag (@pxref{MML Definition}) when composing the message.
905 The encoding of characters (quoted-printable, 8bit etc) is orthogonal
906 to the discussion here, and is controlled by the variables
907 @code{mm-body-charset-encoding-alist} and
908 @code{mm-content-transfer-encoding-defaults} (@pxref{Encoding
915 A (multipart) @acronym{MIME} message can be converted to @acronym{MML}
916 with the @code{mime-to-mml} function. It works on the message in the
917 current buffer, and substitutes @acronym{MML} markup for @acronym{MIME}
918 boundaries. Non-textual parts do not have their contents in the buffer,
919 but instead have the contents in separate buffers that are referred to
920 from the @acronym{MML} tags.
923 An @acronym{MML} message can be converted back to @acronym{MIME} by the
924 @code{mml-to-mime} function.
926 These functions are in certain senses ``lossy''---you will not get back
927 an identical message if you run @code{mime-to-mml} and then
928 @code{mml-to-mime}. Not only will trivial things like the order of the
929 headers differ, but the contents of the headers may also be different.
930 For instance, the original message may use base64 encoding on text,
931 while @code{mml-to-mime} may decide to use quoted-printable encoding, and
934 In essence, however, these two functions should be the inverse of each
935 other. The resulting contents of the message should remain equivalent,
941 @cindex format=flowed
943 The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines}
944 variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines,
945 emacs, Emacs Manual}) when encoding a message, and the
946 ``format=flowed'' Content-Type parameter when decoding a message.
948 On encoding text, regardless of @code{use-hard-newlines}, lines
949 terminated by soft newline characters are filled together and wrapped
950 after the column decided by @code{fill-flowed-encode-column}.
951 Quotation marks (matching @samp{^>* ?}) are respected. The variable
952 controls how the text will look in a client that does not support
953 flowed text, the default is to wrap after 66 characters. If hard
954 newline characters are not present in the buffer, no flow encoding
957 On decoding flowed text, lines with soft newline characters are filled
958 together and wrapped after the column decided by
959 @code{fill-flowed-display-column}. The default is to wrap after
964 @vindex mm-fill-flowed
965 If non-@code{nil} a format=flowed article will be displayed flowed.
969 @node Interface Functions
970 @chapter Interface Functions
971 @cindex interface functions
974 The @code{mail-parse} library is an abstraction over the actual
975 low-level libraries that are described in the next chapter.
977 Standards change, and so programs have to change to fit in the new
978 mold. For instance, RFC2045 describes a syntax for the
979 @code{Content-Type} header that only allows @acronym{ASCII} characters in the
980 parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme
981 for continuation headers and non-@acronym{ASCII} characters.
983 The traditional way to deal with this is just to update the library
984 functions to parse the new syntax. However, this is sometimes the wrong
985 thing to do. In some instances it may be vital to be able to understand
986 both the old syntax as well as the new syntax, and if there is only one
987 library, one must choose between the old version of the library and the
988 new version of the library.
990 The Emacs @acronym{MIME} library takes a different tack. It defines a
991 series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el}
992 and so on) that parses strictly according to the corresponding
993 standard. However, normal programs would not use the functions
994 provided by these libraries directly, but instead use the functions
995 provided by the @code{mail-parse} library. The functions in this
996 library are just aliases to the corresponding functions in the latest
997 low-level libraries. Using this scheme, programs get a consistent
998 interface they can use, and library developers are free to create
999 write code that handles new standards.
1001 The following functions are defined by this library:
1004 @item mail-header-parse-content-type
1005 @findex mail-header-parse-content-type
1006 Parse a @code{Content-Type} header and return a list on the following
1011 (attribute1 . value1)
1012 (attribute2 . value2)
1019 (mail-header-parse-content-type
1020 "image/gif; name=\"b980912.gif\"")
1021 @result{} ("image/gif" (name . "b980912.gif"))
1024 @item mail-header-parse-content-disposition
1025 @findex mail-header-parse-content-disposition
1026 Parse a @code{Content-Disposition} header and return a list on the same
1027 format as the function above.
1029 @item mail-content-type-get
1030 @findex mail-content-type-get
1031 Takes two parameters---a list on the format above, and an attribute.
1032 Returns the value of the attribute.
1035 (mail-content-type-get
1036 '("image/gif" (name . "b980912.gif")) 'name)
1037 @result{} "b980912.gif"
1040 @item mail-header-encode-parameter
1041 @findex mail-header-encode-parameter
1042 Takes a parameter string and returns an encoded version of the string.
1043 This is used for parameters in headers like @code{Content-Type} and
1044 @code{Content-Disposition}.
1046 @item mail-header-remove-comments
1047 @findex mail-header-remove-comments
1048 Return a comment-free version of a header.
1051 (mail-header-remove-comments
1052 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1053 @result{} "Gnus/5.070027 "
1056 @item mail-header-remove-whitespace
1057 @findex mail-header-remove-whitespace
1058 Remove linear white space from a header. Space inside quoted strings
1059 and comments is preserved.
1062 (mail-header-remove-whitespace
1063 "image/gif; name=\"Name with spaces\"")
1064 @result{} "image/gif;name=\"Name with spaces\""
1067 @item mail-header-get-comment
1068 @findex mail-header-get-comment
1069 Return the last comment in a header.
1072 (mail-header-get-comment
1073 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1074 @result{} "Finnish Landrace"
1077 @item mail-header-parse-address
1078 @findex mail-header-parse-address
1079 Parse an address and return a list containing the mailbox and the
1083 (mail-header-parse-address
1084 "Hrvoje Niksic <hniksic@@srce.hr>")
1085 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
1088 @item mail-header-parse-addresses
1089 @findex mail-header-parse-addresses
1090 Parse a string with list of addresses and return a list of elements like
1091 the one described above.
1094 (mail-header-parse-addresses
1095 "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
1096 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
1097 ("sb@@metis.no" . "Steinar Bang"))
1100 @item mail-header-parse-date
1101 @findex mail-header-parse-date
1102 Parse a date string and return an Emacs time structure.
1104 @item mail-narrow-to-head
1105 @findex mail-narrow-to-head
1106 Narrow the buffer to the header section of the buffer. Point is placed
1107 at the beginning of the narrowed buffer.
1109 @item mail-header-narrow-to-field
1110 @findex mail-header-narrow-to-field
1111 Narrow the buffer to the header under point. Understands continuation
1114 @item mail-header-fold-field
1115 @findex mail-header-fold-field
1116 Fold the header under point.
1118 @item mail-header-unfold-field
1119 @findex mail-header-unfold-field
1120 Unfold the header under point.
1122 @item mail-header-field-value
1123 @findex mail-header-field-value
1124 Return the value of the field under point.
1126 @item mail-encode-encoded-word-region
1127 @findex mail-encode-encoded-word-region
1128 Encode the non-@acronym{ASCII} words in the region. For instance,
1129 @samp{Na@"{@dotless{i}}ve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
1131 @item mail-encode-encoded-word-buffer
1132 @findex mail-encode-encoded-word-buffer
1133 Encode the non-@acronym{ASCII} words in the current buffer. This function is
1134 meant to be called narrowed to the headers of a message.
1136 @item mail-encode-encoded-word-string
1137 @findex mail-encode-encoded-word-string
1138 Encode the words that need encoding in a string, and return the result.
1141 (mail-encode-encoded-word-string
1142 "This is na@"{@dotless{i}}ve, baby")
1143 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
1146 @item mail-decode-encoded-word-region
1147 @findex mail-decode-encoded-word-region
1148 Decode the encoded words in the region.
1150 @item mail-decode-encoded-word-string
1151 @findex mail-decode-encoded-word-string
1152 Decode the encoded words in the string and return the result.
1155 (mail-decode-encoded-word-string
1156 "This is =?iso-8859-1?q?na=EFve,?= baby")
1157 @result{} "This is na@"{@dotless{i}}ve, baby"
1162 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
1163 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented
1164 in the subsequent sections.
1168 @node Basic Functions
1169 @chapter Basic Functions
1171 This chapter describes the basic, ground-level functions for parsing and
1172 handling. Covered here is parsing @code{From} lines, removing comments
1173 from header lines, decoding encoded words, parsing date headers and so
1174 on. High-level functionality is dealt with in the first chapter
1175 (@pxref{Decoding and Viewing}).
1178 * rfc2045:: Encoding @code{Content-Type} headers.
1179 * rfc2231:: Parsing @code{Content-Type} headers.
1180 * ietf-drums:: Handling mail headers defined by RFC822bis.
1181 * rfc2047:: En/decoding encoded words in headers.
1182 * time-date:: Functions for parsing dates and manipulating time.
1183 * qp:: Quoted-Printable en/decoding.
1184 * base64:: Base64 en/decoding.
1185 * binhex:: Binhex decoding.
1186 * uudecode:: Uuencode decoding.
1187 * yenc:: Yenc decoding.
1188 * rfc1843:: Decoding HZ-encoded text.
1189 * mailcap:: How parts are displayed is specified by the @file{.mailcap} file
1196 RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would
1197 imagine that there would be a lot to implement. But there isn't, since
1198 most of the implementation details are delegated to the subsequent
1201 So @file{rfc2045.el} has only a single function:
1204 @item rfc2045-encode-string
1205 @findex rfc2045-encode-string
1206 Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
1207 @var{value} will be quoted if there are non-safe characters in it.
1214 RFC2231 defines a syntax for the @code{Content-Type} and
1215 @code{Content-Disposition} headers. Its snappy name is @dfn{MIME
1216 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
1219 In short, these headers look something like this:
1222 Content-Type: application/x-stuff;
1223 title*0*=us-ascii'en'This%20is%20even%20more%20;
1224 title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1228 They usually aren't this bad, though.
1230 The following functions are defined by this library:
1233 @item rfc2231-parse-string
1234 @findex rfc2231-parse-string
1235 Parse a @code{Content-Type} header and return a list describing its
1239 (rfc2231-parse-string
1240 "application/x-stuff;
1241 title*0*=us-ascii'en'This%20is%20even%20more%20;
1242 title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1243 title*2=\"isn't it!\"")
1244 @result{} ("application/x-stuff"
1245 (title . "This is even more ***fun*** isn't it!"))
1248 @item rfc2231-get-value
1249 @findex rfc2231-get-value
1250 Takes one of the lists on the format above and returns
1251 the value of the specified attribute.
1253 @item rfc2231-encode-string
1254 @findex rfc2231-encode-string
1255 Encode a parameter in headers likes @code{Content-Type} and
1256 @code{Content-Disposition}.
1264 @dfn{drums} is an IETF working group that is working on the replacement
1267 The functions provided by this library include:
1270 @item ietf-drums-remove-comments
1271 @findex ietf-drums-remove-comments
1272 Remove the comments from the argument and return the results.
1274 @item ietf-drums-remove-whitespace
1275 @findex ietf-drums-remove-whitespace
1276 Remove linear white space from the string and return the results.
1277 Spaces inside quoted strings and comments are left untouched.
1279 @item ietf-drums-get-comment
1280 @findex ietf-drums-get-comment
1281 Return the last most comment from the string.
1283 @item ietf-drums-parse-address
1284 @findex ietf-drums-parse-address
1285 Parse an address string and return a list that contains the mailbox and
1286 the plain text name.
1288 @item ietf-drums-parse-addresses
1289 @findex ietf-drums-parse-addresses
1290 Parse a string that contains any number of comma-separated addresses and
1291 return a list that contains mailbox/plain text pairs.
1293 @item ietf-drums-parse-date
1294 @findex ietf-drums-parse-date
1295 Parse a date string and return an Emacs time structure.
1297 @item ietf-drums-narrow-to-header
1298 @findex ietf-drums-narrow-to-header
1299 Narrow the buffer to the header section of the current buffer.
1307 RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how
1308 non-@acronym{ASCII} text in headers are to be encoded. This is actually rather
1309 complicated, so a number of variables are necessary to tweak what this
1312 The following variables are tweakable:
1315 @item rfc2047-header-encoding-alist
1316 @vindex rfc2047-header-encoding-alist
1317 This is an alist of header / encoding-type pairs. Its main purpose is
1318 to prevent encoding of certain headers.
1320 The keys can either be header regexps, or @code{t}.
1322 The values can be @code{nil}, in which case the header(s) in question
1323 won't be encoded, @code{mime}, which means that they will be encoded, or
1324 @code{address-mime}, which means the header(s) will be encoded carefully
1325 assuming they contain addresses.
1327 @item rfc2047-charset-encoding-alist
1328 @vindex rfc2047-charset-encoding-alist
1329 RFC2047 specifies two forms of encoding---@code{Q} (a
1330 Quoted-Printable-like encoding) and @code{B} (base64). This alist
1331 specifies which charset should use which encoding.
1333 @item rfc2047-encode-function-alist
1334 @vindex rfc2047-encode-function-alist
1335 This is an alist of encoding / function pairs. The encodings are
1336 @code{Q}, @code{B} and @code{nil}.
1338 @item rfc2047-encoded-word-regexp
1339 @vindex rfc2047-encoded-word-regexp
1340 When decoding words, this library looks for matches to this regexp.
1342 @item rfc2047-encode-encoded-words
1343 @vindex rfc2047-encode-encoded-words
1344 The boolean variable specifies whether encoded words
1345 (e.g. @samp{=?hello?=}) should be encoded again.
1349 Those were the variables, and these are this functions:
1352 @item rfc2047-narrow-to-field
1353 @findex rfc2047-narrow-to-field
1354 Narrow the buffer to the header on the current line.
1356 @item rfc2047-encode-message-header
1357 @findex rfc2047-encode-message-header
1358 Should be called narrowed to the header of a message. Encodes according
1359 to @code{rfc2047-header-encoding-alist}.
1361 @item rfc2047-encode-region
1362 @findex rfc2047-encode-region
1363 Encodes all encodable words in the region specified.
1365 @item rfc2047-encode-string
1366 @findex rfc2047-encode-string
1367 Encode a string and return the results.
1369 @item rfc2047-decode-region
1370 @findex rfc2047-decode-region
1371 Decode the encoded words in the region.
1373 @item rfc2047-decode-string
1374 @findex rfc2047-decode-string
1375 Decode a string and return the results.
1377 @item rfc2047-encode-parameter
1378 @findex rfc2047-encode-parameter
1379 Encode a parameter in the RFC2047-like style. This is a replacement for
1380 the @code{rfc2231-encode-string} function. @xref{rfc2231}.
1382 When attaching files as @acronym{MIME} parts, we should use the RFC2231
1383 encoding to specify the file names containing non-@acronym{ASCII}
1384 characters. However, many mail softwares don't support it in practice
1385 and recipients won't be able to extract files with correct names.
1386 Instead, the RFC2047-like encoding is acceptable generally. This
1387 function provides the very RFC2047-like encoding, resigning to such a
1388 regrettable trend. To use it, put the following line in your
1389 @file{~/.gnus.el} file:
1392 (defalias 'mail-header-encode-parameter 'rfc2047-encode-parameter)
1401 While not really a part of the @acronym{MIME} library, it is convenient to
1402 document this library here. It deals with parsing @code{Date} headers
1403 and manipulating time. (Not by using tesseracts, though, I'm sorry to
1406 These functions convert between five formats: A date string, an Emacs
1407 time structure, a decoded time list, a second number, and a day number.
1409 Here's a bunch of time/date/second/day examples:
1412 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
1413 @result{} (54 21 12 12 9 1998 6 nil 7200)
1415 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
1416 @result{} (13818 19266)
1418 (time-to-seconds '(13818 19266))
1419 @result{} 905595714.0
1421 (seconds-to-time 905595714.0)
1422 @result{} (13818 19266 0)
1424 (time-to-days '(13818 19266))
1427 (days-to-time 729644)
1428 @result{} (961933 65536)
1430 (time-since '(13818 19266))
1433 (time-less-p '(13818 19266) '(13818 19145))
1436 (subtract-time '(13818 19266) '(13818 19145))
1439 (days-between "Sat Sep 12 12:21:54 1998 +0200"
1440 "Sat Sep 07 12:21:54 1998 +0200")
1443 (date-leap-year-p 2000)
1446 (time-to-day-in-year '(13818 19266))
1449 (time-to-number-of-days
1451 (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
1452 @result{} 4.146122685185185
1455 And finally, we have @code{safe-date-to-time}, which does the same as
1456 @code{date-to-time}, but returns a zero time if the date is
1457 syntactically malformed.
1459 The five data representations used are the following:
1463 An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12
1464 12:21:54 1998 +0200"}.
1467 An internal Emacs time. For instance: @code{(13818 26466)}.
1470 A floating point representation of the internal Emacs time. For
1471 instance: @code{905595714.0}.
1474 An integer number representing the number of days since 00000101. For
1475 instance: @code{729644}.
1478 A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t
1482 All the examples above represent the same moment.
1484 These are the functions available:
1488 Take a date and return a time.
1490 @item time-to-seconds
1491 Take a time and return seconds.
1493 @item seconds-to-time
1494 Take seconds and return a time.
1497 Take a time and return days.
1500 Take days and return a time.
1503 Take a date and return days.
1505 @item time-to-number-of-days
1506 Take a time and return the number of days that represents.
1508 @item safe-date-to-time
1509 Take a date and return a time. If the date is not syntactically valid,
1510 return a ``zero'' time.
1513 Take two times and say whether the first time is less (i. e., earlier)
1514 than the second time.
1517 Take a time and return a time saying how long it was since that time.
1520 Take two times and subtract the second from the first. I. e., return
1521 the time between the two times.
1524 Take two days and return the number of days between those two days.
1526 @item date-leap-year-p
1527 Take a year number and say whether it's a leap year.
1529 @item time-to-day-in-year
1530 Take a time and return the day number within the year that the time is
1539 This library deals with decoding and encoding Quoted-Printable text.
1541 Very briefly explained, qp encoding means translating all 8-bit
1542 characters (and lots of control characters) into things that look like
1543 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
1546 The following functions are defined by the library:
1549 @item quoted-printable-decode-region
1550 @findex quoted-printable-decode-region
1551 QP-decode all the encoded text in the specified region.
1553 @item quoted-printable-decode-string
1554 @findex quoted-printable-decode-string
1555 Decode the QP-encoded text in a string and return the results.
1557 @item quoted-printable-encode-region
1558 @findex quoted-printable-encode-region
1559 QP-encode all the encodable characters in the specified region. The third
1560 optional parameter @var{fold} specifies whether to fold long lines.
1561 (Long here means 72.)
1563 @item quoted-printable-encode-string
1564 @findex quoted-printable-encode-string
1565 QP-encode all the encodable characters in a string and return the
1575 Base64 is an encoding that encodes three bytes into four characters,
1576 thereby increasing the size by about 33%. The alphabet used for
1577 encoding is very resistant to mangling during transit.
1579 The following functions are defined by this library:
1582 @item base64-encode-region
1583 @findex base64-encode-region
1584 base64 encode the selected region. Return the length of the encoded
1585 text. Optional third argument @var{no-line-break} means do not break
1586 long lines into shorter lines.
1588 @item base64-encode-string
1589 @findex base64-encode-string
1590 base64 encode a string and return the result.
1592 @item base64-decode-region
1593 @findex base64-decode-region
1594 base64 decode the selected region. Return the length of the decoded
1595 text. If the region can't be decoded, return @code{nil} and don't
1598 @item base64-decode-string
1599 @findex base64-decode-string
1600 base64 decode a string and return the result. If the string can't be
1601 decoded, @code{nil} is returned.
1612 @code{binhex} is an encoding that originated in Macintosh environments.
1613 The following function is supplied to deal with these:
1616 @item binhex-decode-region
1617 @findex binhex-decode-region
1618 Decode the encoded text in the region. If given a third parameter, only
1619 decode the @code{binhex} header and return the filename.
1628 @code{uuencode} is probably still the most popular encoding of binaries
1629 used on Usenet, although @code{base64} rules the mail world.
1631 The following function is supplied by this package:
1634 @item uudecode-decode-region
1635 @findex uudecode-decode-region
1636 Decode the text in the region.
1644 @code{yenc} is used for encoding binaries on Usenet. The following
1645 function is supplied by this package:
1648 @item yenc-decode-region
1649 @findex yenc-decode-region
1650 Decode the encoded text in the region.
1661 RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages. In
1662 essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this:
1665 This sentence is in @acronym{ASCII}.
1666 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
1669 Simple enough, and widely used in China.
1671 The following functions are available to handle this encoding:
1674 @item rfc1843-decode-region
1675 Decode HZ-encoded text in the region.
1677 @item rfc1843-decode-string
1678 Decode a HZ-encoded string and return the result.
1686 The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message
1687 handlers and describes how elements are supposed to be displayed.
1688 Here's an example file:
1692 audio/wav; wavplayer %s
1693 application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc
1696 This says that all image files should be displayed with @code{gimp},
1697 that WAVE audio files should be played by @code{wavplayer}, and that
1698 MS-WORD files should be inlined by @code{catdoc}.
1700 The @code{mailcap} library parses this file, and provides functions for
1704 @item mailcap-mime-data
1705 @vindex mailcap-mime-data
1706 This variable is an alist of alists containing backup viewing rules.
1710 Interface functions:
1713 @item mailcap-parse-mailcaps
1714 @findex mailcap-parse-mailcaps
1715 Parse the @file{~/.mailcap} file.
1717 @item mailcap-mime-info
1718 Takes a @acronym{MIME} type as its argument and returns the matching viewer.
1728 The Emacs @acronym{MIME} library implements handling of various elements
1729 according to a (somewhat) large number of RFCs, drafts and standards
1730 documents. This chapter lists the relevant ones. They can all be
1731 fetched from @uref{http://quimby.gnus.org/notes/}.
1736 Standard for the Format of ARPA Internet Text Messages.
1739 Standard for Interchange of USENET Messages
1742 Format of Internet Message Bodies
1748 Message Header Extensions for Non-@acronym{ASCII} Text
1751 Registration Procedures
1754 Conformance Criteria and Examples
1757 @acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets,
1758 Languages, and Continuations
1761 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1762 @acronym{ASCII} characters
1764 @item draft-ietf-drums-msg-fmt-05.txt
1765 Draft for the successor of RFC822
1768 The @acronym{MIME} Multipart/Related Content-type
1771 The Multipart/Report Content Type for the Reporting of Mail System
1772 Administrative Messages
1775 Communicating Presentation Information in Internet Messages: The
1776 Content-Disposition Header Field
1779 Documentation of the text/plain format parameter for flowed text.
1795 @c coding: iso-8859-1