*** empty log message ***
[emacs.git] / man / emacs-mime.texi
blob35dbe1e5797257982eda91745e6544bfa5a5e063
1 \input texinfo
3 @setfilename ../info/emacs-mime
4 @settitle Emacs MIME Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
9 @copying
10 This file documents the Emacs MIME interface functionality.
12 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
13           Free Software Foundation, Inc.
15 @quotation
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.
32 @end quotation
33 @end copying
35 @dircategory Emacs
36 @direntry
37 * Emacs MIME: (emacs-mime).   Emacs MIME de/composition library.
38 @end direntry
39 @iftex
40 @finalout
41 @end iftex
42 @setchapternewpage odd
44 @titlepage
45 @title Emacs MIME Manual
47 @author by Lars Magne Ingebrigtsen
48 @page
49 @vskip 0pt plus 1filll
50 @insertcopying
51 @end titlepage
53 @node Top
54 @top Emacs MIME
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.
72 @menu
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.
79 @end menu
82 @node Decoding and Viewing
83 @chapter Decoding and Viewing
85 This chapter deals with decoding and viewing @acronym{MIME} messages on a
86 higher level.
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.
92 @menu
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.
100 @end menu
103 @node Dissection
104 @section Dissection
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.
111 @node Non-MIME
112 @section Non-MIME
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,
120 @lisp
121 (require 'mm-uu)
122 (add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
123 @end lisp
125 @table @code
126 @item postscript
127 @findex postscript
128 Postscript file.
130 @item uu
131 @findex uu
132 Uuencoded file.
134 @item binhex
135 @findex binhex
136 Binhex encoded file.
138 @item yenc
139 @findex yenc
140 Yenc encoded file.
142 @item shar
143 @findex shar
144 Shar archive file.
146 @item forward
147 @findex forward
148 Non-@acronym{MIME} forwarded message.
150 @item gnatsweb
151 @findex gnatsweb
152 Gnatsweb attachment.
154 @item pgp-signed
155 @findex pgp-signed
156 @acronym{PGP} signed clear text.
158 @item pgp-encrypted
159 @findex pgp-encrypted
160 @acronym{PGP} encrypted clear text.
162 @item pgp-key
163 @findex pgp-key
164 @acronym{PGP} public keys.
166 @item emacs-sources
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}.
172 @item diff
173 @vindex diff
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}.
179 @end table
181 @node Handles
182 @section Handles
184 A @acronym{MIME} handle is a list that fully describes a @acronym{MIME}
185 component.
187 The following macros can be used to access elements in a handle:
189 @table @code
190 @item mm-handle-buffer
191 @findex mm-handle-buffer
192 Return the buffer that holds the contents of the undecoded @acronym{MIME}
193 part.
195 @item mm-handle-type
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
206 has been displayed).
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}.
219 @end table
222 @node Display
223 @section Display
225 Functions for displaying, removing and saving.
227 @table @code
228 @item mm-display-part
229 @findex mm-display-part
230 Display the part.
232 @item mm-remove-part
233 @findex mm-remove-part
234 Remove the part (if it has been displayed).
236 @item mm-inlinable-p
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.
248 @item mm-save-part
249 @findex mm-save-part
250 Offer to save the part in a file.
252 @item mm-pipe-part
253 @findex mm-pipe-part
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.
260 @end table
263 @node Display Customization
264 @section Display Customization
266 @table @code
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
294 external viewer.
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:
318 @lisp
319 (setq mm-discouraged-alternatives
320       '("text/html" "text/richtext")
321       mm-automatic-display
322       (remove "text/html" mm-automatic-display))
323 @end lisp
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
334 their size.
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}
366 or @kbd{I} instead.}
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
373 all URLs safe.
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
398 @code{ask}.
400 @end table
402 @node Files and Directories
403 @section Files and Directories
405 @table @code
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
422 @table @code
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.
451 @end table
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.
463 @end table
465 @node New Viewers
466 @section New Viewers
468 Here's an example viewer for displaying @code{text/enriched} inline:
470 @lisp
471 (defun mm-display-enriched-inline (handle)
472   (let (text)
473     (with-temp-buffer
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)))
479 @end lisp
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.
494 @node Composing
495 @chapter Composing
496 @cindex Composing
497 @cindex MIME Composing
498 @cindex MML
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.
511 @menu
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.
519 @end menu
522 @node Simple MML Example
523 @section Simple MML Example
525 Here's a simple @samp{multipart/alternative}:
527 @example
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>
532 <#/multipart>
533 @end example
535 After running this through @code{mml-generate-mime}, we get this:
537 @example
538 Content-Type: multipart/alternative; boundary="=-=-="
541 --=-=-=
544 This is a plain text part.
546 --=-=-=
547 Content-Type: text/enriched
550 <center>This is a centered enriched part</center>
552 --=-=-=--
553 @end example
556 @node MML Definition
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.
582 @table @samp
583 @item type
584 The @acronym{MIME} type of the part (@code{Content-Type}).
586 @item filename
587 Use the contents of the file in the body of the part
588 (@code{Content-Disposition}).
590 @item charset
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}.
594 @item name
595 Might be used to suggest a file name if the part is to be saved
596 to a file (@code{Content-Type}).
598 @item disposition
599 Valid values are @samp{inline} and @samp{attachment}
600 (@code{Content-Disposition}).
602 @item encoding
603 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
604 @samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset
605 Translation}.
607 @item description
608 A description of the part (@code{Content-Description}).
610 @item creation-date
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}).
616 @item read-date
617 RFC822 date when the part was read (@code{Content-Disposition}).
619 @item recipients
620 Who to encrypt/sign the part to.  This field is used to override any
621 auto-detection based on the To/CC headers.
623 @item sender
624 Identity used to sign the part.  This field is used to override the
625 default key used.
627 @item size
628 The size (in octets) of the part (@code{Content-Disposition}).
630 @item sign
631 What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp}
632 or @code{pgpmime})
634 @item encrypt
635 What technology to encrypt this @acronym{MML} part with (@code{smime},
636 @code{pgp} or @code{pgpmime})
638 @end table
640 Parameters for @samp{text/plain}:
642 @table @samp
643 @item format
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}.
648 @end table
650 Parameters for @samp{application/octet-stream}:
652 @table @samp
653 @item type
654 Type of the part; informal---meant for human readers
655 (@code{Content-Type}).
656 @end table
658 Parameters for @samp{message/external-body}:
660 @table @samp
661 @item access-type
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}.)
666 @item expiration
667 The RFC822 date after which the file may no longer be fetched.
668 (@code{Content-Type}.)
670 @item size
671 The size (in octets) of the file.  (@code{Content-Type}.)
673 @item permission
674 Valid values are @samp{read} and @samp{read-write}
675 (@code{Content-Type}).
677 @end table
679 Parameters for @samp{sign=smime}:
681 @table @samp
683 @item keyfile
684 File containing key and certificate for signer.
686 @end table
688 Parameters for @samp{encrypt=smime}:
690 @table @samp
692 @item certfile
693 File containing certificate for recipient.
695 @end table
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}.
704 @example
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>
711 <#/multipart>
712 This is a new plain text part.
713 <#part disposition=attachment>
714 This plain text part is an attachment.
715 <#/multipart>
716 @end example
718 And this is the resulting @acronym{MIME} message:
720 @example
721 Content-Type: multipart/mixed; boundary="=-=-="
724 --=-=-=
728 --=-=-=
729 Content-Type: image/jpeg;
730  filename="~/rms.jpg"
731 Content-Disposition: inline;
732  filename="~/rms.jpg"
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==
753 --=-=-=
754 Content-Type: multipart/alternative; boundary="==-=-="
757 --==-=-=
760 This is a plain text part.
762 --==-=-=
763 Content-Type: text/enriched;
764  name="enriched.txt"
767 <center>This is a centered enriched part</center>
769 --==-=-=--
771 --=-=-=
773 This is a new plain text part.
775 --=-=-=
776 Content-Disposition: attachment
779 This plain text part is an attachment.
781 --=-=-=--
782 @end example
784 @node Encoding Customization
785 @section Encoding Customization
787 @table @code
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
794 default is
796 @lisp
797 ((iso-2022-jp . 7bit)
798  (iso-2022-jp-2 . 7bit)
799  (utf-16 . base64)
800  (utf-16be . base64)
801  (utf-16le . base64))
802 @end lisp
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
830 used.
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
834 @code{base64}.
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).
853 @end table
855 @node Charset Translation
856 @section Charset Translation
857 @cindex charsets
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
873 used, of course.
875 @cindex MULE
876 @cindex UTF-8
877 @cindex Unicode
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
900 Customization}).
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
909 Customization}).
911 @node Conversion
912 @section Conversion
914 @findex mime-to-mml
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.
922 @findex mml-to-mime
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
932 so on.
934 In essence, however, these two functions should be the inverse of each
935 other.  The resulting contents of the message should remain equivalent,
936 if not identical.
939 @node Flowed text
940 @section Flowed text
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
955 occurs.
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
960 @code{fill-column}.
965 @node Interface Functions
966 @chapter Interface Functions
967 @cindex interface functions
968 @cindex mail-parse
970 The @code{mail-parse} library is an abstraction over the actual
971 low-level libraries that are described in the next chapter.
973 Standards change, and so programs have to change to fit in the new
974 mold.  For instance, RFC2045 describes a syntax for the
975 @code{Content-Type} header that only allows @acronym{ASCII} characters in the
976 parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
977 for continuation headers and non-@acronym{ASCII} characters.
979 The traditional way to deal with this is just to update the library
980 functions to parse the new syntax.  However, this is sometimes the wrong
981 thing to do.  In some instances it may be vital to be able to understand
982 both the old syntax as well as the new syntax, and if there is only one
983 library, one must choose between the old version of the library and the
984 new version of the library.
986 The Emacs @acronym{MIME} library takes a different tack.  It defines a
987 series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el}
988 and so on) that parses strictly according to the corresponding
989 standard.  However, normal programs would not use the functions
990 provided by these libraries directly, but instead use the functions
991 provided by the @code{mail-parse} library.  The functions in this
992 library are just aliases to the corresponding functions in the latest
993 low-level libraries.  Using this scheme, programs get a consistent
994 interface they can use, and library developers are free to create
995 write code that handles new standards.
997 The following functions are defined by this library:
999 @table @code
1000 @item mail-header-parse-content-type
1001 @findex mail-header-parse-content-type
1002 Parse a @code{Content-Type} header and return a list on the following
1003 format:
1005 @lisp
1006 ("type/subtype"
1007  (attribute1 . value1)
1008  (attribute2 . value2)
1009  ...)
1010 @end lisp
1012 Here's an example:
1014 @example
1015 (mail-header-parse-content-type
1016  "image/gif; name=\"b980912.gif\"")
1017 @result{} ("image/gif" (name . "b980912.gif"))
1018 @end example
1020 @item mail-header-parse-content-disposition
1021 @findex mail-header-parse-content-disposition
1022 Parse a @code{Content-Disposition} header and return a list on the same
1023 format as the function above.
1025 @item mail-content-type-get
1026 @findex mail-content-type-get
1027 Takes two parameters---a list on the format above, and an attribute.
1028 Returns the value of the attribute.
1030 @example
1031 (mail-content-type-get
1032  '("image/gif" (name . "b980912.gif")) 'name)
1033 @result{} "b980912.gif"
1034 @end example
1036 @item mail-header-encode-parameter
1037 @findex mail-header-encode-parameter
1038 Takes a parameter string and returns an encoded version of the string.
1039 This is used for parameters in headers like @code{Content-Type} and
1040 @code{Content-Disposition}.
1042 @item mail-header-remove-comments
1043 @findex mail-header-remove-comments
1044 Return a comment-free version of a header.
1046 @example
1047 (mail-header-remove-comments
1048  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1049 @result{} "Gnus/5.070027  "
1050 @end example
1052 @item mail-header-remove-whitespace
1053 @findex mail-header-remove-whitespace
1054 Remove linear white space from a header.  Space inside quoted strings
1055 and comments is preserved.
1057 @example
1058 (mail-header-remove-whitespace
1059  "image/gif; name=\"Name with spaces\"")
1060 @result{} "image/gif;name=\"Name with spaces\""
1061 @end example
1063 @item mail-header-get-comment
1064 @findex mail-header-get-comment
1065 Return the last comment in a header.
1067 @example
1068 (mail-header-get-comment
1069  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1070 @result{} "Finnish Landrace"
1071 @end example
1073 @item mail-header-parse-address
1074 @findex mail-header-parse-address
1075 Parse an address and return a list containing the mailbox and the
1076 plaintext name.
1078 @example
1079 (mail-header-parse-address
1080  "Hrvoje Niksic <hniksic@@srce.hr>")
1081 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
1082 @end example
1084 @item mail-header-parse-addresses
1085 @findex mail-header-parse-addresses
1086 Parse a string with list of addresses and return a list of elements like
1087 the one described above.
1089 @example
1090 (mail-header-parse-addresses
1091  "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
1092 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
1093      ("sb@@metis.no" . "Steinar Bang"))
1094 @end example
1096 @item mail-header-parse-date
1097 @findex mail-header-parse-date
1098 Parse a date string and return an Emacs time structure.
1100 @item mail-narrow-to-head
1101 @findex mail-narrow-to-head
1102 Narrow the buffer to the header section of the buffer.  Point is placed
1103 at the beginning of the narrowed buffer.
1105 @item mail-header-narrow-to-field
1106 @findex mail-header-narrow-to-field
1107 Narrow the buffer to the header under point.  Understands continuation
1108 headers.
1110 @item mail-header-fold-field
1111 @findex mail-header-fold-field
1112 Fold the header under point.
1114 @item mail-header-unfold-field
1115 @findex mail-header-unfold-field
1116 Unfold the header under point.
1118 @item mail-header-field-value
1119 @findex mail-header-field-value
1120 Return the value of the field under point.
1122 @item mail-encode-encoded-word-region
1123 @findex mail-encode-encoded-word-region
1124 Encode the non-@acronym{ASCII} words in the region.  For instance,
1125 @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
1127 @item mail-encode-encoded-word-buffer
1128 @findex mail-encode-encoded-word-buffer
1129 Encode the non-@acronym{ASCII} words in the current buffer.  This function is
1130 meant to be called narrowed to the headers of a message.
1132 @item mail-encode-encoded-word-string
1133 @findex mail-encode-encoded-word-string
1134 Encode the words that need encoding in a string, and return the result.
1136 @example
1137 (mail-encode-encoded-word-string
1138  "This is naïve, baby")
1139 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
1140 @end example
1142 @item mail-decode-encoded-word-region
1143 @findex mail-decode-encoded-word-region
1144 Decode the encoded words in the region.
1146 @item mail-decode-encoded-word-string
1147 @findex mail-decode-encoded-word-string
1148 Decode the encoded words in the string and return the result.
1150 @example
1151 (mail-decode-encoded-word-string
1152  "This is =?iso-8859-1?q?na=EFve,?= baby")
1153 @result{} "This is naïve, baby"
1154 @end example
1156 @end table
1158 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
1159 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}.  These are documented
1160 in the subsequent sections.
1164 @node Basic Functions
1165 @chapter Basic Functions
1167 This chapter describes the basic, ground-level functions for parsing and
1168 handling.  Covered here is parsing @code{From} lines, removing comments
1169 from header lines, decoding encoded words, parsing date headers and so
1170 on.  High-level functionality is dealt with in the first chapter
1171 (@pxref{Decoding and Viewing}).
1173 @menu
1174 * rfc2045::      Encoding @code{Content-Type} headers.
1175 * rfc2231::      Parsing @code{Content-Type} headers.
1176 * ietf-drums::   Handling mail headers defined by RFC822bis.
1177 * rfc2047::      En/decoding encoded words in headers.
1178 * time-date::    Functions for parsing dates and manipulating time.
1179 * qp::           Quoted-Printable en/decoding.
1180 * base64::       Base64 en/decoding.
1181 * binhex::       Binhex decoding.
1182 * uudecode::     Uuencode decoding.
1183 * yenc::         Yenc decoding.
1184 * rfc1843::      Decoding HZ-encoded text.
1185 * mailcap::      How parts are displayed is specified by the @file{.mailcap} file
1186 @end menu
1189 @node rfc2045
1190 @section rfc2045
1192 RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would
1193 imagine that there would be a lot to implement.  But there isn't, since
1194 most of the implementation details are delegated to the subsequent
1195 RFCs.
1197 So @file{rfc2045.el} has only a single function:
1199 @table @code
1200 @item rfc2045-encode-string
1201 @findex rfc2045-encode-string
1202 Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
1203 @var{value} will be quoted if there are non-safe characters in it.
1204 @end table
1207 @node rfc2231
1208 @section rfc2231
1210 RFC2231 defines a syntax for the @code{Content-Type} and
1211 @code{Content-Disposition} headers.  Its snappy name is @dfn{MIME
1212 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
1213 and Continuations}.
1215 In short, these headers look something like this:
1217 @example
1218 Content-Type: application/x-stuff;
1219  title*0*=us-ascii'en'This%20is%20even%20more%20;
1220  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1221  title*2="isn't it!"
1222 @end example
1224 They usually aren't this bad, though.
1226 The following functions are defined by this library:
1228 @table @code
1229 @item rfc2231-parse-string
1230 @findex rfc2231-parse-string
1231 Parse a @code{Content-Type} header and return a list describing its
1232 elements.
1234 @example
1235 (rfc2231-parse-string
1236  "application/x-stuff;
1237  title*0*=us-ascii'en'This%20is%20even%20more%20;
1238  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1239  title*2=\"isn't it!\"")
1240 @result{} ("application/x-stuff"
1241     (title . "This is even more ***fun*** isn't it!"))
1242 @end example
1244 @item rfc2231-get-value
1245 @findex rfc2231-get-value
1246 Takes one of the lists on the format above and returns
1247 the value of the specified attribute.
1249 @item rfc2231-encode-string
1250 @findex rfc2231-encode-string
1251 Encode a parameter in headers likes @code{Content-Type} and
1252 @code{Content-Disposition}.
1254 @end table
1257 @node ietf-drums
1258 @section ietf-drums
1260 @dfn{drums} is an IETF working group that is working on the replacement
1261 for RFC822.
1263 The functions provided by this library include:
1265 @table @code
1266 @item ietf-drums-remove-comments
1267 @findex ietf-drums-remove-comments
1268 Remove the comments from the argument and return the results.
1270 @item ietf-drums-remove-whitespace
1271 @findex ietf-drums-remove-whitespace
1272 Remove linear white space from the string and return the results.
1273 Spaces inside quoted strings and comments are left untouched.
1275 @item ietf-drums-get-comment
1276 @findex ietf-drums-get-comment
1277 Return the last most comment from the string.
1279 @item ietf-drums-parse-address
1280 @findex ietf-drums-parse-address
1281 Parse an address string and return a list that contains the mailbox and
1282 the plain text name.
1284 @item ietf-drums-parse-addresses
1285 @findex ietf-drums-parse-addresses
1286 Parse a string that contains any number of comma-separated addresses and
1287 return a list that contains mailbox/plain text pairs.
1289 @item ietf-drums-parse-date
1290 @findex ietf-drums-parse-date
1291 Parse a date string and return an Emacs time structure.
1293 @item ietf-drums-narrow-to-header
1294 @findex ietf-drums-narrow-to-header
1295 Narrow the buffer to the header section of the current buffer.
1297 @end table
1300 @node rfc2047
1301 @section rfc2047
1303 RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how
1304 non-@acronym{ASCII} text in headers are to be encoded.  This is actually rather
1305 complicated, so a number of variables are necessary to tweak what this
1306 library does.
1308 The following variables are tweakable:
1310 @table @code
1311 @item rfc2047-header-encoding-alist
1312 @vindex rfc2047-header-encoding-alist
1313 This is an alist of header / encoding-type pairs.  Its main purpose is
1314 to prevent encoding of certain headers.
1316 The keys can either be header regexps, or @code{t}.
1318 The values can be @code{nil}, in which case the header(s) in question
1319 won't be encoded, @code{mime}, which means that they will be encoded, or
1320 @code{address-mime}, which means the header(s) will be encoded carefully
1321 assuming they contain addresses.
1323 @item rfc2047-charset-encoding-alist
1324 @vindex rfc2047-charset-encoding-alist
1325 RFC2047 specifies two forms of encoding---@code{Q} (a
1326 Quoted-Printable-like encoding) and @code{B} (base64).  This alist
1327 specifies which charset should use which encoding.
1329 @item rfc2047-encode-function-alist
1330 @vindex rfc2047-encode-function-alist
1331 This is an alist of encoding / function pairs.  The encodings are
1332 @code{Q}, @code{B} and @code{nil}.
1334 @item rfc2047-encoded-word-regexp
1335 @vindex rfc2047-encoded-word-regexp
1336 When decoding words, this library looks for matches to this regexp.
1338 @item rfc2047-encode-encoded-words
1339 @vindex rfc2047-encode-encoded-words
1340 The boolean variable specifies whether encoded words
1341 (e.g. @samp{=?hello?=}) should be encoded again.
1343 @end table
1345 Those were the variables, and these are this functions:
1347 @table @code
1348 @item rfc2047-narrow-to-field
1349 @findex rfc2047-narrow-to-field
1350 Narrow the buffer to the header on the current line.
1352 @item rfc2047-encode-message-header
1353 @findex rfc2047-encode-message-header
1354 Should be called narrowed to the header of a message.  Encodes according
1355 to @code{rfc2047-header-encoding-alist}.
1357 @item rfc2047-encode-region
1358 @findex rfc2047-encode-region
1359 Encodes all encodable words in the region specified.
1361 @item rfc2047-encode-string
1362 @findex rfc2047-encode-string
1363 Encode a string and return the results.
1365 @item rfc2047-decode-region
1366 @findex rfc2047-decode-region
1367 Decode the encoded words in the region.
1369 @item rfc2047-decode-string
1370 @findex rfc2047-decode-string
1371 Decode a string and return the results.
1373 @item rfc2047-encode-parameter
1374 @findex rfc2047-encode-parameter
1375 Encode a parameter in the RFC2047-like style.  This is a replacement for
1376 the @code{rfc2231-encode-string} function.  @xref{rfc2231}.
1378 When attaching files as @acronym{MIME} parts, we should use the RFC2231
1379 encoding to specify the file names containing non-@acronym{ASCII}
1380 characters.  However, many mail softwares don't support it in practice
1381 and recipients won't be able to extract files with correct names.
1382 Instead, the RFC2047-like encoding is acceptable generally.  This
1383 function provides the very RFC2047-like encoding, resigning to such a
1384 regrettable trend.  To use it, put the following line in your
1385 @file{~/.gnus.el} file:
1387 @lisp
1388 (defalias 'mail-header-encode-parameter 'rfc2047-encode-parameter)
1389 @end lisp
1391 @end table
1394 @node time-date
1395 @section time-date
1397 While not really a part of the @acronym{MIME} library, it is convenient to
1398 document this library here.  It deals with parsing @code{Date} headers
1399 and manipulating time.  (Not by using tesseracts, though, I'm sorry to
1400 say.)
1402 These functions convert between five formats: A date string, an Emacs
1403 time structure, a decoded time list, a second number, and a day number.
1405 Here's a bunch of time/date/second/day examples:
1407 @example
1408 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
1409 @result{} (54 21 12 12 9 1998 6 nil 7200)
1411 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
1412 @result{} (13818 19266)
1414 (time-to-seconds '(13818 19266))
1415 @result{} 905595714.0
1417 (seconds-to-time 905595714.0)
1418 @result{} (13818 19266 0)
1420 (time-to-days '(13818 19266))
1421 @result{} 729644
1423 (days-to-time 729644)
1424 @result{} (961933 65536)
1426 (time-since '(13818 19266))
1427 @result{} (0 430)
1429 (time-less-p '(13818 19266) '(13818 19145))
1430 @result{} nil
1432 (subtract-time '(13818 19266) '(13818 19145))
1433 @result{} (0 121)
1435 (days-between "Sat Sep 12 12:21:54 1998 +0200"
1436               "Sat Sep 07 12:21:54 1998 +0200")
1437 @result{} 5
1439 (date-leap-year-p 2000)
1440 @result{} t
1442 (time-to-day-in-year '(13818 19266))
1443 @result{} 255
1445 (time-to-number-of-days
1446  (time-since
1447   (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
1448 @result{} 4.146122685185185
1449 @end example
1451 And finally, we have @code{safe-date-to-time}, which does the same as
1452 @code{date-to-time}, but returns a zero time if the date is
1453 syntactically malformed.
1455 The five data representations used are the following:
1457 @table @var
1458 @item date
1459 An RFC822 (or similar) date string.  For instance: @code{"Sat Sep 12
1460 12:21:54 1998 +0200"}.
1462 @item time
1463 An internal Emacs time.  For instance: @code{(13818 26466)}.
1465 @item seconds
1466 A floating point representation of the internal Emacs time.  For
1467 instance: @code{905595714.0}.
1469 @item days
1470 An integer number representing the number of days since 00000101.  For
1471 instance: @code{729644}.
1473 @item decoded time
1474 A list of decoded time.  For instance: @code{(54 21 12 12 9 1998 6 t
1475 7200)}.
1476 @end table
1478 All the examples above represent the same moment.
1480 These are the functions available:
1482 @table @code
1483 @item date-to-time
1484 Take a date and return a time.
1486 @item time-to-seconds
1487 Take a time and return seconds.
1489 @item seconds-to-time
1490 Take seconds and return a time.
1492 @item time-to-days
1493 Take a time and return days.
1495 @item days-to-time
1496 Take days and return a time.
1498 @item date-to-day
1499 Take a date and return days.
1501 @item time-to-number-of-days
1502 Take a time and return the number of days that represents.
1504 @item safe-date-to-time
1505 Take a date and return a time.  If the date is not syntactically valid,
1506 return a ``zero'' time.
1508 @item time-less-p
1509 Take two times and say whether the first time is less (i. e., earlier)
1510 than the second time.
1512 @item time-since
1513 Take a time and return a time saying how long it was since that time.
1515 @item subtract-time
1516 Take two times and subtract the second from the first.  I. e., return
1517 the time between the two times.
1519 @item days-between
1520 Take two days and return the number of days between those two days.
1522 @item date-leap-year-p
1523 Take a year number and say whether it's a leap year.
1525 @item time-to-day-in-year
1526 Take a time and return the day number within the year that the time is
1529 @end table
1532 @node qp
1533 @section qp
1535 This library deals with decoding and encoding Quoted-Printable text.
1537 Very briefly explained, qp encoding means translating all 8-bit
1538 characters (and lots of control characters) into things that look like
1539 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
1540 string.
1542 The following functions are defined by the library:
1544 @table @code
1545 @item quoted-printable-decode-region
1546 @findex quoted-printable-decode-region
1547 QP-decode all the encoded text in the specified region.
1549 @item quoted-printable-decode-string
1550 @findex quoted-printable-decode-string
1551 Decode the QP-encoded text in a string and return the results.
1553 @item quoted-printable-encode-region
1554 @findex quoted-printable-encode-region
1555 QP-encode all the encodable characters in the specified region.  The third
1556 optional parameter @var{fold} specifies whether to fold long lines.
1557 (Long here means 72.)
1559 @item quoted-printable-encode-string
1560 @findex quoted-printable-encode-string
1561 QP-encode all the encodable characters in a string and return the
1562 results.
1564 @end table
1567 @node base64
1568 @section base64
1569 @cindex base64
1571 Base64 is an encoding that encodes three bytes into four characters,
1572 thereby increasing the size by about 33%.  The alphabet used for
1573 encoding is very resistant to mangling during transit.
1575 The following functions are defined by this library:
1577 @table @code
1578 @item base64-encode-region
1579 @findex base64-encode-region
1580 base64 encode the selected region.  Return the length of the encoded
1581 text.  Optional third argument @var{no-line-break} means do not break
1582 long lines into shorter lines.
1584 @item base64-encode-string
1585 @findex base64-encode-string
1586 base64 encode a string and return the result.
1588 @item base64-decode-region
1589 @findex base64-decode-region
1590 base64 decode the selected region.  Return the length of the decoded
1591 text.  If the region can't be decoded, return @code{nil} and don't
1592 modify the buffer.
1594 @item base64-decode-string
1595 @findex base64-decode-string
1596 base64 decode a string and return the result.  If the string can't be
1597 decoded, @code{nil} is returned.
1599 @end table
1602 @node binhex
1603 @section binhex
1604 @cindex binhex
1605 @cindex Apple
1606 @cindex Macintosh
1608 @code{binhex} is an encoding that originated in Macintosh environments.
1609 The following function is supplied to deal with these:
1611 @table @code
1612 @item binhex-decode-region
1613 @findex binhex-decode-region
1614 Decode the encoded text in the region.  If given a third parameter, only
1615 decode the @code{binhex} header and return the filename.
1617 @end table
1619 @node uudecode
1620 @section uudecode
1621 @cindex uuencode
1622 @cindex uudecode
1624 @code{uuencode} is probably still the most popular encoding of binaries
1625 used on Usenet, although @code{base64} rules the mail world.
1627 The following function is supplied by this package:
1629 @table @code
1630 @item uudecode-decode-region
1631 @findex uudecode-decode-region
1632 Decode the text in the region.
1633 @end table
1636 @node yenc
1637 @section yenc
1638 @cindex yenc
1640 @code{yenc} is used for encoding binaries on Usenet.  The following
1641 function is supplied by this package:
1643 @table @code
1644 @item yenc-decode-region
1645 @findex yenc-decode-region
1646 Decode the encoded text in the region.
1648 @end table
1651 @node rfc1843
1652 @section rfc1843
1653 @cindex rfc1843
1654 @cindex HZ
1655 @cindex Chinese
1657 RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages.  In
1658 essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this:
1660 @example
1661 This sentence is in @acronym{ASCII}.
1662 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
1663 @end example
1665 Simple enough, and widely used in China.
1667 The following functions are available to handle this encoding:
1669 @table @code
1670 @item rfc1843-decode-region
1671 Decode HZ-encoded text in the region.
1673 @item rfc1843-decode-string
1674 Decode a HZ-encoded string and return the result.
1676 @end table
1679 @node mailcap
1680 @section mailcap
1682 The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message
1683 handlers and describes how elements are supposed to be displayed.
1684 Here's an example file:
1686 @example
1687 image/*; gimp -8 %s
1688 audio/wav; wavplayer %s
1689 application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc
1690 @end example
1692 This says that all image files should be displayed with @code{gimp},
1693 that WAVE audio files should be played by @code{wavplayer}, and that
1694 MS-WORD files should be inlined by @code{catdoc}.
1696 The @code{mailcap} library parses this file, and provides functions for
1697 matching types.
1699 @table @code
1700 @item mailcap-mime-data
1701 @vindex mailcap-mime-data
1702 This variable is an alist of alists containing backup viewing rules.
1704 @end table
1706 Interface functions:
1708 @table @code
1709 @item mailcap-parse-mailcaps
1710 @findex mailcap-parse-mailcaps
1711 Parse the @file{~/.mailcap} file.
1713 @item mailcap-mime-info
1714 Takes a @acronym{MIME} type as its argument and returns the matching viewer.
1716 @end table
1721 @node Standards
1722 @chapter Standards
1724 The Emacs @acronym{MIME} library implements handling of various elements
1725 according to a (somewhat) large number of RFCs, drafts and standards
1726 documents.  This chapter lists the relevant ones.  They can all be
1727 fetched from @uref{http://quimby.gnus.org/notes/}.
1729 @table @dfn
1730 @item RFC822
1731 @itemx STD11
1732 Standard for the Format of ARPA Internet Text Messages.
1734 @item RFC1036
1735 Standard for Interchange of USENET Messages
1737 @item RFC2045
1738 Format of Internet Message Bodies
1740 @item RFC2046
1741 Media Types
1743 @item RFC2047
1744 Message Header Extensions for Non-@acronym{ASCII} Text
1746 @item RFC2048
1747 Registration Procedures
1749 @item RFC2049
1750 Conformance Criteria and Examples
1752 @item RFC2231
1753 @acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets,
1754 Languages, and Continuations
1756 @item RFC1843
1757 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1758 @acronym{ASCII} characters
1760 @item draft-ietf-drums-msg-fmt-05.txt
1761 Draft for the successor of RFC822
1763 @item RFC2112
1764 The @acronym{MIME} Multipart/Related Content-type
1766 @item RFC1892
1767 The Multipart/Report Content Type for the Reporting of Mail System
1768 Administrative Messages
1770 @item RFC2183
1771 Communicating Presentation Information in Internet Messages: The
1772 Content-Disposition Header Field
1774 @item RFC2646
1775 Documentation of the text/plain format parameter for flowed text.
1777 @end table
1780 @node Index
1781 @chapter Index
1782 @printindex cp
1784 @summarycontents
1785 @contents
1786 @bye
1789 @c Local Variables:
1790 @c mode: texinfo
1791 @c coding: iso-8859-1
1792 @c End:
1794 @ignore
1795    arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d
1796 @end ignore