Importing pgnus-0.34

[elisp/gnus.git-] / texi / emacs-mime.texi

\input texinfo                  @c -*-texinfo-*-

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

@ifinfo

This file documents the Emacs MIME interface functionality.

Copyright (C) 1996 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@tex

@titlepage
@title Emacs MIME Manual

@author by Lars Magne Ingebrigtsen
@page

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

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.

@end titlepage
@page

@end tex

@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
* Basic Functions::       Utility and basic parsing functions.
* Decoding and Viewing::  A framework for decoding and viewing.
* Index::                 Function and variable index.
@end menu


@node Basic Functions
@chapter Basic Functions

This chapter describes the basic, ground-level functions for parsing and
handling.  Covered here is parsing @code{From} lines, removing comments
from header lines, decoding encoded words, parsing date headers and so
on.  High-level functionality is dealt with in the next chapter
(@pxref{Decoding and Viewing}).

@menu
* mail-parse::   The generalized @sc{mime} and mail interface.
* rfc2231::      Parsing @code{Content-Type} headers.
* drums::        Handling mail headers defined by RFC822bis.
* rfc2047::      En/decoding encoded words in headers.
* time-date::    Functions for parsing dates and manipulating time.
* qp::           Quoted-Printable en/decoding.
* base64::       Base64 en/decoding.
* mailcap::      How parts are displayed is specified by the @file{.mailcap} file
@end menu


@node mail-parse
@section mail-parse

It is perhaps misleading to place the @code{mail-parse} library in this
chapter.  It is not a basic low-level library---rather, it is an
abstraction over the actual low-level libraries that are described in the
subsequent sections.

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 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\"")
=> ("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)
=> "b980912.gif"
@end example

@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)")
=> "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\"")
=> "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)")
=> "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>")
=> ("hniksic@@srce.hr" . "Hrvoje Niksic")
@end example

@item mail-header-parse-addresses
@findex mail-header-parse-addresses
Parse a string with 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>")
=> (("hniksic@@srce.hr" . "Hrvoje Niksic")
     ("sb@@metis.no" . "Steinar Bang"))
@end example

@item mail-header-parse-date
@findex mail-header-parse-date
Parse a date string and return an Emacs time structure.

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

@item mail-header-narrow-to-field
@findex mail-header-narrow-to-field
Narrow the buffer to the header under point.

@item mail-encode-encoded-word-region
@findex mail-encode-encoded-word-region
Encode the non-ASCII words in the region.  For instance,
@samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.

@item mail-encode-encoded-word-buffer
@findex mail-encode-encoded-word-buffer
Encode the non-ASCII words in the current buffer.  This function is
meant to be called narrowed to the headers of a message.

@item mail-encode-encoded-word-string
@findex mail-encode-encoded-word-string
Encode the words that need encoding in a string, and return the result.

@example
(mail-encode-encoded-word-string
 "This is naïve, baby")
=> "This is =?iso-8859-1?q?na=EFve,?= baby"
@end example

@item mail-decode-encoded-word-region
@findex mail-decode-encoded-word-region
Decode the encoded words in the region.

@item mail-decode-encoded-word-string
@findex mail-decode-encoded-word-string
Decode the encoded words in the string and return the result.

@example
(mail-decode-encoded-word-string
 "This is =?iso-8859-1?q?na=EFve,?= baby")
=> "This is naïve, baby"
@end example

@end table

Currently, @code{mail-parse} is an abstraction over @code{drums},
@code{rfc2047} and @code{rfc2231}.  These are documented in the
subsequent sections.


@node rfc2231
@section rfc2231

RFC2231 defines a syntax for the @code{Content-Type} and
@code{Content-Disposition} headers.  Its snappy name is @dfn{MIME
Parameter Value and Encoded Word Extensions: Character Sets, Languages,
and Continuations}.

In short, these headers look something like this:

@example
Content-Type: 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!"
@end example

They usually aren't this bad, though.

The following functions are defined by this library:

@table @code
@item rfc2231-parse-string
@findex rfc2231-parse-string
Parse a @code{Content-Type} header and return a list describing its
elements.

@example
(rfc2231-parse-string
 "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!\"")
=> ("application/x-stuff"
    (title . "This is even more ***fun*** isn't it!"))
@end example

@item rfc2231-get-value
@findex rfc2231-get-value
Takes one of the lists on the format above and return
the value of the specified attribute.

@end table


@node drums
@section drums

@dfn{drums} is an IETF working group that is working on the replacement
for RFC822.

The functions provided by this library include:

@table @code
@item drums-remove-comments
@findex drums-remove-comments
Remove the comments from the argument and return the results.

@item drums-remove-whitespace
@findex drums-remove-whitespace
Remove linear white space from the string and return the results.
Spaces inside quoted strings and comments are left untouched.

