Remove non-free old and crusty clearcase pkg
[packages] / xemacs-packages / gnus / texi / emacs-mime.texi
1 \input texinfo
2
3 @setfilename emacs-mime
4 @settitle Emacs MIME Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
8
9 @copying
10 This file documents the Emacs MIME interface functionality.
11
12 Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
13 2006, 2007, 2008 Free Software Foundation, Inc.
14
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.
23
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.''
27
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
34
35 @c Node ``Interface Functions'' uses Latin-1 characters
36 @documentencoding ISO-8859-1
37
38 @dircategory Emacs
39 @direntry
40 * Emacs MIME: (emacs-mime).   Emacs MIME de/composition library.
41 @end direntry
42 @iftex
43 @finalout
44 @end iftex
45 @setchapternewpage odd
46
47 @titlepage
48 @title Emacs MIME Manual
49
50 @author by Lars Magne Ingebrigtsen
51 @page
52 @vskip 0pt plus 1filll
53 @insertcopying
54 @end titlepage
55
56 @node Top
57 @top Emacs MIME
58
59 This manual documents the libraries used to compose and display
60 @acronym{MIME} messages.
61
62 This manual is directed at users who want to modify the behavior of
63 the @acronym{MIME} encoding/decoding process or want a more detailed
64 picture of how the Emacs @acronym{MIME} library works, and people who want
65 to write functions and commands that manipulate @acronym{MIME} elements.
66
67 @acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}.
68 This standard is documented in a number of RFCs; mainly RFC2045 (Format
69 of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
70 Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration
71 Procedures), RFC2049 (Conformance Criteria and Examples).  It is highly
72 recommended that anyone who intends writing @acronym{MIME}-compliant software
73 read at least RFC2045 and RFC2047.
74
75 @menu
76 * Decoding and Viewing::  A framework for decoding and viewing.
77 * Composing::             @acronym{MML}; a language for describing @acronym{MIME} parts.
78 * Interface Functions::   An abstraction over the basic functions.
79 * Basic Functions::       Utility and basic parsing functions.
80 * Standards::             A summary of RFCs and working documents used.
81 * GNU Free Documentation License:: The license for this documentation.
82 * Index::                 Function and variable index.
83 @end menu
84
85
86 @node Decoding and Viewing
87 @chapter Decoding and Viewing
88
89 This chapter deals with decoding and viewing @acronym{MIME} messages on a
90 higher level.
91
92 The main idea is to first analyze a @acronym{MIME} article, and then allow
93 other programs to do things based on the list of @dfn{handles} that are
94 returned as a result of this analysis.
95
96 @menu
97 * Dissection::             Analyzing a @acronym{MIME} message.
98 * Non-MIME::               Analyzing a non-@acronym{MIME} message.
99 * Handles::                Handle manipulations.
100 * Display::                Displaying handles.
101 * Display Customization::  Variables that affect display.
102 * Files and Directories::  Saving and naming attachments.
103 * New Viewers::            How to write your own viewers.
104 @end menu
105
106
107 @node Dissection
108 @section Dissection
109
110 The @code{mm-dissect-buffer} is the function responsible for dissecting
111 a @acronym{MIME} article.  If given a multipart message, it will recursively
112 descend the message, following the structure, and return a tree of
113 @acronym{MIME} handles that describes the structure of the message.
114
115 @node Non-MIME
116 @section Non-MIME
117 @vindex mm-uu-configure-list
118
119 Gnus also understands some non-@acronym{MIME} attachments, such as
120 postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp,
121 diff.  Each of these features can be disabled by add an item into
122 @code{mm-uu-configure-list}.  For example,
123
124 @lisp
125 (require 'mm-uu)
126 (add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
127 @end lisp
128
129 @table @code
130 @item postscript
131 @findex postscript
132 PostScript file.
133
134 @item uu
135 @findex uu
136 Uuencoded file.
137
138 @item binhex
139 @findex binhex
140 Binhex encoded file.
141
142 @item yenc
143 @findex yenc
144 Yenc encoded file.
145
146 @item shar
147 @findex shar
148 Shar archive file.
149
150 @item forward
151 @findex forward
152 Non-@acronym{MIME} forwarded message.
153
154 @item gnatsweb
155 @findex gnatsweb
156 Gnatsweb attachment.
157
158 @item pgp-signed
159 @findex pgp-signed
160 @acronym{PGP} signed clear text.
161
162 @item pgp-encrypted
163 @findex pgp-encrypted
164 @acronym{PGP} encrypted clear text.
165
166 @item pgp-key
167 @findex pgp-key
168 @acronym{PGP} public keys.
169
170 @item emacs-sources
171 @findex emacs-sources
172 @vindex mm-uu-emacs-sources-regexp
173 Emacs source code.  This item works only in the groups matching
174 @code{mm-uu-emacs-sources-regexp}.
175
176 @item diff
177 @vindex diff
178 @vindex mm-uu-diff-groups-regexp
179 Patches.  This is intended for groups where diffs of committed files
180 are automatically sent to.  It only works in groups matching
181 @code{mm-uu-diff-groups-regexp}.
182
183 @end table
184
185 @node Handles
186 @section Handles
187
188 A @acronym{MIME} handle is a list that fully describes a @acronym{MIME}
189 component.
190
191 The following macros can be used to access elements in a handle:
192
193 @table @code
194 @item mm-handle-buffer
195 @findex mm-handle-buffer
196 Return the buffer that holds the contents of the undecoded @acronym{MIME}
197 part.
198
199 @item mm-handle-type
200 @findex mm-handle-type
201 Return the parsed @code{Content-Type} of the part.
202
203 @item mm-handle-encoding
204 @findex mm-handle-encoding
205 Return the @code{Content-Transfer-Encoding} of the part.
206
207 @item mm-handle-undisplayer
208 @findex mm-handle-undisplayer
209 Return the object that can be used to remove the displayed part (if it
210 has been displayed).
211
212 @item mm-handle-set-undisplayer
213 @findex mm-handle-set-undisplayer
214 Set the undisplayer object.
215
216 @item mm-handle-disposition
217 @findex mm-handle-disposition
218 Return the parsed @code{Content-Disposition} of the part.
219
220 @item mm-get-content-id
221 Returns the handle(s) referred to by @code{Content-ID}.
222
223 @end table
224
225
226 @node Display
227 @section Display
228
229 Functions for displaying, removing and saving.
230
231 @table @code
232 @item mm-display-part
233 @findex mm-display-part
234 Display the part.
235
236 @item mm-remove-part
237 @findex mm-remove-part
238 Remove the part (if it has been displayed).
239
240 @item mm-inlinable-p
241 @findex mm-inlinable-p
242 Say whether a @acronym{MIME} type can be displayed inline.
243
244 @item mm-automatic-display-p
245 @findex mm-automatic-display-p
246 Say whether a @acronym{MIME} type should be displayed automatically.
247
248 @item mm-destroy-part
249 @findex mm-destroy-part
250 Free all resources occupied by a part.
251
252 @item mm-save-part
253 @findex mm-save-part
254 Offer to save the part in a file.
255
256 @item mm-pipe-part
257 @findex mm-pipe-part
258 Offer to pipe the part to some process.
259
260 @item mm-interactively-view-part
261 @findex mm-interactively-view-part
262 Prompt for a mailcap method to use to view the part.
263
264 @end table
265
266
267 @node Display Customization
268 @section Display Customization
269
270 @table @code
271
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.
278
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.
282
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.
288
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.
294
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.
299
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.
304
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.)
311
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:
321
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
328
329 Adding @code{"image/.*"} might also be useful.  Spammers use images as
330 the preferred part of @samp{multipart/alternative} messages, so you might
331 not notice there are other parts.  See also
332 @code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands,
333 gnus, Gnus Manual}.  After adding @code{"multipart/alternative"} to
334 @code{gnus-buttonized-mime-types} you can choose manually which
335 alternative you'd like to view.  For example, you can set those
336 variables like:
337
338 @lisp
339 (setq gnus-buttonized-mime-types
340       '("multipart/alternative" "multipart/signed")
341       mm-discouraged-alternatives
342       '("text/html" "image/.*"))
343 @end lisp
344
345 In this case, Gnus will display radio buttons for such a kind of spam
346 message as follows:
347
348 @example
349 1.  (*) multipart/alternative  ( ) image/gif
350
351 2.  (*) text/plain          ( ) text/html
352 @end example
353
354 @item mm-inline-large-images
355 @vindex mm-inline-large-images
356 When displaying inline images that are larger than the window, Emacs
357 does not enable scrolling, which means that you cannot see the whole
358 image.  To prevent this, the library tries to determine the image size
359 before displaying it inline, and if it doesn't fit the window, the
360 library will display it externally (e.g. with @samp{ImageMagick} or
361 @samp{xv}).  Setting this variable to @code{t} disables this check and
362 makes the library display all inline images as inline, regardless of
363 their size.
364
365 @item mm-inline-override-types
366 @vindex mm-inline-override-types
367 @code{mm-inlined-types} may include regular expressions, for example to
368 specify that all @samp{text/.*} parts be displayed inline.  If a user
369 prefers to have a type that matches such a regular expression be treated
370 as an attachment, that can be accomplished by setting this variable to a
371 list containing that type.  For example assuming @code{mm-inlined-types}
372 includes @samp{text/.*}, then including @samp{text/html} in this
373 variable will cause @samp{text/html} parts to be treated as attachments.
374
375 @item mm-text-html-renderer
376 @vindex mm-text-html-renderer
377 This selects the function used to render @acronym{HTML}.  The predefined
378 renderers are selected by the symbols @code{w3},
379 @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more
380 information about emacs-w3m}, @code{links}, @code{lynx},
381 @code{w3m-standalone} or @code{html2text}.  If @code{nil} use an
382 external viewer.  You can also specify a function, which will be
383 called with a @acronym{MIME} handle as the argument.
384
385 @item mm-inline-text-html-with-images
386 @vindex mm-inline-text-html-with-images
387 Some @acronym{HTML} mails might have the trick of spammers using
388 @samp{<img>} tags.  It is likely to be intended to verify whether you
389 have read the mail.  You can prevent your personal informations from
390 leaking by setting this option to @code{nil} (which is the default).
391 It is currently ignored by Emacs/w3.  For emacs-w3m, you may use the
392 command @kbd{t} on the image anchor to show an image even if it is
393 @code{nil}.@footnote{The command @kbd{T} will load all images.  If you
394 have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i}
395 or @kbd{I} instead.}
396
397 @item mm-w3m-safe-url-regexp
398 @vindex mm-w3m-safe-url-regexp
399 A regular expression that matches safe URL names, i.e. URLs that are
400 unlikely to leak personal information when rendering @acronym{HTML}
401 email (the default value is @samp{\\`cid:}).  If @code{nil} consider
402 all URLs safe.
403
404 @item mm-inline-text-html-with-w3m-keymap
405 @vindex mm-inline-text-html-with-w3m-keymap
406 You can use emacs-w3m command keys in the inlined text/html part by
407 setting this option to non-@code{nil}.  The default value is @code{t}.
408
409 @item mm-external-terminal-program
410 @vindex mm-external-terminal-program
411 The program used to start an external terminal.
412
413 @item mm-enable-external
414 @vindex mm-enable-external
415 Indicate whether external @acronym{MIME} handlers should be used.
416
417 If @code{t}, all defined external @acronym{MIME} handlers are used.  If
418 @code{nil}, files are saved to disk (@code{mailcap-save-binary-file}).
419 If it is the symbol @code{ask}, you are prompted before the external
420 @acronym{MIME} handler is invoked.
421
422 When you launch an attachment through mailcap (@pxref{mailcap}) an
423 attempt is made to use a safe viewer with the safest options---this isn't
424 the case if you save it to disk and launch it in a different way
425 (command line or double-clicking).  Anyhow, if you want to be sure not
426 to launch any external programs, set this variable to @code{nil} or
427 @code{ask}.
428
429 @end table
430
431 @node Files and Directories
432 @section Files and Directories
433
434 @table @code
435
436 @item mm-default-directory
437 @vindex mm-default-directory
438 The default directory for saving attachments.  If @code{nil} use
439 @code{default-directory}.
440
441 @item mm-tmp-directory
442 @vindex mm-tmp-directory
443 Directory for storing temporary files.
444
445 @item mm-file-name-rewrite-functions
446 @vindex mm-file-name-rewrite-functions
447 A list of functions used for rewriting file names of @acronym{MIME}
448 parts.  Each function is applied successively to the file name.
449 Ready-made functions include
450
451 @table @code
452 @item mm-file-name-delete-control
453 @findex mm-file-name-delete-control
454 Delete all control characters.
455
456 @item mm-file-name-delete-gotchas
457 @findex mm-file-name-delete-gotchas
458 Delete characters that could have unintended consequences when used
459 with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and
460 @samp{-}, @samp{.} as the first character.
461
462 @item mm-file-name-delete-whitespace
463 @findex mm-file-name-delete-whitespace
464 Remove all whitespace.
465
466 @item mm-file-name-trim-whitespace
467 @findex mm-file-name-trim-whitespace
468 Remove leading and trailing whitespace.
469
470 @item mm-file-name-collapse-whitespace
471 @findex mm-file-name-collapse-whitespace
472 Collapse multiple whitespace characters.
473
474 @item mm-file-name-replace-whitespace
475 @findex mm-file-name-replace-whitespace
476 @vindex mm-file-name-replace-whitespace
477 Replace whitespace with underscores.  Set the variable
478 @code{mm-file-name-replace-whitespace} to any other string if you do
479 not like underscores.
480 @end table
481
482 The standard Emacs functions @code{capitalize}, @code{downcase},
483 @code{upcase} and @code{upcase-initials} might also prove useful.
484
485 @item mm-path-name-rewrite-functions
486 @vindex mm-path-name-rewrite-functions
487 List of functions used for rewriting the full file names of @acronym{MIME}
488 parts.  This is used when viewing parts externally, and is meant for
489 transforming the absolute name so that non-compliant programs can find
490 the file where it's saved.
491
492 @end table
493
494 @node New Viewers
495 @section New Viewers
496
497 Here's an example viewer for displaying @code{text/enriched} inline:
498
499 @lisp
500 (defun mm-display-enriched-inline (handle)
501   (let (text)
502     (with-temp-buffer
503       (mm-insert-part handle)
504       (save-window-excursion
505         (enriched-decode (point-min) (point-max))
506         (setq text (buffer-string))))
507     (mm-insert-inline handle text)))
508 @end lisp
509
510 We see that the function takes a @acronym{MIME} handle as its parameter.  It
511 then goes to a temporary buffer, inserts the text of the part, does some
512 work on the text, stores the result, goes back to the buffer it was
513 called from and inserts the result.
514
515 The two important helper functions here are @code{mm-insert-part} and
516 @code{mm-insert-inline}.  The first function inserts the text of the
517 handle in the current buffer.  It handles charset and/or content
518 transfer decoding.  The second function just inserts whatever text you
519 tell it to insert, but it also sets things up so that the text can be
520 ``undisplayed'' in a convenient manner.
521
522
523 @node Composing
524 @chapter Composing
525 @cindex Composing
526 @cindex MIME Composing
527 @cindex MML
528 @cindex MIME Meta Language
529
530 Creating a @acronym{MIME} message is boring and non-trivial.  Therefore,
531 a library called @code{mml} has been defined that parses a language
532 called @acronym{MML} (@acronym{MIME} Meta Language) and generates
533 @acronym{MIME} messages.
534
535 @findex mml-generate-mime
536 The main interface function is @code{mml-generate-mime}.  It will
537 examine the contents of the current (narrowed-to) buffer and return a
538 string containing the @acronym{MIME} message.
539
540 @menu
541 * Simple MML Example::             An example @acronym{MML} document.
542 * MML Definition::                 All valid @acronym{MML} elements.
543 * Advanced MML Example::           Another example @acronym{MML} document.
544 * Encoding Customization::         Variables that affect encoding.
545 * Charset Translation::            How charsets are mapped from @sc{mule} to @acronym{MIME}.
546 * Conversion::                     Going from @acronym{MIME} to @acronym{MML} and vice versa.
547 * Flowed text::                    Soft and hard newlines.
548 @end menu
549
550
551 @node Simple MML Example
552 @section Simple MML Example
553
554 Here's a simple @samp{multipart/alternative}:
555
556 @example
557 <#multipart type=alternative>
558 This is a plain text part.
559 <#part type=text/enriched>
560 <center>This is a centered enriched part</center>
561 <#/multipart>
562 @end example
563
564 After running this through @code{mml-generate-mime}, we get this:
565
566 @example
567 Content-Type: multipart/alternative; boundary="=-=-="
568
569
570 --=-=-=
571
572
573 This is a plain text part.
574
575 --=-=-=
576 Content-Type: text/enriched
577
578
579 <center>This is a centered enriched part</center>
580
581 --=-=-=--
582 @end example
583
584
585 @node MML Definition
586 @section MML Definition
587
588 The @acronym{MML} language is very simple.  It looks a bit like an SGML
589 application, but it's not.
590
591 The main concept of @acronym{MML} is the @dfn{part}.  Each part can be of a
592 different type or use a different charset.  The way to delineate a part
593 is with a @samp{<#part ...>} tag.  Multipart parts can be introduced
594 with the @samp{<#multipart ...>} tag.  Parts are ended by the
595 @samp{<#/part>} or @samp{<#/multipart>} tags.  Parts started with the
596 @samp{<#part ...>} tags are also closed by the next open tag.
597
598 There's also the @samp{<#external ...>} tag.  These introduce
599 @samp{external/message-body} parts.
600
601 Each tag can contain zero or more parameters on the form
602 @samp{parameter=value}.  The values may be enclosed in quotation marks,
603 but that's not necessary unless the value contains white space.  So
604 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
605
606 The following parameters have meaning in @acronym{MML}; parameters that have no
607 meaning are ignored.  The @acronym{MML} parameter names are the same as the
608 @acronym{MIME} parameter names; the things in the parentheses say which
609 header it will be used in.
610
611 @table @samp
612 @item type
613 The @acronym{MIME} type of the part (@code{Content-Type}).
614
615 @item filename
616 Use the contents of the file in the body of the part
617 (@code{Content-Disposition}).
618
619 @item charset
620 The contents of the body of the part are to be encoded in the character
621 set specified (@code{Content-Type}). @xref{Charset Translation}.
622
623 @item name
624 Might be used to suggest a file name if the part is to be saved
625 to a file (@code{Content-Type}).
626
627 @item disposition
628 Valid values are @samp{inline} and @samp{attachment}
629 (@code{Content-Disposition}).
630
631 @item encoding
632 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
633 @samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset
634 Translation}.
635
636 @item description
637 A description of the part (@code{Content-Description}).
638
639 @item creation-date
640 RFC822 date when the part was created (@code{Content-Disposition}).
641
642 @item modification-date
643 RFC822 date when the part was modified (@code{Content-Disposition}).
644
645 @item read-date
646 RFC822 date when the part was read (@code{Content-Disposition}).
647
648 @item recipients
649 Who to encrypt/sign the part to.  This field is used to override any
650 auto-detection based on the To/CC headers.
651
652 @item sender
653 Identity used to sign the part.  This field is used to override the
654 default key used.
655
656 @item size
657 The size (in octets) of the part (@code{Content-Disposition}).
658
659 @item sign
660 What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp}
661 or @code{pgpmime})
662
663 @item encrypt
664 What technology to encrypt this @acronym{MML} part with (@code{smime},
665 @code{pgp} or @code{pgpmime})
666
667 @end table
668
669 Parameters for @samp{text/plain}:
670
671 @table @samp
672 @item format
673 Formatting parameter for the text, valid values include @samp{fixed}
674 (the default) and @samp{flowed}.  Normally you do not specify this
675 manually, since it requires the textual body to be formatted in a
676 special way described in RFC 2646.  @xref{Flowed text}.
677 @end table
678
679 Parameters for @samp{application/octet-stream}:
680
681 @table @samp
682 @item type
683 Type of the part; informal---meant for human readers
684 (@code{Content-Type}).
685 @end table
686
687 Parameters for @samp{message/external-body}:
688
689 @table @samp
690 @item access-type
691 A word indicating the supported access mechanism by which the file may
692 be obtained.  Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
693 @samp{localfile}, and @samp{mailserver}.  (@code{Content-Type}.)
694
695 @item expiration
696 The RFC822 date after which the file may no longer be fetched.
697 (@code{Content-Type}.)
698
699 @item size
700 The size (in octets) of the file.  (@code{Content-Type}.)
701
702 @item permission
703 Valid values are @samp{read} and @samp{read-write}
704 (@code{Content-Type}).
705
706 @end table
707
708 Parameters for @samp{sign=smime}:
709
710 @table @samp
711
712 @item keyfile
713 File containing key and certificate for signer.
714
715 @end table
716
717 Parameters for @samp{encrypt=smime}:
718
719 @table @samp
720
721 @item certfile
722 File containing certificate for recipient.
723
724 @end table
725
726
727 @node Advanced MML Example
728 @section Advanced MML Example
729
730 Here's a complex multipart message.  It's a @samp{multipart/mixed} that
731 contains many parts, one of which is a @samp{multipart/alternative}.
732
733 @example
734 <#multipart type=mixed>
735 <#part type=image/jpeg filename=~/rms.jpg disposition=inline>
736 <#multipart type=alternative>
737 This is a plain text part.
738 <#part type=text/enriched name=enriched.txt>
739 <center>This is a centered enriched part</center>
740 <#/multipart>
741 This is a new plain text part.
742 <#part disposition=attachment>
743 This plain text part is an attachment.
744 <#/multipart>
745 @end example
746
747 And this is the resulting @acronym{MIME} message:
748
749 @example
750 Content-Type: multipart/mixed; boundary="=-=-="
751
752
753 --=-=-=
754
755
756
757 --=-=-=
758 Content-Type: image/jpeg;
759  filename="~/rms.jpg"
760 Content-Disposition: inline;
761  filename="~/rms.jpg"
762 Content-Transfer-Encoding: base64
763
764 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
765 Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
766 AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
767 BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
768 RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
769 qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
770 AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
771 AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
772 sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
773 2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
774 5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
775 L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
776 34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
777 tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
778 7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
779 pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
780 jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
781
782 --=-=-=
783 Content-Type: multipart/alternative; boundary="==-=-="
784
785
786 --==-=-=
787
788
789 This is a plain text part.
790
791 --==-=-=
792 Content-Type: text/enriched;
793  name="enriched.txt"
794
795
796 <center>This is a centered enriched part</center>
797
798 --==-=-=--
799
800 --=-=-=
801
802 This is a new plain text part.
803
804 --=-=-=
805 Content-Disposition: attachment
806
807
808 This plain text part is an attachment.
809
810 --=-=-=--
811 @end example
812
813 @node Encoding Customization
814 @section Encoding Customization
815
816 @table @code
817
818 @item mm-body-charset-encoding-alist
819 @vindex mm-body-charset-encoding-alist
820 Mapping from @acronym{MIME} charset to encoding to use.  This variable is
821 usually used except, e.g., when other requirements force a specific
822 encoding (digitally signed messages require 7bit encodings).  The
823 default is
824
825 @lisp
826 ((iso-2022-jp . 7bit)
827  (iso-2022-jp-2 . 7bit)
828  (utf-16 . base64)
829  (utf-16be . base64)
830  (utf-16le . base64))
831 @end lisp
832
833 As an example, if you do not want to have ISO-8859-1 characters
834 quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to
835 this variable.  You can override this setting on a per-message basis
836 by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}).
837
838 @item mm-coding-system-priorities
839 @vindex mm-coding-system-priorities
840 Prioritize coding systems to use for outgoing messages.  The default
841 is @code{nil}, which means to use the defaults in Emacs, but is
842 @code{(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8)} when
843 running Emacs in the Japanese language environment.  It is a list of
844 coding system symbols (aliases of coding systems are also allowed, use
845 @kbd{M-x describe-coding-system} to make sure you are specifying correct
846 coding system names).  For example, if you have configured Emacs
847 to prefer UTF-8, but wish that outgoing messages should be sent in
848 ISO-8859-1 if possible, you can set this variable to
849 @code{(iso-8859-1)}.  You can override this setting on a per-message
850 basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}).
851
852 @item mm-content-transfer-encoding-defaults
853 @vindex mm-content-transfer-encoding-defaults
854 Mapping from @acronym{MIME} types to encoding to use.  This variable is usually
855 used except, e.g., when other requirements force a safer encoding
856 (digitally signed messages require 7bit encoding).  Besides the normal
857 @acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for
858 each case the most efficient of quoted-printable and base64 should be
859 used.
860
861 @code{qp-or-base64} has another effect.  It will fold long lines so that
862 MIME parts may not be broken by MTA.  So do @code{quoted-printable} and
863 @code{base64}.
864
865 Note that it affects body encoding only when a part is a raw forwarded
866 message (which will be made by @code{gnus-summary-mail-forward} with the
867 arg 2 for example) or is neither the @samp{text/*} type nor the
868 @samp{message/*} type.  Even though in those cases, you can override
869 this setting on a per-message basis by using the @code{encoding}
870 @acronym{MML} tag (@pxref{MML Definition}).
871
872 @item mm-use-ultra-safe-encoding
873 @vindex mm-use-ultra-safe-encoding
874 When this is non-@code{nil}, it means that textual parts are encoded as
875 quoted-printable if they contain lines longer than 76 characters or
876 starting with "From " in the body.  Non-7bit encodings (8bit, binary)
877 are generally disallowed.  This reduce the probability that a non-8bit
878 clean MTA or MDA changes the message.  This should never be set
879 directly, but bound by other functions when necessary (e.g., when
880 encoding messages that are to be digitally signed).
881
882 @end table
883
884 @node Charset Translation
885 @section Charset Translation
886 @cindex charsets
887
888 During translation from @acronym{MML} to @acronym{MIME}, for each
889 @acronym{MIME} part which has been composed inside Emacs, an appropriate
890 charset has to be chosen.
891
892 @vindex mail-parse-charset
893 If you are running a non-@sc{mule} Emacs, this process is simple: If the
894 part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset
895 given by @code{mail-parse-charset} (a symbol) is used.  (Never set this
896 variable directly, though.  If you want to change the default charset,
897 please consult the documentation of the package which you use to process
898 @acronym{MIME} messages.
899 @xref{Various Message Variables, , Various Message Variables, message,
900       Message Manual}, for example.)
901 If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is
902 used, of course.
903
904 @cindex MULE
905 @cindex UTF-8
906 @cindex Unicode
907 @vindex mm-mime-mule-charset-alist
908 Things are slightly more complicated when running Emacs with @sc{mule}
909 support.  In this case, a list of the @sc{mule} charsets used in the
910 part is obtained, and the @sc{mule} charsets are translated to
911 @acronym{MIME} charsets by consulting the table provided by Emacs itself
912 or the variable @code{mm-mime-mule-charset-alist} for XEmacs.
913 If this results in a single @acronym{MIME} charset, this is used to encode
914 the part.  But if the resulting list of @acronym{MIME} charsets contains more
915 than one element, two things can happen: If it is possible to encode the
916 part via UTF-8, this charset is used.  (For this, Emacs must support
917 the @code{utf-8} coding system, and the part must consist entirely of
918 characters which have Unicode counterparts.)  If UTF-8 is not available
919 for some reason, the part is split into several ones, so that each one
920 can be encoded with a single @acronym{MIME} charset.  The part can only be
921 split at line boundaries, though---if more than one @acronym{MIME} charset is
922 required to encode a single line, it is not possible to encode the part.
923
924 When running Emacs with @sc{mule} support, the preferences for which
925 coding system to use is inherited from Emacs itself.  This means that
926 if Emacs is set up to prefer UTF-8, it will be used when encoding
927 messages.  You can modify this by altering the
928 @code{mm-coding-system-priorities} variable though (@pxref{Encoding
929 Customization}).
930
931 The charset to be used can be overridden by setting the @code{charset}
932 @acronym{MML} tag (@pxref{MML Definition}) when composing the message.
933
934 The encoding of characters (quoted-printable, 8bit etc) is orthogonal
935 to the discussion here, and is controlled by the variables
936 @code{mm-body-charset-encoding-alist} and
937 @code{mm-content-transfer-encoding-defaults} (@pxref{Encoding
938 Customization}).
939
940 @node Conversion
941 @section Conversion
942
943 @findex mime-to-mml
944 A (multipart) @acronym{MIME} message can be converted to @acronym{MML}
945 with the @code{mime-to-mml} function.  It works on the message in the
946 current buffer, and substitutes @acronym{MML} markup for @acronym{MIME}
947 boundaries.  Non-textual parts do not have their contents in the buffer,
948 but instead have the contents in separate buffers that are referred to
949 from the @acronym{MML} tags.
950
951 @findex mml-to-mime
952 An @acronym{MML} message can be converted back to @acronym{MIME} by the
953 @code{mml-to-mime} function.
954
955 These functions are in certain senses ``lossy''---you will not get back
956 an identical message if you run @code{mime-to-mml} and then
957 @code{mml-to-mime}.  Not only will trivial things like the order of the
958 headers differ, but the contents of the headers may also be different.
959 For instance, the original message may use base64 encoding on text,
960 while @code{mml-to-mime} may decide to use quoted-printable encoding, and
961 so on.
962
963 In essence, however, these two functions should be the inverse of each
964 other.  The resulting contents of the message should remain equivalent,
965 if not identical.
966
967
968 @node Flowed text
969 @section Flowed text
970 @cindex format=flowed
971
972 The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines}
973 variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines,
974 emacs, Emacs Manual}) when encoding a message, and the
975 ``format=flowed'' Content-Type parameter when decoding a message.
976
977 On encoding text, regardless of @code{use-hard-newlines}, lines
978 terminated by soft newline characters are filled together and wrapped
979 after the column decided by @code{fill-flowed-encode-column}.
980 Quotation marks (matching @samp{^>* ?}) are respected.  The variable
981 controls how the text will look in a client that does not support
982 flowed text, the default is to wrap after 66 characters.  If hard
983 newline characters are not present in the buffer, no flow encoding
984 occurs.
985
986 On decoding flowed text, lines with soft newline characters are filled
987 together and wrapped after the column decided by
988 @code{fill-flowed-display-column}.  The default is to wrap after
989 @code{fill-column}.
990
991 @table @code
992 @item mm-fill-flowed
993 @vindex mm-fill-flowed
994 If non-@code{nil} a format=flowed article will be displayed flowed.
995 @end table
996
997
998 @node Interface Functions
999 @chapter Interface Functions
1000 @cindex interface functions
1001 @cindex mail-parse
1002
1003 The @code{mail-parse} library is an abstraction over the actual
1004 low-level libraries that are described in the next chapter.
1005
1006 Standards change, and so programs have to change to fit in the new
1007 mold.  For instance, RFC2045 describes a syntax for the
1008 @code{Content-Type} header that only allows @acronym{ASCII} characters in the
1009 parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
1010 for continuation headers and non-@acronym{ASCII} characters.
1011
1012 The traditional way to deal with this is just to update the library
1013 functions to parse the new syntax.  However, this is sometimes the wrong
1014 thing to do.  In some instances it may be vital to be able to understand
1015 both the old syntax as well as the new syntax, and if there is only one
1016 library, one must choose between the old version of the library and the
1017 new version of the library.
1018
1019 The Emacs @acronym{MIME} library takes a different tack.  It defines a
1020 series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el}
1021 and so on) that parses strictly according to the corresponding
1022 standard.  However, normal programs would not use the functions
1023 provided by these libraries directly, but instead use the functions
1024 provided by the @code{mail-parse} library.  The functions in this
1025 library are just aliases to the corresponding functions in the latest
1026 low-level libraries.  Using this scheme, programs get a consistent
1027 interface they can use, and library developers are free to create
1028 write code that handles new standards.
1029
1030 The following functions are defined by this library:
1031
1032 @table @code
1033 @item mail-header-parse-content-type
1034 @findex mail-header-parse-content-type
1035 Parse a @code{Content-Type} header and return a list on the following
1036 format:
1037
1038 @lisp
1039 ("type/subtype"
1040  (attribute1 . value1)
1041  (attribute2 . value2)
1042  ...)
1043 @end lisp
1044
1045 Here's an example:
1046
1047 @example
1048 (mail-header-parse-content-type
1049  "image/gif; name=\"b980912.gif\"")
1050 @result{} ("image/gif" (name . "b980912.gif"))
1051 @end example
1052
1053 @item mail-header-parse-content-disposition
1054 @findex mail-header-parse-content-disposition
1055 Parse a @code{Content-Disposition} header and return a list on the same
1056 format as the function above.
1057
1058 @item mail-content-type-get
1059 @findex mail-content-type-get
1060 Takes two parameters---a list on the format above, and an attribute.
1061 Returns the value of the attribute.
1062
1063 @example
1064 (mail-content-type-get
1065  '("image/gif" (name . "b980912.gif")) 'name)
1066 @result{} "b980912.gif"
1067 @end example
1068
1069 @item mail-header-encode-parameter
1070 @findex mail-header-encode-parameter
1071 Takes a parameter string and returns an encoded version of the string.
1072 This is used for parameters in headers like @code{Content-Type} and
1073 @code{Content-Disposition}.
1074
1075 @item mail-header-remove-comments
1076 @findex mail-header-remove-comments
1077 Return a comment-free version of a header.
1078
1079 @example
1080 (mail-header-remove-comments
1081  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1082 @result{} "Gnus/5.070027  "
1083 @end example
1084
1085 @item mail-header-remove-whitespace
1086 @findex mail-header-remove-whitespace
1087 Remove linear white space from a header.  Space inside quoted strings
1088 and comments is preserved.
1089
1090 @example
1091 (mail-header-remove-whitespace
1092  "image/gif; name=\"Name with spaces\"")
1093 @result{} "image/gif;name=\"Name with spaces\""
1094 @end example
1095
1096 @item mail-header-get-comment
1097 @findex mail-header-get-comment
1098 Return the last comment in a header.
1099
1100 @example
1101 (mail-header-get-comment
1102  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1103 @result{} "Finnish Landrace"
1104 @end example
1105
1106 @item mail-header-parse-address
1107 @findex mail-header-parse-address
1108 Parse an address and return a list containing the mailbox and the
1109 plaintext name.
1110
1111 @example
1112 (mail-header-parse-address
1113  "Hrvoje Niksic <hniksic@@srce.hr>")
1114 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
1115 @end example
1116
1117 @item mail-header-parse-addresses
1118 @findex mail-header-parse-addresses
1119 Parse a string with list of addresses and return a list of elements like
1120 the one described above.
1121
1122 @example
1123 (mail-header-parse-addresses
1124  "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
1125 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
1126      ("sb@@metis.no" . "Steinar Bang"))
1127 @end example
1128
1129 @item mail-header-parse-date
1130 @findex mail-header-parse-date
1131 Parse a date string and return an Emacs time structure.
1132
1133 @item mail-narrow-to-head
1134 @findex mail-narrow-to-head
1135 Narrow the buffer to the header section of the buffer.  Point is placed
1136 at the beginning of the narrowed buffer.
1137
1138 @item mail-header-narrow-to-field
1139 @findex mail-header-narrow-to-field
1140 Narrow the buffer to the header under point.  Understands continuation
1141 headers.
1142
1143 @item mail-header-fold-field
1144 @findex mail-header-fold-field
1145 Fold the header under point.
1146
1147 @item mail-header-unfold-field
1148 @findex mail-header-unfold-field
1149 Unfold the header under point.
1150
1151 @item mail-header-field-value
1152 @findex mail-header-field-value
1153 Return the value of the field under point.
1154
1155 @item mail-encode-encoded-word-region
1156 @findex mail-encode-encoded-word-region
1157 Encode the non-@acronym{ASCII} words in the region.  For instance,
1158 @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
1159
1160 @item mail-encode-encoded-word-buffer
1161 @findex mail-encode-encoded-word-buffer
1162 Encode the non-@acronym{ASCII} words in the current buffer.  This function is
1163 meant to be called narrowed to the headers of a message.
1164
1165 @item mail-encode-encoded-word-string
1166 @findex mail-encode-encoded-word-string
1167 Encode the words that need encoding in a string, and return the result.
1168
1169 @example
1170 (mail-encode-encoded-word-string
1171  "This is naïve, baby")
1172 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
1173 @end example
1174
1175 @item mail-decode-encoded-word-region
1176 @findex mail-decode-encoded-word-region
1177 Decode the encoded words in the region.
1178
1179 @item mail-decode-encoded-word-string
1180 @findex mail-decode-encoded-word-string
1181 Decode the encoded words in the string and return the result.
1182
1183 @example
1184 (mail-decode-encoded-word-string
1185  "This is =?iso-8859-1?q?na=EFve,?= baby")
1186 @result{} "This is naïve, baby"
1187 @end example
1188
1189 @end table
1190
1191 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
1192 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}.  These are documented
1193 in the subsequent sections.
1194
1195
1196
1197 @node Basic Functions
1198 @chapter Basic Functions
1199
1200 This chapter describes the basic, ground-level functions for parsing and
1201 handling.  Covered here is parsing @code{From} lines, removing comments
1202 from header lines, decoding encoded words, parsing date headers and so
1203 on.  High-level functionality is dealt with in the first chapter
1204 (@pxref{Decoding and Viewing}).
1205
1206 @menu
1207 * rfc2045::      Encoding @code{Content-Type} headers.
1208 * rfc2231::      Parsing @code{Content-Type} headers.
1209 * ietf-drums::   Handling mail headers defined by RFC822bis.
1210 * rfc2047::      En/decoding encoded words in headers.
1211 * time-date::    Functions for parsing dates and manipulating time.
1212 * qp::           Quoted-Printable en/decoding.
1213 * base64::       Base64 en/decoding.
1214 * binhex::       Binhex decoding.
1215 * uudecode::     Uuencode decoding.
1216 * yenc::         Yenc decoding.
1217 * rfc1843::      Decoding HZ-encoded text.
1218 * mailcap::      How parts are displayed is specified by the @file{.mailcap} file
1219 @end menu
1220
1221
1222 @node rfc2045
1223 @section rfc2045
1224
1225 RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would
1226 imagine that there would be a lot to implement.  But there isn't, since
1227 most of the implementation details are delegated to the subsequent
1228 RFCs.
1229
1230 So @file{rfc2045.el} has only a single function:
1231
1232 @table @code
1233 @item rfc2045-encode-string
1234 @findex rfc2045-encode-string
1235 Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
1236 @var{value} will be quoted if there are non-safe characters in it.
1237 @end table
1238
1239
1240 @node rfc2231
1241 @section rfc2231
1242
1243 RFC2231 defines a syntax for the @code{Content-Type} and
1244 @code{Content-Disposition} headers.  Its snappy name is @dfn{MIME
1245 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
1246 and Continuations}.
1247
1248 In short, these headers look something like this:
1249
1250 @example
1251 Content-Type: application/x-stuff;
1252  title*0*=us-ascii'en'This%20is%20even%20more%20;
1253  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1254  title*2="isn't it!"
1255 @end example
1256
1257 They usually aren't this bad, though.
1258
1259 The following functions are defined by this library:
1260
1261 @table @code
1262 @item rfc2231-parse-string
1263 @findex rfc2231-parse-string
1264 Parse a @code{Content-Type} header and return a list describing its
1265 elements.
1266
1267 @example
1268 (rfc2231-parse-string
1269  "application/x-stuff;
1270  title*0*=us-ascii'en'This%20is%20even%20more%20;
1271  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1272  title*2=\"isn't it!\"")
1273 @result{} ("application/x-stuff"
1274     (title . "This is even more ***fun*** isn't it!"))
1275 @end example
1276
1277 @item rfc2231-get-value
1278 @findex rfc2231-get-value
1279 Takes one of the lists on the format above and returns
1280 the value of the specified attribute.
1281
1282 @item rfc2231-encode-string
1283 @findex rfc2231-encode-string
1284 Encode a parameter in headers likes @code{Content-Type} and
1285 @code{Content-Disposition}.
1286
1287 @end table
1288
1289
1290 @node ietf-drums
1291 @section ietf-drums
1292
1293 @dfn{drums} is an IETF working group that is working on the replacement
1294 for RFC822.
1295
1296 The functions provided by this library include:
1297
1298 @table @code
1299 @item ietf-drums-remove-comments
1300 @findex ietf-drums-remove-comments
1301 Remove the comments from the argument and return the results.
1302
1303 @item ietf-drums-remove-whitespace
1304 @findex ietf-drums-remove-whitespace
1305 Remove linear white space from the string and return the results.
1306 Spaces inside quoted strings and comments are left untouched.
1307
1308 @item ietf-drums-get-comment
1309 @findex ietf-drums-get-comment
1310 Return the last most comment from the string.
1311
1312 @item ietf-drums-parse-address
1313 @findex ietf-drums-parse-address
1314 Parse an address string and return a list that contains the mailbox and
1315 the plain text name.
1316
1317 @item ietf-drums-parse-addresses
1318 @findex ietf-drums-parse-addresses
1319 Parse a string that contains any number of comma-separated addresses and
1320 return a list that contains mailbox/plain text pairs.
1321
1322 @item ietf-drums-parse-date
1323 @findex ietf-drums-parse-date
1324 Parse a date string and return an Emacs time structure.
1325
1326 @item ietf-drums-narrow-to-header
1327 @findex ietf-drums-narrow-to-header
1328 Narrow the buffer to the header section of the current buffer.
1329
1330 @end table
1331
1332
1333 @node rfc2047
1334 @section rfc2047
1335
1336 RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how
1337 non-@acronym{ASCII} text in headers are to be encoded.  This is actually rather
1338 complicated, so a number of variables are necessary to tweak what this
1339 library does.
1340
1341 The following variables are tweakable:
1342
1343 @table @code
1344 @item rfc2047-header-encoding-alist
1345 @vindex rfc2047-header-encoding-alist
1346 This is an alist of header / encoding-type pairs.  Its main purpose is
1347 to prevent encoding of certain headers.
1348
1349 The keys can either be header regexps, or @code{t}.
1350
1351 The values can be @code{nil}, in which case the header(s) in question
1352 won't be encoded, @code{mime}, which means that they will be encoded, or
1353 @code{address-mime}, which means the header(s) will be encoded carefully
1354 assuming they contain addresses.
1355
1356 @item rfc2047-charset-encoding-alist
1357 @vindex rfc2047-charset-encoding-alist
1358 RFC2047 specifies two forms of encoding---@code{Q} (a
1359 Quoted-Printable-like encoding) and @code{B} (base64).  This alist
1360 specifies which charset should use which encoding.
1361
1362 @item rfc2047-encode-function-alist
1363 @vindex rfc2047-encode-function-alist
1364 This is an alist of encoding / function pairs.  The encodings are
1365 @code{Q}, @code{B} and @code{nil}.
1366
1367 @item rfc2047-encoded-word-regexp
1368 @vindex rfc2047-encoded-word-regexp
1369 When decoding words, this library looks for matches to this regexp.
1370
1371 @item rfc2047-encode-encoded-words
1372 @vindex rfc2047-encode-encoded-words
1373 The boolean variable specifies whether encoded words
1374 (e.g. @samp{=?hello?=}) should be encoded again.
1375
1376 @end table
1377
1378 Those were the variables, and these are this functions:
1379
1380 @table @code
1381 @item rfc2047-narrow-to-field
1382 @findex rfc2047-narrow-to-field
1383 Narrow the buffer to the header on the current line.
1384
1385 @item rfc2047-encode-message-header
1386 @findex rfc2047-encode-message-header
1387 Should be called narrowed to the header of a message.  Encodes according
1388 to @code{rfc2047-header-encoding-alist}.
1389
1390 @item rfc2047-encode-region
1391 @findex rfc2047-encode-region
1392 Encodes all encodable words in the region specified.
1393
1394 @item rfc2047-encode-string
1395 @findex rfc2047-encode-string
1396 Encode a string and return the results.
1397
1398 @item rfc2047-decode-region
1399 @findex rfc2047-decode-region
1400 Decode the encoded words in the region.
1401
1402 @item rfc2047-decode-string
1403 @findex rfc2047-decode-string
1404 Decode a string and return the results.
1405
1406 @item rfc2047-encode-parameter
1407 @findex rfc2047-encode-parameter
1408 Encode a parameter in the RFC2047-like style.  This is a replacement for
1409 the @code{rfc2231-encode-string} function.  @xref{rfc2231}.
1410
1411 When attaching files as @acronym{MIME} parts, we should use the RFC2231
1412 encoding to specify the file names containing non-@acronym{ASCII}
1413 characters.  However, many mail softwares don't support it in practice
1414 and recipients won't be able to extract files with correct names.
1415 Instead, the RFC2047-like encoding is acceptable generally.  This
1416 function provides the very RFC2047-like encoding, resigning to such a
1417 regrettable trend.  To use it, put the following line in your
1418 @file{~/.gnus.el} file:
1419
1420 @lisp
1421 (defalias 'mail-header-encode-parameter 'rfc2047-encode-parameter)
1422 @end lisp
1423
1424 @end table
1425
1426
1427 @node time-date
1428 @section time-date
1429
1430 While not really a part of the @acronym{MIME} library, it is convenient to
1431 document this library here.  It deals with parsing @code{Date} headers
1432 and manipulating time.  (Not by using tesseracts, though, I'm sorry to
1433 say.)
1434
1435 These functions convert between five formats: A date string, an Emacs
1436 time structure, a decoded time list, a second number, and a day number.
1437
1438 Here's a bunch of time/date/second/day examples:
1439
1440 @example
1441 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
1442 @result{} (54 21 12 12 9 1998 6 nil 7200)
1443
1444 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
1445 @result{} (13818 19266)
1446
1447 (time-to-seconds '(13818 19266))
1448 @result{} 905595714.0
1449
1450 (seconds-to-time 905595714.0)
1451 @result{} (13818 19266 0)
1452
1453 (time-to-days '(13818 19266))
1454 @result{} 729644
1455
1456 (days-to-time 729644)
1457 @result{} (961933 65536)
1458
1459 (time-since '(13818 19266))
1460 @result{} (0 430)
1461
1462 (time-less-p '(13818 19266) '(13818 19145))
1463 @result{} nil
1464
1465 (subtract-time '(13818 19266) '(13818 19145))
1466 @result{} (0 121)
1467
1468 (days-between "Sat Sep 12 12:21:54 1998 +0200"
1469               "Sat Sep 07 12:21:54 1998 +0200")
1470 @result{} 5
1471
1472 (date-leap-year-p 2000)
1473 @result{} t
1474
1475 (time-to-day-in-year '(13818 19266))
1476 @result{} 255
1477
1478 (time-to-number-of-days
1479  (time-since
1480   (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
1481 @result{} 4.146122685185185
1482 @end example
1483
1484 And finally, we have @code{safe-date-to-time}, which does the same as
1485 @code{date-to-time}, but returns a zero time if the date is
1486 syntactically malformed.
1487
1488 The five data representations used are the following:
1489
1490 @table @var
1491 @item date
1492 An RFC822 (or similar) date string.  For instance: @code{"Sat Sep 12
1493 12:21:54 1998 +0200"}.
1494
1495 @item time
1496 An internal Emacs time.  For instance: @code{(13818 26466)}.
1497
1498 @item seconds
1499 A floating point representation of the internal Emacs time.  For
1500 instance: @code{905595714.0}.
1501
1502 @item days
1503 An integer number representing the number of days since 00000101.  For
1504 instance: @code{729644}.
1505
1506 @item decoded time
1507 A list of decoded time.  For instance: @code{(54 21 12 12 9 1998 6 t
1508 7200)}.
1509 @end table
1510
1511 All the examples above represent the same moment.
1512
1513 These are the functions available:
1514
1515 @table @code
1516 @item date-to-time
1517 Take a date and return a time.
1518
1519 @item time-to-seconds
1520 Take a time and return seconds.
1521
1522 @item seconds-to-time
1523 Take seconds and return a time.
1524
1525 @item time-to-days
1526 Take a time and return days.
1527
1528 @item days-to-time
1529 Take days and return a time.
1530
1531 @item date-to-day
1532 Take a date and return days.
1533
1534 @item time-to-number-of-days
1535 Take a time and return the number of days that represents.
1536
1537 @item safe-date-to-time
1538 Take a date and return a time.  If the date is not syntactically valid,
1539 return a ``zero'' time.
1540
1541 @item time-less-p
1542 Take two times and say whether the first time is less (i. e., earlier)
1543 than the second time.
1544
1545 @item time-since
1546 Take a time and return a time saying how long it was since that time.
1547
1548 @item subtract-time
1549 Take two times and subtract the second from the first.  I. e., return
1550 the time between the two times.
1551
1552 @item days-between
1553 Take two days and return the number of days between those two days.
1554
1555 @item date-leap-year-p
1556 Take a year number and say whether it's a leap year.
1557
1558 @item time-to-day-in-year
1559 Take a time and return the day number within the year that the time is
1560 in.
1561
1562 @end table
1563
1564
1565 @node qp
1566 @section qp
1567
1568 This library deals with decoding and encoding Quoted-Printable text.
1569
1570 Very briefly explained, qp encoding means translating all 8-bit
1571 characters (and lots of control characters) into things that look like
1572 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
1573 string.
1574
1575 The following functions are defined by the library:
1576
1577 @table @code
1578 @item quoted-printable-decode-region
1579 @findex quoted-printable-decode-region
1580 QP-decode all the encoded text in the specified region.
1581
1582 @item quoted-printable-decode-string
1583 @findex quoted-printable-decode-string
1584 Decode the QP-encoded text in a string and return the results.
1585
1586 @item quoted-printable-encode-region
1587 @findex quoted-printable-encode-region
1588 QP-encode all the encodable characters in the specified region.  The third
1589 optional parameter @var{fold} specifies whether to fold long lines.
1590 (Long here means 72.)
1591
1592 @item quoted-printable-encode-string
1593 @findex quoted-printable-encode-string
1594 QP-encode all the encodable characters in a string and return the
1595 results.
1596
1597 @end table
1598
1599
1600 @node base64
1601 @section base64
1602 @cindex base64
1603
1604 Base64 is an encoding that encodes three bytes into four characters,
1605 thereby increasing the size by about 33%.  The alphabet used for
1606 encoding is very resistant to mangling during transit.
1607
1608 The following functions are defined by this library:
1609
1610 @table @code
1611 @item base64-encode-region
1612 @findex base64-encode-region
1613 base64 encode the selected region.  Return the length of the encoded
1614 text.  Optional third argument @var{no-line-break} means do not break
1615 long lines into shorter lines.
1616
1617 @item base64-encode-string
1618 @findex base64-encode-string
1619 base64 encode a string and return the result.
1620
1621 @item base64-decode-region
1622 @findex base64-decode-region
1623 base64 decode the selected region.  Return the length of the decoded
1624 text.  If the region can't be decoded, return @code{nil} and don't
1625 modify the buffer.
1626
1627 @item base64-decode-string
1628 @findex base64-decode-string
1629 base64 decode a string and return the result.  If the string can't be
1630 decoded, @code{nil} is returned.
1631
1632 @end table
1633
1634
1635 @node binhex
1636 @section binhex
1637 @cindex binhex
1638 @cindex Apple
1639 @cindex Macintosh
1640
1641 @code{binhex} is an encoding that originated in Macintosh environments.
1642 The following function is supplied to deal with these:
1643
1644 @table @code
1645 @item binhex-decode-region
1646 @findex binhex-decode-region
1647 Decode the encoded text in the region.  If given a third parameter, only
1648 decode the @code{binhex} header and return the filename.
1649
1650 @end table
1651
1652 @node uudecode
1653 @section uudecode
1654 @cindex uuencode
1655 @cindex uudecode
1656
1657 @code{uuencode} is probably still the most popular encoding of binaries
1658 used on Usenet, although @code{base64} rules the mail world.
1659
1660 The following function is supplied by this package:
1661
1662 @table @code
1663 @item uudecode-decode-region
1664 @findex uudecode-decode-region
1665 Decode the text in the region.
1666 @end table
1667
1668
1669 @node yenc
1670 @section yenc
1671 @cindex yenc
1672
1673 @code{yenc} is used for encoding binaries on Usenet.  The following
1674 function is supplied by this package:
1675
1676 @table @code
1677 @item yenc-decode-region
1678 @findex yenc-decode-region
1679 Decode the encoded text in the region.
1680
1681 @end table
1682
1683
1684 @node rfc1843
1685 @section rfc1843
1686 @cindex rfc1843
1687 @cindex HZ
1688 @cindex Chinese
1689
1690 RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages.  In
1691 essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this:
1692
1693 @example
1694 This sentence is in @acronym{ASCII}.
1695 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
1696 @end example
1697
1698 Simple enough, and widely used in China.
1699
1700 The following functions are available to handle this encoding:
1701
1702 @table @code
1703 @item rfc1843-decode-region
1704 Decode HZ-encoded text in the region.
1705
1706 @item rfc1843-decode-string
1707 Decode a HZ-encoded string and return the result.
1708
1709 @end table
1710
1711
1712 @node mailcap
1713 @section mailcap
1714
1715 The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message
1716 handlers and describes how elements are supposed to be displayed.
1717 Here's an example file:
1718
1719 @example
1720 image/*; gimp -8 %s
1721 audio/wav; wavplayer %s
1722 application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc
1723 @end example
1724
1725 This says that all image files should be displayed with @code{gimp},
1726 that WAVE audio files should be played by @code{wavplayer}, and that
1727 MS-WORD files should be inlined by @code{catdoc}.
1728
1729 The @code{mailcap} library parses this file, and provides functions for
1730 matching types.
1731
1732 @table @code
1733 @item mailcap-mime-data
1734 @vindex mailcap-mime-data
1735 This variable is an alist of alists containing backup viewing rules.
1736
1737 @end table
1738
1739 Interface functions:
1740
1741 @table @code
1742 @item mailcap-parse-mailcaps
1743 @findex mailcap-parse-mailcaps
1744 Parse the @file{~/.mailcap} file.
1745
1746 @item mailcap-mime-info
1747 Takes a @acronym{MIME} type as its argument and returns the matching viewer.
1748
1749 @end table
1750
1751
1752
1753
1754 @node Standards
1755 @chapter Standards
1756
1757 The Emacs @acronym{MIME} library implements handling of various elements
1758 according to a (somewhat) large number of RFCs, drafts and standards
1759 documents.  This chapter lists the relevant ones.  They can all be
1760 fetched from @uref{http://quimby.gnus.org/notes/}.
1761
1762 @table @dfn
1763 @item RFC822
1764 @itemx STD11
1765 Standard for the Format of ARPA Internet Text Messages.
1766
1767 @item RFC1036
1768 Standard for Interchange of USENET Messages
1769
1770 @item RFC2045
1771 Format of Internet Message Bodies
1772
1773 @item RFC2046
1774 Media Types
1775
1776 @item RFC2047
1777 Message Header Extensions for Non-@acronym{ASCII} Text
1778
1779 @item RFC2048
1780 Registration Procedures
1781
1782 @item RFC2049
1783 Conformance Criteria and Examples
1784
1785 @item RFC2231
1786 @acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets,
1787 Languages, and Continuations
1788
1789 @item RFC1843
1790 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1791 @acronym{ASCII} characters
1792
1793 @item draft-ietf-drums-msg-fmt-05.txt
1794 Draft for the successor of RFC822
1795
1796 @item RFC2112
1797 The @acronym{MIME} Multipart/Related Content-type
1798
1799 @item RFC1892
1800 The Multipart/Report Content Type for the Reporting of Mail System
1801 Administrative Messages
1802
1803 @item RFC2183
1804 Communicating Presentation Information in Internet Messages: The
1805 Content-Disposition Header Field
1806
1807 @item RFC2646
1808 Documentation of the text/plain format parameter for flowed text.
1809
1810 @end table
1811
1812 @node GNU Free Documentation License
1813 @chapter GNU Free Documentation License
1814 @include doclicense.texi
1815
1816 @node Index
1817 @chapter Index
1818 @printindex cp
1819
1820 @summarycontents
1821 @contents
1822 @bye
1823
1824 \f
1825 @c Local Variables:
1826 @c mode: texinfo
1827 @c coding: iso-8859-1
1828 @c End:
1829
1830 @ignore
1831    arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d
1832 @end ignore