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