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