/[emacs]/emacs/man/emacs-mime.texi
ViewVC logotype

Diff of /emacs/man/emacs-mime.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.15.2.2 by miles, Tue Oct 14 22:56:22 2003 UTC revision 1.15.2.3 by miles, Thu Sep 16 00:12:17 2004 UTC
# Line 1  Line 1 
1  \input texinfo                  @c -*-mode: texinfo; coding: latin-1 -*-  \input texinfo
2    
3  @setfilename ../info/emacs-mime  @setfilename ../info/emacs-mime
4  @settitle Emacs MIME Manual  @settitle Emacs MIME Manual
# Line 9  Line 9 
9  @copying  @copying
10  This file documents the Emacs MIME interface functionality.  This file documents the Emacs MIME interface functionality.
11    
12  Copyright (C) 1998, 1999, 2000, 2002 Free Software Foundation, Inc.  Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
13              Free Software Foundation, Inc.
14    
15  @quotation  @quotation
16  Permission is granted to copy, distribute and/or modify this document  Permission is granted to copy, distribute and/or modify this document
17  under the terms of the GNU Free Documentation License, Version 1.1 or  under the terms of the GNU Free Documentation License, Version 1.1 or
18  any later version published by the Free Software Foundation; with no  any later version published by the Free Software Foundation; with no
19  Invariant Sections, with the Front-Cover texts being ``A GNU  Invariant Sections, with the Front-Cover texts being ``A GNU
20  Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the  Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
21  license is included in the section entitled ``GNU Free Documentation  license is included in the section entitled ``GNU Free Documentation
22  License'' in the Emacs manual.  License'' in the Emacs manual.
23    
# Line 33  license to the document, as described in Line 34  license to the document, as described in
34    
35  @dircategory Emacs  @dircategory Emacs
36  @direntry  @direntry
37  * MIME: (emacs-mime).   Emacs MIME de/composition library.  * Emacs MIME: (emacs-mime).   Emacs MIME de/composition library.
38  @end direntry  @end direntry
39  @iftex  @iftex
40  @finalout  @finalout
# Line 49  license to the document, as described in Line 50  license to the document, as described in
50  @insertcopying  @insertcopying
51  @end titlepage  @end titlepage
52    
   
