| 1 | \input texinfo @c -*-texinfo-*- |
| 2 | |
| 3 | @setfilename ../emacs-mime |
| 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 |