@item drums-get-comment
@findex drums-get-comment
Return the last most comment from the string.

@item drums-parse-address
@findex drums-parse-address
Parse an address string and return a list that contains the mailbox and
the plain text name.

@item drums-parse-addresses
@findex drums-parse-addresses
Parse a string that contains any number of comma-separated addresses and
return a list that contains mailbox/plain text pairs.

@item drums-parse-date
@findex drums-parse-date
Parse a date string and return an Emacs time structure.

@item drums-narrow-to-header
@findex drums-narrow-to-header
Narrow the buffer to the header section of the current buffer.

@end table


@node rfc2047
@section rfc2047

RFC2047 (Message Header Extensions for Non-ASCII Text) specifies how
non-ASCII text in headers are to be encoded.  This is actually rather
complicated, so a number of variables are necessary to tweak what this
library does.

The following variables are tweakable:

@table @code
@item rfc2047-default-charset
@vindex rfc2047-default-charset
Characters in this charset should not be decoded by this library.
This defaults to @code{iso-8859-1}.

@item rfc2047-header-encoding-list
@vindex rfc2047-header-encoding-list
This is an alist of header / encoding-type pairs.  Its main purpose is
to prevent encoding of certain headers.

The keys can either be header regexps, or @code{t}.

The values can be either @code{nil}, in which case the header(s) in
question won't be encoded, or @code{mime}, which means that they will be
encoded.

@item rfc2047-charset-encoding-alist
@vindex rfc2047-charset-encoding-alist
RFC2047 specifies two forms of encoding---@code{Q} (a
Quoted-Printable-like encoding) and @code{B} (base64).  This alist
specifies which charset should use which encoding.

@item rfc2047-encoding-function-alist
@vindex rfc2047-encoding-function-alist
This is an alist of encoding / function pairs.  The encodings are
@code{Q}, @code{B} and @code{nil}.

@item rfc2047-q-encoding-alist
@vindex rfc2047-q-encoding-alist
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. 

@item rfc2047-encoded-word-regexp
@vindex rfc2047-encoded-word-regexp
When decoding words, this library looks for matches to this regexp. 

@end table

Those were the variables, and these are this functions:

@table @code
@item rfc2047-narrow-to-field
@findex rfc2047-narrow-to-field
Narrow the buffer to the header on the current line.

@item rfc2047-encode-message-header
@findex rfc2047-encode-message-header
Should be called narrowed to the header of a message.  Encodes according
to @code{rfc2047-header-encoding-alist}.

@item rfc2047-encode-region
@findex rfc2047-encode-region
Encodes all encodable words in the region specified.

@item rfc2047-encode-string
@findex rfc2047-encode-string
Encode a string and return the results.

@item rfc2047-decode-region
@findex rfc2047-decode-region
Decode the encoded words in the region.

@item rfc2047-decode-string
@findex rfc2047-decode-string
Decode a string and return the results.

@end table


@node time-date
@section time-date

While not really a part of the @sc{mime} library, it is convenient to
document this library here.  It deals with parsing @code{Date} headers
and manipulating time.  (Not by using tesseracts, though, I'm sorry to
say.)

These functions converts between five formats: A date string, an Emacs
time structure, a decoded time list, a second number, and a day number.

The functions have quite self-explanatory names, so the following just
gives an overview of which functions are available.

