X-Git-Url: http://cgit.sxemacs.org/?p=gnus;a=blobdiff_plain;f=texi%2Femacs-mime.texi;h=6c0a830b2e8f674ff7f62e8fd380bded7a4e8a0c;hp=40b91b1f52863db7c9826d84d79e8cfa1c13ac3d;hb=dd9fdb9123576f1c0fa65094365f2ba83937b044;hpb=7e7b6c3f6baa900a15efa7f3d9e833126e162ab7 diff --git a/texi/emacs-mime.texi b/texi/emacs-mime.texi index 40b91b1f5..6c0a830b2 100644 --- a/texi/emacs-mime.texi +++ b/texi/emacs-mime.texi @@ -1,76 +1,58 @@ \input texinfo +@include gnus-overrides.texi + @setfilename emacs-mime @settitle Emacs MIME Manual @synindex fn cp @synindex vr cp @synindex pg cp -@dircategory Emacs -@direntry -* Emacs MIME: (emacs-mime). The MIME de/composition library. -@end direntry -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@ifnottex +@copying This file documents the Emacs MIME interface functionality. -Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 - Free Software Foundation, Inc. +Copyright @copyright{} 1998--2014 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''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@c Node ``Interface Functions'' uses non-ASCII characters +@documentencoding UTF-8 -@tex +@dircategory Emacs lisp libraries +@direntry +* Emacs MIME: (emacs-mime). Emacs MIME de/composition library. +@end direntry +@iftex +@finalout +@end iftex +@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 - @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 @@ -78,7 +60,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. @@ -91,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:: MML; a language for describing @acronym{MIME} parts. +* 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 @@ -147,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 @@ -198,8 +185,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 @@ -235,10 +241,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}. @@ -348,16 +350,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 +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 @@ -372,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 @@ -383,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 @@ -407,6 +442,22 @@ setting this option to non-@code{nil}. The default value is @code{t}. @vindex mm-external-terminal-program The program used to start an external terminal. +@item mm-enable-external +@vindex mm-enable-external +Indicate whether external @acronym{MIME} handlers should be used. + +If @code{t}, all defined external @acronym{MIME} handlers are used. If +@code{nil}, files are saved to disk (@code{mailcap-save-binary-file}). +If it is the symbol @code{ask}, you are prompted before the external +@acronym{MIME} handler is invoked. + +When you launch an attachment through mailcap (@pxref{mailcap}) an +attempt is made to use a safe viewer with the safest options---this isn't +the case if you save it to disk and launch it in a different way +(command line or double-clicking). Anyhow, if you want to be sure not +to launch any external programs, set this variable to @code{nil} or +@code{ask}. + @end table @node Files and Directories @@ -430,6 +481,16 @@ parts. Each function is applied successively to the file name. Ready-made functions include @table @code +@item mm-file-name-delete-control +@findex mm-file-name-delete-control +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 +@samp{-}, @samp{.} as the first character. + @item mm-file-name-delete-whitespace @findex mm-file-name-delete-whitespace Remove all whitespace. @@ -448,7 +509,6 @@ Collapse multiple whitespace characters. Replace whitespace with underscores. Set the variable @code{mm-file-name-replace-whitespace} to any other string if you do not like underscores. - @end table The standard Emacs functions @code{capitalize}, @code{downcase}, @@ -499,9 +559,10 @@ tell it to insert, but it also sets things up so that the text can be @cindex MML @cindex MIME Meta Language -Creating a @acronym{MIME} message is boring and non-trivial. Therefore, a -library called @code{mml} has been defined that parses a language called -MML (@acronym{MIME} Meta Language) and generates @acronym{MIME} messages. +Creating a @acronym{MIME} message is boring and non-trivial. Therefore, +a library called @code{mml} has been defined that parses a language +called @acronym{MML} (@acronym{MIME} Meta Language) and generates +@acronym{MIME} messages. @findex mml-generate-mime The main interface function is @code{mml-generate-mime}. It will @@ -509,12 +570,12 @@ examine the contents of the current (narrowed-to) buffer and return a string containing the @acronym{MIME} message. @menu -* Simple MML Example:: An example MML document. -* MML Definition:: All valid MML elements. -* Advanced MML Example:: Another example MML document. +* Simple MML Example:: An example @acronym{MML} document. +* MML Definition:: All valid @acronym{MML} elements. +* Advanced MML Example:: Another example @acronym{MML} document. * Encoding Customization:: Variables that affect encoding. * Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}. -* Conversion:: Going from @acronym{MIME} to MML and vice versa. +* Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa. * Flowed text:: Soft and hard newlines. @end menu @@ -556,10 +617,10 @@ Content-Type: text/enriched @node MML Definition @section MML Definition -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 application, but it's not. -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 different type or use a different charset. The way to delineate a part is with a @samp{<#part ...>} tag. Multipart parts can be introduced with the @samp{<#multipart ...>} tag. Parts are ended by the @@ -574,8 +635,8 @@ Each tag can contain zero or more parameters on the form but that's not necessary unless the value contains white space. So @samp{filename=/home/user/#hello$^yes} is perfectly valid. -The following parameters have meaning in MML; parameters that have no -meaning are ignored. The MML parameter names are the same as the +The following parameters have meaning in @acronym{MML}; parameters that have no +meaning are ignored. The @acronym{MML} parameter names are the same as the @acronym{MIME} parameter names; the things in the parentheses say which header it will be used in. @@ -587,9 +648,15 @@ 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 speficied (@code{Content-Type}). @xref{Charset Translation}. +set specified (@code{Content-Type}). @xref{Charset Translation}. @item name Might be used to suggest a file name if the part is to be saved @@ -628,15 +695,25 @@ default key used. The size (in octets) of the part (@code{Content-Disposition}). @item sign -What technology to sign this MML part with (@code{smime}, @code{pgp} +What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp} or @code{pgpmime}) @item encrypt -What technology to encrypt this MML part with (@code{smime}, +What technology to encrypt this @acronym{MML} part with (@code{smime}, @code{pgp} or @code{pgpmime}) @end table +Parameters for @samp{text/plain}: + +@table @samp +@item format +Formatting parameter for the text, valid values include @samp{fixed} +(the default) and @samp{flowed}. Normally you do not specify this +manually, since it requires the textual body to be formatted in a +special way described in RFC 2646. @xref{Flowed text}. +@end table + Parameters for @samp{application/octet-stream}: @table @samp @@ -781,7 +858,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) @@ -794,29 +871,71 @@ default is As an example, if you do not want to have ISO-8859-1 characters quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to this variable. You can override this setting on a per-message basis -by using the @code{encoding} MML tag (@pxref{MML Definition}). +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 -coding system symbols (aliases of coding systems does not work, use -@kbd{M-x describe-coding-system} to make sure you are not specifying -an alias in this variable). For example, if you have configured Emacs -to use 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-latin-1)}. You can override this setting on a per-message -basis by using the @code{charset} MML tag (@pxref{MML Definition}). +is @code{nil}, which means to use the defaults in Emacs, but is +@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} 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 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 used except, e.g., when other requirements force a safer encoding -(digitally signed messages require 7bit encoding). Besides the normal +(digitally signed messages require 7bit encoding). Besides the normal @acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for each case the most efficient of quoted-printable and base64 should be -used. You can override this setting on a per-message basis by using -the @code{encoding} MML tag (@pxref{MML Definition}). +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 +@code{base64}. + +Note that it affects body encoding only when a part is a raw forwarded +message (which will be made by @code{gnus-summary-mail-forward} with the +arg 2 for example) or is neither the @samp{text/*} type nor the +@samp{message/*} type. Even though in those cases, you can override +this setting on a per-message basis by using the @code{encoding} +@acronym{MML} tag (@pxref{MML Definition}). @item mm-use-ultra-safe-encoding @vindex mm-use-ultra-safe-encoding @@ -834,8 +953,9 @@ encoding messages that are to be digitally signed). @section Charset Translation @cindex charsets -During translation from MML to @acronym{MIME}, for each @acronym{MIME} part which -has been composed inside Emacs, an appropriate charset has to be chosen. +During translation from @acronym{MML} to @acronym{MIME}, for each +@acronym{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 @@ -855,8 +975,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 @@ -875,10 +996,10 @@ messages. You can modify this by altering the @code{mm-coding-system-priorities} variable though (@pxref{Encoding Customization}). -The charset to be used can be overriden by setting the @code{charset} -MML tag (@pxref{MML Definition}) when composing the message. +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 @@ -888,15 +1009,15 @@ Customization}). @section Conversion @findex mime-to-mml -A (multipart) @acronym{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 @acronym{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. +A (multipart) @acronym{MIME} message can be converted to @acronym{MML} +with the @code{mime-to-mml} function. It works on the message in the +current buffer, and substitutes @acronym{MML} markup for @acronym{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 @acronym{MML} tags. @findex mml-to-mime -An MML message can be converted back to @acronym{MIME} by the +An @acronym{MML} message can be converted back to @acronym{MIME} by the @code{mml-to-mime} function. These functions are in certain senses ``lossy''---you will not get back @@ -921,19 +1042,29 @@ variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines, emacs, Emacs Manual}) when encoding a message, and the ``format=flowed'' Content-Type parameter when decoding a message. -On encoding text, lines terminated by soft newline characters are -filled together and wrapped after the column decided by -@code{fill-flowed-encode-column}. This variable controls how the text -will look in a client that does not support flowed text, the default -is to wrap after 66 characters. If hard newline characters are not -present in the buffer, no flow encoding occurs. +On encoding text, regardless of @code{use-hard-newlines}, lines +terminated by soft newline characters are filled together and wrapped +after the column decided by @code{fill-flowed-encode-column}. +Quotation marks (matching @samp{^>* ?}) are respected. The variable +controls how the text will look in a client that does not support +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 @code{fill-column}. - +@table @code +@item mm-fill-flowed +@vindex mm-fill-flowed +If non-@code{nil} a format=flowed article will be displayed flowed. +@end table @node Interface Functions @@ -1096,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ï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 @@ -1109,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ïve, baby") + "This is naïve, baby") @result{} "This is =?iso-8859-1?q?na=EFve,?= baby" @end example @@ -1124,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ïve, baby" +@result{} "This is naïve, baby" @end example @end table @@ -1141,7 +1272,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 @@ -1282,11 +1413,6 @@ library does. The following variables are tweakable: @table @code -@item rfc2047-default-charset -@vindex rfc2047-default-charset -Characters in this charset should not be decoded by this library. -This defaults to @code{iso-8859-1}. - @item rfc2047-header-encoding-alist @vindex rfc2047-header-encoding-alist This is an alist of header / encoding-type pairs. Its main purpose is @@ -1294,9 +1420,10 @@ to prevent encoding of certain headers. 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. +The values can be @code{nil}, in which case the header(s) in question +won't be encoded, @code{mime}, which means that they will be encoded, or +@code{address-mime}, which means the header(s) will be encoded carefully +assuming they contain addresses. @item rfc2047-charset-encoding-alist @vindex rfc2047-charset-encoding-alist @@ -1304,22 +1431,33 @@ 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. -@item rfc2047-encoding-function-alist -@vindex rfc2047-encoding-function-alist +@item rfc2047-encode-function-alist +@vindex rfc2047-encode-function-alist This is an alist of encoding / function pairs. The encodings are @code{Q}, @code{B} and @code{nil}. -@item rfc2047-q-encoding-alist -@vindex 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 / allowable character -ranges. - @item rfc2047-encoded-word-regexp @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{=?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 Those were the variables, and these are this functions: @@ -1350,6 +1488,12 @@ Decode the encoded words in the region. @findex rfc2047-decode-string 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 substitution +for the @code{rfc2231-encode-string} function, that is the standard but +many mailers don't support it. @xref{rfc2231}. + @end table @@ -1373,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 @@ -1407,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 @@ -1422,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 @@ -1445,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. @@ -1465,17 +1609,17 @@ 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) +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 @@ -1716,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 @@ -1738,17 +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: