X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=texi%2Femacs-mime.texi;h=a41377bbffb9cb7ddcdec36368d133063e9733e1;hb=0563df167689ba46e219f7915c6f5b321da614ce;hp=e40194a68cac40dc09e2005ab37a2035d38210dd;hpb=bfabb8c4d7752929d50386f84d264034b1e0b725;p=elisp%2Fgnus.git- diff --git a/texi/emacs-mime.texi b/texi/emacs-mime.texi index e40194a..a41377b 100644 --- a/texi/emacs-mime.texi +++ b/texi/emacs-mime.texi @@ -5,39 +5,38 @@ @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) 1998,99 Free Software Foundation, Inc. +Copyright (C) 1998, 1999, 2000 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,99 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 @@ -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 realaudio files should be played by @code{rvplayer}. The @code{mailcap} library parses this file, and provides functions for matching types. @@ -742,9 +823,11 @@ 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. +* Handles:: Handle manipulations. +* Display:: Displaying handles. +* Customization:: Variables that affect display. +* New Viewers:: How to write your own viewers. @end menu @@ -843,6 +926,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 @@ -863,6 +1041,7 @@ 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 @@ -966,6 +1145,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} or +@code{pgpmime}) + +@item encrypt +What technology to encrypt this MML part with (@code{smime} or +@code{pgpmime}) + @end table Parameters for @samp{application/octet-stream}: @@ -997,6 +1184,24 @@ 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 @@ -1084,6 +1289,43 @@ 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 @@ -1119,7 +1361,7 @@ if not identical. 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 @samp{http://quimby.gnus.org/notes/}. @table @dfn @item RFC822