@example
(parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
=> (54 21 12 12 9 1998 6 nil 7200)

(date-to-time "Sat Sep 12 12:21:54 1998 +0200")
=> (13818 19266)

(time-to-seconds '(13818 19266))
=> 905595714.0

(seconds-to-time 905595714.0)
=> (13818 19266 0)

(time-to-day '(13818 19266))
=> 729644

(days-to-time 729644)
=> (961933 65536)

(time-since '(13818 19266))
=> (0 430)

(time-less-p '(13818 19266) '(13818 19145))
=> nil

(subtract-time '(13818 19266) '(13818 19145))
=> (0 121)

(days-between "Sat Sep 12 12:21:54 1998 +0200"
              "Sat Sep 07 12:21:54 1998 +0200")
=> 5

(date-leap-year-p 2000)
=> t

(time-to-day-in-year '(13818 19266))
=> 255

@end example

And finally, we have @code{safe-date-to-time}, which does the same as
@code{date-to-time}, but returns a zero time if the date is
syntactically malformed.



@node qp
@section qp

This library deals with decoding and encoding Quoted-Printable text.

Very briefly explained, qp encoding means translating all 8-bit
characters (and lots of control characters) into things that look like
@samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
string.

The following functions are defined by the library:

@table @code
@item quoted-printable-decode-region
@findex quoted-printable-decode-region
QP-decode all the encoded text in the specified region.

@item quoted-printable-decode-string
@findex quoted-printable-decode-string
Decode the QP-encoded text in a string and return the results.

@item quoted-printable-encode-region
@findex quoted-printable-encode-region
QP-encode all the encodable characters in the specified region.  The third
optional parameter @var{fold} specifies whether to fold long lines.
(Long here means 72.)

@item quoted-printable-encode-string
@findex quoted-printable-encode-string
QP-encode all the encodable characters in a string and return the
results.

@end table


@node base64
@section base64

Base64 is an encoding that encodes three bytes into four characters,
thereby increasing the size by about 33%.  The alphabet used for
encoding is very resistant to mangling during transit.

The following functions are defined by this library:

@table @code
@item base64-encode-region
@findex base64-encode-region
base64 encode the selected region.  Return the length of the encoded
text.  Optional third argument @var{no-line-break} means do not break
long lines into shorter lines.

@item base64-encode-string
@findex base64-encode-string
base64 encode a string and return the result.

@item base64-decode-region
@findex base64-decode-region
base64 decode the selected region.  Return the length of the decoded
text.  If the region can't be decoded, return @code{nil} and don't
modify the buffer.

@item base64-decode-string
@findex base64-decode-string
base64 decode a string and return the result.  If the string can't be
decoded, @code{nil} is returned.

@end table


@node mailcap
@section mailcap

The @file{~/.mailcap} file is parsed by most @sc{mime}-aware message
handlers and describes how elements are supposed to be displayed.
Here's an example file:

@example
image/*; xv -8 %s
audio/x-pn-realaudio; rvplayer %s
@end example

This says that all image files should be displayed with @samp{xv}, and
that realaudio files should be played by @samp{rvplayer}.

The @code{mailcap} library parses this file, and provides functions for
matching types.

@table @code
@item mailcap-mime-data
@vindex mailcap-mime-data
This variable is an alist of alists containing backup viewing rules.

@end table

Interface functions:

@table @code
@item mailcap-parse-mailcaps
@findex mailcap-parse-mailcaps
Parse the @code{~/.mailcap} file.

@item mailcap-mime-info
Takes a @sc{mime} type as its argument and returns the matching viewer.

@end table




@node Decoding and Viewing
@chapter Decoding and Viewing

This chapter deals with decoding and viewing @sc{mime} messages on a
higher level.

The main idea is to first analyze a @sc{mime} article, and then allow
other programs to do things based on the list of @dfn{handles} that are
returned as a result of this analysis.

@menu
* Dissection::  Analyzing a @sc{mime} message.
* Handles::     Handle manipulations.
* Display::     Displaying handles.
@end menu


@node Dissection
@section Dissection

The @code{mm-dissect-buffer} is the function responsible for dissecting
a @sc{mime} article.  If given a multipart message, it will recursively
descend the message, following the structure, and return a tree of
@sc{mime} handles that describes the structure of the message.


@node Handles
@section Handles

A @sc{mime} handle is a list that fully describes a @sc{mime}
component.

The following macros can be used to access elements in a handle:

@table @code
@item mm-handle-buffer
@findex mm-handle-buffer
Return the buffer that holds the contents of the undecoded @sc{mime}
part.

@item mm-handle-type
@findex mm-handle-type
Return the parsed @code{Content-Type} of the part.

@item mm-handle-encoding
@findex mm-handle-encoding
Return the @code{Content-Transfer-Encoding} of the part.

@item mm-handle-undisplayer
@findex mm-handle-undisplayer
Return the object that can be used to remove the displayed part (if it
has been displayed).

@item mm-handle-set-undisplayer
@findex mm-handle-set-undisplayer
Set the undisplayer object.

@item mm-handle-disposition
@findex mm-handle-disposition
Return the parsed @code{Content-Disposition} of the part.

@item mm-handle-disposition
@findex mm-handle-disposition
Return the description of the part.

@item mm-get-content-id
Returns the handle(s) referred to by @code{Content-ID}.

@end table


@node Display
@section Display

Functions for displaying, removing and saving.

@table @code
@item mm-display-part
@findex mm-display-part
Display the part.

@item mm-remove-part
@findex mm-remove-part
Remove the part (if it has been displayed).

@item mm-inlinable-p
@findex mm-inlinable-p
Say whether a @sc{mime} type can be displayed inline.

@item mm-automatic-display-p
@findex mm-automatic-display-p
Say whether a @sc{mime} type should be displayed automatically.

@item mm-destroy-part
@findex mm-destroy-part
Free all resources occupied by a part.

@item mm-save-part
@findex mm-save-part
Offer to save the part in a file.

@item mm-pipe-part
@findex mm-pipe-part
Offer to pipe the part to some process.

@item mm-interactively-view-part
@findex mm-interactively-view-part
Prompt for a mailcap method to use to view the part.

@end table
 

 
@node Index
@chapter Index
@printindex cp

@summarycontents
@contents
@bye

@c End: