Sync to HEAD

[bpt/emacs.git] / man / emacs-mime.texi

\input texinfo                  @c -*-mode: texinfo; coding: latin-1 -*-

@setfilename ../info/emacs-mime
@settitle Emacs MIME Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp

@copying
This file documents the Emacs MIME interface functionality.

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

@quotation
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 quotation
@end copying

@dircategory Emacs
@direntry
* MIME: (emacs-mime).   Emacs MIME de/composition library.
@end direntry
@iftex
@finalout
@end iftex
@setchapternewpage odd

@titlepage
@title Emacs MIME Manual

@author by Lars Magne Ingebrigtsen
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@node Top
@top Emacs MIME

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

This is not a manual meant for users; it's a manual directed at 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 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 @sc{ascii} characters in the
parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
for continuation headers and non-@sc{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 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:

@defun mail-header-parse-content-type string
Parse @var{string}, a @code{Content-Type} header, and return a
content-type list in the following format:

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

@defun mail-header-parse-content-disposition string
Parse @var{string}, a @code{Content-Disposition} header, and return a
content-type list in the format above.
@end defun

@defun mail-content-type-get ct attribute
@findex mail-content-type-get
Returns the value of the given @var{attribute} from the content-type
list @var{ct}.

@example
(mail-content-type-get
 '("image/gif" (name . "b980912.gif")) 'name)
@result{} "b980912.gif"
@end example
@end defun

@defun mail-header-encode-parameter param value
Takes a parameter string @samp{@var{param}=@var{value}} and returns an
encoded version of it.  This is used for parameters in headers like
@samp{Content-Type} and @samp{Content-Disposition}.
@end defun

@defun mail-header-remove-comments string
Return a comment-free version of @var{string}.

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

@defun mail-header-remove-whitespace string
Remove linear white space from @var{string}.  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
@end defun

@defun mail-header-get-comment string
Return the last comment in @var{string}.

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


@defun mail-header-parse-address string
Parse an address string @var{string} 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
@end defun

@defun mail-header-parse-addresses string
Parse @var{string} as a list of addresses and return a list of elements
like the one described above.

@example
(mail-header-parse-addresses
 "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
     ("sb@@metis.no" . "Steinar Bang"))
@end example
@end defun

@defun mail-header-parse-date string
Parse a date @var{string} and return an Emacs time structure.
@end defun

@defun mail-narrow-to-head
Narrow the buffer to the header section of the buffer.  Point is placed
at the beginning of the narrowed buffer.
@end defun

@defun mail-header-narrow-to-field
Narrow the buffer to the header under point.
@end defun

@defun mail-encode-encoded-word-region start end
Encode the non-@sc{ascii} words in the region @var{start}to @var{end}.  For