-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*- -*- coding: iso-latin-1 -*-
@setfilename emacs-mime
@settitle Emacs MIME Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
-@c @direntry
-@c * Emacs MIME: (emacs-mime). The MIME de/composition library.
-@c @end direntry
+@dircategory Emacs
+@direntry
+* Emacs MIME: (emacs-mime). The MIME de/composition library.
+@end direntry
@iftex
@finalout
@end iftex
@setchapternewpage odd
-@ifinfo
+@ifnottex
This file documents the Emacs MIME interface functionality.
-Copyright (C) 1998,99 Free Software Foundation, Inc.
+Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
-@ignore
-Permission is granted to process this file through Tex and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@end ifinfo
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end ifnottex
@tex
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1998,99 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-
+Copyright @copyright{} 1998, 1999, 2000 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being none, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
@end titlepage
@page
These functions convert between five formats: A date string, an Emacs
time structure, a decoded time list, a second number, and a day number.
-The functions have quite self-explanatory names, so the following just
-gives an overview of which functions are available.
+Here's a bunch of time/date/second/day examples:
@example
(parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
(seconds-to-time 905595714.0)
@result{} (13818 19266 0)
-(time-to-day '(13818 19266))
+(time-to-days '(13818 19266))
@result{} 729644
(days-to-time 729644)
(time-to-day-in-year '(13818 19266))
@result{} 255
+(time-to-number-of-days
+ (time-since
+ (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
+@result{} 4.146122685185185
@end example
And finally, we have @code{safe-date-to-time}, which does the same as
@code{date-to-time}, but returns a zero time if the date is
syntactically malformed.
+The five data representations used are the following:
+
+@table @var
+@item date
+An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12
+12:21:54 1998 +0200"}.
+
+@item time
+An internal Emacs time. For instance: @code{(13818 26466)}.
+
+@item seconds
+A floating point representation of the internal Emacs time. For
+instance: @code{905595714.0}.
+
+@item days
+An integer number representing the number of days since 00000101. For
+instance: @code{729644}.
+
+@item decoded time
+A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t
+7200)}.
+@end table
+
+All the examples above represent the same moment.
+
+These are the functions available:
+
+@table @code
+@item date-to-time
+Take a date and return a time.
+
+@item time-to-seconds
+Take a time and return seconds.
+
+@item seconds-to-time
+Take seconds and return a time.
+
+@item time-to-days
+Take a time and return days.
+
+@item days-to-time
+Take days and return a time.
+
+@item date-to-day
+Take a date and return days.
+
+@item time-to-number-of-days
+Take a time and return the number of days that represents.
+
+@item safe-date-to-time
+Take a date and return a time. If the date is not syntactically valid,
+return a "zero" date.
+
+@item time-less-p
+Take two times and say whether the first time is less (i. e., earlier)
+than the second time.
+
+@item time-since
+Take a time and return a time saying how long it was since that time.
+
+@item subtract-time
+Take two times and subtract the second from the first. I. e., return
+the time between the two times.
+
+@item days-between
+Take two days and return the number of days between those two days.
+
+@item date-leap-year-p
+Take a year number and say whether it's a leap year.
+
+@item time-to-day-in-year
+Take a time and return the day number within the year that the time is
+in.
+
+@end table
@node qp
audio/wav; wavplayer %s
@end example
-This says that all image files should be displayed with @samp{xv}, and
-that realaudio files should be played by @samp{rvplayer}.
+This says that all image files should be displayed with @code{gimp}, and
+that WAVE audio files should be played by @code{wavplayer}.
The @code{mailcap} library parses this file, and provides functions for
matching types.
@menu
* Dissection:: Analyzing a @sc{mime} message.
+* Non-MIME:: Analyzing a non-@sc{mime} message.
* Handles:: Handle manipulations.
* Display:: Displaying handles.
* Customization:: Variables that affect display.
descend the message, following the structure, and return a tree of
@sc{mime} handles that describes the structure of the message.
+@node Non-MIME
+@section Non-MIME
+
+Gnus also understands some non-MIME attachments, such as postscript,
+uuencode, binhex, shar, forward, gnatsweb, pgp. Each of these features
+can be disabled by add an item into @code{mm-uu-configure-list}.
+For example,
+
+@lisp
+(require 'mm-uu)
+(add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
+@end lisp
+
+@table @code
+@item postscript
+@findex postscript
+Postscript file.
+
+@item uu
+@findex uu
+Uuencoded file.
+
+@item binhex
+@findex binhex
+Binhex encoded file.
+
+@item shar
+@findex shar
+Shar archive file.
+
+@item forward
+@findex forward
+Non-@sc{mime} forwarded message.
+
+@item gnatsweb
+@findex gnatsweb
+Gnatsweb attachment.
+
+@item pgp-signed
+@findex pgp-signed
+PGP signed clear text.
+
+@item pgp-encrypted
+@findex pgp-encrypted
+PGP encrypted clear text.
+
+@item pgp-key
+@findex pgp-key
+PGP public keys.
+
+@item emacs-sources
+@findex emacs-sources
+Emacs source code. This item works only in the groups matching
+@code{mm-uu-emacs-sources-regexp}.
+
+@end table
@node Handles
@section Handles
* Simple MML Example:: An example MML document.
* MML Definition:: All valid MML elements.
* Advanced MML Example:: Another example MML document.
+* Charset Translation:: How charsets are mapped from @sc{mule} to MIME.
* Conversion:: Going from @sc{mime} to MML and vice versa.
@end menu
@item size
The size (in octets) of the part (@code{Content-Disposition}).
+@item sign
+What technology to sign this MML part with (@code{smime}, @code{pgp}
+or @code{pgpmime})
+
+@item encrypt
+What technology to encrypt this MML part with (@code{smime},
+@code{pgp} or @code{pgpmime})
+
@end table
Parameters for @samp{application/octet-stream}:
@end table
+Parameters for @samp{sign=smime}:
+
+@table @samp
+
+@item keyfile
+File containing key and certificate for signer.
+
+@end table
+
+Parameters for @samp{encrypt=smime}:
+
+@table @samp
+
+@item certfile
+File containing certificate for recipient.
+
+@end table
+
@node Advanced MML Example
@section Advanced MML Example
--=-=-=--
@end example
+@node Charset Translation
+@section Charset Translation
+@cindex charsets
+
+During translation from MML to @sc{mime}, for each @sc{mime} part which
+has been composed inside Emacs, an appropriate charset has to be chosen.
+
+@vindex mail-parse-charset
+If you are running a non-@sc{mule} Emacs, this process is simple: If the
+part contains any non-ASCII (8-bit) characters, the @sc{mime} charset
+given by @code{mail-parse-charset} (a symbol) is used. (Never set this
+variable directly, though. If you want to change the default charset,
+please consult the documentation of the package which you use to process
+@sc{mime} messages.
+@xref{Various Message Variables, , Various Message Variables, message,
+ Message Manual}, for example.)
+If there are only ASCII characters, the @sc{mime} charset US-ASCII is
+used, of course.
+
+@cindex MULE
+@cindex UTF-8
+@cindex Unicode
+@vindex mm-mime-mule-charset-alist
+Things are slightly more complicated when running Emacs with @sc{mule}
+support. In this case, a list of the @sc{mule} charsets used in the
+part is obtained, and the @sc{mule} charsets are translated to @sc{mime}
+charsets by consulting the variable @code{mm-mime-mule-charset-alist}.
+If this results in a single @sc{mime} charset, this is used to encode
+the part. But if the resulting list of @sc{mime} charsets contains more
+than one element, two things can happen: If it is possible to encode the
+part via UTF-8, this charset is used. (For this, Emacs must support
+the @code{utf-8} coding system, and the part must consist entirely of
+characters which have Unicode counterparts.) If UTF-8 is not available
+for some reason, the part is split into several ones, so that each one
+can be encoded with a single @sc{mime} charset. The part can only be
+split at line boundaries, though---if more than one @sc{mime} charset is
+required to encode a single line, it is not possible to encode the part.
@node Conversion
@section Conversion
The Emacs @sc{mime} library implements handling of various elements
according to a (somewhat) large number of RFCs, drafts and standards
documents. This chapter lists the relevant ones. They can all be
-fetched from @samp{http://quimby.gnus.org/notes/}.
+fetched from @uref{http://quimby.gnus.org/notes/}.
@table @dfn
@item RFC822
projects / gnus / blobdiff