(dabbrev-expand): When handling SPC M-/,
[emacs.git] / man / emacs-mime.texi
blobc128ed096c38bd119f7aa3da8d7e195fdac27d51
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
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.1 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 behaviour 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-handle-disposition
217 @findex mm-handle-disposition
218 Return the description of the part.
220 @item mm-get-content-id
221 Returns the handle(s) referred to by @code{Content-ID}.
223 @end table
226 @node Display
227 @section Display
229 Functions for displaying, removing and saving.
231 @table @code
232 @item mm-display-part
233 @findex mm-display-part
234 Display the part.
236 @item mm-remove-part
237 @findex mm-remove-part
238 Remove the part (if it has been displayed).
240 @item mm-inlinable-p
241 @findex mm-inlinable-p
242 Say whether a @acronym{MIME} type can be displayed inline.
244 @item mm-automatic-display-p
245 @findex mm-automatic-display-p
246 Say whether a @acronym{MIME} type should be displayed automatically.
248 @item mm-destroy-part
249 @findex mm-destroy-part
250 Free all resources occupied by a part.
252 @item mm-save-part
253 @findex mm-save-part
254 Offer to save the part in a file.
256 @item mm-pipe-part
257 @findex mm-pipe-part
258 Offer to pipe the part to some process.
260 @item mm-interactively-view-part
261 @findex mm-interactively-view-part
262 Prompt for a mailcap method to use to view the part.
264 @end table
267 @node Display Customization
268 @section Display Customization
270 @table @code
272 @item mm-inline-media-tests
273 @vindex mm-inline-media-tests
274 This is an alist where the key is a @acronym{MIME} type, the second element
275 is a function to display the part @dfn{inline} (i.e., inside Emacs), and
276 the third element is a form to be @code{eval}ed to say whether the part
277 can be displayed inline.
279 This variable specifies whether a part @emph{can} be displayed inline,
280 and, if so, how to do it.  It does not say whether parts are
281 @emph{actually} displayed inline.
283 @item mm-inlined-types
284 @vindex mm-inlined-types
285 This, on the other hand, says what types are to be displayed inline, if
286 they satisfy the conditions set by the variable above.  It's a list of
287 @acronym{MIME} media types.
289 @item mm-automatic-display
290 @vindex mm-automatic-display
291 This is a list of types that are to be displayed ``automatically'', but
292 only if the above variable allows it.  That is, only inlinable parts can
293 be displayed automatically.
295 @item mm-automatic-external-display
296 @vindex mm-automatic-external-display
297 This is a list of types that will be displayed automatically in an
298 external viewer.
300 @item mm-keep-viewer-alive-types
301 @vindex mm-keep-viewer-alive-types
302 This is a list of media types for which the external viewer will not
303 be killed when selecting a different article.
305 @item mm-attachment-override-types
306 @vindex mm-attachment-override-types
307 Some @acronym{MIME} agents create parts that have a content-disposition of
308 @samp{attachment}.  This variable allows overriding that disposition and
309 displaying the part inline.  (Note that the disposition is only
310 overridden if we are able to, and want to, display the part inline.)
312 @item mm-discouraged-alternatives
313 @vindex mm-discouraged-alternatives
314 List of @acronym{MIME} types that are discouraged when viewing
315 @samp{multipart/alternative}.  Viewing agents are supposed to view the
316 last possible part of a message, as that is supposed to be the richest.
317 However, users may prefer other types instead, and this list says what
318 types are most unwanted.  If, for instance, @samp{text/html} parts are
319 very unwanted, and @samp{text/richtext} parts are somewhat unwanted,
320 you could say something like:
322 @lisp
323 (setq mm-discouraged-alternatives
324       '("text/html" "text/richtext")
325       mm-automatic-display
326       (remove "text/html" mm-automatic-display))
327 @end lisp
329 @item mm-inline-large-images
330 @vindex mm-inline-large-images
331 When displaying inline images that are larger than the window, Emacs
332 does not enable scrolling, which means that you cannot see the whole
333 image.  To prevent this, the library tries to determine the image size
334 before displaying it inline, and if it doesn't fit the window, the
335 library will display it externally (e.g. with @samp{ImageMagick} or
336 @samp{xv}).  Setting this variable to @code{t} disables this check and
337 makes the library display all inline images as inline, regardless of
338 their size.
340 @item mm-inline-override-types
341 @vindex mm-inline-override-types
342 @code{mm-inlined-types} may include regular expressions, for example to
343 specify that all @samp{text/.*} parts be displayed inline.  If a user
344 prefers to have a type that matches such a regular expression be treated
345 as an attachment, that can be accomplished by setting this variable to a
346 list containing that type.  For example assuming @code{mm-inlined-types}
347 includes @samp{text/.*}, then including @samp{text/html} in this
348 variable will cause @samp{text/html} parts to be treated as attachments.
350 @item mm-text-html-renderer
351 @vindex mm-text-html-renderer
352 This selects the function used to render @acronym{HTML}.  The predefined
353 renderers are selected by the symbols @code{w3},
354 @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more
355 information about emacs-w3m}, @code{links}, @code{lynx},
356 @code{w3m-standalone} or @code{html2text}.  If @code{nil} use an
357 external viewer.  You can also specify a function, which will be
358 called with a @acronym{MIME} handle as the argument.
360 @item mm-inline-text-html-with-images
361 @vindex mm-inline-text-html-with-images
362 Some @acronym{HTML} mails might have the trick of spammers using
363 @samp{<img>} tags.  It is likely to be intended to verify whether you
364 have read the mail.  You can prevent your personal informations from
365 leaking by setting this option to @code{nil} (which is the default).
366 It is currently ignored by Emacs/w3.  For emacs-w3m, you may use the
367 command @kbd{t} on the image anchor to show an image even if it is
368 @code{nil}.@footnote{The command @kbd{T} will load all images.  If you
369 have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i}
370 or @kbd{I} instead.}
372 @item mm-w3m-safe-url-regexp
373 @vindex mm-w3m-safe-url-regexp
374 A regular expression that matches safe URL names, i.e. URLs that are
375 unlikely to leak personal information when rendering @acronym{HTML}
376 email (the default value is @samp{\\`cid:}).  If @code{nil} consider
377 all URLs safe.
379 @item mm-inline-text-html-with-w3m-keymap
380 @vindex mm-inline-text-html-with-w3m-keymap
381 You can use emacs-w3m command keys in the inlined text/html part by
382 setting this option to non-@code{nil}.  The default value is @code{t}.
384 @item mm-external-terminal-program
385 @vindex mm-external-terminal-program
386 The program used to start an external terminal.
388 @item mm-enable-external
389 @vindex mm-enable-external
390 Indicate whether external MIME handlers should be used.
392 If @code{t}, all defined external MIME handlers are used.  If
393 @code{nil}, files are saved to disk (@code{mailcap-save-binary-file}).
394 If it is the symbol @code{ask}, you are prompted before the external
395 @acronym{MIME} handler is invoked.
397 When you launch an attachment through mailcap (@pxref{mailcap}) an
398 attempt is made to use a safe viewer with the safest options--this isn't
399 the case if you save it to disk and launch it in a different way
400 (command line or double-clicking).  Anyhow, if you want to be sure not
401 to launch any external programs, set this variable to @code{nil} or
402 @code{ask}.
404 @end table
406 @node Files and Directories
407 @section Files and Directories
409 @table @code
411 @item mm-default-directory
412 @vindex mm-default-directory
413 The default directory for saving attachments.  If @code{nil} use
414 @code{default-directory}.
416 @item mm-tmp-directory
417 @vindex mm-tmp-directory
418 Directory for storing temporary files.
420 @item mm-file-name-rewrite-functions
421 @vindex mm-file-name-rewrite-functions
422 A list of functions used for rewriting file names of @acronym{MIME}
423 parts.  Each function is applied successively to the file name.
424 Ready-made functions include
426 @table @code
427 @item mm-file-name-delete-control
428 @findex mm-file-name-delete-control
429 Delete all control characters.
431 @item mm-file-name-delete-gotchas
432 @findex mm-file-name-delete-gotchas
433 Delete characters that could have unintended consequences when used
434 with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and
435 @samp{-}, @samp{.} as the first character.
437 @item mm-file-name-delete-whitespace
438 @findex mm-file-name-delete-whitespace
439 Remove all whitespace.
441 @item mm-file-name-trim-whitespace
442 @findex mm-file-name-trim-whitespace
443 Remove leading and trailing whitespace.
445 @item mm-file-name-collapse-whitespace
446 @findex mm-file-name-collapse-whitespace
447 Collapse multiple whitespace characters.
449 @item mm-file-name-replace-whitespace
450 @findex mm-file-name-replace-whitespace
451 @vindex mm-file-name-replace-whitespace
452 Replace whitespace with underscores.  Set the variable
453 @code{mm-file-name-replace-whitespace} to any other string if you do
454 not like underscores.
455 @end table
457 The standard Emacs functions @code{capitalize}, @code{downcase},
458 @code{upcase} and @code{upcase-initials} might also prove useful.
460 @item mm-path-name-rewrite-functions
461 @vindex mm-path-name-rewrite-functions
462 List of functions used for rewriting the full file names of @acronym{MIME}
463 parts.  This is used when viewing parts externally, and is meant for
464 transforming the absolute name so that non-compliant programs can find
465 the file where it's saved.
467 @end table
469 @node New Viewers
470 @section New Viewers
472 Here's an example viewer for displaying @code{text/enriched} inline:
474 @lisp
475 (defun mm-display-enriched-inline (handle)
476   (let (text)
477     (with-temp-buffer
478       (mm-insert-part handle)
479       (save-window-excursion
480         (enriched-decode (point-min) (point-max))
481         (setq text (buffer-string))))
482     (mm-insert-inline handle text)))
483 @end lisp
485 We see that the function takes a @acronym{MIME} handle as its parameter.  It
486 then goes to a temporary buffer, inserts the text of the part, does some
487 work on the text, stores the result, goes back to the buffer it was
488 called from and inserts the result.
490 The two important helper functions here are @code{mm-insert-part} and
491 @code{mm-insert-inline}.  The first function inserts the text of the
492 handle in the current buffer.  It handles charset and/or content
493 transfer decoding.  The second function just inserts whatever text you
494 tell it to insert, but it also sets things up so that the text can be
495 ``undisplayed'' in a convenient manner.
498 @node Composing
499 @chapter Composing
500 @cindex Composing
501 @cindex MIME Composing
502 @cindex MML
503 @cindex MIME Meta Language
505 Creating a @acronym{MIME} message is boring and non-trivial.  Therefore,
506 a library called @code{mml} has been defined that parses a language
507 called @acronym{MML} (@acronym{MIME} Meta Language) and generates
508 @acronym{MIME} messages.
510 @findex mml-generate-mime
511 The main interface function is @code{mml-generate-mime}.  It will
512 examine the contents of the current (narrowed-to) buffer and return a
513 string containing the @acronym{MIME} message.
515 @menu
516 * Simple MML Example::             An example @acronym{MML} document.
517 * MML Definition::                 All valid @acronym{MML} elements.
518 * Advanced MML Example::           Another example @acronym{MML} document.
519 * Encoding Customization::         Variables that affect encoding.
520 * Charset Translation::            How charsets are mapped from @sc{mule} to @acronym{MIME}.
521 * Conversion::                     Going from @acronym{MIME} to @acronym{MML} and vice versa.
522 * Flowed text::                    Soft and hard newlines.
523 @end menu
526 @node Simple MML Example
527 @section Simple MML Example
529 Here's a simple @samp{multipart/alternative}:
531 @example
532 <#multipart type=alternative>
533 This is a plain text part.
534 <#part type=text/enriched>
535 <center>This is a centered enriched part</center>
536 <#/multipart>
537 @end example
539 After running this through @code{mml-generate-mime}, we get this:
541 @example
542 Content-Type: multipart/alternative; boundary="=-=-="
545 --=-=-=
548 This is a plain text part.
550 --=-=-=
551 Content-Type: text/enriched
554 <center>This is a centered enriched part</center>
556 --=-=-=--
557 @end example
560 @node MML Definition
561 @section MML Definition
563 The @acronym{MML} language is very simple.  It looks a bit like an SGML
564 application, but it's not.
566 The main concept of @acronym{MML} is the @dfn{part}.  Each part can be of a
567 different type or use a different charset.  The way to delineate a part
568 is with a @samp{<#part ...>} tag.  Multipart parts can be introduced
569 with the @samp{<#multipart ...>} tag.  Parts are ended by the
570 @samp{<#/part>} or @samp{<#/multipart>} tags.  Parts started with the
571 @samp{<#part ...>} tags are also closed by the next open tag.
573 There's also the @samp{<#external ...>} tag.  These introduce
574 @samp{external/message-body} parts.
576 Each tag can contain zero or more parameters on the form
577 @samp{parameter=value}.  The values may be enclosed in quotation marks,
578 but that's not necessary unless the value contains white space.  So
579 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
581 The following parameters have meaning in @acronym{MML}; parameters that have no
582 meaning are ignored.  The @acronym{MML} parameter names are the same as the
583 @acronym{MIME} parameter names; the things in the parentheses say which
584 header it will be used in.
586 @table @samp
587 @item type
588 The @acronym{MIME} type of the part (@code{Content-Type}).
590 @item filename
591 Use the contents of the file in the body of the part
592 (@code{Content-Disposition}).
594 @item charset
595 The contents of the body of the part are to be encoded in the character
596 set specified (@code{Content-Type}). @xref{Charset Translation}.
598 @item name
599 Might be used to suggest a file name if the part is to be saved
600 to a file (@code{Content-Type}).
602 @item disposition
603 Valid values are @samp{inline} and @samp{attachment}
604 (@code{Content-Disposition}).
606 @item encoding
607 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
608 @samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset
609 Translation}.
611 @item description
612 A description of the part (@code{Content-Description}).
614 @item creation-date
615 RFC822 date when the part was created (@code{Content-Disposition}).
617 @item modification-date
618 RFC822 date when the part was modified (@code{Content-Disposition}).
620 @item read-date
621 RFC822 date when the part was read (@code{Content-Disposition}).
623 @item recipients
624 Who to encrypt/sign the part to.  This field is used to override any
625 auto-detection based on the To/CC headers.
627 @item sender
628 Identity used to sign the part.  This field is used to override the
629 default key used.
631 @item size
632 The size (in octets) of the part (@code{Content-Disposition}).
634 @item sign
635 What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp}
636 or @code{pgpmime})
638 @item encrypt
639 What technology to encrypt this @acronym{MML} part with (@code{smime},
640 @code{pgp} or @code{pgpmime})
642 @end table
644 Parameters for @samp{text/plain}:
646 @table @samp
647 @item format
648 Formatting parameter for the text, valid values include @samp{fixed}
649 (the default) and @samp{flowed}.  Normally you do not specify this
650 manually, since it requires the textual body to be formatted in a
651 special way described in RFC 2646.  @xref{Flowed text}.
652 @end table
654 Parameters for @samp{application/octet-stream}:
656 @table @samp
657 @item type
658 Type of the part; informal---meant for human readers
659 (@code{Content-Type}).
660 @end table
662 Parameters for @samp{message/external-body}:
664 @table @samp
665 @item access-type
666 A word indicating the supported access mechanism by which the file may
667 be obtained.  Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
668 @samp{localfile}, and @samp{mailserver}.  (@code{Content-Type}.)
670 @item expiration
671 The RFC822 date after which the file may no longer be fetched.
672 (@code{Content-Type}.)
674 @item size
675 The size (in octets) of the file.  (@code{Content-Type}.)
677 @item permission
678 Valid values are @samp{read} and @samp{read-write}
679 (@code{Content-Type}).
681 @end table
683 Parameters for @samp{sign=smime}:
685 @table @samp
687 @item keyfile
688 File containing key and certificate for signer.
690 @end table
692 Parameters for @samp{encrypt=smime}:
694 @table @samp
696 @item certfile
697 File containing certificate for recipient.
699 @end table
702 @node Advanced MML Example
703 @section Advanced MML Example
705 Here's a complex multipart message.  It's a @samp{multipart/mixed} that
706 contains many parts, one of which is a @samp{multipart/alternative}.
708 @example
709 <#multipart type=mixed>
710 <#part type=image/jpeg filename=~/rms.jpg disposition=inline>
711 <#multipart type=alternative>
712 This is a plain text part.
713 <#part type=text/enriched name=enriched.txt>
714 <center>This is a centered enriched part</center>
715 <#/multipart>
716 This is a new plain text part.
717 <#part disposition=attachment>
718 This plain text part is an attachment.
719 <#/multipart>
720 @end example
722 And this is the resulting @acronym{MIME} message:
724 @example
725 Content-Type: multipart/mixed; boundary="=-=-="
728 --=-=-=
732 --=-=-=
733 Content-Type: image/jpeg;
734  filename="~/rms.jpg"
735 Content-Disposition: inline;
736  filename="~/rms.jpg"
737 Content-Transfer-Encoding: base64
739 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
740 Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
741 AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
742 BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
743 RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
744 qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
745 AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
746 AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
747 sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
748 2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
749 5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
750 L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
751 34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
752 tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
753 7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
754 pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
755 jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
757 --=-=-=
758 Content-Type: multipart/alternative; boundary="==-=-="
761 --==-=-=
764 This is a plain text part.
766 --==-=-=
767 Content-Type: text/enriched;
768  name="enriched.txt"
771 <center>This is a centered enriched part</center>
773 --==-=-=--
775 --=-=-=
777 This is a new plain text part.
779 --=-=-=
780 Content-Disposition: attachment
783 This plain text part is an attachment.
785 --=-=-=--
786 @end example
788 @node Encoding Customization
789 @section Encoding Customization
791 @table @code
793 @item mm-body-charset-encoding-alist
794 @vindex mm-body-charset-encoding-alist
795 Mapping from @acronym{MIME} charset to encoding to use.  This variable is
796 usually used except, e.g., when other requirements force a specific
797 encoding (digitally signed messages require 7bit encodings).  The
798 default is 
800 @lisp
801 ((iso-2022-jp . 7bit)
802  (iso-2022-jp-2 . 7bit)
803  (utf-16 . base64)
804  (utf-16be . base64)
805  (utf-16le . base64))
806 @end lisp
808 As an example, if you do not want to have ISO-8859-1 characters
809 quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to
810 this variable.  You can override this setting on a per-message basis
811 by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}).
813 @item mm-coding-system-priorities
814 @vindex mm-coding-system-priorities
815 Prioritize coding systems to use for outgoing messages.  The default
816 is @code{nil}, which means to use the defaults in Emacs.  It is a list of
817 coding system symbols (aliases of coding systems are also allowed, use
818 @kbd{M-x describe-coding-system} to make sure you are specifying correct
819 coding system names).  For example, if you have configured Emacs
820 to prefer UTF-8, but wish that outgoing messages should be sent in
821 ISO-8859-1 if possible, you can set this variable to
822 @code{(iso-8859-1)}.  You can override this setting on a per-message
823 basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}).
825 @item mm-content-transfer-encoding-defaults
826 @vindex mm-content-transfer-encoding-defaults
827 Mapping from @acronym{MIME} types to encoding to use.  This variable is usually
828 used except, e.g., when other requirements force a safer encoding
829 (digitally signed messages require 7bit encoding).  Besides the normal
830 @acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for
831 each case the most efficient of quoted-printable and base64 should be
832 used.
834 @code{qp-or-base64} has another effect.  It will fold long lines so that
835 MIME parts may not be broken by MTA.  So do @code{quoted-printable} and
836 @code{base64}.
838 Note that it affects body encoding only when a part is a raw forwarded
839 message (which will be made by @code{gnus-summary-mail-forward} with the
840 arg 2 for example) or is neither the @samp{text/*} type nor the
841 @samp{message/*} type.  Even though in those cases, you can override
842 this setting on a per-message basis by using the @code{encoding}
843 @acronym{MML} tag (@pxref{MML Definition}).
845 @item mm-use-ultra-safe-encoding
846 @vindex mm-use-ultra-safe-encoding
847 When this is non-@code{nil}, it means that textual parts are encoded as
848 quoted-printable if they contain lines longer than 76 characters or
849 starting with "From " in the body.  Non-7bit encodings (8bit, binary)
850 are generally disallowed.  This reduce the probability that a non-8bit
851 clean MTA or MDA changes the message.  This should never be set
852 directly, but bound by other functions when necessary (e.g., when
853 encoding messages that are to be digitally signed).
855 @end table
857 @node Charset Translation
858 @section Charset Translation
859 @cindex charsets
861 During translation from @acronym{MML} to @acronym{MIME}, for each
862 @acronym{MIME} part which has been composed inside Emacs, an appropriate
863 charset has to be chosen.
865 @vindex mail-parse-charset
866 If you are running a non-@sc{mule} Emacs, this process is simple: If the
867 part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset
868 given by @code{mail-parse-charset} (a symbol) is used.  (Never set this
869 variable directly, though.  If you want to change the default charset,
870 please consult the documentation of the package which you use to process
871 @acronym{MIME} messages.
872 @xref{Various Message Variables, , Various Message Variables, message,
873       Message Manual}, for example.)
874 If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is
875 used, of course.
877 @cindex MULE
878 @cindex UTF-8
879 @cindex Unicode
880 @vindex mm-mime-mule-charset-alist
881 Things are slightly more complicated when running Emacs with @sc{mule}
882 support.  In this case, a list of the @sc{mule} charsets used in the
883 part is obtained, and the @sc{mule} charsets are translated to @acronym{MIME}
884 charsets by consulting the variable @code{mm-mime-mule-charset-alist}.
885 If this results in a single @acronym{MIME} charset, this is used to encode
886 the part.  But if the resulting list of @acronym{MIME} charsets contains more
887 than one element, two things can happen: If it is possible to encode the
888 part via UTF-8, this charset is used.  (For this, Emacs must support
889 the @code{utf-8} coding system, and the part must consist entirely of
890 characters which have Unicode counterparts.)  If UTF-8 is not available
891 for some reason, the part is split into several ones, so that each one
892 can be encoded with a single @acronym{MIME} charset.  The part can only be
893 split at line boundaries, though---if more than one @acronym{MIME} charset is
894 required to encode a single line, it is not possible to encode the part.
896 When running Emacs with @sc{mule} support, the preferences for which
897 coding system to use is inherited from Emacs itself.  This means that
898 if Emacs is set up to prefer UTF-8, it will be used when encoding
899 messages.  You can modify this by altering the
900 @code{mm-coding-system-priorities} variable though (@pxref{Encoding
901 Customization}).
903 The charset to be used can be overridden by setting the @code{charset}
904 @acronym{MML} tag (@pxref{MML Definition}) when composing the message.
906 The encoding of characters (quoted-printable, 8bit etc) is orthogonal
907 to the discussion here, and is controlled by the variables
908 @code{mm-body-charset-encoding-alist} and
909 @code{mm-content-transfer-encoding-defaults} (@pxref{Encoding
910 Customization}).
912 @node Conversion
913 @section Conversion
915 @findex mime-to-mml
916 A (multipart) @acronym{MIME} message can be converted to @acronym{MML}
917 with the @code{mime-to-mml} function.  It works on the message in the
918 current buffer, and substitutes @acronym{MML} markup for @acronym{MIME}
919 boundaries.  Non-textual parts do not have their contents in the buffer,
920 but instead have the contents in separate buffers that are referred to
921 from the @acronym{MML} tags.
923 @findex mml-to-mime
924 An @acronym{MML} message can be converted back to @acronym{MIME} by the
925 @code{mml-to-mime} function.
927 These functions are in certain senses ``lossy''---you will not get back
928 an identical message if you run @code{mime-to-mml} and then
929 @code{mml-to-mime}.  Not only will trivial things like the order of the
930 headers differ, but the contents of the headers may also be different.
931 For instance, the original message may use base64 encoding on text,
932 while @code{mml-to-mime} may decide to use quoted-printable encoding, and
933 so on.
935 In essence, however, these two functions should be the inverse of each
936 other.  The resulting contents of the message should remain equivalent,
937 if not identical.
940 @node Flowed text
941 @section Flowed text
942 @cindex format=flowed
944 The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines}
945 variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines,
946 emacs, Emacs Manual}) when encoding a message, and the
947 ``format=flowed'' Content-Type parameter when decoding a message.
949 On encoding text, regardless of @code{use-hard-newlines}, lines
950 terminated by soft newline characters are filled together and wrapped
951 after the column decided by @code{fill-flowed-encode-column}.
952 Quotation marks (matching @samp{^>* ?}) are respected.  The variable
953 controls how the text will look in a client that does not support
954 flowed text, the default is to wrap after 66 characters.  If hard
955 newline characters are not present in the buffer, no flow encoding
956 occurs.
958 On decoding flowed text, lines with soft newline characters are filled
959 together and wrapped after the column decided by
960 @code{fill-flowed-display-column}.  The default is to wrap after
961 @code{fill-column}.
966 @node Interface Functions
967 @chapter Interface Functions
968 @cindex interface functions
969 @cindex mail-parse
971 The @code{mail-parse} library is an abstraction over the actual
972 low-level libraries that are described in the next chapter.
974 Standards change, and so programs have to change to fit in the new
975 mold.  For instance, RFC2045 describes a syntax for the
976 @code{Content-Type} header that only allows @acronym{ASCII} characters in the
977 parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
978 for continuation headers and non-@acronym{ASCII} characters.
980 The traditional way to deal with this is just to update the library
981 functions to parse the new syntax.  However, this is sometimes the wrong
982 thing to do.  In some instances it may be vital to be able to understand
983 both the old syntax as well as the new syntax, and if there is only one
984 library, one must choose between the old version of the library and the
985 new version of the library.
987 The Emacs @acronym{MIME} library takes a different tack.  It defines a
988 series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el}
989 and so on) that parses strictly according to the corresponding
990 standard.  However, normal programs would not use the functions
991 provided by these libraries directly, but instead use the functions
992 provided by the @code{mail-parse} library.  The functions in this
993 library are just aliases to the corresponding functions in the latest
994 low-level libraries.  Using this scheme, programs get a consistent
995 interface they can use, and library developers are free to create
996 write code that handles new standards.
998 The following functions are defined by this library:
1000 @table @code
1001 @item mail-header-parse-content-type
1002 @findex mail-header-parse-content-type
1003 Parse a @code{Content-Type} header and return a list on the following
1004 format:
1006 @lisp
1007 ("type/subtype"
1008  (attribute1 . value1)
1009  (attribute2 . value2)
1010  ...)
1011 @end lisp
1013 Here's an example:
1015 @example
1016 (mail-header-parse-content-type
1017  "image/gif; name=\"b980912.gif\"")
1018 @result{} ("image/gif" (name . "b980912.gif"))
1019 @end example
1021 @item mail-header-parse-content-disposition
1022 @findex mail-header-parse-content-disposition
1023 Parse a @code{Content-Disposition} header and return a list on the same
1024 format as the function above.
1026 @item mail-content-type-get
1027 @findex mail-content-type-get
1028 Takes two parameters---a list on the format above, and an attribute.
1029 Returns the value of the attribute.
1031 @example
1032 (mail-content-type-get
1033  '("image/gif" (name . "b980912.gif")) 'name)
1034 @result{} "b980912.gif"
1035 @end example
1037 @item mail-header-encode-parameter
1038 @findex mail-header-encode-parameter
1039 Takes a parameter string and returns an encoded version of the string.
1040 This is used for parameters in headers like @code{Content-Type} and
1041 @code{Content-Disposition}.
1043 @item mail-header-remove-comments
1044 @findex mail-header-remove-comments
1045 Return a comment-free version of a header.
1047 @example
1048 (mail-header-remove-comments
1049  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1050 @result{} "Gnus/5.070027  "
1051 @end example
1053 @item mail-header-remove-whitespace
1054 @findex mail-header-remove-whitespace
1055 Remove linear white space from a header.  Space inside quoted strings
1056 and comments is preserved.
1058 @example
1059 (mail-header-remove-whitespace
1060  "image/gif; name=\"Name with spaces\"")
1061 @result{} "image/gif;name=\"Name with spaces\""
1062 @end example
1064 @item mail-header-get-comment
1065 @findex mail-header-get-comment
1066 Return the last comment in a header.
1068 @example
1069 (mail-header-get-comment
1070  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1071 @result{} "Finnish Landrace"
1072 @end example
1074 @item mail-header-parse-address
1075 @findex mail-header-parse-address
1076 Parse an address and return a list containing the mailbox and the
1077 plaintext name.
1079 @example
1080 (mail-header-parse-address
1081  "Hrvoje Niksic <hniksic@@srce.hr>")
1082 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
1083 @end example
1085 @item mail-header-parse-addresses
1086 @findex mail-header-parse-addresses
1087 Parse a string with list of addresses and return a list of elements like
1088 the one described above.
1090 @example
1091 (mail-header-parse-addresses
1092  "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
1093 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
1094      ("sb@@metis.no" . "Steinar Bang"))
1095 @end example
1097 @item mail-header-parse-date
1098 @findex mail-header-parse-date
1099 Parse a date string and return an Emacs time structure.
1101 @item mail-narrow-to-head
1102 @findex mail-narrow-to-head
1103 Narrow the buffer to the header section of the buffer.  Point is placed
1104 at the beginning of the narrowed buffer.
1106 @item mail-header-narrow-to-field
1107 @findex mail-header-narrow-to-field
1108 Narrow the buffer to the header under point.  Understands continuation
1109 headers.
1111 @item mail-header-fold-field
1112 @findex mail-header-fold-field
1113 Fold the header under point.
1115 @item mail-header-unfold-field
1116 @findex mail-header-unfold-field
1117 Unfold the header under point.
1119 @item mail-header-field-value
1120 @findex mail-header-field-value
1121 Return the value of the field under point.
1123 @item mail-encode-encoded-word-region
1124 @findex mail-encode-encoded-word-region
1125 Encode the non-@acronym{ASCII} words in the region.  For instance,
1126 @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
1128 @item mail-encode-encoded-word-buffer
1129 @findex mail-encode-encoded-word-buffer
1130 Encode the non-@acronym{ASCII} words in the current buffer.  This function is
1131 meant to be called narrowed to the headers of a message.
1133 @item mail-encode-encoded-word-string
1134 @findex mail-encode-encoded-word-string
1135 Encode the words that need encoding in a string, and return the result.
1137 @example
1138 (mail-encode-encoded-word-string
1139  "This is naïve, baby")
1140 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
1141 @end example
1143 @item mail-decode-encoded-word-region
1144 @findex mail-decode-encoded-word-region
1145 Decode the encoded words in the region.
1147 @item mail-decode-encoded-word-string
1148 @findex mail-decode-encoded-word-string
1149 Decode the encoded words in the string and return the result.
1151 @example
1152 (mail-decode-encoded-word-string
1153  "This is =?iso-8859-1?q?na=EFve,?= baby")
1154 @result{} "This is naïve, baby"
1155 @end example
1157 @end table
1159 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
1160 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}.  These are documented
1161 in the subsequent sections.
1165 @node Basic Functions
1166 @chapter Basic Functions
1168 This chapter describes the basic, ground-level functions for parsing and
1169 handling.  Covered here is parsing @code{From} lines, removing comments
1170 from header lines, decoding encoded words, parsing date headers and so
1171 on.  High-level functionality is dealt with in the next chapter
1172 (@pxref{Decoding and Viewing}).
1174 @menu
1175 * rfc2045::      Encoding @code{Content-Type} headers.
1176 * rfc2231::      Parsing @code{Content-Type} headers.
1177 * ietf-drums::   Handling mail headers defined by RFC822bis.
1178 * rfc2047::      En/decoding encoded words in headers.
1179 * time-date::    Functions for parsing dates and manipulating time.
1180 * qp::           Quoted-Printable en/decoding.
1181 * base64::       Base64 en/decoding.
1182 * binhex::       Binhex decoding.
1183 * uudecode::     Uuencode decoding.
1184 * yenc::         Yenc decoding.
1185 * rfc1843::      Decoding HZ-encoded text.
1186 * mailcap::      How parts are displayed is specified by the @file{.mailcap} file
1187 @end menu
1190 @node rfc2045
1191 @section rfc2045
1193 RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would
1194 imagine that there would be a lot to implement.  But there isn't, since
1195 most of the implementation details are delegated to the subsequent
1196 RFCs.
1198 So @file{rfc2045.el} has only a single function:
1200 @table @code
1201 @item rfc2045-encode-string
1202 @findex rfc2045-encode-string
1203 Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
1204 @var{value} will be quoted if there are non-safe characters in it.
1205 @end table
1208 @node rfc2231
1209 @section rfc2231
1211 RFC2231 defines a syntax for the @code{Content-Type} and
1212 @code{Content-Disposition} headers.  Its snappy name is @dfn{MIME
1213 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
1214 and Continuations}.
1216 In short, these headers look something like this:
1218 @example
1219 Content-Type: application/x-stuff;
1220  title*0*=us-ascii'en'This%20is%20even%20more%20;
1221  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1222  title*2="isn't it!"
1223 @end example
1225 They usually aren't this bad, though.
1227 The following functions are defined by this library:
1229 @table @code
1230 @item rfc2231-parse-string
1231 @findex rfc2231-parse-string
1232 Parse a @code{Content-Type} header and return a list describing its
1233 elements.
1235 @example
1236 (rfc2231-parse-string
1237  "application/x-stuff;
1238  title*0*=us-ascii'en'This%20is%20even%20more%20;
1239  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1240  title*2=\"isn't it!\"")
1241 @result{} ("application/x-stuff"
1242     (title . "This is even more ***fun*** isn't it!"))
1243 @end example
1245 @item rfc2231-get-value
1246 @findex rfc2231-get-value
1247 Takes one of the lists on the format above and returns
1248 the value of the specified attribute.
1250 @item rfc2231-encode-string
1251 @findex rfc2231-encode-string
1252 Encode a parameter in headers likes @code{Content-Type} and
1253 @code{Content-Disposition}.
1255 @end table
1258 @node ietf-drums
1259 @section ietf-drums
1261 @dfn{drums} is an IETF working group that is working on the replacement
1262 for RFC822.
1264 The functions provided by this library include:
1266 @table @code
1267 @item ietf-drums-remove-comments
1268 @findex ietf-drums-remove-comments
1269 Remove the comments from the argument and return the results.
1271 @item ietf-drums-remove-whitespace
1272 @findex ietf-drums-remove-whitespace
1273 Remove linear white space from the string and return the results.
1274 Spaces inside quoted strings and comments are left untouched.
1276 @item ietf-drums-get-comment
1277 @findex ietf-drums-get-comment
1278 Return the last most comment from the string.
1280 @item ietf-drums-parse-address
1281 @findex ietf-drums-parse-address
1282 Parse an address string and return a list that contains the mailbox and
1283 the plain text name.
1285 @item ietf-drums-parse-addresses
1286 @findex ietf-drums-parse-addresses
1287 Parse a string that contains any number of comma-separated addresses and
1288 return a list that contains mailbox/plain text pairs.
1290 @item ietf-drums-parse-date
1291 @findex ietf-drums-parse-date
1292 Parse a date string and return an Emacs time structure.
1294 @item ietf-drums-narrow-to-header
1295 @findex ietf-drums-narrow-to-header
1296 Narrow the buffer to the header section of the current buffer.
1298 @end table
1301 @node rfc2047
1302 @section rfc2047
1304 RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how
1305 non-@acronym{ASCII} text in headers are to be encoded.  This is actually rather
1306 complicated, so a number of variables are necessary to tweak what this
1307 library does.
1309 The following variables are tweakable:
1311 @table @code
1312 @item rfc2047-header-encoding-alist
1313 @vindex rfc2047-header-encoding-alist
1314 This is an alist of header / encoding-type pairs.  Its main purpose is
1315 to prevent encoding of certain headers.
1317 The keys can either be header regexps, or @code{t}.
1319 The values can be @code{nil}, in which case the header(s) in question
1320 won't be encoded, @code{mime}, which means that they will be encoded, or
1321 @code{address-mime}, which means the header(s) will be encoded carefully
1322 assuming they contain addresses.
1324 @item rfc2047-charset-encoding-alist
1325 @vindex rfc2047-charset-encoding-alist
1326 RFC2047 specifies two forms of encoding---@code{Q} (a
1327 Quoted-Printable-like encoding) and @code{B} (base64).  This alist
1328 specifies which charset should use which encoding.
1330 @item rfc2047-encoding-function-alist
1331 @vindex rfc2047-encoding-function-alist
1332 This is an alist of encoding / function pairs.  The encodings are
1333 @code{Q}, @code{B} and @code{nil}.
1335 @item rfc2047-encoded-word-regexp
1336 @vindex rfc2047-encoded-word-regexp
1337 When decoding words, this library looks for matches to this regexp.
1339 @end table
1341 Those were the variables, and these are this functions:
1343 @table @code
1344 @item rfc2047-narrow-to-field
1345 @findex rfc2047-narrow-to-field
1346 Narrow the buffer to the header on the current line.
1348 @item rfc2047-encode-message-header
1349 @findex rfc2047-encode-message-header
1350 Should be called narrowed to the header of a message.  Encodes according
1351 to @code{rfc2047-header-encoding-alist}.
1353 @item rfc2047-encode-region
1354 @findex rfc2047-encode-region
1355 Encodes all encodable words in the region specified.
1357 @item rfc2047-encode-string
1358 @findex rfc2047-encode-string
1359 Encode a string and return the results.
1361 @item rfc2047-decode-region
1362 @findex rfc2047-decode-region
1363 Decode the encoded words in the region.
1365 @item rfc2047-decode-string
1366 @findex rfc2047-decode-string
1367 Decode a string and return the results.
1369 @end table
1372 @node time-date
1373 @section time-date
1375 While not really a part of the @acronym{MIME} library, it is convenient to
1376 document this library here.  It deals with parsing @code{Date} headers
1377 and manipulating time.  (Not by using tesseracts, though, I'm sorry to
1378 say.)
1380 These functions convert between five formats: A date string, an Emacs
1381 time structure, a decoded time list, a second number, and a day number.
1383 Here's a bunch of time/date/second/day examples:
1385 @example
1386 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
1387 @result{} (54 21 12 12 9 1998 6 nil 7200)
1389 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
1390 @result{} (13818 19266)
1392 (time-to-seconds '(13818 19266))
1393 @result{} 905595714.0
1395 (seconds-to-time 905595714.0)
1396 @result{} (13818 19266 0)
1398 (time-to-days '(13818 19266))
1399 @result{} 729644
1401 (days-to-time 729644)
1402 @result{} (961933 65536)
1404 (time-since '(13818 19266))
1405 @result{} (0 430)
1407 (time-less-p '(13818 19266) '(13818 19145))
1408 @result{} nil
1410 (subtract-time '(13818 19266) '(13818 19145))
1411 @result{} (0 121)
1413 (days-between "Sat Sep 12 12:21:54 1998 +0200"
1414               "Sat Sep 07 12:21:54 1998 +0200")
1415 @result{} 5
1417 (date-leap-year-p 2000)
1418 @result{} t
1420 (time-to-day-in-year '(13818 19266))
1421 @result{} 255
1423 (time-to-number-of-days
1424  (time-since
1425   (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
1426 @result{} 4.146122685185185
1427 @end example
1429 And finally, we have @code{safe-date-to-time}, which does the same as
1430 @code{date-to-time}, but returns a zero time if the date is
1431 syntactically malformed.
1433 The five data representations used are the following:
1435 @table @var
1436 @item date
1437 An RFC822 (or similar) date string.  For instance: @code{"Sat Sep 12
1438 12:21:54 1998 +0200"}.
1440 @item time
1441 An internal Emacs time.  For instance: @code{(13818 26466)}.
1443 @item seconds
1444 A floating point representation of the internal Emacs time.  For
1445 instance: @code{905595714.0}.
1447 @item days
1448 An integer number representing the number of days since 00000101.  For
1449 instance: @code{729644}.
1451 @item decoded time
1452 A list of decoded time.  For instance: @code{(54 21 12 12 9 1998 6 t
1453 7200)}.
1454 @end table
1456 All the examples above represent the same moment.
1458 These are the functions available:
1460 @table @code
1461 @item date-to-time
1462 Take a date and return a time.
1464 @item time-to-seconds
1465 Take a time and return seconds.
1467 @item seconds-to-time
1468 Take seconds and return a time.
1470 @item time-to-days
1471 Take a time and return days.
1473 @item days-to-time
1474 Take days and return a time.
1476 @item date-to-day
1477 Take a date and return days.
1479 @item time-to-number-of-days
1480 Take a time and return the number of days that represents.
1482 @item safe-date-to-time
1483 Take a date and return a time.  If the date is not syntactically valid,
1484 return a ``zero'' date.
1486 @item time-less-p
1487 Take two times and say whether the first time is less (i. e., earlier)
1488 than the second time.
1490 @item time-since
1491 Take a time and return a time saying how long it was since that time.
1493 @item subtract-time
1494 Take two times and subtract the second from the first.  I. e., return
1495 the time between the two times.
1497 @item days-between
1498 Take two days and return the number of days between those two days.
1500 @item date-leap-year-p
1501 Take a year number and say whether it's a leap year.
1503 @item time-to-day-in-year
1504 Take a time and return the day number within the year that the time is
1507 @end table
1510 @node qp
1511 @section qp
1513 This library deals with decoding and encoding Quoted-Printable text.
1515 Very briefly explained, qp encoding means translating all 8-bit
1516 characters (and lots of control characters) into things that look like
1517 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
1518 string.
1520 The following functions are defined by the library:
1522 @table @code
1523 @item quoted-printable-decode-region
1524 @findex quoted-printable-decode-region
1525 QP-decode all the encoded text in the specified region.
1527 @item quoted-printable-decode-string
1528 @findex quoted-printable-decode-string
1529 Decode the QP-encoded text in a string and return the results.
1531 @item quoted-printable-encode-region
1532 @findex quoted-printable-encode-region
1533 QP-encode all the encodable characters in the specified region.  The third
1534 optional parameter @var{fold} specifies whether to fold long lines.
1535 (Long here means 72.)
1537 @item quoted-printable-encode-string
1538 @findex quoted-printable-encode-string
1539 QP-encode all the encodable characters in a string and return the
1540 results.
1542 @end table
1545 @node base64
1546 @section base64
1547 @cindex base64
1549 Base64 is an encoding that encodes three bytes into four characters,
1550 thereby increasing the size by about 33%.  The alphabet used for
1551 encoding is very resistant to mangling during transit.
1553 The following functions are defined by this library:
1555 @table @code
1556 @item base64-encode-region
1557 @findex base64-encode-region
1558 base64 encode the selected region.  Return the length of the encoded
1559 text.  Optional third argument @var{no-line-break} means do not break
1560 long lines into shorter lines.
1562 @item base64-encode-string
1563 @findex base64-encode-string
1564 base64 encode a string and return the result.
1566 @item base64-decode-region
1567 @findex base64-decode-region
1568 base64 decode the selected region.  Return the length of the decoded
1569 text.  If the region can't be decoded, return @code{nil} and don't
1570 modify the buffer.
1572 @item base64-decode-string
1573 @findex base64-decode-string
1574 base64 decode a string and return the result.  If the string can't be
1575 decoded, @code{nil} is returned.
1577 @end table
1580 @node binhex
1581 @section binhex
1582 @cindex binhex
1583 @cindex Apple
1584 @cindex Macintosh
1586 @code{binhex} is an encoding that originated in Macintosh environments.
1587 The following function is supplied to deal with these:
1589 @table @code
1590 @item binhex-decode-region
1591 @findex binhex-decode-region
1592 Decode the encoded text in the region.  If given a third parameter, only
1593 decode the @code{binhex} header and return the filename.
1595 @end table
1597 @node uudecode
1598 @section uudecode
1599 @cindex uuencode
1600 @cindex uudecode
1602 @code{uuencode} is probably still the most popular encoding of binaries
1603 used on Usenet, although @code{base64} rules the mail world.
1605 The following function is supplied by this package:
1607 @table @code
1608 @item uudecode-decode-region
1609 @findex uudecode-decode-region
1610 Decode the text in the region.
1611 @end table
1614 @node yenc
1615 @section yenc
1616 @cindex yenc
1618 @code{yenc} is used for encoding binaries on Usenet.  The following
1619 function is supplied by this package:
1621 @table @code
1622 @item yenc-decode-region
1623 @findex yenc-decode-region
1624 Decode the encoded text in the region.
1626 @end table
1629 @node rfc1843
1630 @section rfc1843
1631 @cindex rfc1843
1632 @cindex HZ
1633 @cindex Chinese
1635 RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages.  In
1636 essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this:
1638 @example
1639 This sentence is in @acronym{ASCII}.
1640 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
1641 @end example
1643 Simple enough, and widely used in China.
1645 The following functions are available to handle this encoding:
1647 @table @code
1648 @item rfc1843-decode-region
1649 Decode HZ-encoded text in the region.
1651 @item rfc1843-decode-string
1652 Decode a HZ-encoded string and return the result.
1654 @end table
1657 @node mailcap
1658 @section mailcap
1660 The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message
1661 handlers and describes how elements are supposed to be displayed.
1662 Here's an example file:
1664 @example
1665 image/*; gimp -8 %s
1666 audio/wav; wavplayer %s
1667 application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc
1668 @end example
1670 This says that all image files should be displayed with @code{gimp},
1671 that WAVE audio files should be played by @code{wavplayer}, and that
1672 MS-WORD files should be inlined by @code{catdoc}.
1674 The @code{mailcap} library parses this file, and provides functions for
1675 matching types.
1677 @table @code
1678 @item mailcap-mime-data
1679 @vindex mailcap-mime-data
1680 This variable is an alist of alists containing backup viewing rules.
1682 @end table
1684 Interface functions:
1686 @table @code
1687 @item mailcap-parse-mailcaps
1688 @findex mailcap-parse-mailcaps
1689 Parse the @file{~/.mailcap} file.
1691 @item mailcap-mime-info
1692 Takes a @acronym{MIME} type as its argument and returns the matching viewer.
1694 @end table
1699 @node Standards
1700 @chapter Standards
1702 The Emacs @acronym{MIME} library implements handling of various elements
1703 according to a (somewhat) large number of RFCs, drafts and standards
1704 documents.  This chapter lists the relevant ones.  They can all be
1705 fetched from @uref{http://quimby.gnus.org/notes/}.
1707 @table @dfn
1708 @item RFC822
1709 @itemx STD11
1710 Standard for the Format of ARPA Internet Text Messages.
1712 @item RFC1036
1713 Standard for Interchange of USENET Messages
1715 @item RFC2045
1716 Format of Internet Message Bodies
1718 @item RFC2046
1719 Media Types
1721 @item RFC2047
1722 Message Header Extensions for Non-@acronym{ASCII} Text
1724 @item RFC2048
1725 Registration Procedures
1727 @item RFC2049
1728 Conformance Criteria and Examples
1730 @item RFC2231
1731 @acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets,
1732 Languages, and Continuations
1734 @item RFC1843
1735 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1736 @acronym{ASCII} characters
1738 @item draft-ietf-drums-msg-fmt-05.txt
1739 Draft for the successor of RFC822
1741 @item RFC2112
1742 The @acronym{MIME} Multipart/Related Content-type
1744 @item RFC1892
1745 The Multipart/Report Content Type for the Reporting of Mail System
1746 Administrative Messages
1748 @item RFC2183
1749 Communicating Presentation Information in Internet Messages: The
1750 Content-Disposition Header Field
1752 @item RFC2646
1753 Documentation of the text/plain format parameter for flowed text.
1755 @end table
1758 @node Index
1759 @chapter Index
1760 @printindex cp
1762 @summarycontents
1763 @contents
1764 @bye
1767 @c Local Variables:
1768 @c mode: texinfo
1769 @c coding: iso-8859-1
1770 @c End:
1772 @ignore
1773    arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d
1774 @end ignore