X-Git-Url: http://cgit.sxemacs.org/?p=gnus;a=blobdiff_plain;f=texi%2Femacs-mime.texi;h=57bf9af973badfadca8c8b89746883b69fe89b78;hp=642aff00897d082621699b98deb4fb588a691ce9;hb=b52037f4a9c6bee1ff556c22750e158da1208d4b;hpb=4f8a34929d9635cef317a56c994504d1d935bfbf diff --git a/texi/emacs-mime.texi b/texi/emacs-mime.texi index 642aff008..57bf9af97 100644 --- a/texi/emacs-mime.texi +++ b/texi/emacs-mime.texi @@ -1,7 +1,10 @@ \input texinfo -@setfilename emacs-mime +@include gnus-overrides.texi + +@setfilename emacs-mime.info @settitle Emacs MIME Manual +@include docstyle.texi @synindex fn cp @synindex vr cp @synindex pg cp @@ -9,32 +12,26 @@ @copying This file documents the Emacs MIME interface functionality. -Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, -2006 Free Software Foundation, Inc. +Copyright @copyright{} 1998--2016 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.2 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. +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''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' @end quotation @end copying -@dircategory Emacs +@c Node ``Interface Functions'' uses non-ASCII characters + +@dircategory Emacs lisp libraries @direntry -* Emacs MIME: (emacs-mime). Emacs MIME de/composition library. +* Emacs MIME: (emacs-mime). Emacs MIME de/composition library. @end direntry @iftex @finalout @@ -42,7 +39,12 @@ license to the document, as described in section 6 of the license. @setchapternewpage odd @titlepage +@ifset WEBHACKDEVEL +@title Emacs MIME Manual (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title Emacs MIME Manual +@end ifclear @author by Lars Magne Ingebrigtsen @page @@ -50,6 +52,8 @@ license to the document, as described in section 6 of the license. @insertcopying @end titlepage +@contents + @node Top @top Emacs MIME @@ -69,12 +73,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 @@ -125,7 +134,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 @@ -370,12 +379,18 @@ message as follows: @vindex mm-inline-large-images 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 +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. +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 @@ -390,7 +405,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{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 @@ -401,20 +416,22 @@ called with a @acronym{MIME} handle as the argument. @vindex mm-inline-text-html-with-images Some @acronym{HTML} mails might have the trick of spammers using @samp{} tags. It is likely to be intended to verify whether you -have read the mail. You can prevent your personal informations from +have read the mail. You can prevent your personal information from leaking by setting this option to @code{nil} (which is the default). -It is currently ignored by Emacs/w3. For emacs-w3m, you may use the -command @kbd{t} on the image anchor to show an image even if it is -@code{nil}.@footnote{The command @kbd{T} will load all images. If you -have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i} -or @kbd{I} instead.} +For emacs-w3m, you may use the command @kbd{t} on the image anchor to +show an image even if it is @code{nil}.@footnote{The command @kbd{T} +will load all images. If you have set the option +@code{w3m-key-binding} to @code{info}, use @kbd{i} or @kbd{I} +instead.} @item mm-w3m-safe-url-regexp @vindex mm-w3m-safe-url-regexp -A regular expression that matches safe URL names, i.e. URLs that are +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 @@ -471,7 +488,7 @@ Delete all control characters. @item mm-file-name-delete-gotchas @findex mm-file-name-delete-gotchas Delete characters that could have unintended consequences when used -with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and +with flawed shell scripts, i.e., @samp{|}, @samp{>} and @samp{<}; and @samp{-}, @samp{.} as the first character. @item mm-file-name-delete-whitespace @@ -631,6 +648,12 @@ The @acronym{MIME} type of the part (@code{Content-Type}). Use the contents of the file in the body of the part (@code{Content-Disposition}). +@item recipient-filename +Use this as the file name in the generated @acronym{MIME} message for +the recipient. That is, even if the file is called @file{foo.txt} +locally, use this name instead in the @code{Content-Disposition} in +the sent message. + @item charset The contents of the body of the part are to be encoded in the character set specified (@code{Content-Type}). @xref{Charset Translation}. @@ -854,18 +877,18 @@ by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}). @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, 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 -to prefer UTF-8, but wish that outgoing messages should be sent in -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}). +@code{(iso-8859-1 iso-2022-jp 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 to prefer UTF-8, but wish that outgoing +messages should be sent in 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} accoriding to the hierarchy in Gnus. +@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 @@ -877,20 +900,20 @@ Here's an example: (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)))) + (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 utf-8))) + ("^ru\\." ;; Cyrillic + (mm-coding-system-priorities + '(koi8-r iso-8859-5 iso-8859-1 utf-8)))) gnus-parameters)) @end lisp @@ -904,7 +927,7 @@ each case the most efficient of quoted-printable and base64 should be used. @code{qp-or-base64} has another effect. It will fold long lines so that -MIME parts may not be broken by MTA. So do @code{quoted-printable} and +MIME parts may not be broken by MTA@. So do @code{quoted-printable} and @code{base64}. Note that it affects body encoding only when a part is a raw forwarded @@ -976,7 +999,7 @@ Customization}). The charset to be used can be overridden by setting the @code{charset} @acronym{MML} tag (@pxref{MML Definition}) when composing the message. -The encoding of characters (quoted-printable, 8bit etc) is orthogonal +The encoding of characters (quoted-printable, 8bit, etc.)@: is orthogonal to the discussion here, and is controlled by the variables @code{mm-body-charset-encoding-alist} and @code{mm-content-transfer-encoding-defaults} (@pxref{Encoding @@ -1028,6 +1051,10 @@ flowed text, the default is to wrap after 66 characters. If hard newline characters are not present in the buffer, no flow encoding occurs. +You can customize the value of the @code{mml-enable-flowed} variable +to enable or disable the flowed encoding usage when newline +characters are present in the buffer. + On decoding flowed text, lines with soft newline characters are filled together and wrapped after the column decided by @code{fill-flowed-display-column}. The default is to wrap after @@ -1200,7 +1227,7 @@ Return the value of the field under point. @item mail-encode-encoded-word-region @findex mail-encode-encoded-word-region Encode the non-@acronym{ASCII} words in the region. For instance, -@samp{Na@"{@dotless{i}}ve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}. +@samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}. @item mail-encode-encoded-word-buffer @findex mail-encode-encoded-word-buffer @@ -1213,7 +1240,7 @@ Encode the words that need encoding in a string, and return the result. @example (mail-encode-encoded-word-string - "This is na@"{@dotless{i}}ve, baby") + "This is naïve, baby") @result{} "This is =?iso-8859-1?q?na=EFve,?= baby" @end example @@ -1228,7 +1255,7 @@ Decode the encoded words in the string and return the result. @example (mail-decode-encoded-word-string "This is =?iso-8859-1?q?na=EFve,?= baby") -@result{} "This is na@"{@dotless{i}}ve, baby" +@result{} "This is naïve, baby" @end example @end table @@ -1413,10 +1440,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 @@ -1450,21 +1490,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 @@ -1489,20 +1517,20 @@ Here's a bunch of time/date/second/day examples: (date-to-time "Sat Sep 12 12:21:54 1998 +0200") @result{} (13818 19266) -(time-to-seconds '(13818 19266)) +(float-time '(13818 19266)) @result{} 905595714.0 (seconds-to-time 905595714.0) -@result{} (13818 19266 0) +@result{} (13818 19266 0 0) (time-to-days '(13818 19266)) @result{} 729644 (days-to-time 729644) -@result{} (961933 65536) +@result{} (961933 512) (time-since '(13818 19266)) -@result{} (0 430) +@result{} (6797 9607 984839 247000) (time-less-p '(13818 19266) '(13818 19145)) @result{} nil @@ -1523,7 +1551,7 @@ Here's a bunch of time/date/second/day examples: (time-to-number-of-days (time-since (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) -@result{} 4.146122685185185 +@result{} 4314.095589286675 @end example And finally, we have @code{safe-date-to-time}, which does the same as @@ -1538,7 +1566,7 @@ 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)}. +An internal Emacs time. For instance: @code{(13818 26466 0 0)}. @item seconds A floating point representation of the internal Emacs time. For @@ -1561,8 +1589,8 @@ These are the functions available: @item date-to-time Take a date and return a time. -@item time-to-seconds -Take a time and return seconds. +@item float-time +Take a time and return seconds. (This is a built-in function.) @item seconds-to-time Take seconds and return a time. @@ -1584,14 +1612,14 @@ Take a date and return a time. If the date is not syntactically valid, return a ``zero'' time. @item time-less-p -Take two times and say whether the first time is less (i. e., earlier) +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 +Take two times and subtract the second from the first. I.e., return the time between the two times. @item days-between @@ -1832,7 +1860,7 @@ Conformance Criteria and Examples Languages, and Continuations @item RFC1843 -HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and +HZ---A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and @acronym{ASCII} characters @item draft-ietf-drums-msg-fmt-05.txt @@ -1854,21 +1882,18 @@ 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 @c Local Variables: @c mode: texinfo -@c coding: iso-8859-1 +@c coding: utf-8 @c End: - -@ignore - arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d -@end ignore