@synindex fn cp
@synindex vr cp
@synindex pg cp
-@dircategory Editors
+@dircategory Emacs
@direntry
-* Emacs MIME: (emacs-mime). The MIME de/composition library.
+* MIME: (emacs-mime). Emacs MIME de/composition library.
@end direntry
@iftex
@finalout
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
+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''.
+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 ifnottex
@tex
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''.
+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
Standards change, and so programs have to change to fit in the new
mold. For instance, RFC2045 describes a syntax for the
-@code{Content-Type} header that only allows ASCII characters in the
+@code{Content-Type} header that only allows @sc{ascii} characters in the
parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme
-for continuation headers and non-ASCII characters.
+for continuation headers and non-@sc{ascii} characters.
The traditional way to deal with this is just to update the library
functions to parse the new syntax. However, this is sometimes the wrong
The following functions are defined by this library:
-@table @code
-@item mail-header-parse-content-type
-@findex mail-header-parse-content-type
-Parse a @code{Content-Type} header and return a list on the following
-format:
+@defun mail-header-parse-content-type string
+Parse @var{string}, a @code{Content-Type} header, and return a
+content-type list in the following format:
@lisp
("type/subtype"
(attribute1 . value1)
(attribute2 . value2)
- ...)
+ @dots{})
@end lisp
Here's an example:
"image/gif; name=\"b980912.gif\"")
@result{} ("image/gif" (name . "b980912.gif"))
@end example
+@end defun
-@item mail-header-parse-content-disposition
-@findex mail-header-parse-content-disposition
-Parse a @code{Content-Disposition} header and return a list on the same
-format as the function above.
+@defun mail-header-parse-content-disposition string
+Parse @var{string}, a @code{Content-Disposition} header, and return a
+content-type list in the format above.
+@end defun
-@item mail-content-type-get
+@defun mail-content-type-get ct attribute
@findex mail-content-type-get
-Takes two parameters---a list on the format above, and an attribute.
-Returns the value of the attribute.
+Returns the value of the given @var{attribute} from the content-type
+list @var{ct}.
@example
(mail-content-type-get
'("image/gif" (name . "b980912.gif")) 'name)
@result{} "b980912.gif"
@end example
+@end defun
-@item mail-header-encode-parameter
-@findex mail-header-encode-parameter
-Takes a parameter string and returns an encoded version of the string.
-This is used for parameters in headers like @code{Content-Type} and
-@code{Content-Disposition}.
+@defun mail-header-encode-parameter param value
+Takes a parameter string @samp{@var{param}=@var{value}} and returns an
+encoded version of it. This is used for parameters in headers like
+@samp{Content-Type} and @samp{Content-Disposition}.
+@end defun
-@item mail-header-remove-comments
-@findex mail-header-remove-comments
-Return a comment-free version of a header.
+@defun mail-header-remove-comments string
+Return a comment-free version of @var{string}.
@example
(mail-header-remove-comments
"Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
@result{} "Gnus/5.070027 "
@end example
+@end defun
-@item mail-header-remove-whitespace
-@findex mail-header-remove-whitespace
-Remove linear white space from a header. Space inside quoted strings
-and comments is preserved.
+@defun mail-header-remove-whitespace string
+Remove linear white space from @var{string}. Space inside quoted
+strings and comments is preserved.
@example
(mail-header-remove-whitespace
"image/gif; name=\"Name with spaces\"")
@result{} "image/gif;name=\"Name with spaces\""
@end example
+@end defun
-@item mail-header-get-comment
-@findex mail-header-get-comment
-Return the last comment in a header.
+@defun mail-header-get-comment string
+Return the last comment in @var{string}.
@example
(mail-header-get-comment
"Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
@result{} "Finnish Landrace"
@end example
+@end defun
+
-@item mail-header-parse-address
-@findex mail-header-parse-address
-Parse an address and return a list containing the mailbox and the
-plaintext name.
+@defun mail-header-parse-address string
+Parse an address string @var{string} and return a list containing the
+mailbox and the plaintext name.
@example
(mail-header-parse-address
"Hrvoje Niksic <hniksic@@srce.hr>")
@result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
@end example
+@end defun
-@item mail-header-parse-addresses
-@findex mail-header-parse-addresses
-Parse a string with list of addresses and return a list of elements like
-the one described above.
+@defun mail-header-parse-addresses string
+Parse @var{string} as a list of addresses and return a list of elements
+like the one described above.
@example
(mail-header-parse-addresses
@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
("sb@@metis.no" . "Steinar Bang"))
@end example
+@end defun
-@item mail-header-parse-date
-@findex mail-header-parse-date
-Parse a date string and return an Emacs time structure.
+@defun mail-header-parse-date string
+Parse a date @var{string} and return an Emacs time structure.
+@end defun
-@item mail-narrow-to-head
-@findex mail-narrow-to-head
+@defun mail-narrow-to-head
Narrow the buffer to the header section of the buffer. Point is placed
at the beginning of the narrowed buffer.
+@end defun
-@item mail-header-narrow-to-field
-@findex mail-header-narrow-to-field
+@defun mail-header-narrow-to-field
Narrow the buffer to the header under point.
+@end defun
-@item mail-encode-encoded-word-region
-@findex mail-encode-encoded-word-region
-Encode the non-ASCII words in the region. For instance,
-@samp{Na\7fve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
+@defun mail-encode-encoded-word-region start end
+Encode the non-@sc{ascii} words in the region @var{start}to @var{end}. For
+instance, @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
+@end defun
-@item mail-encode-encoded-word-buffer
-@findex mail-encode-encoded-word-buffer
-Encode the non-ASCII words in the current buffer. This function is
-meant to be called narrowed to the headers of a message.
+@defun mail-encode-encoded-word-buffer
+Encode the non-@sc{ascii} words in the current buffer. This function is
+meant to be called with the buffer narrowed to the headers of a message.
+@end defun
-@item mail-encode-encoded-word-string
-@findex mail-encode-encoded-word-string
-Encode the words that need encoding in a string, and return the result.
+@defun mail-encode-encoded-word-string string
+Encode the words that need encoding in @var{string}, and return the
+result.
@example
(mail-encode-encoded-word-string
"This is naïve, baby")
@result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
@end example
+@end defun
-@item mail-decode-encoded-word-region
-@findex mail-decode-encoded-word-region
-Decode the encoded words in the region.
+@defun mail-decode-encoded-word-region start end
+Decode the encoded words in the region @var{start}to @var{end}.
+@end defun
-@item mail-decode-encoded-word-string
-@findex mail-decode-encoded-word-string
-Decode the encoded words in the string and return the result.
+@defun mail-decode-encoded-word-string string
+Decode the encoded words in @var{string} and return the result.
@example
(mail-decode-encoded-word-string
"This is =?iso-8859-1?q?na=EFve,?= baby")
@result{} "This is naïve, baby"
@end example
-
-@end table
+@end defun
Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
@code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented
* binhex:: Binhex decoding.
* uudecode:: Uuencode decoding.
* rfc1843:: Decoding HZ-encoded text.
-* mailcap:: How parts are displayed is specified by the @file{.mailcap} file
+* mailcap:: How parts are displayed is specified by mailcap files
@end menu
So @file{rfc2045.el} has only a single function:
-@table @code
-@item rfc2045-encode-string
+@defun rfc2045-encode-string parameter value
@findex rfc2045-encode-string
-Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
-@var{value} will be quoted if there are non-safe characters in it.
-@end table
+Takes a @var{parameter} and a @var{value} and returns a
+@samp{@var{param}=@var{value}} string. @var{value} will be quoted if
+there are non-safe characters in it.
+@end defun
@node rfc2231
@section rfc2231
-RFC2231 defines a syntax for the @code{Content-Type} and
-@code{Content-Disposition} headers. Its snappy name is @dfn{MIME
+RFC2231 defines a syntax for the @samp{Content-Type} and
+@samp{Content-Disposition} headers. Its snappy name is @dfn{MIME
Parameter Value and Encoded Word Extensions: Character Sets, Languages,
and Continuations}.
The following functions are defined by this library:
-@table @code
-@item rfc2231-parse-string
-@findex rfc2231-parse-string
-Parse a @code{Content-Type} header and return a list describing its
-elements.
+@defun rfc2231-parse-string string
+Parse a @samp{Content-Type} header @var{string} and return a list
+describing its elements.
@example
(rfc2231-parse-string
@result{} ("application/x-stuff"
(title . "This is even more ***fun*** isn't it!"))
@end example
+@end defun
-@item rfc2231-get-value
-@findex rfc2231-get-value
-Takes one of the lists on the format above and returns
-the value of the specified attribute.
-
-@item rfc2231-encode-string
-@findex rfc2231-encode-string
-Encode a parameter in headers likes @code{Content-Type} and
-@code{Content-Disposition}.
-
-@end table
+@defun rfc2231-get-value ct attribute
+Takes a list @var{ct} of the format above and returns the value of the
+specified @var{attribute}.
+@end defun
+@defun rfc2231-encode-string parameter value
+Encode the string @samp{@var{parameter}=@var{value}} for inclusion in
+headers likes @samp{Content-Type} and @samp{Content-Disposition}.
+@end defun
@node ietf-drums
@section ietf-drums
The functions provided by this library include:
-@table @code
-@item ietf-drums-remove-comments
-@findex ietf-drums-remove-comments
-Remove the comments from the argument and return the results.
+@defun ietf-drums-remove-comments string
+Remove the comments from @var{string} and return the result.
+@end defun
-@item ietf-drums-remove-whitespace
-@findex ietf-drums-remove-whitespace
-Remove linear white space from the string and return the results.
+@defun ietf-drums-remove-whitespace string
+Remove linear white space from @var{string} and return the result.
Spaces inside quoted strings and comments are left untouched.
+@end defun
-@item ietf-drums-get-comment
-@findex ietf-drums-get-comment
-Return the last most comment from the string.
+@defun ietf-drums-get-comment string
+Return the last most comment from @var{string}.
+@end defun
-@item ietf-drums-parse-address
-@findex ietf-drums-parse-address
-Parse an address string and return a list that contains the mailbox and
-the plain text name.
+@defun ietf-drums-parse-address string
+Parse an address @var{string} and return a list of the mailbox and the
+plain text name.
+@end defun
-@item ietf-drums-parse-addresses
-@findex ietf-drums-parse-addresses
-Parse a string that contains any number of comma-separated addresses and
-return a list that contains mailbox/plain text pairs.
+@defun ietf-drums-parse-addresses string
+Parse @var{string}, containing any number of comma-separated addresses,
+and return a list of mailbox/plain text pairs.
+@end defun
-@item ietf-drums-parse-date
-@findex ietf-drums-parse-date
-Parse a date string and return an Emacs time structure.
+@defun ietf-drums-parse-date string
+Parse the date @var{string} and return an Emacs time structure.
+@end defun
-@item ietf-drums-narrow-to-header
-@findex ietf-drums-narrow-to-header
+@defun ietf-drums-narrow-to-header
Narrow the buffer to the header section of the current buffer.
-
-@end table
+@end defun
@node rfc2047
@section rfc2047
RFC2047 (Message Header Extensions for Non-ASCII Text) specifies how
-non-ASCII text in headers are to be encoded. This is actually rather
+non-@sc{ascii} text in headers are to be encoded. This is actually rather
complicated, so a number of variables are necessary to tweak what this
library does.
The following variables are tweakable:
-@table @code
-@item rfc2047-default-charset
-@vindex rfc2047-default-charset
+@defvar rfc2047-default-charset
Characters in this charset should not be decoded by this library.
-This defaults to @code{iso-8859-1}.
+This defaults to @samp{iso-8859-1}.
+@end defvar
-@item rfc2047-header-encoding-list
-@vindex rfc2047-header-encoding-list
+@defvar rfc2047-header-encoding-list
This is an alist of header / encoding-type pairs. Its main purpose is
to prevent encoding of certain headers.
+@end defvar
The keys can either be header regexps, or @code{t}.
question won't be encoded, or @code{mime}, which means that they will be
encoded.
-@item rfc2047-charset-encoding-alist
-@vindex rfc2047-charset-encoding-alist
+@defvar rfc2047-charset-encoding-alist
RFC2047 specifies two forms of encoding---@code{Q} (a
Quoted-Printable-like encoding) and @code{B} (base64). This alist
specifies which charset should use which encoding.
+@end defvar
-@item rfc2047-encoding-function-alist
-@vindex rfc2047-encoding-function-alist
+@defvar rfc2047-encoding-function-alist
This is an alist of encoding / function pairs. The encodings are
@code{Q}, @code{B} and @code{nil}.
+@end defvar
-@item rfc2047-q-encoding-alist
-@vindex rfc2047-q-encoding-alist
+@defvar rfc2047-q-encoding-alist
The @code{Q} encoding isn't quite the same for all headers. Some
headers allow a narrower range of characters, and that is what this
-variable is for. It's an alist of header regexps / allowable character
+variable is for. It's an alist of header regexps and allowable character
ranges.
+@end defvar
-@item rfc2047-encoded-word-regexp
-@vindex rfc2047-encoded-word-regexp
+@defvar rfc2047-encoded-word-regexp
When decoding words, this library looks for matches to this regexp.
+@end defvar
-@end table
-
-Those were the variables, and these are this functions:
+Those were the variables, and these are the functions:
-@table @code
-@item rfc2047-narrow-to-field
-@findex rfc2047-narrow-to-field
+@defun rfc2047-narrow-to-field
Narrow the buffer to the header on the current line.
+@end defun
-@item rfc2047-encode-message-header
-@findex rfc2047-encode-message-header
+@defun rfc2047-encode-message-header
Should be called narrowed to the header of a message. Encodes according
to @code{rfc2047-header-encoding-alist}.
+@end defun
-@item rfc2047-encode-region
-@findex rfc2047-encode-region
-Encodes all encodable words in the region specified.
+@defun rfc2047-encode-region start end
+Encodes all encodable words in the region @var{start} to @var{end}.
+@end defun
-@item rfc2047-encode-string
-@findex rfc2047-encode-string
-Encode a string and return the results.
+@defun rfc2047-encode-string string
+Encode @var{string} and return the result.
+@end defun
-@item rfc2047-decode-region
-@findex rfc2047-decode-region
-Decode the encoded words in the region.
+@defun rfc2047-decode-region start end
+Decode the encoded words in the region @var{start} to @var{end}.
+@end defun
-@item rfc2047-decode-string
-@findex rfc2047-decode-string
-Decode a string and return the results.
+@defun rfc2047-decode-string string
+Decode @var{string} and return the result.
+@end defun
-@end table
@node time-date
@section time-date
While not really a part of the @sc{mime} library, it is convenient to
-document this library here. It deals with parsing @code{Date} headers
+document this library here. It deals with parsing @samp{Date} headers
and manipulating time. (Not by using tesseracts, though, I'm sorry to
say.)
-These functions convert between five formats: A date string, an Emacs
-time structure, a decoded time list, a second number, and a day number.
+These functions convert between five formats: a date string, an Emacs
+time structure, a decoded time list, a number of seconds, and a day number.
The functions have quite self-explanatory names, so the following just
gives an overview of which functions are available.
+@findex parse-time-string
+@findex date-to-time
+@findex time-to-seconds
+@findex seconds-to-time
+@findex time-to-day
+@findex days-to-time
+@findex time-since
+@findex time-less-p
+@findex subtract-time
+@findex days-between
+@findex date-leap-year-p
+@findex time-to-day-in-year
@example
(parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
@result{} (54 21 12 12 9 1998 6 nil 7200)
(time-to-day-in-year '(13818 19266))
@result{} 255
-
@end example
+@findex safe-date-to-time
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.
This library deals with decoding and encoding Quoted-Printable text.
-Very briefly explained, qp encoding means translating all 8-bit
+Very briefly explained, QP encoding means translating all 8-bit
characters (and lots of control characters) into things that look like
@samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
-string.
+string. It is defined in RFC 2045.
The following functions are defined by the library:
-@table @code
-@item quoted-printable-decode-region
-@findex quoted-printable-decode-region
-QP-decode all the encoded text in the specified region.
-
-@item quoted-printable-decode-string
-@findex quoted-printable-decode-string
-Decode the QP-encoded text in a string and return the results.
-
-@item quoted-printable-encode-region
-@findex quoted-printable-encode-region
-QP-encode all the encodable characters in the specified region. The third
-optional parameter @var{fold} specifies whether to fold long lines.
-(Long here means 72.)
-
-@item quoted-printable-encode-string
-@findex quoted-printable-encode-string
-QP-encode all the encodable characters in a string and return the
-results.
-
-@end table
-
+@deffn Command quoted-printable-decode-region @var{from} @var{to} &optional @var{coding-system}
+QP-decode all the encoded text in the region. If @var{coding-system}
+is non-nil, decode bytes into characters with that coding-system. It
+is probably better not to use @var{coding-system}; instead decode into
+a unibyte buffer, decode that appropriately and then interpret it as
+multibyte.
+@end deffn
+
+@defun quoted-printable-decode-string @var{string} &optional @var{coding-system}
+Return a QP-encoded copy of @var{string}. If @var{coding-system} is
+non-nil, decode bytes into characters with that coding-system.
+@end defun
+
+@deffn Command quoted-printable-encode-region @var{from} @var{to} &optional @var{fold} @var{class}
+QP-encode all the region. If @var{fold} is non-@var{nil}, fold lines
+at 76 characters, as required by the RFC. If @var{class} is
+non-@code{nil}, translate the characters not matched by that regexp
+class, which should be in the form expected by
+@var{skip-chars-forward} and should probably not contain literal
+eight-bit characters. Specifying @var{class} makes sense to do extra
+encoding in header fields.
+
+If variable @var{mm-use-ultra-safe-encoding} is defined and
+non-@code{nil}, fold lines unconditionally and encode @samp{From } and
+@samp{-} at the start of lines..
+@end deffn
+
+@defun quoted-printable-encode-string string
+Return a QP-encoded copy of @var{string}.
+@end defun
@node base64
@section base64
Base64 is an encoding that encodes three bytes into four characters,
thereby increasing the size by about 33%. The alphabet used for
-encoding is very resistant to mangling during transit.
-
-The following functions are defined by this library:
-
-@table @code
-@item base64-encode-region
-@findex base64-encode-region
-base64 encode the selected region. Return the length of the encoded
-text. Optional third argument @var{no-line-break} means do not break
-long lines into shorter lines.
-
-@item base64-encode-string
-@findex base64-encode-string
-base64 encode a string and return the result.
-
-@item base64-decode-region
-@findex base64-decode-region
-base64 decode the selected region. Return the length of the decoded
-text. If the region can't be decoded, return @code{nil} and don't
-modify the buffer.
-
-@item base64-decode-string
-@findex base64-decode-string
-base64 decode a string and return the result. If the string can't be
-decoded, @code{nil} is returned.
-
-@end table
-
+encoding is very resistant to mangling during transit. @xref{Base
+64,,Base 64 Encoding, elisp, The Emacs Lisp Reference Manual}.
@node binhex
@section binhex
@cindex Apple
@cindex Macintosh
-@code{binhex} is an encoding that originated in Macintosh environments.
+Binhex is an encoding that originated in Macintosh environments.
The following function is supplied to deal with these:
-@table @code
-@item binhex-decode-region
-@findex binhex-decode-region
-Decode the encoded text in the region. If given a third parameter, only
-decode the @code{binhex} header and return the filename.
-
-@end table
+@defun binhex-decode-region start end &optional header-only
+Decode the encoded text in the region @var{start} to @var{end}. If
+@var{header-only} is non-@code{nil}, only decode the @samp{binhex}
+header and return the file name.
+@end defun
@node uudecode
@cindex uuencode
@cindex uudecode
-@code{uuencode} is probably still the most popular encoding of binaries
-used on Usenet, although @code{base64} rules the mail world.
+Uuencoding is probably still the most popular encoding of binaries
+used on Usenet, although Base64 rules the mail world.
The following function is supplied by this package:
-@table @code
-@item uudecode-decode-region
-@findex uudecode-decode-region
-Decode the text in the region.
-@end table
+@defun uudecode-decode-region start end &optional file-name
+Decode the text in the region @var{start} to @var{end}. If
+@var{file-name} is non-@code{nil}, save the result to @var{file-name}.
+@end defun
@node rfc1843
@cindex HZ
@cindex Chinese
-RFC1843 deals with mixing Chinese and ASCII characters in messages. In
-essence, RFC1843 switches between ASCII and Chinese by doing this:
+RFC1843 deals with mixing Chinese and @sc{ascii} characters in messages. In
+essence, RFC1843 switches between @sc{ascii} and Chinese by doing this:
@example
This sentence is in ASCII.
The following functions are available to handle this encoding:
-@table @code
-@item rfc1843-decode-region
-Decode HZ-encoded text in the region.
-
-@item rfc1843-decode-string
-Decode a HZ-encoded string and return the result.
+@defun rfc1843-decode-region start end
+Decode HZ-encoded text in the region @var{start} to @var{end}.
+@end defun
-@end table
+@defun rfc1843-decode-string string
+Decode the HZ-encoded @var{string} and return the result.
+@end defun
@node mailcap
@section mailcap
-The @file{~/.mailcap} file is parsed by most @sc{mime}-aware message
-handlers and describes how elements are supposed to be displayed.
-Here's an example file:
+As specified by RFC 1524, @sc{mime}-aware message handlers parse
+@dfn{mailcap} files from a default list, which can be overridden by the
+@code{MAILCAP} environment variable. These describe how elements are
+supposed to be displayed. Here's an example file:
@example
image/*; gimp -8 %s
audio/wav; wavplayer %s
@end example
-This says that all image files should be displayed with @code{gimp}, and
-that realaudio files should be played by @code{rvplayer}.
+This says that all image files should be displayed with @command{gimp},
+and that WAVE audio files should be played by @code{wavplayer}.
-The @code{mailcap} library parses this file, and provides functions for
+The @code{mailcap} library parses such files, and provides functions for
matching types.
-@table @code
-@item mailcap-mime-data
-@vindex mailcap-mime-data
-This variable is an alist of alists containing backup viewing rules.
+@defvar mailcap-mime-data
+This variable is an alist of alists containing backup viewing rules for
+@sc{mime} types. These are overridden by rules for a type found in
+mailcap files. The outer alist is keyed on the major content-type and
+the inner alists are keyed on the minor content-type (which can be a
+regular expression).
-@end table
+@c Fixme: document this properly!
+For example:
+@example
+(("application"
+ ("octet-stream"
+ (viewer . mailcap-save-binary-file)
+ (non-viewer . t)
+ (type . "application/octet-stream"))
+ ("plain"
+ (viewer . view-mode)
+ (test fboundp 'view-mode)
+ (type . "text/plain")))
+@end example
+@end defvar
-Interface functions:
+@defopt mailcap-default-mime-data
+This variable is the default value of @code{mailcap-mime-data}. It
+exists to allow setting the value using Custom. It is merged with
+values from mailcap files by @code{mailcap-parse-mailcaps}.
+@end defopt
-@table @code
-@item mailcap-parse-mailcaps
-@findex mailcap-parse-mailcaps
-Parse the @code{~/.mailcap} file.
+Although it is not specified by the RFC, @sc{mime} tools normally use a
+common means of associating file extensions with defualt @sc{mime} types
+in the absence of other information about the type of a file. The
+information is found in per-user files @file{~/.mime.types} and system
+@file{mime.types} files found in quasi-standard places. Here is an
+example:
-@item mailcap-mime-info
-Takes a @sc{mime} type as its argument and returns the matching viewer.
+@example
+application/x-dvi dvi
+audio/mpeg mpga mpega mp2 mp3
+image/jpeg jpeg jpg jpe
+@end example
-@end table
+@defvar mailcap-mime-extensions
+This variable is an alist @sc{mime} types keyed by file extensions.
+This is overridden by entries found in @file{mime.types} files.
+@end defvar
+@defopt mailcap-default-mime-extensions
+This variable is the default value of @code{mailcap-mime-extensions}.
+It exists to allow setting the value using Custom. It is merged with
+values from mailcap files by @code{mailcap-parse-mimetypes}.
+@end defopt
+
+Interface functions:
+
+@defun mailcap-parse-mailcaps &optional path force
+Parse all the mailcap files specified in a path string @var{path} and
+merge them with the values from @code{mailcap-mime-data}. Components of
+@var{path} are separated by the @code{path-separator} character
+appropriate for the system. If @var{force} is non-@code{nil}, the files
+are re-parsed even if they have been parsed already. If @var{path} is
+omitted, use the value of environment variable @code{MAILCAPS} if it is
+set; otherwise (on GNU and Unix) use the path defined in RFC 1524, plus
+@file{/usr/local/etc/mailcap}.
+@end defun
+
+@defun mailcap-parse-mimetypes &optional path force
+Parse all the mimetypes specified in a path string @var{path}
+and merge them with the values from @code{mailcap-mime-extensions}.
+Components of @var{path} are separated by the @code{path-separator}
+character appropriate for the system. If @var{path} is omitted, use the
+value of environment variable @code{MIMETYPES} if set; otherwise use a
+default path consistent with that used by @code{mailcap-parse-mailcaps}.
+If @var{force} is non-@code{nil}, the files are re-parsed even if they
+have been parsed already.
+@end defun
+
+@defun mailcap-mime-info string &optional request
+Gets the viewer command for content-type @var{string}. @code{nil} is
+returned if none is found. Expects @var{string} to be a complete
+content-type header line.
+
+If @var{request} is non-@code{nil} it specifies what information to
+return. If it is nil or the empty string, the viewer (second field of
+the mailcap entry) will be returned. If it is a string, then the
+mailcap field corresponding to that string will be returned
+(@samp{print}, @samp{description}, whatever). If it is a number, all
+the information for this viewer is returned. If it is @code{all}, then
+all possible viewers for this type is returned.
+@end defun
+
+@defun mailcap-mime-types
+This function returns a list of all the defined media types.
+@end defun
+
+@defun mailcap-extension-to-mime extension
+This function returns the content type defined for a file with the given
+@var{extension}.
+@end defun
@node Decoding and Viewing
@node Handles
@section Handles
-A @sc{mime} handle is a list that fully describes a @sc{mime}
-component.
+A @sc{mime} handle is a list that fully describes a @sc{mime} component.
-The following macros can be used to access elements in a handle:
+The following macros can be used to access elements from the
+@var{handle} argument:
-@table @code
-@item mm-handle-buffer
-@findex mm-handle-buffer
+@defmac mm-handle-buffer handle
Return the buffer that holds the contents of the undecoded @sc{mime}
part.
+@end defmac
-@item mm-handle-type
-@findex mm-handle-type
-Return the parsed @code{Content-Type} of the part.
+@defmac mm-handle-type handle
+Return the parsed @samp{Content-Type} of the part.
+@end defmac
-@item mm-handle-encoding
-@findex mm-handle-encoding
-Return the @code{Content-Transfer-Encoding} of the part.
+@defmac mm-handle-encoding handle
+Return the @samp{Content-Transfer-Encoding} of the part.
+@end defmac
-@item mm-handle-undisplayer
-@findex mm-handle-undisplayer
-Return the object that can be used to remove the displayed part (if it
+@defmac mm-handle-undisplayer handle
+Return the function that can be used to remove the displayed part (if it
has been displayed).
+@end defmac
-@item mm-handle-set-undisplayer
-@findex mm-handle-set-undisplayer
-Set the undisplayer object.
+@defmac mm-handle-set-undisplayer handle function
+Set the undisplayer function for the part to function.
+@end defmac
-@item mm-handle-disposition
-@findex mm-handle-disposition
-Return the parsed @code{Content-Disposition} of the part.
+@defmac mm-handle-disposition
+Return the parsed @samp{Content-Disposition} of the part.
+@end defmac
-@item mm-handle-disposition
-@findex mm-handle-disposition
+@defmac mm-handle-disposition
Return the description of the part.
+@end defmac
-@item mm-get-content-id
-Returns the handle(s) referred to by @code{Content-ID}.
-
-@end table
+@defmac mm-get-content-id id
+Returns the handle(s) referred to by @var{id}, the @samp{Content-ID} of
+the part.
+@end defmac
@node Display
@section Display
-Functions for displaying, removing and saving.
-
-@table @code
-@item mm-display-part
-@findex mm-display-part
-Display the part.
+Functions for displaying, removing and saving. In the descriptions
+below, `the part' means the @sc{mime} part represented by the
+@var{handle} argument.
-@item mm-remove-part
-@findex mm-remove-part
-Remove the part (if it has been displayed).
+@defun mm-display-part handle &optional no-default
+Display the part. Return @code{nil} if the part is removed,
+@code{inline} if it is displayed inline or @code{external} if it is
+displayed externally. If @var{no-default} is non-@code{nil}, the part
+is not displayed unless the @sc{mime} type of @var{handle} is defined to
+be displayed inline or there is an display method defined for it; i.e.@:
+no default external method will be used.
+@end defun
-@item mm-inlinable-p
-@findex mm-inlinable-p
-Say whether a @sc{mime} type can be displayed inline.
+@defun mm-remove-part handle
+Remove the part if it has been displayed.
+@end defun
-@item mm-automatic-display-p
-@findex mm-automatic-display-p
-Say whether a @sc{mime} type should be displayed automatically.
+@defun mm-inlinable-p handle
+Return non-@code{nil} if the part can be displayed inline.
+@end defun
-@item mm-destroy-part
-@findex mm-destroy-part
-Free all resources occupied by a part.
+@defun mm-automatic-display-p handle
+Return non-@code{nil} if the user has requested automatic display of the
+@sc{mime} type of the part.
+@end defun
-@item mm-save-part
-@findex mm-save-part
-Offer to save the part in a file.
+@defun mm-destroy-part handle
+Free all the resources used by the part.
+@end defun
-@item mm-pipe-part
-@findex mm-pipe-part
-Offer to pipe the part to some process.
+@defun mm-save-part handle
+Save the part to a file. The user is prompted for a file name to use.
+@end defun
-@item mm-interactively-view-part
-@findex mm-interactively-view-part
-Prompt for a mailcap method to use to view the part.
+@defun mm-pipe-part handle
+Pipe the part through a shell command. The user is prompted for the
+command to use.
+@end defun
-@end table
+@defun mm-interactively-view-part handle
+Prompt for a mailcap method to use to view the part and display it
+externally using that method.
+@end defun
@node Customization
@section Customization
-@table @code
+The display of @sc{mime} types may be customized with the following
+options.
-@item mm-inline-media-tests
+@defopt 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
the third element is a form to be @code{eval}ed to say whether the part
This variable specifies whether a part @emph{can} be displayed inline,
and, if so, how to do it. It does not say whether parts are
@emph{actually} displayed inline.
+@end defopt
-@item mm-inlined-types
+@defopt mm-inlined-types
This, on the other hand, says what types are to be displayed inline, if
they satisfy the conditions set by the variable above. It's a list of
@sc{mime} media types.
+@end defopt
-@item mm-automatic-display
+@defopt mm-automatic-display
This is a list of types that are to be displayed ``automatically'', but
only if the above variable allows it. That is, only inlinable parts can
be displayed automatically.
+@end defopt
-@item mm-attachment-override-types
+@defopt 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
displaying the part inline. (Note that the disposition is only
overridden if we are able to, and want to, display the part inline.)
+@end defopt
-@item mm-discouraged-alternatives
+@defopt mm-discouraged-alternatives
List of @sc{mime} types that are discouraged when viewing
@samp{multipart/alternative}. Viewing agents are supposed to view the
last possible part of a message, as that is supposed to be the richest.
@lisp
("text/html" "text/richtext")
@end lisp
+@end defopt
-@item mm-inline-large-images-p
+@defopt mm-inline-large-images-p
When displaying inline images that are larger than the window, XEmacs
does not enable scrolling, which means that you cannot see the whole
image. To prevent this, the library tries to determine the image size
@samp{xv}). Setting this variable to @code{t} disables this check and
makes the library display all inline images as inline, regardless of
their size.
+@end defopt
-@item mm-inline-override-p
+@defopt mm-inline-override-p
@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
list containing that type. For example assuming @code{mm-inlined-types}
includes @samp{text/.*}, then including @samp{text/html} in this
variable will cause @samp{text/html} parts to be treated as attachments.
-
-@end table
+@end defopt
@node New Viewers
@section New Viewers
-Here's an example viewer for displaying @code{text/enriched} inline:
+Here's an example viewer for displaying @samp{text/enriched} inline:
@lisp
(defun mm-display-enriched-inline (handle)
* 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.
+* Charset Translation:: How charsets are mapped from Mule to MIME.
* Conversion:: Going from @sc{mime} to MML and vice versa.
@end menu
@table @samp
@item type
-The @sc{mime} type of the part (@code{Content-Type}).
+The @sc{mime} type of the part (@samp{Content-Type}).
@item filename
Use the contents of the file in the body of the part
-(@code{Content-Disposition}).
+(@samp{Content-Disposition}).
@item charset
The contents of the body of the part are to be encoded in the character
-set speficied (@code{Content-Type}).
+set speficied (@samp{Content-Type}).
@item name
Might be used to suggest a file name if the part is to be saved
-to a file (@code{Content-Type}).
+to a file (@samp{Content-Type}).
@item disposition
Valid values are @samp{inline} and @samp{attachment}
-(@code{Content-Disposition}).
+(@samp{Content-Disposition}).
@item encoding
Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
-@samp{base64} (@code{Content-Transfer-Encoding}).
+@samp{base64} (@samp{Content-Transfer-Encoding}).
@item description
-A description of the part (@code{Content-Description}).
+A description of the part (@samp{Content-Description}).
@item creation-date
-RFC822 date when the part was created (@code{Content-Disposition}).
+RFC822 date when the part was created (@samp{Content-Disposition}).
@item modification-date
-RFC822 date when the part was modified (@code{Content-Disposition}).
+RFC822 date when the part was modified (@samp{Content-Disposition}).
@item read-date
-RFC822 date when the part was read (@code{Content-Disposition}).
+RFC822 date when the part was read (@samp{Content-Disposition}).
@item size
-The size (in octets) of the part (@code{Content-Disposition}).
+The size (in octets) of the part (@samp{Content-Disposition}).
@end table
@table @samp
@item type
Type of the part; informal---meant for human readers
-(@code{Content-Type}).
+(@samp{Content-Type}).
@end table
Parameters for @samp{message/external-body}:
@item access-type
A word indicating the supported access mechanism by which the file may
be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
-@samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.)
+@samp{localfile}, and @samp{mailserver}. (@samp{Content-Type}.)
@item expiration
The RFC822 date after which the file may no longer be fetched.
-(@code{Content-Type}.)
+(@samp{Content-Type}.)
@item size
-The size (in octets) of the file. (@code{Content-Type}.)
+The size (in octets) of the file. (@samp{Content-Type}.)
@item permission
Valid values are @samp{read} and @samp{read-write}
-(@code{Content-Type}).
+(@samp{Content-Type}).
@end table
@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.
+has been composed inside Emacs, an appropriate @sc{mime} 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
+If you are running a non-Mule Emacs, this process is simple: if the part
+contains any non-@sc{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.
+@sc{mime} messages. @xref{Various Message Variables, , Various Message
+Variables, message, Message Manual}, for example.) If there are only
+@sc{ascii} characters, the @sc{mime} charset @samp{US-ASCII} is used, of
+course.
-@cindex MULE
+@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.
+Things are slightly more complicated when running Emacs with Mule
+support. In this case, a list of the Mule charsets used in the part is
+obtained, and the corresponding @sc{mime} charsets are determined. 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,
+the part is split into several, 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
@item RFC1036
Standard for Interchange of USENET Messages
+@item RFC1524
+A User Agent Configuration Mechanism For Multimedia Mail Format
+Information
+
@item RFC2045
Format of Internet Message Bodies
@node Index
@chapter Index
@printindex cp
+@printindex fn
@summarycontents
@contents
HCoop / bpt / emacs.git / blobdiff