[gnus] / texi / emacs-mime.texi

\input texinfo

@setfilename emacs-mime
@settitle Emacs MIME Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@dircategory Emacs
@direntry
* Emacs MIME: (emacs-mime).   The MIME de/composition library.
@end direntry
@iftex
@finalout
@end iftex
@setchapternewpage odd

@ifnottex

This file documents the Emacs MIME interface functionality.

Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end ifnottex

@tex

@titlepage
@title Emacs MIME Manual

@author by Lars Magne Ingebrigtsen
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1998, 1999, 2000, 2001, 2002 Free Software
Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being none, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end titlepage
@page

@end tex

@node Top
@top Emacs MIME

This manual documents the libraries used to compose and display
@sc{mime} messages.

This manual is directed at users who want to modify the behaviour of
the MIME encoding/decoding process or want a more detailed picture of
how the Emacs MIME library works, and people who want to write
functions and commands that manipulate @sc{mime} elements.

@sc{mime} is short for @dfn{Multipurpose Internet Mail Extensions}.
This standard is documented in a number of RFCs; mainly RFC2045 (Format
of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
Header Extensions for Non-ASCII Text), RFC2048 (Registration
Procedures), RFC2049 (Conformance Criteria and Examples).  It is highly
recommended that anyone who intends writing @sc{mime}-compliant software
read at least RFC2045 and RFC2047.

@menu
* Interface Functions::   An abstraction over the basic functions.
* Basic Functions::       Utility and basic parsing functions.
* Decoding and Viewing::  A framework for decoding and viewing.
* Composing::             MML; a language for describing @sc{mime} parts.
* Standards::             A summary of RFCs and working documents used.
* Index::                 Function and variable index.
@end menu


@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 ASCII characters in the
parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
for continuation headers and non-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 @sc{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:

@table @code
@item mail-header-parse-content-type
@findex mail-header-parse-content-type
Parse a @code{Content-Type} header and return a list on the following
format:

@lisp
("type/subtype"
 (attribute1 . value1)
 (attribute2 . value2)
 ...)
@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

@item mail-header-parse-content-disposition
@findex mail-header-parse-content-disposition
Parse a @code{Content-Disposition} header and return a list on the same
format as the function above.

@item mail-content-type-get
@findex mail-content-type-get
Takes two parameters---a list on the format above, and an attribute.
Returns the value of the attribute.

@example
(mail-content-type-get
 '("image/gif" (name . "b980912.gif")) 'name)
@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.

@example
(mail-header-remove-comments
 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
@result{} "Gnus/5.070027  "
@end example

@item mail-header-remove-whitespace
@findex mail-header-remove-whitespace
Remove linear white space from a header.  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

@item mail-header-get-comment
@findex mail-header-get-comment
Return the last comment in a header.

@example
(mail-header-get-comment
 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
@result{} "Finnish Landrace"
@end example

@item mail-header-parse-address
@findex mail-header-parse-address
Parse an address 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

@item mail-header-parse-addresses
@findex mail-header-parse-addresses
Parse a string with list of addr