X-Git-Url: http://cgit.sxemacs.org/?a=blobdiff_plain;f=texi%2Femacs-mime.texi;h=ee60af9d168e0b461e1dd086f475854448e69e97;hb=274bb9d9277463d040ae2a3c24cef2fb68b4cd02;hp=97c707406a52deb84bd6793cddebf0465e560e02;hpb=80fad32731c174666ecfa2586dbb670e090d3db2;p=gnus diff --git a/texi/emacs-mime.texi b/texi/emacs-mime.texi index 97c707406..ee60af9d1 100644 --- a/texi/emacs-mime.texi +++ b/texi/emacs-mime.texi @@ -5,73 +5,49 @@ @synindex fn cp @synindex vr cp @synindex pg cp -@dircategory Emacs -@direntry -* Emacs MIME: (emacs-mime). The MIME de/composition library. -@end direntry -@documentencoding ISO-8859-1 -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@ifnottex +@copying This file documents the Emacs MIME interface functionality. -Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 - Free Software Foundation, Inc. +Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, +2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. +@quotation Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify -this GNU Manual, like GNU software. Copies published by the Free -Software Foundation raise funds for GNU development.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end ifnottex +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''. -@tex +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' +@end quotation +@end copying + +@c Node ``Interface Functions'' uses Latin-1 characters +@documentencoding ISO-8859-1 + +@dircategory Emacs +@direntry +* Emacs MIME: (emacs-mime). Emacs MIME de/composition library. +@end direntry +@iftex +@finalout +@end iftex +@setchapternewpage odd @titlepage @title Emacs MIME Manual @author by Lars Magne Ingebrigtsen @page - @vskip 0pt plus 1filll -Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003 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. +@insertcopying @end titlepage -@page -@end tex +@contents @node Top @top Emacs MIME @@ -79,7 +55,7 @@ license to the document, as described in section 6 of the license. This manual documents the libraries used to compose and display @acronym{MIME} messages. -This manual is directed at users who want to modify the behaviour of +This manual is directed at users who want to modify the behavior of the @acronym{MIME} encoding/decoding process or want a more detailed picture of how the Emacs @acronym{MIME} library works, and people who want to write functions and commands that manipulate @acronym{MIME} elements. @@ -92,12 +68,17 @@ Procedures), RFC2049 (Conformance Criteria and Examples). It is highly recommended that anyone who intends writing @acronym{MIME}-compliant software read at least RFC2045 and RFC2047. +@ifnottex +@insertcopying +@end ifnottex + @menu * Decoding and Viewing:: A framework for decoding and viewing. * Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts. * Interface Functions:: An abstraction over the basic functions. * Basic Functions:: Utility and basic parsing functions. * Standards:: A summary of RFCs and working documents used. +* GNU Free Documentation License:: The license for this documentation. * Index:: Function and variable index. @end menu @@ -148,7 +129,7 @@ diff. Each of these features can be disabled by add an item into @table @code @item postscript @findex postscript -Postscript file. +PostScript file. @item uu @findex uu @@ -199,8 +180,27 @@ Patches. This is intended for groups where diffs of committed files are automatically sent to. It only works in groups matching @code{mm-uu-diff-groups-regexp}. +@item verbatim-marks +@cindex verbatim-marks +Slrn-style verbatim marks. + +@item LaTeX +@cindex LaTeX +LaTeX documents. It only works in groups matching +@code{mm-uu-tex-groups-regexp}. + @end table +@cindex text/x-verbatim +@c Is @vindex suitable for a face? +@vindex mm-uu-extract +Some inlined non-@acronym{MIME} attachments are displayed using the face +@code{mm-uu-extract}. By default, no @acronym{MIME} button for these +parts is displayed. You can force displaying a button using @kbd{K b} +(@code{gnus-summary-display-buttonized}) or add @code{text/x-verbatim} +to @code{gnus-buttonized-mime-types}, @xref{MIME Commands, ,MIME +Commands, gnus, Gnus Manual}. + @node Handles @section Handles @@ -236,10 +236,6 @@ Set the undisplayer object. @findex mm-handle-disposition Return the parsed @code{Content-Disposition} of the part. -@item mm-handle-disposition -@findex mm-handle-disposition -Return the description of the part. - @item mm-get-content-id Returns the handle(s) referred to by @code{Content-ID}. @@ -349,16 +345,47 @@ you could say something like: (remove "text/html" mm-automatic-display)) @end lisp +Adding @code{"image/.*"} might also be useful. Spammers use images as +the preferred part of @samp{multipart/alternative} messages, so you might +not notice there are other parts. See also +@code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands, +gnus, Gnus Manual}. After adding @code{"multipart/alternative"} to +@code{gnus-buttonized-mime-types} you can choose manually which +alternative you'd like to view. For example, you can set those +variables like: + +@lisp +(setq gnus-buttonized-mime-types + '("multipart/alternative" "multipart/signed") + mm-discouraged-alternatives + '("text/html" "image/.*")) +@end lisp + +In this case, Gnus will display radio buttons for such a kind of spam +message as follows: + +@example +1. (*) multipart/alternative ( ) image/gif + +2. (*) text/plain ( ) text/html +@end example + @item mm-inline-large-images @vindex mm-inline-large-images -When displaying inline images that are larger than the window, XEmacs +When displaying inline images that are larger than the window, Emacs does not enable scrolling, which means that you cannot see the whole -image. To prevent this, the library tries to determine the image size +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 +@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. +their size. If you set this variable to @code{resize}, the image will +be displayed resized to fit in the window, if Emacs has the ability to +resize images. + +@item mm-inline-large-images-proportion +@vindex mm-inline-images-max-proportion +The proportion used when resizing large images. @item mm-inline-override-types @vindex mm-inline-override-types @@ -373,7 +400,7 @@ variable will cause @samp{text/html} parts to be treated as attachments. @item mm-text-html-renderer @vindex mm-text-html-renderer This selects the function used to render @acronym{HTML}. The predefined -renderers are selected by the symbols @code{w3}, +renderers are selected by the symbols @code{gnus-article-html}, @code{w3}, @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more information about emacs-w3m}, @code{links}, @code{lynx}, @code{w3m-standalone} or @code{html2text}. If @code{nil} use an @@ -397,7 +424,9 @@ or @kbd{I} instead.} A regular expression that matches safe URL names, i.e. URLs that are unlikely to leak personal information when rendering @acronym{HTML} email (the default value is @samp{\\`cid:}). If @code{nil} consider -all URLs safe. +all URLs safe. In Gnus, this will be overridden according to the value +of the variable @code{gnus-safe-html-newsgroups}, @xref{Various +Various, ,Various Various, gnus, Gnus Manual}. @item mm-inline-text-html-with-w3m-keymap @vindex mm-inline-text-html-with-w3m-keymap @@ -818,7 +847,7 @@ This plain text part is an attachment. Mapping from @acronym{MIME} charset to encoding to use. This variable is usually used except, e.g., when other requirements force a specific encoding (digitally signed messages require 7bit encodings). The -default is +default is @lisp ((iso-2022-jp . 7bit) @@ -836,7 +865,9 @@ by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}). @item mm-coding-system-priorities @vindex mm-coding-system-priorities Prioritize coding systems to use for outgoing messages. The default -is @code{nil}, which means to use the defaults in Emacs. It is a list of +is @code{nil}, which means to use the defaults in Emacs, but is +@code{(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8)} when +running Emacs in the Japanese language environment. It is a list of coding system symbols (aliases of coding systems are also allowed, use @kbd{M-x describe-coding-system} to make sure you are specifying correct coding system names). For example, if you have configured Emacs @@ -845,6 +876,36 @@ ISO-8859-1 if possible, you can set this variable to @code{(iso-8859-1)}. You can override this setting on a per-message basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}). +As different hierarchies prefer different charsets, you may want to set +@code{mm-coding-system-priorities} according to the hierarchy in Gnus. +Here's an example: + +@c Corrections about preferred charsets are welcome. de, fr and fj +@c should be correct, I don't know about the rest (so these are only +@c examples): +@lisp +(add-to-list 'gnus-newsgroup-variables 'mm-coding-system-priorities) +(setq gnus-parameters + (nconc + ;; Some charsets are just examples! + '(("^cn\\." ;; Chinese + (mm-coding-system-priorities + '(iso-8859-1 cn-big5 chinese-iso-7bit utf-8))) + ("^cz\\.\\|^pl\\." ;; Central and Eastern European + (mm-coding-system-priorities '(iso-8859-2 utf-8))) + ("^de\\." ;; German language + (mm-coding-system-priorities '(iso-8859-1 iso-8859-15 utf-8))) + ("^fr\\." ;; French + (mm-coding-system-priorities '(iso-8859-15 iso-8859-1 utf-8))) + ("^fj\\." ;; Japanese + (mm-coding-system-priorities + '(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8))) + ("^ru\\." ;; Cyrillic + (mm-coding-system-priorities + '(koi8-r iso-8859-5 iso-8859-1 utf-8)))) + gnus-parameters)) +@end lisp + @item mm-content-transfer-encoding-defaults @vindex mm-content-transfer-encoding-defaults Mapping from @acronym{MIME} types to encoding to use. This variable is usually @@ -903,8 +964,9 @@ used, of course. @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 @acronym{MIME} -charsets by consulting the variable @code{mm-mime-mule-charset-alist}. +part is obtained, and the @sc{mule} charsets are translated to +@acronym{MIME} charsets by consulting the table provided by Emacs itself +or the variable @code{mm-mime-mule-charset-alist} for XEmacs. If this results in a single @acronym{MIME} charset, this is used to encode the part. But if the resulting list of @acronym{MIME} charsets contains more than one element, two things can happen: If it is possible to encode the @@ -1195,7 +1257,7 @@ in the subsequent sections. 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 +on. High-level functionality is dealt with in the first chapter (@pxref{Decoding and Viewing}). @menu @@ -1363,10 +1425,23 @@ This is an alist of encoding / function pairs. The encodings are @vindex rfc2047-encoded-word-regexp When decoding words, this library looks for matches to this regexp. +@item rfc2047-encoded-word-regexp-loose +@vindex rfc2047-encoded-word-regexp-loose +This is a version from which the regexp for the Q encoding pattern of +@code{rfc2047-encoded-word-regexp} is made loose. + @item rfc2047-encode-encoded-words @vindex rfc2047-encode-encoded-words The boolean variable specifies whether encoded words -(e.g. @samp{=?hello?=}) should be encoded again. +(e.g. @samp{=?us-ascii?q?hello?=}) should be encoded again. +@code{rfc2047-encoded-word-regexp} is used to look for such words. + +@item rfc2047-allow-irregular-q-encoded-words +@vindex rfc2047-allow-irregular-q-encoded-words +The boolean variable specifies whether irregular Q encoded words +(e.g. @samp{=?us-ascii?q?hello??=}) should be decoded. If it is +non-@code{nil}, @code{rfc2047-encoded-word-regexp-loose} is used instead +of @code{rfc2047-encoded-word-regexp} to look for encoded words. @end table @@ -1400,21 +1475,9 @@ Decode a string and return the results. @item rfc2047-encode-parameter @findex rfc2047-encode-parameter -Encode a parameter in the RFC2047-like style. This is a replacement for -the @code{rfc2231-encode-string} function. @xref{rfc2231}. - -When attaching files as @acronym{MIME} parts, we should use the RFC2231 -encoding to specify the file names containing non-@acronym{ASCII} -characters. However, many mail softwares don't support it in practice -and recipients won't be able to extract files with correct names. -Instead, the RFC2047-like encoding is acceptable generally. This -function provides the very RFC2047-like encoding, resigning to such a -regrettable trend. To use it, put the following line in your -@file{~/.gnus.el} file: - -@lisp -(defalias 'mail-header-encode-parameter 'rfc2047-encode-parameter) -@end lisp +Encode a parameter in the RFC2047-like style. This is a substitution +for the @code{rfc2231-encode-string} function, that is the standard but +many mailers don't support it. @xref{rfc2231}. @end table @@ -1512,7 +1575,8 @@ These are the functions available: Take a date and return a time. @item time-to-seconds -Take a time and return seconds. +Take a time and return seconds. Note that Emacs has a built-in +function, @code{float-time}, that does this. @item seconds-to-time Take seconds and return a time. @@ -1531,7 +1595,7 @@ 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. +return a ``zero'' time. @item time-less-p Take two times and say whether the first time is less (i. e., earlier) @@ -1804,13 +1868,14 @@ Documentation of the text/plain format parameter for flowed text. @end table +@node GNU Free Documentation License +@chapter GNU Free Documentation License +@include doclicense.texi @node Index @chapter Index @printindex cp -@summarycontents -@contents @bye @@ -1818,7 +1883,3 @@ Documentation of the text/plain format parameter for flowed text. @c mode: texinfo @c coding: iso-8859-1 @c End: - -@ignore - arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d -@end ignore