X-Git-Url: http://cgit.sxemacs.org/?a=blobdiff_plain;f=texi%2Femacs-mime.texi;h=ee8af04a0164adffab058ab368de4bfab38ae34a;hb=148c7162ca8004574c3c9c798e94735f234eecfe;hp=916878d2c3e30d8c165895af6057adad99ed5c88;hpb=349d090fc583e68873040e5fae72a5093127f4f4;p=gnus diff --git a/texi/emacs-mime.texi b/texi/emacs-mime.texi index 916878d2c..ee8af04a0 100644 --- a/texi/emacs-mime.texi +++ b/texi/emacs-mime.texi @@ -1,43 +1,42 @@ -\input texinfo @c -*-texinfo-*- +\input texinfo @c -*-texinfo-*- -*- coding: iso-latin-1 -*- @setfilename emacs-mime @settitle Emacs MIME Manual @synindex fn cp @synindex vr cp @synindex pg cp -@c @direntry -@c * Emacs MIME: (emacs-mime). The MIME de/composition library. -@c @end direntry +@dircategory Emacs +@direntry +* Emacs MIME: (emacs-mime). The MIME de/composition library. +@end direntry @iftex @finalout @end iftex @setchapternewpage odd -@ifinfo +@ifnottex This file documents the Emacs MIME interface functionality. -Copyright (C) 1996 Free Software Foundation, Inc. +Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc. -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. -@ignore -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end ifinfo +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end ifnottex @tex @@ -48,20 +47,24 @@ into another language, under the above conditions for modified versions. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1998 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. - +Copyright @copyright{} 1998, 1999, 2000 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being none, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. @end titlepage @page @@ -198,9 +201,9 @@ and comments is preserved. Return the last comment in a header. @example -(mail-header-get-comment +(mail-header-get-comment "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") -@result{} "Finnish Landrace" +@result{} "Finnish Landrace" @end example @item mail-header-parse-address @@ -276,8 +279,8 @@ Decode the encoded words in the string and return the result. @end table Currently, @code{mail-parse} is an abstraction over @code{ietf-drums}, -@code{rfc2047} and @code{rfc2231}. These are documented in the -subsequent sections. +@code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented +in the subsequent sections. @@ -352,7 +355,7 @@ elements. @example (rfc2231-parse-string - "application/x-stuff; + "application/x-stuff; title*0*=us-ascii'en'This%20is%20even%20more%20; title*1*=%2A%2A%2Afun%2A%2A%2A%20; title*2=\"isn't it!\"") @@ -368,7 +371,7 @@ the value of the specified attribute. @item rfc2231-encode-string @findex rfc2231-encode-string Encode a parameter in headers likes @code{Content-Type} and -@code{Content-Disposition}. +@code{Content-Disposition}. @end table @@ -459,11 +462,11 @@ This is an alist of encoding / function pairs. The encodings are The @code{Q} encoding isn't quite the same for all headers. Some headers allow a narrower range of characters, and that is what this variable is for. It's an alist of header regexps / allowable character -ranges. +ranges. @item rfc2047-encoded-word-regexp @vindex rfc2047-encoded-word-regexp -When decoding words, this library looks for matches to this regexp. +When decoding words, this library looks for matches to this regexp. @end table @@ -509,8 +512,7 @@ say.) These functions convert between five formats: A date string, an Emacs time structure, a decoded time list, a second number, and a day number. -The functions have quite self-explanatory names, so the following just -gives an overview of which functions are available. +Here's a bunch of time/date/second/day examples: @example (parse-time-string "Sat Sep 12 12:21:54 1998 +0200") @@ -525,7 +527,7 @@ gives an overview of which functions are available. (seconds-to-time 905595714.0) @result{} (13818 19266 0) -(time-to-day '(13818 19266)) +(time-to-days '(13818 19266)) @result{} 729644 (days-to-time 729644) @@ -550,12 +552,91 @@ gives an overview of which functions are available. (time-to-day-in-year '(13818 19266)) @result{} 255 +(time-to-number-of-days + (time-since + (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) +@result{} 4.146122685185185 @end example And finally, we have @code{safe-date-to-time}, which does the same as @code{date-to-time}, but returns a zero time if the date is syntactically malformed. +The five data representations used are the following: + +@table @var +@item date +An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 +12:21:54 1998 +0200"}. + +@item time +An internal Emacs time. For instance: @code{(13818 26466)}. + +@item seconds +A floating point representation of the internal Emacs time. For +instance: @code{905595714.0}. + +@item days +An integer number representing the number of days since 00000101. For +instance: @code{729644}. + +@item decoded time +A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t +7200)}. +@end table + +All the examples above represent the same moment. + +These are the functions available: + +@table @code +@item date-to-time +Take a date and return a time. + +@item time-to-seconds +Take a time and return seconds. + +@item seconds-to-time +Take seconds and return a time. + +@item time-to-days +Take a time and return days. + +@item days-to-time +Take days and return a time. + +@item date-to-day +Take a date and return days. + +@item time-to-number-of-days +Take a time and return the number of days that represents. + +@item safe-date-to-time +Take a date and return a time. If the date is not syntactically valid, +return a "zero" date. + +@item time-less-p +Take two times and say whether the first time is less (i. e., earlier) +than the second time. + +@item time-since +Take a time and return a time saying how long it was since that time. + +@item subtract-time +Take two times and subtract the second from the first. I. e., return +the time between the two times. + +@item days-between +Take two days and return the number of days between those two days. + +@item date-leap-year-p +Take a year number and say whether it's a leap year. + +@item time-to-day-in-year +Take a time and return the day number within the year that the time is +in. + +@end table @node qp @@ -703,8 +784,8 @@ image/*; gimp -8 %s audio/wav; wavplayer %s @end example -This says that all image files should be displayed with @samp{xv}, and -that realaudio files should be played by @samp{rvplayer}. +This says that all image files should be displayed with @code{gimp}, and +that WAVE audio files should be played by @code{wavplayer}. The @code{mailcap} library parses this file, and provides functions for matching types. @@ -742,9 +823,12 @@ other programs to do things based on the list of @dfn{handles} that are returned as a result of this analysis. @menu -* Dissection:: Analyzing a @sc{mime} message. -* Handles:: Handle manipulations. -* Display:: Displaying handles. +* Dissection:: Analyzing a @sc{mime} message. +* Non-MIME:: Analyzing a non-@sc{mime} message. +* Handles:: Handle manipulations. +* Display:: Displaying handles. +* Customization:: Variables that affect display. +* New Viewers:: How to write your own viewers. @end menu @@ -756,6 +840,62 @@ a @sc{mime} article. If given a multipart message, it will recursively descend the message, following the structure, and return a tree of @sc{mime} handles that describes the structure of the message. +@node Non-MIME +@section Non-MIME + +Gnus also understands some non-MIME attachments, such as postscript, +uuencode, binhex, shar, forward, gnatsweb, pgp. Each of these features +can be disabled by add an item into @code{mm-uu-configure-list}. +For example, + +@lisp +(require 'mm-uu) +(add-to-list 'mm-uu-configure-list '(pgp-signed . disabled)) +@end lisp + +@table @code +@item postscript +@findex postscript +Postscript file. + +@item uu +@findex uu +Uuencoded file. + +@item binhex +@findex binhex +Binhex encoded file. + +@item shar +@findex shar +Shar archive file. + +@item forward +@findex forward +Non-@sc{mime} forwarded message. + +@item gnatsweb +@findex gnatsweb +Gnatsweb attachment. + +@item pgp-signed +@findex pgp-signed +PGP signed clear text. + +@item pgp-encrypted +@findex pgp-encrypted +PGP encrypted clear text. + +@item pgp-key +@findex pgp-key +PGP public keys. + +@item emacs-sources +@findex emacs-sources +Emacs source code. This item works only in the groups matching +@code{mm-uu-emacs-sources-regexp}. + +@end table @node Handles @section Handles @@ -843,6 +983,101 @@ Prompt for a mailcap method to use to view the part. @end table +@node Customization +@section Customization + +@table @code + +@item mm-inline-media-tests +This is an alist where the key is a @sc{mime} type, the second element +is a function to display the part @dfn{inline} (i.e., inside Emacs), and +the third element is a form to be @code{eval}ed to say whether the part +can be displayed inline. + +This variable specifies whether a part @emph{can} be displayed inline, +and, if so, how to do it. It does not say whether parts are +@emph{actually} displayed inline. + +@item mm-inlined-types +This, on the other hand, says what types are to be displayed inline, if +they satisfy the conditions set by the variable above. It's a list of +@sc{mime} media types. + +@item mm-automatic-display +This is a list of types that are to be displayed ``automatically'', but +only if the above variable allows it. That is, only inlinable parts can +be displayed automatically. + +@item mm-attachment-override-types +Some @sc{mime} agents create parts that have a content-disposition of +@samp{attachment}. This variable allows overriding that disposition and +displaying the part inline. (Note that the disposition is only +overridden if we are able to, and want to, display the part inline.) + +@item mm-discouraged-alternatives +List of @sc{mime} types that are discouraged when viewing +@samp{multipart/alternative}. Viewing agents are supposed to view the +last possible part of a message, as that is supposed to be the richest. +However, users may prefer other types instead, and this list says what +types are most unwanted. If, for instance, @samp{text/html} parts are +very unwanted, and @samp{text/richtech} parts are somewhat unwanted, +then the value of this variable should be set to: + +@lisp +("text/html" "text/richtext") +@end lisp + +@item mm-inline-large-images-p +When displaying inline images that are larger than the window, XEmacs +does not enable scrolling, which means that you cannot see the whole +image. To prevent this, the library tries to determine the image size +before displaying it inline, and if it doesn't fit the window, the +library will display it externally (e.g. with @samp{ImageMagick} or +@samp{xv}). Setting this variable to @code{t} disables this check and +makes the library display all inline images as inline, regardless of +their size. + +@item mm-inline-override-p +@code{mm-inlined-types} may include regular expressions, for example to +specify that all @samp{text/.*} parts be displayed inline. If a user +prefers to have a type that matches such a regular expression be treated +as an attachment, that can be accomplished by setting this variable to a +list containing that type. For example assuming @code{mm-inlined-types} +includes @samp{text/.*}, then including @samp{text/html} in this +variable will cause @samp{text/html} parts to be treated as attachments. + +@end table + + +@node New Viewers +@section New Viewers + +Here's an example viewer for displaying @code{text/enriched} inline: + +@lisp +(defun mm-display-enriched-inline (handle) + (let (text) + (with-temp-buffer + (mm-insert-part handle) + (save-window-excursion + (enriched-decode (point-min) (point-max)) + (setq text (buffer-string)))) + (mm-insert-inline handle text))) +@end lisp + +We see that the function takes a @sc{mime} handle as its parameter. It +then goes to a temporary buffer, inserts the text of the part, does some +work on the text, stores the result, goes back to the buffer it was +called from and inserts the result. + +The two important helper functions here are @code{mm-insert-part} and +@code{mm-insert-inline}. The first function inserts the text of the +handle in the current buffer. It handles charset and/or content +transfer decoding. The second function just inserts whatever text you +tell it to insert, but it also sets things up so that the text can be +``undisplayed' in a convenient manner. + + @node Composing @chapter Composing @cindex Composing @@ -851,7 +1086,7 @@ Prompt for a mailcap method to use to view the part. @cindex MIME Meta Language Creating a @sc{mime} message is boring and non-trivial. Therefore, a -library called @code{mml} has been defined that parses a language called +library called @code{mml} has been defined that parses a language called MML (@sc{mime} Meta Language) and generates @sc{mime} messages. @findex mml-generate-mime @@ -863,6 +1098,8 @@ string containing the @sc{mime} message. * Simple MML Example:: An example MML document. * MML Definition:: All valid MML elements. * Advanced MML Example:: Another example MML document. +* Charset Translation:: How charsets are mapped from @sc{mule} to MIME. +* Conversion:: Going from @sc{mime} to MML and vice versa. @end menu @@ -939,7 +1176,7 @@ The contents of the body of the part are to be encoded in the character set speficied (@code{Content-Type}). @item name -Might be used to suggest a file name if the part is to be saved +Might be used to suggest a file name if the part is to be saved to a file (@code{Content-Type}). @item disposition @@ -965,6 +1202,14 @@ RFC822 date when the part was read (@code{Content-Disposition}). @item size The size (in octets) of the part (@code{Content-Disposition}). +@item sign +What technology to sign this MML part with (@code{smime}, @code{pgp} +or @code{pgpmime}) + +@item encrypt +What technology to encrypt this MML part with (@code{smime}, +@code{pgp} or @code{pgpmime}) + @end table Parameters for @samp{application/octet-stream}: @@ -996,12 +1241,30 @@ Valid values are @samp{read} and @samp{read-write} @end table +Parameters for @samp{sign=smime}: + +@table @samp + +@item keyfile +File containing key and certificate for signer. + +@end table + +Parameters for @samp{encrypt=smime}: + +@table @samp + +@item certfile +File containing certificate for recipient. + +@end table + @node Advanced MML Example @section Advanced MML Example Here's a complex multipart message. It's a @samp{multipart/mixed} that -contains many parts, one of which is a @samp{multipart/alternative}. +contains many parts, one of which is a @samp{multipart/alternative}. @example <#multipart type=mixed> @@ -1083,6 +1346,70 @@ This plain text part is an attachment. --=-=-=-- @end example +@node Charset Translation +@section Charset Translation +@cindex charsets + +During translation from MML to @sc{mime}, for each @sc{mime} part which +has been composed inside Emacs, an appropriate charset has to be chosen. + +@vindex mail-parse-charset +If you are running a non-@sc{mule} Emacs, this process is simple: If the +part contains any non-ASCII (8-bit) characters, the @sc{mime} charset +given by @code{mail-parse-charset} (a symbol) is used. (Never set this +variable directly, though. If you want to change the default charset, +please consult the documentation of the package which you use to process +@sc{mime} messages. +@xref{Various Message Variables, , Various Message Variables, message, + Message Manual}, for example.) +If there are only ASCII characters, the @sc{mime} charset US-ASCII is +used, of course. + +@cindex MULE +@cindex UTF-8 +@cindex Unicode +@vindex mm-mime-mule-charset-alist +Things are slightly more complicated when running Emacs with @sc{mule} +support. In this case, a list of the @sc{mule} charsets used in the +part is obtained, and the @sc{mule} charsets are translated to @sc{mime} +charsets by consulting the variable @code{mm-mime-mule-charset-alist}. +If this results in a single @sc{mime} charset, this is used to encode +the part. But if the resulting list of @sc{mime} charsets contains more +than one element, two things can happen: If it is possible to encode the +part via UTF-8, this charset is used. (For this, Emacs must support +the @code{utf-8} coding system, and the part must consist entirely of +characters which have Unicode counterparts.) If UTF-8 is not available +for some reason, the part is split into several ones, so that each one +can be encoded with a single @sc{mime} charset. The part can only be +split at line boundaries, though---if more than one @sc{mime} charset is +required to encode a single line, it is not possible to encode the part. + +@node Conversion +@section Conversion + +@findex mime-to-mml +A (multipart) @sc{mime} message can be converted to MML with the +@code{mime-to-mml} function. It works on the message in the current +buffer, and substitutes MML markup for @sc{mime} boundaries. +Non-textual parts do not have their contents in the buffer, but instead +have the contents in separate buffers that are referred to from the MML +tags. + +@findex mml-to-mime +An MML message can be converted back to @sc{mime} by the +@code{mml-to-mime} function. + +These functions are in certain senses ``lossy''---you will not get back +an identical message if you run @sc{mime-to-mml} and then +@sc{mml-to-mime}. Not only will trivial things like the order of the +headers differ, but the contents of the headers may also be different. +For instance, the original message may use base64 encoding on text, +while @sc{mml-to-mime} may decide to use quoted-printable encoding, and +so on. + +In essence, however, these two functions should be the inverse of each +other. The resulting contents of the message should remain equivalent, +if not identical. @node Standards @@ -1091,7 +1418,7 @@ This plain text part is an attachment. The Emacs @sc{mime} library implements handling of various elements according to a (somewhat) large number of RFCs, drafts and standards documents. This chapter lists the relevant ones. They can all be -fetched from @samp{http://www.stud.ifi.uio.no/~larsi/notes/}. +fetched from @uref{http://quimby.gnus.org/notes/}. @table @dfn @item RFC822 @@ -1139,8 +1466,8 @@ Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field @end table - - + + @node Index @chapter Index @printindex cp