-\input texinfo @c -*-texinfo-*-
+\input texinfo
@setfilename emacs-mime
@settitle Emacs MIME Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
-@dircategory Editors
+@dircategory Emacs
@direntry
* Emacs MIME: (emacs-mime). The MIME de/composition library.
@end direntry
@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, 2002 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
@item mail-header-narrow-to-field
@findex mail-header-narrow-to-field
-Narrow the buffer to the header under point.
+Narrow the buffer to the header under point. Understands continuation
+headers.
+
+@item mail-header-fold-field
+@findex mail-header-fold-field
+Fold the header under point.
+
+@item mail-header-unfold-field
+@findex mail-header-unfold-field
+Unfold the header under point.
+
+@item mail-header-field-value
+@findex mail-header-field-value
+Return the value of the field under point.
@item mail-encode-encoded-word-region
@findex mail-encode-encoded-word-region
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
@table @code
+@item mm-inline-text-html-renderer
+@findex mm-inline-text-html-render-with-w3
+@findex mm-inline-text-html-render-with-w3m
+This function will be used to convert the HTML to the text. There are
+two pre-defined functions: @code{mm-inline-text-html-render-with-w3},
+which uses Emacs/w3; and @code{mm-inline-text-html-render-with-w3m},
+which uses emacs-w3m (see @uref{http://emacs-w3m.namazu.org/} for more
+information about emacs-w3m). The function will be called with a MIME
+handle as the argument.
+
+@item mm-inline-text-html-with-images
+Some HTML mails might have the trick of spammers using @samp{<img>} tags.
+It is likely to be intended to verify whether you have read the mail.
+You can prevent your personal informations from leaking by setting this
+option to @code{nil} (which is the default). It is currently ignored by
+Emacs/w3. For emacs-w3m, you may use the command @kbd{t} on the image
+anchor to show an image even if it is @code{nil}.
+
@item mm-inline-media-tests
This is an alist where the key is a @sc{mime} type, the second element
-is a function to display the part @dfn{inline} (i.e., inside Emacs), and
+is a function to display the part @dfn{inline} (i.e., inside Emacs), and
the third element is a form to be @code{eval}ed to say whether the part
can be displayed inline.
@item mm-attachment-override-types
Some @sc{mime} agents create parts that have a content-disposition of
-@samp{attachment}. This variable allows overriding that disposition and
+@samp{attachment}. This variable allows overriding that disposition and
displaying the part inline. (Note that the disposition is only
overridden if we are able to, and want to, display the part inline.)
However, users may prefer other types instead, and this list says what
types are most unwanted. If, for instance, @samp{text/html} parts are
very unwanted, and @samp{text/richtech} parts are somewhat unwanted,
-then the value of this variable should be set to:
+you could say something like:
@lisp
-("text/html" "text/richtext")
+(setq mm-discouraged-alternatives
+ '("text/html" "text/richtext")
+ mm-automatic-display
+ (remove "text/html" mm-automatic-display))
@end lisp
@item mm-inline-large-images-p
makes the library display all inline images as inline, regardless of
their size.
-@item mm-inline-override-p
+@item mm-inline-override-type
@code{mm-inlined-types} may include regular expressions, for example to
specify that all @samp{text/.*} parts be displayed inline. If a user
prefers to have a type that matches such a regular expression be treated
@end lisp
We see that the function takes a @sc{mime} handle as its parameter. It
-then goes to a temporary buffer, inserts the text of the part, does some
+then goes to a temporary buffer, inserts the text of the part, does some
work on the text, stores the result, goes back to the buffer it was
called from and inserts the result.
* 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.
+* Flowed text:: Soft and hard newlines.
@end menu
@item read-date
RFC822 date when the part was read (@code{Content-Disposition}).
+@item recipients
+Who to encrypt/sign the part to. This field is used to override any
+auto-detection based on the To/CC headers.
+
@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
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,
+@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.
if not identical.
+@node Flowed text
+@section Flowed text
+@cindex format=flowed
+
+The Emacs @sc{mime} library will respect the @code{use-hard-newlines}
+variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines,
+emacs, Emacs Manual}) when encoding a message, and the
+``format=flowed'' Content-Type parameter when decoding a message.
+
+On encoding text, lines terminated by soft newline characters are
+filled together and wrapped after the column decided by
+@code{fill-flowed-encode-column}. This variable controls how the text
+will look in a client that does not support flowed text, the default
+is to wrap after 66 characters. If hard newline characters are not
+present in the buffer, no flow encoding occurs.
+
+On decoding flowed text, lines with soft newline characters are filled
+together and wrapped after the column decided by
+@code{fill-flowed-display-column}. The default is to wrap after
+@code{fill-column}.
+
@node Standards
@chapter Standards
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
Communicating Presentation Information in Internet Messages: The
Content-Disposition Header Field
+@item RFC2646
+Documentation of the text/plain format parameter for flowed text.
+
@end table
@contents
@bye
+\f
+@c Local Variables:
+@c mode: texinfo
+@c coding: iso-8859-1
@c End:
projects / gnus / blobdiff