53  @node Top  @node Top
54  @top Emacs MIME  @top Emacs MIME
55    
56  This manual documents the libraries used to compose and display  This manual documents the libraries used to compose and display
57  @sc{mime} messages.  @acronym{MIME} messages.
58    
59  This is not a manual meant for users; it's a manual directed at people  This manual is directed at users who want to modify the behaviour of
60  who want to write functions and commands that manipulate @sc{mime}  the @acronym{MIME} encoding/decoding process or want a more detailed
61  elements.  picture of how the Emacs @acronym{MIME} library works, and people who want
62    to write functions and commands that manipulate @acronym{MIME} elements.
63    
64  @sc{mime} is short for @dfn{Multipurpose Internet Mail Extensions}.  @acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}.
65  This standard is documented in a number of RFCs; mainly RFC2045 (Format  This standard is documented in a number of RFCs; mainly RFC2045 (Format
66  of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message  of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
67  Header Extensions for Non-ASCII Text), RFC2048 (Registration  Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration
68  Procedures), RFC2049 (Conformance Criteria and Examples).  It is highly  Procedures), RFC2049 (Conformance Criteria and Examples).  It is highly
69  recommended that anyone who intends writing @sc{mime}-compliant software  recommended that anyone who intends writing @acronym{MIME}-compliant software
70  read at least RFC2045 and RFC2047.  read at least RFC2045 and RFC2047.
71    
72  @menu  @menu
73    * Decoding and Viewing::  A framework for decoding and viewing.
74    * Composing::             @acronym{MML}; a language for describing @acronym{MIME} parts.
75  * Interface Functions::   An abstraction over the basic functions.  * Interface Functions::   An abstraction over the basic functions.
76  * Basic Functions::       Utility and basic parsing 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.  
77  * Standards::             A summary of RFCs and working documents used.  * Standards::             A summary of RFCs and working documents used.
78  * Index::                 Function and variable index.  * Index::                 Function and variable index.
79  @end menu  @end menu
80    
81    
 @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  
 instance, @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.  
 @end defun  
   
 @defun mail-encode-encoded-word-buffer  
 Encode the non-@sc{ascii} words in the current buffer.  This function is  
 meant to be called with the buffer narrowed to the headers of a message.  
 @end defun  
   
 @defun mail-encode-encoded-word-string string  
 Encode the words that need encoding in @var{string}, and return the  
 result.  
   
 @example  
 (mail-encode-encoded-word-string  
  "This is naïve, baby")  
 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"  
 @end example  
 @end defun  
   
 @defun mail-decode-encoded-word-region start end  
 Decode the encoded words in the region @var{start}to @var{end}.  
 @end defun  
   
 @defun mail-decode-encoded-word-string string  
 Decode the encoded words in @var{string} and return the result.  
   
 @example  
 (mail-decode-encoded-word-string  
  "This is =?iso-8859-1?q?na=EFve,?= baby")  
 @result{} "This is naïve, baby"  
 @end example  
 @end defun  
   
 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},  
 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}.  These are documented  
 in the subsequent sections.  
   
   
   
 @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  
 * 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.  
 * time-date::    Functions for parsing dates and manipulating time.  
 * qp::           Quoted-Printable en/decoding.  
 * base64::       Base64 en/decoding.  
 * binhex::       Binhex decoding.  
 * uudecode::     Uuencode decoding.  
 * rfc1843::      Decoding HZ-encoded text.  
 * mailcap::      How parts are displayed is specified by mailcap files  
 @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:  
   
 @defun rfc2045-encode-string parameter value  
 @findex rfc2045-encode-string  
 Takes a @var{parameter} and a @var{value} and returns a  
 @samp{@var{param}=@var{value}} string.  @var{value} will be quoted if  
 there are non-safe characters in it.  
 @end defun  
   
   
 @node rfc2231  
 @section rfc2231  
   
 RFC2231 defines a syntax for the @samp{Content-Type} and  
 @samp{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:  
   
 @defun rfc2231-parse-string string  
 Parse a @samp{Content-Type} header @var{string} 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!\"")  
 @result{} ("application/x-stuff"  
     (title . "This is even more ***fun*** isn't it!"))  
 @end example  
 @end defun  
   
 @defun rfc2231-get-value ct attribute  
 Takes a list @var{ct} of the format above and returns the value of the  
 specified @var{attribute}.  
 @end defun  
   
 @defun rfc2231-encode-string parameter value  
 Encode the string @samp{@var{parameter}=@var{value}} for inclusion in  
 headers likes @samp{Content-Type} and @samp{Content-Disposition}.  
 @end defun  
   
 @node ietf-drums  
 @section ietf-drums  
   
 @dfn{drums} is an IETF working group that is working on the replacement  
 for RFC822.  
   
 The functions provided by this library include:  
   
 @defun ietf-drums-remove-comments string  
 Remove the comments from @var{string} and return the result.  
 @end defun  
   
 @defun ietf-drums-remove-whitespace string  
 Remove linear white space from @var{string} and return the result.  
 Spaces inside quoted strings and comments are left untouched.  
 @end defun  
   
 @defun ietf-drums-get-comment string  
 Return the last most comment from @var{string}.  
 @end defun  
   
 @defun ietf-drums-parse-address string  
 Parse an address @var{string} and return a list of the mailbox and the  
 plain text name.  
 @end defun  
   
 @defun ietf-drums-parse-addresses string  
 Parse @var{string}, containing any number of comma-separated addresses,  
 and return a list of mailbox/plain text pairs.  
 @end defun  
   
 @defun ietf-drums-parse-date string  
 Parse the date @var{string} and return an Emacs time structure.  
 @end defun  
   
 @defun ietf-drums-narrow-to-header  
 Narrow the buffer to the header section of the current buffer.  
 @end defun  
   
   
 @node rfc2047  
 @section rfc2047  
   
 RFC2047 (Message Header Extensions for Non-ASCII Text) specifies how  
 non-@sc{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:  
   
 @defvar rfc2047-default-charset  
 Characters in this charset should not be decoded by this library.  
 This defaults to @samp{iso-8859-1}.  
 @end defvar  
   
 @defvar rfc2047-header-encoding-list  
 This is an alist of header / encoding-type pairs.  Its main purpose is  
 to prevent encoding of certain headers.  
 @end defvar  
   
 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.  
   
 @defvar 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.  
 @end defvar  
   
 @defvar rfc2047-encoding-function-alist  
 This is an alist of encoding / function pairs.  The encodings are  
 @code{Q}, @code{B} and @code{nil}.  
 @end defvar  
   
 @defvar 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 and allowable character  
 ranges.  
 @end defvar  
   
 @defvar rfc2047-encoded-word-regexp  
 When decoding words, this library looks for matches to this regexp.  
 @end defvar  
   
 Those were the variables, and these are the functions:  
   
 @defun rfc2047-narrow-to-field  
 Narrow the buffer to the header on the current line.  
 @end defun  
   
 @defun rfc2047-encode-message-header  
 Should be called narrowed to the header of a message.  Encodes according  
 to @code{rfc2047-header-encoding-alist}.  
 @end defun  
   
 @defun rfc2047-encode-region start end  
 Encodes all encodable words in the region @var{start} to @var{end}.  
 @end defun  
   
 @defun rfc2047-encode-string string  
 Encode @var{string} and return the result.  
 @end defun  
   
 @defun rfc2047-decode-region start end  
 Decode the encoded words in the region @var{start} to @var{end}.  
 @end defun  
   
 @defun rfc2047-decode-string string  
 Decode @var{string} and return the result.  
 @end defun  
   
   
   
 @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 @samp{Date} headers  
 and manipulating time.  (Not by using tesseracts, though, I'm sorry to  
 say.)  
   
 These functions convert between five formats: a date string, an Emacs  
 time structure, a decoded time list, a number of seconds, and a day number.  
   
 The functions have quite self-explanatory names, so the following just  
 gives an overview of which functions are available.  
   
 @findex parse-time-string  
 @findex date-to-time  
 @findex time-to-seconds  
 @findex seconds-to-time  
 @findex time-to-day  
 @findex days-to-time  
 @findex time-since  
 @findex time-less-p  
 @findex subtract-time  
 @findex days-between  
 @findex date-leap-year-p  
 @findex time-to-day-in-year  
 @example  
 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")  
 @result{} (54 21 12 12 9 1998 6 nil 7200)  
   
 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")  
 @result{} (13818 19266)  
   
 (time-to-seconds '(13818 19266))  
 @result{} 905595714.0  
   
 (seconds-to-time 905595714.0)  
 @result{} (13818 19266 0)  
   
 (time-to-day '(13818 19266))  
 @result{} 729644  
   
 (days-to-time 729644)  
 @result{} (961933 65536)  
   
 (time-since '(13818 19266))  
 @result{} (0 430)  
   
 (time-less-p '(13818 19266) '(13818 19145))  
 @result{} nil  
   
 (subtract-time '(13818 19266) '(13818 19145))  
 @result{} (0 121)  
   
 (days-between "Sat Sep 12 12:21:54 1998 +0200"  
               "Sat Sep 07 12:21:54 1998 +0200")  
 @result{} 5  
   
 (date-leap-year-p 2000)  
 @result{} t  
   
 (time-to-day-in-year '(13818 19266))  
 @result{} 255  
 @end example  
   
 @findex safe-date-to-time  
 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.  It is defined in RFC 2045.  
   
 The following functions are defined by the library:  
   
 @deffn Command quoted-printable-decode-region @var{from} @var{to} &optional @var{coding-system}  
 QP-decode all the encoded text in the region.  If @var{coding-system}  
 is non-nil, decode bytes into characters with that coding-system.  It  
 is probably better not to use @var{coding-system}; instead decode into  
 a unibyte buffer, decode that appropriately and then interpret it as  
 multibyte.  
 @end deffn  
   
 @defun quoted-printable-decode-string @var{string} &optional @var{coding-system}  
 Return a QP-encoded copy of @var{string}.  If @var{coding-system} is  
 non-nil, decode bytes into characters with that coding-system.  
 @end defun  
   
 @deffn Command quoted-printable-encode-region @var{from} @var{to} &optional @var{fold} @var{class}  
 QP-encode all the region.  If @var{fold} is non-@var{nil}, fold lines  
 at 76 characters, as required by the RFC.  If @var{class} is  
 non-@code{nil}, translate the characters not matched by that regexp  
 class, which should be in the form expected by  
 @var{skip-chars-forward} and should probably not contain literal  
 eight-bit characters.  Specifying @var{class} makes sense to do extra  
 encoding in header fields.  
   
 If variable @var{mm-use-ultra-safe-encoding} is defined and  
 non-@code{nil}, fold lines unconditionally and encode @samp{From } and  
 @samp{-} at the start of lines..  
 @end deffn  
   
 @defun quoted-printable-encode-string string  
 Return a QP-encoded copy of @var{string}.  
 @end defun  
   
 @node base64  
 @section base64  
 @cindex 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.  @xref{Base  
 64,,Base 64 Encoding, elisp, The Emacs Lisp Reference Manual}.  
   
 @node binhex  
 @section binhex  
 @cindex binhex  
 @cindex Apple  
 @cindex Macintosh  
   
 Binhex is an encoding that originated in Macintosh environments.  
 The following function is supplied to deal with these:  
   
 @defun binhex-decode-region start end &optional header-only  
 Decode the encoded text in the region @var{start} to @var{end}.  If  
 @var{header-only} is non-@code{nil}, only decode the @samp{binhex}  
 header and return the file name.  
 @end defun  
   
   
 @node uudecode  
 @section uudecode  
 @cindex uuencode  
 @cindex uudecode  
   
 Uuencoding is probably still the most popular encoding of binaries  
 used on Usenet, although Base64 rules the mail world.  
   
 The following function is supplied by this package:  
   
 @defun uudecode-decode-region start end &optional file-name  
 Decode the text in the region @var{start} to @var{end}.  If  
 @var{file-name} is non-@code{nil}, save the result to @var{file-name}.  
 @end defun  
   
   
 @node rfc1843  
 @section rfc1843  
 @cindex rfc1843  
 @cindex HZ  
 @cindex Chinese  
   
 RFC1843 deals with mixing Chinese and @sc{ascii} characters in messages.  In  
 essence, RFC1843 switches between @sc{ascii} and Chinese by doing this:  
   
 @example  
 This sentence is in ASCII.  
 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.  
 @end example  
   
 Simple enough, and widely used in China.  
   
 The following functions are available to handle this encoding:  
   
 @defun rfc1843-decode-region start end  
 Decode HZ-encoded text in the region @var{start} to @var{end}.  
 @end defun  
   
 @defun rfc1843-decode-string string  
 Decode the HZ-encoded @var{string} and return the result.  
 @end defun  
   
   
 @node mailcap  
 @section mailcap  
   
 As specified by RFC 1524, @sc{mime}-aware message handlers parse  
 @dfn{mailcap} files from a default list, which can be overridden by the  
 @code{MAILCAP} environment variable.  These describe how elements are  
 supposed to be displayed.  Here's an example file:  
   
 @example  
 image/*; gimp -8 %s  
 audio/wav; wavplayer %s  
 @end example  
   
 This says that all image files should be displayed with @command{gimp},  
 and that WAVE audio files should be played by @code{wavplayer}.  
   
 The @code{mailcap} library parses such files, and provides functions for  
 matching types.  
   
 @defvar mailcap-mime-data  
 This variable is an alist of alists containing backup viewing rules for  
 @sc{mime} types.  These are overridden by rules for a type found in  
 mailcap files.  The outer alist is keyed on the major content-type and  
 the inner alists are keyed on the minor content-type (which can be a  
 regular expression).  
   
 @c Fixme: document this properly!  
 For example:  
 @example  
 (("application"  
   ("octet-stream"  
    (viewer . mailcap-save-binary-file)  
    (non-viewer . t)  
    (type . "application/octet-stream"))  
   ("plain"  
    (viewer . view-mode)  
    (test fboundp 'view-mode)  
    (type . "text/plain")))  
 @end example  
 @end defvar  
   
 @defopt mailcap-default-mime-data  
 This variable is the default value of @code{mailcap-mime-data}.  It  
 exists to allow setting the value using Custom.  It is merged with  
 values from mailcap files by @code{mailcap-parse-mailcaps}.  
 @end defopt  
   
 Although it is not specified by the RFC, @sc{mime} tools normally use a  
 common means of associating file extensions with defualt @sc{mime} types  
 in the absence of other information about the type of a file.  The  
 information is found in per-user files @file{~/.mime.types} and system  
 @file{mime.types} files found in quasi-standard places.  Here is an  
 example:  
   
 @example  
 application/x-dvi       dvi  
 audio/mpeg              mpga mpega mp2 mp3  
 image/jpeg              jpeg jpg jpe  
 @end example  
   
   
 @defvar mailcap-mime-extensions  
 This variable is an alist @sc{mime} types keyed by file extensions.  
 This is overridden by entries found in @file{mime.types} files.  
 @end defvar  
   
 @defopt mailcap-default-mime-extensions  
 This variable is the default value of @code{mailcap-mime-extensions}.  
 It exists to allow setting the value using Custom.  It is merged with  
 values from mailcap files by @code{mailcap-parse-mimetypes}.  
 @end defopt  
   
 Interface functions:  
   
 @defun mailcap-parse-mailcaps &optional path force  
 Parse all the mailcap files specified in a path string @var{path} and  
 merge them with the values from @code{mailcap-mime-data}.  Components of  
 @var{path} are separated by the @code{path-separator} character  
 appropriate for the system.  If @var{force} is non-@code{nil}, the files  
 are re-parsed even if they have been parsed already.  If @var{path} is  
 omitted, use the value of environment variable @code{MAILCAPS} if it is  
 set; otherwise (on GNU and Unix) use the path defined in RFC 1524, plus  
 @file{/usr/local/etc/mailcap}.  
 @end defun  
   
 @defun mailcap-parse-mimetypes &optional path force  
 Parse all the mimetypes specified in a path string @var{path}  
 and merge them with the values from @code{mailcap-mime-extensions}.  
 Components of @var{path} are separated by the @code{path-separator}  
 character appropriate for the system.  If @var{path} is omitted, use the  
 value of environment variable @code{MIMETYPES} if set; otherwise use a  
 default path consistent with that used by @code{mailcap-parse-mailcaps}.  
 If @var{force} is non-@code{nil}, the files are re-parsed even if they  
 have been parsed already.  
 @end defun  
   
 @defun mailcap-mime-info string &optional request  
 Gets the viewer command for content-type @var{string}.  @code{nil} is  
 returned if none is found.  Expects @var{string} to be a complete  
 content-type header line.  
   
 If @var{request} is non-@code{nil} it specifies what information to  
 return.  If it is nil or the empty string, the viewer (second field of  
 the mailcap entry) will be returned.  If it is a string, then the  
 mailcap field corresponding to that string will be returned  
 (@samp{print}, @samp{description}, whatever).  If it is a number, all  
 the information for this viewer is returned.  If it is @code{all}, then  
 all possible viewers for this type is returned.  
 @end defun  
   
 @defun mailcap-mime-types  
 This function returns a list of all the defined media types.  
 @end defun  
   
 @defun mailcap-extension-to-mime extension  
 This function returns the content type defined for a file with the given  
 @var{extension}.  
 @end defun  
   
   
82  @node Decoding and Viewing  @node Decoding and Viewing
83  @chapter Decoding and Viewing  @chapter Decoding and Viewing
84    
85  This chapter deals with decoding and viewing @sc{mime} messages on a  This chapter deals with decoding and viewing @acronym{MIME} messages on a
86  higher level.  higher level.
87    
88  The main idea is to first analyze a @sc{mime} article, and then allow  The main idea is to first analyze a @acronym{MIME} article, and then allow
89  other programs to do things based on the list of @dfn{handles} that are  other programs to do things based on the list of @dfn{handles} that are
90  returned as a result of this analysis.  returned as a result of this analysis.
91    
92  @menu  @menu
93  * Dissection::     Analyzing a @sc{mime} message.  * Dissection::             Analyzing a @acronym{MIME} message.
94  * Handles::        Handle manipulations.  * Non-MIME::               Analyzing a non-@acronym{MIME} message.
95  * Display::        Displaying handles.  * Handles::                Handle manipulations.
96  * Customization::  Variables that affect display.  * Display::                Displaying handles.
97  * New Viewers::    How to write your own viewers.  * Display Customization::  Variables that affect display.
98    * Files and Directories::  Saving and naming attachments.
99    * New Viewers::            How to write your own viewers.
100  @end menu  @end menu
101    
102    
# Line 795  returned as a result of this analysis. Line 104  returned as a result of this analysis.
104  @section Dissection  @section Dissection
105    
106  The @code{mm-dissect-buffer} is the function responsible for dissecting  The @code{mm-dissect-buffer} is the function responsible for dissecting
107  a @sc{mime} article.  If given a multipart message, it will recursively  a @acronym{MIME} article.  If given a multipart message, it will recursively
108  descend the message, following the structure, and return a tree of  descend the message, following the structure, and return a tree of
109  @sc{mime} handles that describes the structure of the message.  @acronym{MIME} handles that describes the structure of the message.
110    
111    @node Non-MIME
112    @section Non-MIME
113    @vindex mm-uu-configure-list
114    
115    Gnus also understands some non-@acronym{MIME} attachments, such as
116    postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp,
117    diff.  Each of these features can be disabled by add an item into
118    @code{mm-uu-configure-list}.  For example,
119    
120    @lisp
121    (require 'mm-uu)
122    (add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
123    @end lisp
124    
125    @table @code
126    @item postscript
127    @findex postscript
128    Postscript file.
129    
130    @item uu
131    @findex uu
132    Uuencoded file.
133    
134    @item binhex
135    @findex binhex
136    Binhex encoded file.
137    
138    @item yenc
139    @findex yenc
140    Yenc encoded file.
141    
142    @item shar
143    @findex shar
144    Shar archive file.
145    
146    @item forward
147    @findex forward
148    Non-@acronym{MIME} forwarded message.
149    
150    @item gnatsweb
151    @findex gnatsweb
152    Gnatsweb attachment.
153    
154    @item pgp-signed
155    @findex pgp-signed
156    @acronym{PGP} signed clear text.
157    
158    @item pgp-encrypted
159    @findex pgp-encrypted
160    @acronym{PGP} encrypted clear text.
161    
162    @item pgp-key
163    @findex pgp-key
164    @acronym{PGP} public keys.
165    
166    @item emacs-sources
167    @findex emacs-sources
168    @vindex mm-uu-emacs-sources-regexp
169    Emacs source code.  This item works only in the groups matching
170    @code{mm-uu-emacs-sources-regexp}.
171    
172    @item diff
173    @vindex diff
174    @vindex mm-uu-diff-groups-regexp
175    Patches.  This is intended for groups where diffs of committed files
176    are automatically sent to.  It only works in groups matching
177    @code{mm-uu-diff-groups-regexp}.
178    
179    @end table
180    
181  @node Handles  @node Handles
182  @section Handles  @section Handles
183    
184  A @sc{mime} handle is a list that fully describes a @sc{mime} component.  A @acronym{MIME} handle is a list that fully describes a @acronym{MIME}
185    component.
186    
187  The following macros can be used to access elements from the  The following macros can be used to access elements in a handle:
 @var{handle} argument:  
188    
189  @defmac mm-handle-buffer handle  @table @code
190  Return the buffer that holds the contents of the undecoded @sc{mime}  @item mm-handle-buffer
191    @findex mm-handle-buffer
192    Return the buffer that holds the contents of the undecoded @acronym{MIME}
193  part.  part.
 @end defmac  
   
 @defmac mm-handle-type handle  
 Return the parsed @samp{Content-Type} of the part.  
 @end defmac  
   
 @defmac mm-handle-encoding handle  
 Return the @samp{Content-Transfer-Encoding} of the part.  
 @end defmac  
194    
195  @defmac mm-handle-undisplayer handle  @item mm-handle-type
196  Return the function that can be used to remove the displayed part (if it  @findex mm-handle-type
197    Return the parsed @code{Content-Type} of the part.
198    
199    @item mm-handle-encoding
200    @findex mm-handle-encoding
201    Return the @code{Content-Transfer-Encoding} of the part.
202    
203    @item mm-handle-undisplayer
204    @findex mm-handle-undisplayer
205    Return the object that can be used to remove the displayed part (if it
206  has been displayed).  has been displayed).
 @end defmac  
207    
208  @defmac mm-handle-set-undisplayer handle function  @item mm-handle-set-undisplayer
209  Set the undisplayer function for the part to function.  @findex mm-handle-set-undisplayer
210  @end defmac  Set the undisplayer object.
211    
212    @item mm-handle-disposition
213    @findex mm-handle-disposition
214    Return the parsed @code{Content-Disposition} of the part.
215    
216  @defmac mm-handle-disposition  @item mm-handle-disposition
217  Return the parsed @samp{Content-Disposition} of the part.  @findex mm-handle-disposition
 @end defmac  
   
 @defmac mm-handle-disposition  
218  Return the description of the part.  Return the description of the part.
 @end defmac  
219    
220  @defmac mm-get-content-id id  @item mm-get-content-id
221  Returns the handle(s) referred to by @var{id}, the @samp{Content-ID} of  Returns the handle(s) referred to by @code{Content-ID}.
222  the part.  
223  @end defmac  @end table
224    
225    
226  @node Display  @node Display
227  @section Display  @section Display
228    
229  Functions for displaying, removing and saving.  In the descriptions  Functions for displaying, removing and saving.
 below, `the part' means the @sc{mime} part represented by the  
 @var{handle} argument.  
   
 @defun mm-display-part handle &optional no-default  
 Display the part.  Return @code{nil} if the part is removed,  
 @code{inline} if it is displayed inline or @code{external} if it is  
 displayed externally.  If @var{no-default} is non-@code{nil}, the part  
 is not displayed unless the @sc{mime} type of @var{handle} is defined to  
 be displayed inline or there is an display method defined for it; i.e.@:  
 no default external method will be used.  
 @end defun  
   
 @defun mm-remove-part handle  
 Remove the part if it has been displayed.  
 @end defun  
   
 @defun mm-inlinable-p handle  
 Return non-@code{nil} if the part can be displayed inline.  
 @end defun  
   
 @defun mm-automatic-display-p handle  
 Return non-@code{nil} if the user has requested automatic display of the  
 @sc{mime} type of the part.  
 @end defun  
   
 @defun mm-destroy-part handle  
 Free all the resources used by the part.  
 @end defun  
   
 @defun mm-save-part handle  
 Save the part to a file.  The user is prompted for a file name to use.  
 @end defun  
   
 @defun mm-pipe-part handle  
 Pipe the part through a shell command.  The user is prompted for the  
 command to use.  
 @end defun  
   
 @defun mm-interactively-view-part handle  
 Prompt for a mailcap method to use to view the part and display it  
 externally using that method.  
 @end defun  
230    
231    @table @code
232    @item mm-display-part
233    @findex mm-display-part
234    Display the part.
235    
236    @item mm-remove-part
237    @findex mm-remove-part
238    Remove the part (if it has been displayed).
239    
240    @item mm-inlinable-p
241    @findex mm-inlinable-p
242    Say whether a @acronym{MIME} type can be displayed inline.
243    
244    @item mm-automatic-display-p
245    @findex mm-automatic-display-p
246    Say whether a @acronym{MIME} type should be displayed automatically.
247    
248    @item mm-destroy-part
249    @findex mm-destroy-part
250    Free all resources occupied by a part.
251    
252    @item mm-save-part
253    @findex mm-save-part
254    Offer to save the part in a file.
255    
256    @item mm-pipe-part
257    @findex mm-pipe-part
258    Offer to pipe the part to some process.
259    
260    @item mm-interactively-view-part
261    @findex mm-interactively-view-part
262    Prompt for a mailcap method to use to view the part.
263    
264    @end table
265    
 @node Customization  
 @section Customization  
266    
267  The display of @sc{mime} types may be customized with the following  @node Display Customization
268  options.  @section Display Customization
269    
270  @defopt mm-inline-media-tests  @table @code
271  This is an alist where the key is a @sc{mime} type, the second element  
272    @item mm-inline-media-tests
273    @vindex mm-inline-media-tests
274    This is an alist where the key is a @acronym{MIME} type, the second element
275  is a function to display the part @dfn{inline} (i.e., inside Emacs), and  is a function to display the part @dfn{inline} (i.e., inside Emacs), and
276  the third element is a form to be @code{eval}ed to say whether the part  the third element is a form to be @code{eval}ed to say whether the part
277  can be displayed inline.  can be displayed inline.
# Line 907  can be displayed inline. Line 279  can be displayed inline.
279  This variable specifies whether a part @emph{can} be displayed inline,  This variable specifies whether a part @emph{can} be displayed inline,
280  and, if so, how to do it.  It does not say whether parts are  and, if so, how to do it.  It does not say whether parts are
281  @emph{actually} displayed inline.  @emph{actually} displayed inline.
 @end defopt  
282    
283  @defopt mm-inlined-types  @item mm-inlined-types
284    @vindex mm-inlined-types
285  This, on the other hand, says what types are to be displayed inline, if  This, on the other hand, says what types are to be displayed inline, if
286  they satisfy the conditions set by the variable above.  It's a list of  they satisfy the conditions set by the variable above.  It's a list of
287  @sc{mime} media types.  @acronym{MIME} media types.
 @end defopt  
288    
289  @defopt mm-automatic-display  @item mm-automatic-display
290    @vindex mm-automatic-display
291  This is a list of types that are to be displayed ``automatically'', but  This is a list of types that are to be displayed ``automatically'', but
292  only if the above variable allows it.  That is, only inlinable parts can  only if the above variable allows it.  That is, only inlinable parts can
293  be displayed automatically.  be displayed automatically.
 @end defopt  
294    
295  @defopt mm-attachment-override-types  @item mm-automatic-external-display
296  Some @sc{mime} agents create parts that have a content-disposition of  @vindex mm-automatic-external-display
297    This is a list of types that will be displayed automatically in an
298    external viewer.
299    
300    @item mm-keep-viewer-alive-types
301    @vindex mm-keep-viewer-alive-types
302    This is a list of media types for which the external viewer will not
303    be killed when selecting a different article.
304    
305    @item mm-attachment-override-types
306    @vindex mm-attachment-override-types
307    Some @acronym{MIME} agents create parts that have a content-disposition of
308  @samp{attachment}.  This variable allows overriding that disposition and  @samp{attachment}.  This variable allows overriding that disposition and
309  displaying the part inline.  (Note that the disposition is only  displaying the part inline.  (Note that the disposition is only
310  overridden if we are able to, and want to, display the part inline.)  overridden if we are able to, and want to, display the part inline.)
 @end defopt  
311    
312  @defopt mm-discouraged-alternatives  @item mm-discouraged-alternatives
313  List of @sc{mime} types that are discouraged when viewing  @vindex mm-discouraged-alternatives
314    List of @acronym{MIME} types that are discouraged when viewing
315  @samp{multipart/alternative}.  Viewing agents are supposed to view the  @samp{multipart/alternative}.  Viewing agents are supposed to view the
316  last possible part of a message, as that is supposed to be the richest.  last possible part of a message, as that is supposed to be the richest.
317  However, users may prefer other types instead, and this list says what  However, users may prefer other types instead, and this list says what
318  types are most unwanted.  If, for instance, @samp{text/html} parts are  types are most unwanted.  If, for instance, @samp{text/html} parts are
319  very unwanted, and @samp{text/richtech} parts are somewhat unwanted,  very unwanted, and @samp{text/richtext} parts are somewhat unwanted,
320  then the value of this variable should be set to:  you could say something like:
321    
322  @lisp  @lisp
323  ("text/html" "text/richtext")  (setq mm-discouraged-alternatives
324          '("text/html" "text/richtext")
325          mm-automatic-display
326          (remove "text/html" mm-automatic-display))
327  @end lisp  @end lisp
 @end defopt  
328    
329  @defopt mm-inline-large-images-p  @item mm-inline-large-images
330    @vindex mm-inline-large-images
331  When displaying inline images that are larger than the window, XEmacs  When displaying inline images that are larger than the window, XEmacs
332  does not enable scrolling, which means that you cannot see the whole  does not enable scrolling, which means that you cannot see the whole
333  image.  To prevent this, the library tries to determine the image size  image.  To prevent this, the library tries to determine the image size
# Line 951  library will display it externally (e.g. Line 336  library will display it externally (e.g.
336  @samp{xv}).  Setting this variable to @code{t} disables this check and  @samp{xv}).  Setting this variable to @code{t} disables this check and
337  makes the library display all inline images as inline, regardless of  makes the library display all inline images as inline, regardless of
338  their size.  their size.
 @end defopt  
339    
340  @defopt mm-inline-override-p  @item mm-inline-override-types
341    @vindex mm-inline-override-types
342  @code{mm-inlined-types} may include regular expressions, for example to  @code{mm-inlined-types} may include regular expressions, for example to
343  specify that all @samp{text/.*} parts be displayed inline.  If a user  specify that all @samp{text/.*} parts be displayed inline.  If a user
344  prefers to have a type that matches such a regular expression be treated  prefers to have a type that matches such a regular expression be treated
# Line 961  as an attachment, that can be accomplish Line 346  as an attachment, that can be accomplish
346  list containing that type.  For example assuming @code{mm-inlined-types}  list containing that type.  For example assuming @code{mm-inlined-types}
347  includes @samp{text/.*}, then including @samp{text/html} in this  includes @samp{text/.*}, then including @samp{text/html} in this
348  variable will cause @samp{text/html} parts to be treated as attachments.  variable will cause @samp{text/html} parts to be treated as attachments.
 @end defopt  
349    
350    @item mm-text-html-renderer
351    @vindex mm-text-html-renderer
352    This selects the function used to render @acronym{HTML}.  The predefined
353    renderers are selected by the symbols @code{w3},
354    @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more
355    information about emacs-w3m}, @code{links}, @code{lynx},
356    @code{w3m-standalone} or @code{html2text}.  If @code{nil} use an
357    external viewer.  You can also specify a function, which will be
358    called with a @acronym{MIME} handle as the argument.
359    
360    @item mm-inline-text-html-with-images
361    @vindex mm-inline-text-html-with-images
362    Some @acronym{HTML} mails might have the trick of spammers using
363    @samp{<img>} tags.  It is likely to be intended to verify whether you
364    have read the mail.  You can prevent your personal informations from
365    leaking by setting this option to @code{nil} (which is the default).
366    It is currently ignored by Emacs/w3.  For emacs-w3m, you may use the
367    command @kbd{t} on the image anchor to show an image even if it is
368    @code{nil}.@footnote{The command @kbd{T} will load all images.  If you
369    have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i}
370    or @kbd{I} instead.}
371    
372    @item mm-w3m-safe-url-regexp
373    @vindex mm-w3m-safe-url-regexp
374    A regular expression that matches safe URL names, i.e. URLs that are
375    unlikely to leak personal information when rendering @acronym{HTML}
376    email (the default value is @samp{\\`cid:}).  If @code{nil} consider
377    all URLs safe.
378    
379    @item mm-inline-text-html-with-w3m-keymap
380    @vindex mm-inline-text-html-with-w3m-keymap
381    You can use emacs-w3m command keys in the inlined text/html part by
382    setting this option to non-@code{nil}.  The default value is @code{t}.
383    
384    @item mm-external-terminal-program
385    @vindex mm-external-terminal-program
386    The program used to start an external terminal.
387    
388    @item mm-enable-external
389    @vindex mm-enable-external
390    Indicate whether external MIME handlers should be used.
391    
392    If @code{t}, all defined external MIME handlers are used.  If
393    @code{nil}, files are saved to disk (@code{mailcap-save-binary-file}).
394    If it is the symbol @code{ask}, you are prompted before the external
395    @acronym{MIME} handler is invoked.
396    
397    When you launch an attachment through mailcap (@pxref{mailcap}) an
398    attempt is made to use a safe viewer with the safest options--this isn't
399    the case if you save it to disk and launch it in a different way
400    (command line or double-clicking).  Anyhow, if you want to be sure not
401    to launch any external programs, set this variable to @code{nil} or
402    @code{ask}.
403    
404    @end table
405    
406    @node Files and Directories
407    @section Files and Directories
408    
409    @table @code
410    
411    @item mm-default-directory
412    @vindex mm-default-directory
413    The default directory for saving attachments.  If @code{nil} use
414    @code{default-directory}.
415    
416    @item mm-tmp-directory
417    @vindex mm-tmp-directory
418    Directory for storing temporary files.
419    
420    @item mm-file-name-rewrite-functions
421    @vindex mm-file-name-rewrite-functions
422    A list of functions used for rewriting file names of @acronym{MIME}
423    parts.  Each function is applied successively to the file name.
424    Ready-made functions include
425    
426    @table @code
427    @item mm-file-name-delete-control
428    @findex mm-file-name-delete-control
429    Delete all control characters.
430    
431    @item mm-file-name-delete-gotchas
432    @findex mm-file-name-delete-gotchas
433    Delete characters that could have unintended consequences when used
434    with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and
435    @samp{-}, @samp{.} as the first character.
436    
437    @item mm-file-name-delete-whitespace
438    @findex mm-file-name-delete-whitespace
439    Remove all whitespace.
440    
441    @item mm-file-name-trim-whitespace
442    @findex mm-file-name-trim-whitespace
443    Remove leading and trailing whitespace.
444    
445    @item mm-file-name-collapse-whitespace
446    @findex mm-file-name-collapse-whitespace
447    Collapse multiple whitespace characters.
448    
449    @item mm-file-name-replace-whitespace
450    @findex mm-file-name-replace-whitespace
451    @vindex mm-file-name-replace-whitespace
452    Replace whitespace with underscores.  Set the variable
453    @code{mm-file-name-replace-whitespace} to any other string if you do
454    not like underscores.
455    @end table
456    
457    The standard Emacs functions @code{capitalize}, @code{downcase},
458    @code{upcase} and @code{upcase-initials} might also prove useful.
459    
460    @item mm-path-name-rewrite-functions
461    @vindex mm-path-name-rewrite-functions
462    List of functions used for rewriting the full file names of @acronym{MIME}
463    parts.  This is used when viewing parts externally, and is meant for
464    transforming the absolute name so that non-compliant programs can find
465    the file where it's saved.
466    
467    @end table
468    
469  @node New Viewers  @node New Viewers
470  @section New Viewers  @section New Viewers
471    
472  Here's an example viewer for displaying @samp{text/enriched} inline:  Here's an example viewer for displaying @code{text/enriched} inline:
473    
474  @lisp  @lisp
475  (defun mm-display-enriched-inline (handle)  (defun mm-display-enriched-inline (handle)
# Line 980  Here's an example viewer for displaying Line 482  Here's an example viewer for displaying
482      (mm-insert-inline handle text)))      (mm-insert-inline handle text)))
483  @end lisp  @end lisp
484    
485  We see that the function takes a @sc{mime} handle as its parameter.  It  We see that the function takes a @acronym{MIME} handle as its parameter.  It
486  then goes to a temporary buffer, inserts the text of the part, does some  then goes to a temporary buffer, inserts the text of the part, does some
487  work on the text, stores the result, goes back to the buffer it was  work on the text, stores the result, goes back to the buffer it was
488  called from and inserts the result.  called from and inserts the result.
# Line 990  The two important helper functions here Line 492  The two important helper functions here
492  handle in the current buffer.  It handles charset and/or content  handle in the current buffer.  It handles charset and/or content
493  transfer decoding.  The second function just inserts whatever text you  transfer decoding.  The second function just inserts whatever text you
494  tell it to insert, but it also sets things up so that the text can be  tell it to insert, but it also sets things up so that the text can be
495  ``undisplayed' in a convenient manner.  ``undisplayed'' in a convenient manner.
496    
497    
498  @node Composing  @node Composing
# Line 1000  tell it to insert, but it also sets thin Line 502  tell it to insert, but it also sets thin
502  @cindex MML  @cindex MML
503  @cindex MIME Meta Language  @cindex MIME Meta Language
504    
505  Creating a @sc{mime} message is boring and non-trivial.  Therefore, a  Creating a @acronym{MIME} message is boring and non-trivial.  Therefore,
506  library called @code{mml} has been defined that parses a language called  a library called @code{mml} has been defined that parses a language
507  MML (@sc{mime} Meta Language) and generates @sc{mime} messages.  called @acronym{MML} (@acronym{MIME} Meta Language) and generates
508    @acronym{MIME} messages.
509    
510  @findex mml-generate-mime  @findex mml-generate-mime
511  The main interface function is @code{mml-generate-mime}.  It will  The main interface function is @code{mml-generate-mime}.  It will
512  examine the contents of the current (narrowed-to) buffer and return a  examine the contents of the current (narrowed-to) buffer and return a
513  string containing the @sc{mime} message.  string containing the @acronym{MIME} message.
514    
515  @menu  @menu
516  * Simple MML Example::             An example MML document.  * Simple MML Example::             An example @acronym{MML} document.
517  * MML Definition::                 All valid MML elements.  * MML Definition::                 All valid @acronym{MML} elements.
518  * Advanced MML Example::           Another example MML document.  * Advanced MML Example::           Another example @acronym{MML} document.
519  * Charset Translation::            How charsets are mapped from Mule to MIME.  * Encoding Customization::         Variables that affect encoding.
520  * Conversion::                     Going from @sc{mime} to MML and vice versa.  * Charset Translation::            How charsets are mapped from @sc{mule} to @acronym{MIME}.
521    * Conversion::                     Going from @acronym{MIME} to @acronym{MML} and vice versa.
522    * Flowed text::                    Soft and hard newlines.
523  @end menu  @end menu
524    
525    
# Line 1055  Content-Type: text/enriched Line 560  Content-Type: text/enriched
560  @node MML Definition  @node MML Definition
561  @section MML Definition  @section MML Definition
562    
563  The MML language is very simple.  It looks a bit like an SGML  The @acronym{MML} language is very simple.  It looks a bit like an SGML
564  application, but it's not.  application, but it's not.
565    
566  The main concept of MML is the @dfn{part}.  Each part can be of a  The main concept of @acronym{MML} is the @dfn{part}.  Each part can be of a
567  different type or use a different charset.  The way to delineate a part  different type or use a different charset.  The way to delineate a part
568  is with a @samp{<#part ...>} tag.  Multipart parts can be introduced  is with a @samp{<#part ...>} tag.  Multipart parts can be introduced
569  with the @samp{<#multipart ...>} tag.  Parts are ended by the  with the @samp{<#multipart ...>} tag.  Parts are ended by the
# Line 1073  Each tag can contain zero or more parame Line 578  Each tag can contain zero or more parame
578  but that's not necessary unless the value contains white space.  So  but that's not necessary unless the value contains white space.  So
579  @samp{filename=/home/user/#hello$^yes} is perfectly valid.  @samp{filename=/home/user/#hello$^yes} is perfectly valid.
580    
581  The following parameters have meaning in MML; parameters that have no  The following parameters have meaning in @acronym{MML}; parameters that have no
582  meaning are ignored.  The MML parameter names are the same as the  meaning are ignored.  The @acronym{MML} parameter names are the same as the
583  @sc{mime} parameter names; the things in the parentheses say which  @acronym{MIME} parameter names; the things in the parentheses say which
584  header it will be used in.  header it will be used in.
585    
586  @table @samp  @table @samp
587  @item type  @item type
588  The @sc{mime} type of the part (@samp{Content-Type}).  The @acronym{MIME} type of the part (@code{Content-Type}).
589    
590  @item filename  @item filename
591  Use the contents of the file in the body of the part  Use the contents of the file in the body of the part
592  (@samp{Content-Disposition}).  (@code{Content-Disposition}).
593    
594  @item charset  @item charset
595  The contents of the body of the part are to be encoded in the character  The contents of the body of the part are to be encoded in the character
596  set specified (@samp{Content-Type}).  set specified (@code{Content-Type}). @xref{Charset Translation}.
597    
598  @item name  @item name
599  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
600  to a file (@samp{Content-Type}).  to a file (@code{Content-Type}).
601    
602  @item disposition  @item disposition
603  Valid values are @samp{inline} and @samp{attachment}  Valid values are @samp{inline} and @samp{attachment}
604  (@samp{Content-Disposition}).  (@code{Content-Disposition}).
605    
606  @item encoding  @item encoding
607  Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and  Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
608  @samp{base64} (@samp{Content-Transfer-Encoding}).  @samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset
609    Translation}.
610    
611  @item description  @item description
612  A description of the part (@samp{Content-Description}).  A description of the part (@code{Content-Description}).
613    
614  @item creation-date  @item creation-date
615  RFC822 date when the part was created (@samp{Content-Disposition}).  RFC822 date when the part was created (@code{Content-Disposition}).
616    
617  @item modification-date  @item modification-date
618  RFC822 date when the part was modified (@samp{Content-Disposition}).  RFC822 date when the part was modified (@code{Content-Disposition}).
619    
620  @item read-date  @item read-date
621  RFC822 date when the part was read (@samp{Content-Disposition}).  RFC822 date when the part was read (@code{Content-Disposition}).
622    
623    @item recipients
624    Who to encrypt/sign the part to.  This field is used to override any
625    auto-detection based on the To/CC headers.
626    
627    @item sender
628    Identity used to sign the part.  This field is used to override the
629    default key used.
630    
631  @item size  @item size
632  The size (in octets) of the part (@samp{Content-Disposition}).  The size (in octets) of the part (@code{Content-Disposition}).
633    
634    @item sign
635    What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp}
636    or @code{pgpmime})
637    
638    @item encrypt
639    What technology to encrypt this @acronym{MML} part with (@code{smime},
640    @code{pgp} or @code{pgpmime})
641    
642  @end table  @end table
643    
644    Parameters for @samp{text/plain}:
645    
646    @table @samp
647    @item format
648    Formatting parameter for the text, valid values include @samp{fixed}
649    (the default) and @samp{flowed}.  Normally you do not specify this
650    manually, since it requires the textual body to be formatted in a
651    special way described in RFC 2646.  @xref{Flowed text}.
652    @end table
653    
654  Parameters for @samp{application/octet-stream}:  Parameters for @samp{application/octet-stream}:
655    
656  @table @samp  @table @samp
657  @item type  @item type
658  Type of the part; informal---meant for human readers  Type of the part; informal---meant for human readers
659  (@samp{Content-Type}).  (@code{Content-Type}).
660  @end table  @end table
661    
662  Parameters for @samp{message/external-body}:  Parameters for @samp{message/external-body}:
# Line 1133  Parameters for @samp{message/external-bo Line 665  Parameters for @samp{message/external-bo
665  @item access-type  @item access-type
666  A word indicating the supported access mechanism by which the file may  A word indicating the supported access mechanism by which the file may
667  be obtained.  Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},  be obtained.  Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
668  @samp{localfile}, and @samp{mailserver}.  (@samp{Content-Type}.)  @samp{localfile}, and @samp{mailserver}.  (@code{Content-Type}.)
669    
670  @item expiration  @item expiration
671  The RFC822 date after which the file may no longer be fetched.  The RFC822 date after which the file may no longer be fetched.
672  (@samp{Content-Type}.)  (@code{Content-Type}.)
673    
674  @item size  @item size
675  The size (in octets) of the file.  (@samp{Content-Type}.)  The size (in octets) of the file.  (@code{Content-Type}.)
676    
677  @item permission  @item permission
678  Valid values are @samp{read} and @samp{read-write}  Valid values are @samp{read} and @samp{read-write}
679  (@samp{Content-Type}).  (@code{Content-Type}).
680    
681    @end table
682    
683    Parameters for @samp{sign=smime}:
684    
685    @table @samp
686    
687    @item keyfile
688    File containing key and certificate for signer.
689    
690    @end table
691    
692    Parameters for @samp{encrypt=smime}:
693    
694    @table @samp
695    
696    @item certfile
697    File containing certificate for recipient.
698    
699  @end table  @end table
700    
# Line 1169  This plain text part is an attachment. Line 719  This plain text part is an attachment.
719  <#/multipart>  <#/multipart>
720  @end example  @end example
721    
722  And this is the resulting @sc{mime} message:  And this is the resulting @acronym{MIME} message:
723    
724  @example  @example
725  Content-Type: multipart/mixed; boundary="=-=-="  Content-Type: multipart/mixed; boundary="=-=-="
# Line 1235  This plain text part is an attachment. Line 785  This plain text part is an attachment.
785  --=-=-=--  --=-=-=--
786  @end example  @end example
787    
788    @node Encoding Customization
789    @section Encoding Customization
790    
791    @table @code
792    
793    @item mm-body-charset-encoding-alist
794    @vindex mm-body-charset-encoding-alist
795    Mapping from @acronym{MIME} charset to encoding to use.  This variable is
796    usually used except, e.g., when other requirements force a specific
797    encoding (digitally signed messages require 7bit encodings).  The
798    default is
799    
800    @lisp
801    ((iso-2022-jp . 7bit)
802     (iso-2022-jp-2 . 7bit)
803     (utf-16 . base64)
804     (utf-16be . base64)
805     (utf-16le . base64))
806    @end lisp
807    
808    As an example, if you do not want to have ISO-8859-1 characters
809    quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to
810    this variable.  You can override this setting on a per-message basis
811    by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}).
812    
813    @item mm-coding-system-priorities
814    @vindex mm-coding-system-priorities
815    Prioritize coding systems to use for outgoing messages.  The default
816    is @code{nil}, which means to use the defaults in Emacs.  It is a list of
817    coding system symbols (aliases of coding systems does not work, use
818    @kbd{M-x describe-coding-system} to make sure you are not specifying
819    an alias in this variable).  For example, if you have configured Emacs
820    to prefer UTF-8, but wish that outgoing messages should be sent in
821    ISO-8859-1 if possible, you can set this variable to
822    @code{(iso-latin-1)}.  You can override this setting on a per-message
823    basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}).
824    
825    @item mm-content-transfer-encoding-defaults
826    @vindex mm-content-transfer-encoding-defaults
827    Mapping from @acronym{MIME} types to encoding to use.  This variable is usually
828    used except, e.g., when other requirements force a safer encoding
829    (digitally signed messages require 7bit encoding).  Besides the normal
830    @acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for
831    each case the most efficient of quoted-printable and base64 should be
832    used.
833    
834    @code{qp-or-base64} has another effect.  It will fold long lines so that
835    MIME parts may not be broken by MTA.  So do @code{quoted-printable} and
836    @code{base64}.
837    
838    Note that it affects body encoding only when a part is a raw forwarded
839    message (which will be made by @code{gnus-summary-mail-forward} with the
840    arg 2 for example) or is neither the @samp{text/*} type nor the
841    @samp{message/*} type.  Even though in those cases, you can override
842    this setting on a per-message basis by using the @code{encoding}
843    @acronym{MML} tag (@pxref{MML Definition}).
844    
845    @item mm-use-ultra-safe-encoding
846    @vindex mm-use-ultra-safe-encoding
847    When this is non-@code{nil}, it means that textual parts are encoded as
848    quoted-printable if they contain lines longer than 76 characters or
849    starting with "From " in the body.  Non-7bit encodings (8bit, binary)
850    are generally disallowed.  This reduce the probability that a non-8bit
851    clean MTA or MDA changes the message.  This should never be set
852    directly, but bound by other functions when necessary (e.g., when
853    encoding messages that are to be digitally signed).
854    
855    @end table
856    
857  @node Charset Translation  @node Charset Translation
858  @section Charset Translation  @section Charset Translation
859  @cindex charsets  @cindex charsets
860    
861  During translation from MML to @sc{mime}, for each @sc{mime} part which  During translation from @acronym{MML} to @acronym{MIME}, for each
862  has been composed inside Emacs, an appropriate @sc{mime} charset has to  @acronym{MIME} part which has been composed inside Emacs, an appropriate
863  be chosen.  charset has to be chosen.
864    
865  @vindex mail-parse-charset  @vindex mail-parse-charset
866  @cindex unibyte Emacs  If you are running a non-@sc{mule} Emacs, this process is simple: If the
867  If you are running a non-Mule XEmacs, or Emacs in unibyte  part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset
 mode@footnote{Deprecated!}, this process is simple: if the part  
 contains any non-@sc{ascii} (8-bit) characters, the @sc{mime} charset  
868  given by @code{mail-parse-charset} (a symbol) is used.  (Never set this  given by @code{mail-parse-charset} (a symbol) is used.  (Never set this
869  variable directly, though.  If you want to change the default charset,  variable directly, though.  If you want to change the default charset,
870  please consult the documentation of the package which you use to process  please consult the documentation of the package which you use to process
871  @sc{mime} messages.  @xref{Various Message Variables, , Various Message  @acronym{MIME} messages.
872  Variables, message, Message Manual}, for example.)  If there are only  @xref{Various Message Variables, , Various Message Variables, message,
873  @sc{ascii} characters, the @sc{mime} charset @samp{US-ASCII} is used, of        Message Manual}, for example.)
874  course.  If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is
875    used, of course.
876  @cindex multibyte Emacs  
877  @cindex @code{mime-charset} property  @cindex MULE
878  In a normal (multibyte) Emacs session, a list of coding systems is  @cindex UTF-8
879  derived that can encode the message part's content and correspond to  @cindex Unicode
 MIME charsets (according to their @code{mime-charset} property).  This  
 list is according to the normal priority rules and the highest priority  
 one is chosen to encode the part.  If no such coding system can encode  
 the part's contents, they are split into several parts such that each  
 can be encoded with an appropriate coding system/@sc{mime}  
 charset.@footnote{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.}  Note that this  
 procedure works with any correctly-defined coding systems, not just  
 built-in ones.  Given a suitably-defined UTF-8 coding system---one  
 capable of encoding the Emacs charsets you use---it is not normally  
 necessary to split a part by charset.  
   
880  @vindex mm-mime-mule-charset-alist  @vindex mm-mime-mule-charset-alist
881  @cindex XEmacs/Mule  Things are slightly more complicated when running Emacs with @sc{mule}
882  It isn't possible to do this properly in XEmacs/Mule.  Instead, a list  support.  In this case, a list of the @sc{mule} charsets used in the
883  of the Mule charsets used in the part is obtained, and the  part is obtained, and the @sc{mule} charsets are translated to @acronym{MIME}
884  corresponding @sc{mime} charsets are determined by lookup in  charsets by consulting the variable @code{mm-mime-mule-charset-alist}.
885  @code{mm-mime-mule-charset-alist}.  If the list elements all  If this results in a single @acronym{MIME} charset, this is used to encode
886  correspond to a single @sc{mime} charset, that is used to encode the  the part.  But if the resulting list of @acronym{MIME} charsets contains more
887  part.  Otherwise, the part is split as above.  than one element, two things can happen: If it is possible to encode the
888    part via UTF-8, this charset is used.  (For this, Emacs must support
889    the @code{utf-8} coding system, and the part must consist entirely of
890    characters which have Unicode counterparts.)  If UTF-8 is not available
891    for some reason, the part is split into several ones, so that each one
892    can be encoded with a single @acronym{MIME} charset.  The part can only be
893    split at line boundaries, though---if more than one @acronym{MIME} charset is
894    required to encode a single line, it is not possible to encode the part.
895    
896    When running Emacs with @sc{mule} support, the preferences for which
897    coding system to use is inherited from Emacs itself.  This means that
898    if Emacs is set up to prefer UTF-8, it will be used when encoding
899    messages.  You can modify this by altering the
900    @code{mm-coding-system-priorities} variable though (@pxref{Encoding
901    Customization}).
902    
903    The charset to be used can be overridden by setting the @code{charset}
904    @acronym{MML} tag (@pxref{MML Definition}) when composing the message.
905    
906    The encoding of characters (quoted-printable, 8bit etc) is orthogonal
907    to the discussion here, and is controlled by the variables
908    @code{mm-body-charset-encoding-alist} and
909    @code{mm-content-transfer-encoding-defaults} (@pxref{Encoding
910    Customization}).
911    
912  @node Conversion  @node Conversion
913  @section Conversion  @section Conversion
914    
915  @findex mime-to-mml  @findex mime-to-mml
916  A (multipart) @sc{mime} message can be converted to MML with the  A (multipart) @acronym{MIME} message can be converted to @acronym{MML}
917  @code{mime-to-mml} function.  It works on the message in the current  with the @code{mime-to-mml} function.  It works on the message in the
918  buffer, and substitutes MML markup for @sc{mime} boundaries.  current buffer, and substitutes @acronym{MML} markup for @acronym{MIME}
919  Non-textual parts do not have their contents in the buffer, but instead  boundaries.  Non-textual parts do not have their contents in the buffer,
920  have the contents in separate buffers that are referred to from the MML  but instead have the contents in separate buffers that are referred to
921  tags.  from the @acronym{MML} tags.
922    
923  @findex mml-to-mime  @findex mml-to-mime
924  An MML message can be converted back to @sc{mime} by the  An @acronym{MML} message can be converted back to @acronym{MIME} by the
925  @code{mml-to-mime} function.  @code{mml-to-mime} function.
926    
927  These functions are in certain senses ``lossy''---you will not get back  These functions are in certain senses ``lossy''---you will not get back
928  an identical message if you run @sc{mime-to-mml} and then  an identical message if you run @code{mime-to-mml} and then
929  @sc{mml-to-mime}.  Not only will trivial things like the order of the  @code{mml-to-mime}.  Not only will trivial things like the order of the
930  headers differ, but the contents of the headers may also be different.  headers differ, but the contents of the headers may also be different.
931  For instance, the original message may use base64 encoding on text,  For instance, the original message may use base64 encoding on text,
932  while @sc{mml-to-mime} may decide to use quoted-printable encoding, and  while @code{mml-to-mime} may decide to use quoted-printable encoding, and
933  so on.  so on.
934    
935  In essence, however, these two functions should be the inverse of each  In essence, however, these two functions should be the inverse of each
# Line 1310  other.  The resulting contents of the me Line 937  other.  The resulting contents of the me
937  if not identical.  if not identical.
938    
939    
940    @node Flowed text
941    @section Flowed text
942    @cindex format=flowed
943    
944    The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines}
945    variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines,
946    emacs, Emacs Manual}) when encoding a message, and the
947    ``format=flowed'' Content-Type parameter when decoding a message.
948    
949    On encoding text, regardless of @code{use-hard-newlines}, lines
950    terminated by soft newline characters are filled together and wrapped
951    after the column decided by @code{fill-flowed-encode-column}.
952    Quotation marks (matching @samp{^>* ?}) are respected.  The variable
953    controls how the text will look in a client that does not support
954    flowed text, the default is to wrap after 66 characters.  If hard
955    newline characters are not present in the buffer, no flow encoding
956    occurs.
957    
958    On decoding flowed text, lines with soft newline characters are filled
959    together and wrapped after the column decided by
960    @code{fill-flowed-display-column}.  The default is to wrap after
961    @code{fill-column}.
962    
963    
964    
965    
966    @node Interface Functions
967    @chapter Interface Functions
968    @cindex interface functions
969    @cindex mail-parse
970    
971    The @code{mail-parse} library is an abstraction over the actual
972    low-level libraries that are described in the next chapter.
973    
974    Standards change, and so programs have to change to fit in the new
975    mold.  For instance, RFC2045 describes a syntax for the
976    @code{Content-Type} header that only allows @acronym{ASCII} characters in the
977    parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
978    for continuation headers and non-@acronym{ASCII} characters.
979    
980    The traditional way to deal with this is just to update the library
981    functions to parse the new syntax.  However, this is sometimes the wrong
982    thing to do.  In some instances it may be vital to be able to understand
983    both the old syntax as well as the new syntax, and if there is only one
984    library, one must choose between the old version of the library and the
985    new version of the library.
986    
987    The Emacs @acronym{MIME} library takes a different tack.  It defines a
988    series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el}
989    and so on) that parses strictly according to the corresponding
990    standard.  However, normal programs would not use the functions
991    provided by these libraries directly, but instead use the functions
992    provided by the @code{mail-parse} library.  The functions in this
993    library are just aliases to the corresponding functions in the latest
994    low-level libraries.  Using this scheme, programs get a consistent
995    interface they can use, and library developers are free to create
996    write code that handles new standards.
997    
998    The following functions are defined by this library:
999    
1000    @table @code
1001    @item mail-header-parse-content-type
1002    @findex mail-header-parse-content-type
1003    Parse a @code{Content-Type} header and return a list on the following
1004    format:
1005    
1006    @lisp
1007    ("type/subtype"
1008     (attribute1 . value1)
1009     (attribute2 . value2)
1010     ...)
1011    @end lisp
1012    
1013    Here's an example:
1014    
1015    @example
1016    (mail-header-parse-content-type
1017     "image/gif; name=\"b980912.gif\"")
1018    @result{} ("image/gif" (name . "b980912.gif"))
1019    @end example
1020    
1021    @item mail-header-parse-content-disposition
1022    @findex mail-header-parse-content-disposition
1023    Parse a @code{Content-Disposition} header and return a list on the same
1024    format as the function above.
1025    
1026    @item mail-content-type-get
1027    @findex mail-content-type-get
1028    Takes two parameters---a list on the format above, and an attribute.
1029    Returns the value of the attribute.
1030    
1031    @example
1032    (mail-content-type-get
1033     '("image/gif" (name . "b980912.gif")) 'name)
1034    @result{} "b980912.gif"
1035    @end example
1036    
1037    @item mail-header-encode-parameter
1038    @findex mail-header-encode-parameter
1039    Takes a parameter string and returns an encoded version of the string.
1040    This is used for parameters in headers like @code{Content-Type} and
1041    @code{Content-Disposition}.
1042    
1043    @item mail-header-remove-comments
1044    @findex mail-header-remove-comments
1045    Return a comment-free version of a header.
1046    
1047    @example
1048    (mail-header-remove-comments
1049     "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1050    @result{} "Gnus/5.070027  "
1051    @end example
1052    
1053    @item mail-header-remove-whitespace
1054    @findex mail-header-remove-whitespace
1055    Remove linear white space from a header.  Space inside quoted strings
1056    and comments is preserved.
1057    
1058    @example
1059    (mail-header-remove-whitespace
1060     "image/gif; name=\"Name with spaces\"")
1061    @result{} "image/gif;name=\"Name with spaces\""
1062    @end example
1063    
1064    @item mail-header-get-comment
1065    @findex mail-header-get-comment
1066    Return the last comment in a header.
1067    
1068    @example
1069    (mail-header-get-comment
1070     "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1071    @result{} "Finnish Landrace"
1072    @end example
1073    
1074    @item mail-header-parse-address
1075    @findex mail-header-parse-address
1076    Parse an address and return a list containing the mailbox and the
1077    plaintext name.
1078    
1079    @example
1080    (mail-header-parse-address
1081     "Hrvoje Niksic <hniksic@@srce.hr>")
1082    @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
1083    @end example
1084    
1085    @item mail-header-parse-addresses
1086    @findex mail-header-parse-addresses
1087    Parse a string with list of addresses and return a list of elements like
1088    the one described above.
1089    
1090    @example
1091    (mail-header-parse-addresses
1092     "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
1093    @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
1094         ("sb@@metis.no" . "Steinar Bang"))
1095    @end example
1096    
1097    @item mail-header-parse-date
1098    @findex mail-header-parse-date
1099    Parse a date string and return an Emacs time structure.
1100    
1101    @item mail-narrow-to-head
1102    @findex mail-narrow-to-head
1103    Narrow the buffer to the header section of the buffer.  Point is placed
1104    at the beginning of the narrowed buffer.
1105    
1106    @item mail-header-narrow-to-field
1107    @findex mail-header-narrow-to-field
1108    Narrow the buffer to the header under point.  Understands continuation
1109    headers.
1110    
1111    @item mail-header-fold-field
1112    @findex mail-header-fold-field
1113    Fold the header under point.
1114    
1115    @item mail-header-unfold-field
1116    @findex mail-header-unfold-field
1117    Unfold the header under point.
1118    
1119    @item mail-header-field-value
1120    @findex mail-header-field-value
1121    Return the value of the field under point.
1122    
1123    @item mail-encode-encoded-word-region
1124    @findex mail-encode-encoded-word-region
1125    Encode the non-@acronym{ASCII} words in the region.  For instance,
1126    @samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
1127    
1128    @item mail-encode-encoded-word-buffer
1129    @findex mail-encode-encoded-word-buffer
1130    Encode the non-@acronym{ASCII} words in the current buffer.  This function is
1131    meant to be called narrowed to the headers of a message.
1132    
1133    @item mail-encode-encoded-word-string
1134    @findex mail-encode-encoded-word-string
1135    Encode the words that need encoding in a string, and return the result.
1136    
1137    @example
1138    (mail-encode-encoded-word-string
1139     "This is naïve, baby")
1140    @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
1141    @end example
1142    
1143    @item mail-decode-encoded-word-region
1144    @findex mail-decode-encoded-word-region
1145    Decode the encoded words in the region.
1146    
1147    @item mail-decode-encoded-word-string
1148    @findex mail-decode-encoded-word-string
1149    Decode the encoded words in the string and return the result.
1150    
1151    @example
1152    (mail-decode-encoded-word-string
1153     "This is =?iso-8859-1?q?na=EFve,?= baby")
1154    @result{} "This is naïve, baby"
1155    @end example
1156    
1157    @end table
1158    
1159    Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
1160    @code{rfc2047}, @code{rfc2045} and @code{rfc2231}.  These are documented
1161    in the subsequent sections.
1162    
1163    
1164    
1165    @node Basic Functions
1166    @chapter Basic Functions
1167    
1168    This chapter describes the basic, ground-level functions for parsing and
1169    handling.  Covered here is parsing @code{From} lines, removing comments
1170    from header lines, decoding encoded words, parsing date headers and so
1171    on.  High-level functionality is dealt with in the next chapter
1172    (@pxref{Decoding and Viewing}).
1173    
1174    @menu
1175    * rfc2045::      Encoding @code{Content-Type} headers.
1176    * rfc2231::      Parsing @code{Content-Type} headers.
1177    * ietf-drums::   Handling mail headers defined by RFC822bis.
1178    * rfc2047::      En/decoding encoded words in headers.
1179    * time-date::    Functions for parsing dates and manipulating time.
1180    * qp::           Quoted-Printable en/decoding.
1181    * base64::       Base64 en/decoding.
1182    * binhex::       Binhex decoding.
1183    * uudecode::     Uuencode decoding.
1184    * yenc::         Yenc decoding.
1185    * rfc1843::      Decoding HZ-encoded text.
1186    * mailcap::      How parts are displayed is specified by the @file{.mailcap} file
1187    @end menu
1188    
1189    
1190    @node rfc2045
1191    @section rfc2045
1192    
1193    RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would
1194    imagine that there would be a lot to implement.  But there isn't, since
1195    most of the implementation details are delegated to the subsequent
1196    RFCs.
1197    
1198    So @file{rfc2045.el} has only a single function:
1199    
1200    @table @code
1201    @item rfc2045-encode-string
1202    @findex rfc2045-encode-string
1203    Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
1204    @var{value} will be quoted if there are non-safe characters in it.
1205    @end table
1206    
1207    
1208    @node rfc2231
1209    @section rfc2231
1210    
1211    RFC2231 defines a syntax for the @code{Content-Type} and
1212    @code{Content-Disposition} headers.  Its snappy name is @dfn{MIME
1213    Parameter Value and Encoded Word Extensions: Character Sets, Languages,
1214    and Continuations}.
1215    
1216    In short, these headers look something like this:
1217    
1218    @example
1219    Content-Type: application/x-stuff;
1220     title*0*=us-ascii'en'This%20is%20even%20more%20;
1221     title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1222     title*2="isn't it!"
1223    @end example
1224    
1225    They usually aren't this bad, though.
1226    
1227    The following functions are defined by this library:
1228    
1229    @table @code
1230    @item rfc2231-parse-string
1231    @findex rfc2231-parse-string
1232    Parse a @code{Content-Type} header and return a list describing its
1233    elements.
1234    
1235    @example
1236    (rfc2231-parse-string
1237     "application/x-stuff;
1238     title*0*=us-ascii'en'This%20is%20even%20more%20;
1239     title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1240     title*2=\"isn't it!\"")
1241    @result{} ("application/x-stuff"
1242        (title . "This is even more ***fun*** isn't it!"))
1243    @end example
1244    
1245    @item rfc2231-get-value
1246    @findex rfc2231-get-value
1247    Takes one of the lists on the format above and returns
1248    the value of the specified attribute.
1249    
1250    @item rfc2231-encode-string
1251    @findex rfc2231-encode-string
1252    Encode a parameter in headers likes @code{Content-Type} and
1253    @code{Content-Disposition}.
1254    
1255    @end table
1256    
1257    
1258    @node ietf-drums
1259    @section ietf-drums
1260    
1261    @dfn{drums} is an IETF working group that is working on the replacement
1262    for RFC822.
1263    
1264    The functions provided by this library include:
1265    
1266    @table @code
1267    @item ietf-drums-remove-comments
1268    @findex ietf-drums-remove-comments
1269    Remove the comments from the argument and return the results.
1270    
1271    @item ietf-drums-remove-whitespace
1272    @findex ietf-drums-remove-whitespace
1273    Remove linear white space from the string and return the results.
1274    Spaces inside quoted strings and comments are left untouched.
1275    
1276    @item ietf-drums-get-comment
1277    @findex ietf-drums-get-comment
1278    Return the last most comment from the string.
1279    
1280    @item ietf-drums-parse-address
1281    @findex ietf-drums-parse-address
1282    Parse an address string and return a list that contains the mailbox and
1283    the plain text name.
1284    
1285    @item ietf-drums-parse-addresses
1286    @findex ietf-drums-parse-addresses
1287    Parse a string that contains any number of comma-separated addresses and
1288    return a list that contains mailbox/plain text pairs.
1289    
1290    @item ietf-drums-parse-date
1291    @findex ietf-drums-parse-date
1292    Parse a date string and return an Emacs time structure.
1293    
1294    @item ietf-drums-narrow-to-header
1295    @findex ietf-drums-narrow-to-header
1296    Narrow the buffer to the header section of the current buffer.
1297    
1298    @end table
1299    
1300    
1301    @node rfc2047
1302    @section rfc2047
1303    
1304    RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how
1305    non-@acronym{ASCII} text in headers are to be encoded.  This is actually rather
1306    complicated, so a number of variables are necessary to tweak what this
1307    library does.
1308    
1309    The following variables are tweakable:
1310    
1311    @table @code
1312    @item rfc2047-header-encoding-alist
1313    @vindex rfc2047-header-encoding-alist
1314    This is an alist of header / encoding-type pairs.  Its main purpose is
1315    to prevent encoding of certain headers.
1316    
1317    The keys can either be header regexps, or @code{t}.
1318    
1319    The values can be @code{nil}, in which case the header(s) in question
1320    won't be encoded, @code{mime}, which means that they will be encoded, or
1321    @code{address-mime}, which means the header(s) will be encoded carefully
1322    assuming they contain addresses.
1323    
1324    @item rfc2047-charset-encoding-alist
1325    @vindex rfc2047-charset-encoding-alist
1326    RFC2047 specifies two forms of encoding---@code{Q} (a
1327    Quoted-Printable-like encoding) and @code{B} (base64).  This alist
1328    specifies which charset should use which encoding.
1329    
1330    @item rfc2047-encoding-function-alist
1331    @vindex rfc2047-encoding-function-alist
1332    This is an alist of encoding / function pairs.  The encodings are
1333    @code{Q}, @code{B} and @code{nil}.
1334    
1335    @item rfc2047-encoded-word-regexp
1336    @vindex rfc2047-encoded-word-regexp
1337    When decoding words, this library looks for matches to this regexp.
1338    
1339    @end table
1340    
1341    Those were the variables, and these are this functions:
1342    
1343    @table @code
1344    @item rfc2047-narrow-to-field
1345    @findex rfc2047-narrow-to-field
1346    Narrow the buffer to the header on the current line.
1347    
1348    @item rfc2047-encode-message-header
1349    @findex rfc2047-encode-message-header
1350    Should be called narrowed to the header of a message.  Encodes according
1351    to @code{rfc2047-header-encoding-alist}.
1352    
1353    @item rfc2047-encode-region
1354    @findex rfc2047-encode-region
1355    Encodes all encodable words in the region specified.
1356    
1357    @item rfc2047-encode-string
1358    @findex rfc2047-encode-string
1359    Encode a string and return the results.
1360    
1361    @item rfc2047-decode-region
1362    @findex rfc2047-decode-region
1363    Decode the encoded words in the region.
1364    
1365    @item rfc2047-decode-string
1366    @findex rfc2047-decode-string
1367    Decode a string and return the results.
1368    
1369    @end table
1370    
1371    
1372    @node time-date
1373    @section time-date
1374    
1375    While not really a part of the @acronym{MIME} library, it is convenient to
1376    document this library here.  It deals with parsing @code{Date} headers
1377    and manipulating time.  (Not by using tesseracts, though, I'm sorry to
1378    say.)
1379    
1380    These functions convert between five formats: A date string, an Emacs
1381    time structure, a decoded time list, a second number, and a day number.
1382    
1383    Here's a bunch of time/date/second/day examples:
1384    
1385    @example
1386    (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
1387    @result{} (54 21 12 12 9 1998 6 nil 7200)
1388    
1389    (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
1390    @result{} (13818 19266)
1391    
1392    (time-to-seconds '(13818 19266))
1393    @result{} 905595714.0
1394    
1395    (seconds-to-time 905595714.0)
1396    @result{} (13818 19266 0)
1397    
1398    (time-to-days '(13818 19266))
1399    @result{} 729644
1400    
1401    (days-to-time 729644)
1402    @result{} (961933 65536)
1403    
1404    (time-since '(13818 19266))
1405    @result{} (0 430)
1406    
1407    (time-less-p '(13818 19266) '(13818 19145))
1408    @result{} nil
1409    
1410    (subtract-time '(13818 19266) '(13818 19145))
1411    @result{} (0 121)
1412    
1413    (days-between "Sat Sep 12 12:21:54 1998 +0200"
1414                  "Sat Sep 07 12:21:54 1998 +0200")
1415    @result{} 5
1416    
1417    (date-leap-year-p 2000)
1418    @result{} t
1419    
1420    (time-to-day-in-year '(13818 19266))
1421    @result{} 255
1422    
1423    (time-to-number-of-days
1424     (time-since
1425      (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
1426    @result{} 4.146122685185185
1427    @end example
1428    
1429    And finally, we have @code{safe-date-to-time}, which does the same as
1430    @code{date-to-time}, but returns a zero time if the date is
1431    syntactically malformed.
1432    
1433    The five data representations used are the following:
1434    
1435    @table @var
1436    @item date
1437    An RFC822 (or similar) date string.  For instance: @code{"Sat Sep 12
1438    12:21:54 1998 +0200"}.
1439    
1440    @item time
1441    An internal Emacs time.  For instance: @code{(13818 26466)}.
1442    
1443    @item seconds
1444    A floating point representation of the internal Emacs time.  For
1445    instance: @code{905595714.0}.
1446    
1447    @item days
1448    An integer number representing the number of days since 00000101.  For
1449    instance: @code{729644}.
1450    
1451    @item decoded time
1452    A list of decoded time.  For instance: @code{(54 21 12 12 9 1998 6 t
1453    7200)}.
1454    @end table
1455    
1456    All the examples above represent the same moment.
1457    
1458    These are the functions available:
1459    
1460    @table @code
1461    @item date-to-time
1462    Take a date and return a time.
1463    
1464    @item time-to-seconds
1465    Take a time and return seconds.
1466    
1467    @item seconds-to-time
1468    Take seconds and return a time.
1469    
1470    @item time-to-days
1471    Take a time and return days.
1472    
1473    @item days-to-time
1474    Take days and return a time.
1475    
1476    @item date-to-day
1477    Take a date and return days.
1478    
1479    @item time-to-number-of-days
1480    Take a time and return the number of days that represents.
1481    
1482    @item safe-date-to-time
1483    Take a date and return a time.  If the date is not syntactically valid,
1484    return a ``zero'' date.
1485    
1486    @item time-less-p
1487    Take two times and say whether the first time is less (i. e., earlier)
1488    than the second time.
1489    
1490    @item time-since
1491    Take a time and return a time saying how long it was since that time.
1492    
1493    @item subtract-time
1494    Take two times and subtract the second from the first.  I. e., return
1495    the time between the two times.
1496    
1497    @item days-between
1498    Take two days and return the number of days between those two days.
1499    
1500    @item date-leap-year-p
1501    Take a year number and say whether it's a leap year.
1502    
1503    @item time-to-day-in-year
1504    Take a time and return the day number within the year that the time is
1505    in.
1506    
1507    @end table
1508    
1509    
1510    @node qp
1511    @section qp
1512    
1513    This library deals with decoding and encoding Quoted-Printable text.
1514    
1515    Very briefly explained, qp encoding means translating all 8-bit
1516    characters (and lots of control characters) into things that look like
1517    @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
1518    string.
1519    
1520    The following functions are defined by the library:
1521    
1522    @table @code
1523    @item quoted-printable-decode-region
1524    @findex quoted-printable-decode-region
1525    QP-decode all the encoded text in the specified region.
1526    
1527    @item quoted-printable-decode-string
1528    @findex quoted-printable-decode-string
1529    Decode the QP-encoded text in a string and return the results.
1530    
1531    @item quoted-printable-encode-region
1532    @findex quoted-printable-encode-region
1533    QP-encode all the encodable characters in the specified region.  The third
1534    optional parameter @var{fold} specifies whether to fold long lines.
1535    (Long here means 72.)
1536    
1537    @item quoted-printable-encode-string
1538    @findex quoted-printable-encode-string
1539    QP-encode all the encodable characters in a string and return the
1540    results.
1541    
1542    @end table
1543    
1544    
1545    @node base64
1546    @section base64
1547    @cindex base64
1548    
1549    Base64 is an encoding that encodes three bytes into four characters,
1550    thereby increasing the size by about 33%.  The alphabet used for
1551    encoding is very resistant to mangling during transit.
1552    
1553    The following functions are defined by this library:
1554    
1555    @table @code
1556    @item base64-encode-region
1557    @findex base64-encode-region
1558    base64 encode the selected region.  Return the length of the encoded
1559    text.  Optional third argument @var{no-line-break} means do not break
1560    long lines into shorter lines.
1561    
1562    @item base64-encode-string
1563    @findex base64-encode-string
1564    base64 encode a string and return the result.
1565    
1566    @item base64-decode-region
1567    @findex base64-decode-region
1568    base64 decode the selected region.  Return the length of the decoded
1569    text.  If the region can't be decoded, return @code{nil} and don't
1570    modify the buffer.
1571    
1572    @item base64-decode-string
1573    @findex base64-decode-string
1574    base64 decode a string and return the result.  If the string can't be
1575    decoded, @code{nil} is returned.
1576    
1577    @end table
1578    
1579    
1580    @node binhex
1581    @section binhex
1582    @cindex binhex
1583    @cindex Apple
1584    @cindex Macintosh
1585    
1586    @code{binhex} is an encoding that originated in Macintosh environments.
1587    The following function is supplied to deal with these:
1588    
1589    @table @code
1590    @item binhex-decode-region
1591    @findex binhex-decode-region
1592    Decode the encoded text in the region.  If given a third parameter, only
1593    decode the @code{binhex} header and return the filename.
1594    
1595    @end table
1596    
1597    @node uudecode
1598    @section uudecode
1599    @cindex uuencode
1600    @cindex uudecode
1601    
1602    @code{uuencode} is probably still the most popular encoding of binaries
1603    used on Usenet, although @code{base64} rules the mail world.
1604    
1605    The following function is supplied by this package:
1606    
1607    @table @code
1608    @item uudecode-decode-region
1609    @findex uudecode-decode-region
1610    Decode the text in the region.
1611    @end table
1612    
1613    
1614    @node yenc
1615    @section yenc
1616    @cindex yenc
1617    
1618    @code{yenc} is used for encoding binaries on Usenet.  The following
1619    function is supplied by this package:
1620    
1621    @table @code
1622    @item yenc-decode-region
1623    @findex yenc-decode-region
1624    Decode the encoded text in the region.
1625    
1626    @end table
1627    
1628    
1629    @node rfc1843
1630    @section rfc1843
1631    @cindex rfc1843
1632    @cindex HZ
1633    @cindex Chinese
1634    
1635    RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages.  In
1636    essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this:
1637    
1638    @example
1639    This sentence is in @acronym{ASCII}.
1640    The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
1641    @end example
1642    
1643    Simple enough, and widely used in China.
1644    
1645    The following functions are available to handle this encoding:
1646    
1647    @table @code
1648    @item rfc1843-decode-region
1649    Decode HZ-encoded text in the region.
1650    
1651    @item rfc1843-decode-string
1652    Decode a HZ-encoded string and return the result.
1653    
1654    @end table
1655    
1656    
1657    @node mailcap
1658    @section mailcap
1659    
1660    The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message
1661    handlers and describes how elements are supposed to be displayed.
1662    Here's an example file:
1663    
1664    @example
1665    image/*; gimp -8 %s
1666    audio/wav; wavplayer %s
1667    application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc
1668    @end example
1669    
1670    This says that all image files should be displayed with @code{gimp},
1671    that WAVE audio files should be played by @code{wavplayer}, and that
1672    MS-WORD files should be inlined by @code{catdoc}.
1673    
1674    The @code{mailcap} library parses this file, and provides functions for
1675    matching types.
1676    
1677    @table @code
1678    @item mailcap-mime-data
1679    @vindex mailcap-mime-data
1680    This variable is an alist of alists containing backup viewing rules.
1681    
1682    @end table
1683    
1684    Interface functions:
1685    
1686    @table @code
1687    @item mailcap-parse-mailcaps
1688    @findex mailcap-parse-mailcaps
1689    Parse the @file{~/.mailcap} file.
1690    
1691    @item mailcap-mime-info
1692    Takes a @acronym{MIME} type as its argument and returns the matching viewer.
1693    
1694    @end table
1695    
1696    
1697    
1698    
1699  @node Standards  @node Standards
1700  @chapter Standards  @chapter Standards
1701    
1702  The Emacs @sc{mime} library implements handling of various elements  The Emacs @acronym{MIME} library implements handling of various elements
1703  according to a (somewhat) large number of RFCs, drafts and standards  according to a (somewhat) large number of RFCs, drafts and standards
1704  documents.  This chapter lists the relevant ones.  They can all be  documents.  This chapter lists the relevant ones.  They can all be
1705  fetched from @samp{http://quimby.gnus.org/notes/}.  fetched from @uref{http://quimby.gnus.org/notes/}.
1706    
1707  @table @dfn  @table @dfn
1708  @item RFC822  @item RFC822
# Line 1326  Standard for the Format of ARPA Internet Line 1712  Standard for the Format of ARPA Internet
1712  @item RFC1036  @item RFC1036
1713  Standard for Interchange of USENET Messages  Standard for Interchange of USENET Messages
1714    
 @item RFC1524  
 A User Agent Configuration Mechanism For Multimedia Mail Format  
 Information  
   
1715  @item RFC2045  @item RFC2045
1716  Format of Internet Message Bodies  Format of Internet Message Bodies
1717    
# Line 1337  Format of Internet Message Bodies Line 1719  Format of Internet Message Bodies
1719  Media Types  Media Types
1720    
1721  @item RFC2047  @item RFC2047
1722  Message Header Extensions for Non-ASCII Text  Message Header Extensions for Non-@acronym{ASCII} Text
1723    
1724  @item RFC2048  @item RFC2048
1725  Registration Procedures  Registration Procedures
# Line 1346  Registration Procedures Line 1728  Registration Procedures
1728  Conformance Criteria and Examples  Conformance Criteria and Examples
1729    
1730  @item RFC2231  @item RFC2231
1731  MIME Parameter Value and Encoded Word Extensions: Character Sets,  @acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets,
1732  Languages, and Continuations  Languages, and Continuations
1733    
1734  @item RFC1843  @item RFC1843
1735  HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and  HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1736  ASCII characters  @acronym{ASCII} characters
1737    
1738  @item draft-ietf-drums-msg-fmt-05.txt  @item draft-ietf-drums-msg-fmt-05.txt
1739  Draft for the successor of RFC822  Draft for the successor of RFC822
1740    
1741  @item RFC2112  @item RFC2112
1742  The MIME Multipart/Related Content-type  The @acronym{MIME} Multipart/Related Content-type
1743    
1744  @item RFC1892  @item RFC1892
1745  The Multipart/Report Content Type for the Reporting of Mail System  The Multipart/Report Content Type for the Reporting of Mail System
# Line 1367  Administrative Messages Line 1749  Administrative Messages
1749  Communicating Presentation Information in Internet Messages: The  Communicating Presentation Information in Internet Messages: The
1750  Content-Disposition Header Field  Content-Disposition Header Field
1751    
1752    @item RFC2646
1753    Documentation of the text/plain format parameter for flowed text.
1754    
1755  @end table  @end table
1756    
1757    
1758  @node Index  @node Index
1759  @chapter Index  @chapter Index
1760  @printindex cp  @printindex cp
 @printindex fn  
1761    
1762  @summarycontents  @summarycontents
1763  @contents  @contents
1764  @bye  @bye
1765    
1766    
1767    @c Local Variables:
1768    @c mode: texinfo
1769    @c coding: iso-8859-1
1770  @c End:  @c End:
1771    
1772  @ignore  @ignore

Legend:
Removed from v.1.15.2.2  
changed lines
  Added in v.1.15.2.3

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26