This file documents the Emacs MIME interface functionality.
-Copyright (C) 1996 Free Software Foundation, Inc.
+Copyright (C) 1998,99 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1998 Free Software Foundation, Inc.
+Copyright @copyright{} 1998,99 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@result{} "b980912.gif"
@end example
+@item mail-header-encode-parameter
+@findex mail-header-encode-parameter
+Takes a parameter string and returns an encoded version of the string.
+This is used for parameters in headers like @code{Content-Type} and
+@code{Content-Disposition}.
+
@item mail-header-remove-comments
@findex mail-header-remove-comments
Return a comment-free version of a header.
Return the last comment in a header.
@example
-(mail-header-get-comment
+(mail-header-get-comment
"Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
-@result{} "Finnish Landrace"
+@result{} "Finnish Landrace"
@end example
@item mail-header-parse-address
@end table
Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
-@code{rfc2047} and @code{rfc2231}. These are documented in the
-subsequent sections.
+@code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented
+in the subsequent sections.
(@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.
@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:
+
+@table @code
+@item rfc2045-encode-string
+@findex rfc2045-encode-string
+Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
+@var{value} will be quoted if there are non-safe characters in it.
+@end table
+
+
@node rfc2231
@section rfc2231
@example
(rfc2231-parse-string
- "application/x-stuff;
+ "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!\"")
@item rfc2231-get-value
@findex rfc2231-get-value
-Takes one of the lists on the format above and return
+Takes one of the lists on the format above and returns
the value of the specified attribute.
+@item rfc2231-encode-string
+@findex rfc2231-encode-string
+Encode a parameter in headers likes @code{Content-Type} and
+@code{Content-Disposition}.
+
@end table
The @code{Q} encoding isn't quite the same for all headers. Some
headers allow a narrower range of characters, and that is what this
variable is for. It's an alist of header regexps / allowable character
-ranges.
+ranges.
@item rfc2047-encoded-word-regexp
@vindex rfc2047-encoded-word-regexp
-When decoding words, this library looks for matches to this regexp.
+When decoding words, this library looks for matches to this regexp.
@end table
returned as a result of this analysis.
@menu
-* Dissection:: Analyzing a @sc{mime} message.
-* Handles:: Handle manipulations.
-* Display:: Displaying handles.
+* Dissection:: Analyzing a @sc{mime} message.
+* Handles:: Handle manipulations.
+* Display:: Displaying handles.
+* Customization:: Variables that affect display.
+* New Viewers:: How to write your own viewers.
@end menu
@end table
+@node Customization
+@section Customization
+
+@table @code
+
+@item mm-inline-media-tests
+This is an alist where the key is a @sc{mime} type, the second element
+is a function to display the part @dfn{inline} (i.e., inside Emacs), and
+the third element is a form to be @code{eval}ed to say whether the part
+can be displayed inline.
+
+This variable specifies whether a part @emph{can} be displayed inline,
+and, if so, how to do it. It does not say whether parts are
+@emph{actually} displayed inline.
+
+@item mm-inlined-types
+This, on the other hand, says what types are to be displayed inline, if
+they satisfy the conditions set by the variable above. It's a list of
+@sc{mime} media types.
+
+@item mm-automatic-display
+This is a list of types that are to be displayed ``automatically'', but
+only if the above variable allows it. That is, only inlinable parts can
+be displayed automatically.
+
+@item mm-attachment-override-types
+Some @sc{mime} agents create parts that have a content-disposition of
+@samp{attachment}. This variable allows overriding that disposition and
+displaying the part inline. (Note that the disposition is only
+overridden if we are able to, and want to, display the part inline.)
+
+@item mm-discouraged-alternatives
+List of @sc{mime} types that are discouraged when viewing
+@samp{multipart/alternative}. Viewing agents are supposed to view the
+last possible part of a message, as that is supposed to be the richest.
+However, users may prefer other types instead, and this list says what
+types are most unwanted. If, for instance, @samp{text/html} parts are
+very unwanted, and @samp{text/richtech} parts are somewhat unwanted,
+then the value of this variable should be set to:
+
+@lisp
+("text/html" "text/richtext")
+@end lisp
+
+@item mm-inline-large-images-p
+When displaying inline images that are larger than the window, XEmacs
+does not enable scrolling, which means that you cannot see the whole
+image. To prevent this, the library tries to determine the image size
+before displaying it inline, and if it doesn't fit the window, the
+library will display it externally (e.g. with @samp{ImageMagick} or
+@samp{xv}). Setting this variable to @code{t} disables this check and
+makes the library display all inline images as inline, regardless of
+their size.
+
+@item mm-inline-override-p
+@code{mm-inlined-types} may include regular expressions, for example to
+specify that all @samp{text/.*} parts be displayed inline. If a user
+prefers to have a type that matches such a regular expression be treated
+as an attachment, that can be accomplished by setting this variable to a
+list containing that type. For example assuming @code{mm-inlined-types}
+includes @samp{text/.*}, then including @samp{text/html} in this
+variable will cause @samp{text/html} parts to be treated as attachments.
+
+@end table
+
+
+@node New Viewers
+@section New Viewers
+
+Here's an example viewer for displaying @code{text/enriched} inline:
+
+@lisp
+(defun mm-display-enriched-inline (handle)
+ (let (text)
+ (with-temp-buffer
+ (mm-insert-part handle)
+ (save-window-excursion
+ (enriched-decode (point-min) (point-max))
+ (setq text (buffer-string))))
+ (mm-insert-inline handle text)))
+@end lisp
+
+We see that the function takes a @sc{mime} handle as its parameter. It
+then goes to a temporary buffer, inserts the text of the part, does some
+work on the text, stores the result, goes back to the buffer it was
+called from and inserts the result.
+
+The two important helper functions here are @code{mm-insert-part} and
+@code{mm-insert-inline}. The first function inserts the text of the
+handle in the current buffer. It handles charset and/or content
+transfer decoding. The second function just inserts whatever text you
+tell it to insert, but it also sets things up so that the text can be
+``undisplayed' in a convenient manner.
+
+
@node Composing
@chapter Composing
@cindex Composing
@cindex MIME Meta Language
Creating a @sc{mime} message is boring and non-trivial. Therefore, a
-library called @code{mml} has been defined that parses a language called
+library called @code{mml} has been defined that parses a language called
MML (@sc{mime} Meta Language) and generates @sc{mime} messages.
@findex mml-generate-mime
* Simple MML Example:: An example MML document.
* MML Definition:: All valid MML elements.
* Advanced MML Example:: Another example MML document.
+* Charset Translation:: How charsets are mapped from @sc{mule} to MIME.
+* Conversion:: Going from @sc{mime} to MML and vice versa.
@end menu
set speficied (@code{Content-Type}).
@item name
-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
to a file (@code{Content-Type}).
@item disposition
@section Advanced MML Example
Here's a complex multipart message. It's a @samp{multipart/mixed} that
-contains many parts, one of which is a @samp{multipart/alternative}.
+contains many parts, one of which is a @samp{multipart/alternative}.
@example
<#multipart type=mixed>
--=-=-=--
@end example
+@node Charset Translation
+@section Charset Translation
+@cindex charsets
+
+During translation from MML to @sc{mime}, for each @sc{mime} part which
+has been composed inside Emacs, an appropriate charset has to be chosen.
+
+@vindex mail-parse-charset
+If you are running a non-@sc{mule} Emacs, this process is simple: If the
+part contains any non-ASCII (8-bit) characters, the @sc{mime} charset
+given by @code{mail-parse-charset} (a symbol) is used. (Never set this
+variable directly, though. If you want to change the default charset,
+please consult the documentation of the package which you use to process
+@sc{mime} messages.
+@xref{Various Message Variables, , Various Message Variables, message,
+ Message Manual}, for example.)
+If there are only ASCII characters, the @sc{mime} charset US-ASCII is
+used, of course.
+
+@cindex MULE
+@cindex UTF-8
+@cindex Unicode
+@vindex mm-mime-mule-charset-alist
+Things are slightly more complicated when running Emacs with @sc{mule}
+support. In this case, a list of the @sc{mule} charsets used in the
+part is obtained, and the @sc{mule} charsets are translated to @sc{mime}
+charsets by consulting the variable @code{mm-mime-mule-charset-alist}.
+If this results in a single @sc{mime} charset, this is used to encode
+the part. But if the resulting list of @sc{mime} charsets contains more
+than one element, two things can happen: If it is possible to encode the
+part via UTF-8, this charset is used. (For this, Emacs must support
+the @code{utf-8} coding system, and the part must consist entirely of
+characters which have Unicode counterparts.) If UTF-8 is not available
+for some reason, the part is split into several ones, so that each one
+can be encoded with a single @sc{mime} charset. The part can only be
+split at line boundaries, though---if more than one @sc{mime} charset is
+required to encode a single line, it is not possible to encode the part.
+
+@node Conversion
+@section Conversion
+
+@findex mime-to-mml
+A (multipart) @sc{mime} message can be converted to MML with the
+@code{mime-to-mml} function. It works on the message in the current
+buffer, and substitutes MML markup for @sc{mime} boundaries.
+Non-textual parts do not have their contents in the buffer, but instead
+have the contents in separate buffers that are referred to from the MML
+tags.
+
+@findex mml-to-mime
+An MML message can be converted back to @sc{mime} by the
+@code{mml-to-mime} function.
+
+These functions are in certain senses ``lossy''---you will not get back
+an identical message if you run @sc{mime-to-mml} and then
+@sc{mml-to-mime}. Not only will trivial things like the order of the
+headers differ, but the contents of the headers may also be different.
+For instance, the original message may use base64 encoding on text,
+while @sc{mml-to-mime} may decide to use quoted-printable encoding, and
+so on.
+
+In essence, however, these two functions should be the inverse of each
+other. The resulting contents of the message should remain equivalent,
+if not identical.
@node Standards
The Emacs @sc{mime} library implements handling of various elements
according to a (somewhat) large number of RFCs, drafts and standards
documents. This chapter lists the relevant ones. They can all be
-fetched from @samp{http://www.stud.ifi.uio.no/~larsi/notes/}.
+fetched from @samp{http://quimby.gnus.org/notes/}.
@table @dfn
@item RFC822
Content-Disposition Header Field
@end table
-
-
+
+
@node Index
@chapter Index
@printindex cp