Commit | Line | Data |
---|---|---|
00ed1b10 | 1 | \input texinfo @c -*-mode: texinfo; coding: latin-1 -*- |
dd8839b0 | 2 | |
a1720df0 | 3 | @setfilename ../info/emacs-mime |
dd8839b0 DL |
4 | @settitle Emacs MIME Manual |
5 | @synindex fn cp | |
6 | @synindex vr cp | |
7 | @synindex pg cp | |
64566c03 | 8 | @dircategory Emacs |
dd8839b0 DL |
9 | @direntry |
10 | * Emacs MIME: (emacs-mime). The MIME de/composition library. | |
11 | @end direntry | |
12 | @iftex | |
13 | @finalout | |
14 | @end iftex | |
15 | @setchapternewpage odd | |
16 | ||
17 | @ifnottex | |
18 | ||
19 | This file documents the Emacs MIME interface functionality. | |
20 | ||
21 | Copyright (C) 1998,99,2000 Free Software Foundation, Inc. | |
22 | ||
23 | Permission is granted to copy, distribute and/or modify this document | |
24 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
c5c46a26 DL |
25 | any later version published by the Free Software Foundation; with no |
26 | Invariant Sections, with the Front-Cover texts being ``A GNU | |
dd8839b0 DL |
27 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the |
28 | license is included in the section entitled ``GNU Free Documentation | |
2482f038 | 29 | License'' in the Emacs manual. |
dd8839b0 DL |
30 | |
31 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
32 | this GNU Manual, like GNU software. Copies published by the Free | |
33 | Software Foundation raise funds for GNU development.'' | |
2482f038 DL |
34 | |
35 | This document is part of a collection distributed under the GNU Free | |
36 | Documentation License. If you want to distribute this document | |
37 | separately from the collection, you can do so by adding a copy of the | |
38 | license to the document, as described in section 6 of the license. | |
dd8839b0 DL |
39 | @end ifnottex |
40 | ||
41 | @tex | |
42 | ||
43 | @titlepage | |
44 | @title Emacs MIME Manual | |
45 | ||
46 | @author by Lars Magne Ingebrigtsen | |
47 | @page | |
48 | ||
49 | @vskip 0pt plus 1filll | |
50 | Copyright @copyright{} 1998,99,2000 Free Software Foundation, Inc. | |
51 | ||
52 | Permission is granted to copy, distribute and/or modify this document | |
53 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
54 | any later version published by the Free Software Foundation; with the | |
55 | Invariant Sections being none, with the Front-Cover texts being ``A GNU | |
56 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
57 | license is included in the section entitled ``GNU Free Documentation | |
bf957d2d | 58 | License'' in the Emacs manual. |
dd8839b0 DL |
59 | |
60 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
61 | this GNU Manual, like GNU software. Copies published by the Free | |
62 | Software Foundation raise funds for GNU development.'' | |
bf957d2d DL |
63 | |
64 | This document is part of a collection distributed under the GNU Free | |
65 | Documentation License. If you want to distribute this document | |
66 | separately from the collection, you can do so by adding a copy of the | |
67 | license to the document, as described in section 6 of the license. | |
dd8839b0 DL |
68 | @end titlepage |
69 | @page | |
70 | ||
71 | @end tex | |
72 | ||
73 | @node Top | |
74 | @top Emacs MIME | |
75 | ||
76 | This manual documents the libraries used to compose and display | |
77 | @sc{mime} messages. | |
78 | ||
79 | This is not a manual meant for users; it's a manual directed at people | |
80 | who want to write functions and commands that manipulate @sc{mime} | |
81 | elements. | |
82 | ||
83 | @sc{mime} is short for @dfn{Multipurpose Internet Mail Extensions}. | |
84 | This standard is documented in a number of RFCs; mainly RFC2045 (Format | |
85 | of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message | |
86 | Header Extensions for Non-ASCII Text), RFC2048 (Registration | |
87 | Procedures), RFC2049 (Conformance Criteria and Examples). It is highly | |
88 | recommended that anyone who intends writing @sc{mime}-compliant software | |
89 | read at least RFC2045 and RFC2047. | |
90 | ||
91 | @menu | |
92 | * Interface Functions:: An abstraction over the basic functions. | |
93 | * Basic Functions:: Utility and basic parsing functions. | |
94 | * Decoding and Viewing:: A framework for decoding and viewing. | |
95 | * Composing:: MML; a language for describing MIME parts. | |
96 | * Standards:: A summary of RFCs and working documents used. | |
97 | * Index:: Function and variable index. | |
98 | @end menu | |
99 | ||
100 | ||
101 | @node Interface Functions | |
102 | @chapter Interface Functions | |
103 | @cindex interface functions | |
104 | @cindex mail-parse | |
105 | ||
106 | The @code{mail-parse} library is an abstraction over the actual | |
107 | low-level libraries that are described in the next chapter. | |
108 | ||
109 | Standards change, and so programs have to change to fit in the new | |
110 | mold. For instance, RFC2045 describes a syntax for the | |
edcfa240 | 111 | @code{Content-Type} header that only allows @sc{ascii} characters in the |
dd8839b0 | 112 | parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme |
edcfa240 | 113 | for continuation headers and non-@sc{ascii} characters. |
dd8839b0 DL |
114 | |
115 | The traditional way to deal with this is just to update the library | |
116 | functions to parse the new syntax. However, this is sometimes the wrong | |
117 | thing to do. In some instances it may be vital to be able to understand | |
118 | both the old syntax as well as the new syntax, and if there is only one | |
119 | library, one must choose between the old version of the library and the | |
120 | new version of the library. | |
121 | ||
122 | The Emacs MIME library takes a different tack. It defines a series of | |
123 | low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} and so on) | |
124 | that parses strictly according to the corresponding standard. However, | |
125 | normal programs would not use the functions provided by these libraries | |
126 | directly, but instead use the functions provided by the | |
127 | @code{mail-parse} library. The functions in this library are just | |
128 | aliases to the corresponding functions in the latest low-level | |
129 | libraries. Using this scheme, programs get a consistent interface they | |
130 | can use, and library developers are free to create write code that | |
131 | handles new standards. | |
132 | ||
133 | The following functions are defined by this library: | |
134 | ||
edcfa240 DL |
135 | @defun mail-header-parse-content-type string |
136 | Parse @var{string}, a @code{Content-Type} header, and return a | |
137 | content-type list in the following format: | |
dd8839b0 DL |
138 | |
139 | @lisp | |
140 | ("type/subtype" | |
141 | (attribute1 . value1) | |
142 | (attribute2 . value2) | |
edcfa240 | 143 | @dots{}) |
dd8839b0 DL |
144 | @end lisp |
145 | ||
146 | Here's an example: | |
147 | ||
148 | @example | |
149 | (mail-header-parse-content-type | |
150 | "image/gif; name=\"b980912.gif\"") | |
151 | @result{} ("image/gif" (name . "b980912.gif")) | |
152 | @end example | |
edcfa240 | 153 | @end defun |
dd8839b0 | 154 | |
edcfa240 DL |
155 | @defun mail-header-parse-content-disposition string |
156 | Parse @var{string}, a @code{Content-Disposition} header, and return a | |
157 | content-type list in the format above. | |
158 | @end defun | |
dd8839b0 | 159 | |
edcfa240 | 160 | @defun mail-content-type-get ct attribute |
dd8839b0 | 161 | @findex mail-content-type-get |
edcfa240 DL |
162 | Returns the value of the given @var{attribute} from the content-type |
163 | list @var{ct}. | |
dd8839b0 DL |
164 | |
165 | @example | |
166 | (mail-content-type-get | |
167 | '("image/gif" (name . "b980912.gif")) 'name) | |
168 | @result{} "b980912.gif" | |
169 | @end example | |
edcfa240 | 170 | @end defun |
dd8839b0 | 171 | |
edcfa240 DL |
172 | @defun mail-header-encode-parameter param value |
173 | Takes a parameter string @samp{@var{param}=@var{value}} and returns an | |
174 | encoded version of it. This is used for parameters in headers like | |
175 | @samp{Content-Type} and @samp{Content-Disposition}. | |
176 | @end defun | |
dd8839b0 | 177 | |
edcfa240 DL |
178 | @defun mail-header-remove-comments string |
179 | Return a comment-free version of @var{string}. | |
dd8839b0 DL |
180 | |
181 | @example | |
182 | (mail-header-remove-comments | |
183 | "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") | |
184 | @result{} "Gnus/5.070027 " | |
185 | @end example | |
edcfa240 | 186 | @end defun |
dd8839b0 | 187 | |
edcfa240 DL |
188 | @defun mail-header-remove-whitespace string |
189 | Remove linear white space from @var{string}. Space inside quoted | |
190 | strings and comments is preserved. | |
dd8839b0 DL |
191 | |
192 | @example | |
193 | (mail-header-remove-whitespace | |
194 | "image/gif; name=\"Name with spaces\"") | |
195 | @result{} "image/gif;name=\"Name with spaces\"" | |
196 | @end example | |
edcfa240 | 197 | @end defun |
dd8839b0 | 198 | |
edcfa240 DL |
199 | @defun mail-header-get-comment string |
200 | Return the last comment in @var{string}. | |
dd8839b0 DL |
201 | |
202 | @example | |
203 | (mail-header-get-comment | |
204 | "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") | |
205 | @result{} "Finnish Landrace" | |
206 | @end example | |
edcfa240 DL |
207 | @end defun |
208 | ||
dd8839b0 | 209 | |
edcfa240 DL |
210 | @defun mail-header-parse-address string |
211 | Parse an address string @var{string} and return a list containing the | |
212 | mailbox and the plaintext name. | |
dd8839b0 DL |
213 | |
214 | @example | |
215 | (mail-header-parse-address | |
216 | "Hrvoje Niksic <hniksic@@srce.hr>") | |
217 | @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic") | |
218 | @end example | |
edcfa240 | 219 | @end defun |
dd8839b0 | 220 | |
edcfa240 DL |
221 | @defun mail-header-parse-addresses string |
222 | Parse @var{string} as a list of addresses and return a list of elements | |
223 | like the one described above. | |
dd8839b0 DL |
224 | |
225 | @example | |
226 | (mail-header-parse-addresses | |
227 | "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>") | |
228 | @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic") | |
229 | ("sb@@metis.no" . "Steinar Bang")) | |
230 | @end example | |
edcfa240 | 231 | @end defun |
dd8839b0 | 232 | |
edcfa240 DL |
233 | @defun mail-header-parse-date string |
234 | Parse a date @var{string} and return an Emacs time structure. | |
235 | @end defun | |
dd8839b0 | 236 | |
edcfa240 | 237 | @defun mail-narrow-to-head |
dd8839b0 DL |
238 | Narrow the buffer to the header section of the buffer. Point is placed |
239 | at the beginning of the narrowed buffer. | |
edcfa240 | 240 | @end defun |
dd8839b0 | 241 | |
edcfa240 | 242 | @defun mail-header-narrow-to-field |
dd8839b0 | 243 | Narrow the buffer to the header under point. |
edcfa240 | 244 | @end defun |
dd8839b0 | 245 | |
edcfa240 DL |
246 | @defun mail-encode-encoded-word-region start end |
247 | Encode the non-@sc{ascii} words in the region @var{start}to @var{end}. For | |
248 |