* lisp/gnus.el (gnus-revision-number): Increment to 01.

[elisp/gnus.git-] / texi / emacs-mime.texi

diff --git a/texi/emacs-mime.texi b/texi/emacs-mime.texi
index a00948d..e40194a 100644 (file)
--- a/texi/emacs-mime.texi
+++ b/texi/emacs-mime.texi
@@ -17,7 +17,7 @@
 
 This file documents the Emacs MIME interface functionality.
 
 
 This file documents the Emacs MIME interface functionality.
 

-Copyright (C) 1996 Free Software Foundation, Inc.
+Copyright (C) 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
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice

@@ -48,7 +48,7 @@ into another language, under the above conditions for modified versions.
 @page
 
 @vskip 0pt plus 1filll
 @page
 
 @vskip 0pt plus 1filll

-Copyright @copyright{} 1998 Free Software Foundation, Inc. 
+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
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice

@@ -166,6 +166,12 @@ Returns the value of the attribute.
 @result{} "b980912.gif"
 @end example
 
 @result{} "b980912.gif"
 @end example
 

+@item mail-header-encode-parameter
+@findex mail-header-encode-parameter
+Takes a parameter string and returns an encoded version of the string.
+This is used for parameters in headers like @code{Content-Type} and
+@code{Content-Disposition}.
+

 @item mail-header-remove-comments
 @findex mail-header-remove-comments
 Return a comment-free version of a header.
 @item mail-header-remove-comments
 @findex mail-header-remove-comments
 Return a comment-free version of a header.

@@ -192,9 +198,9 @@ and comments is preserved.
 Return the last comment in a header.
 
 @example
 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)")
  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")

-@result{} "Finnish Landrace" 
+@result{} "Finnish Landrace"

 @end example
 
 @item mail-header-parse-address
 @end example
 
 @item mail-header-parse-address

@@ -270,8 +276,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},
 @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.

 
 
 
 
 
 

@@ -285,6 +291,7 @@ on.  High-level functionality is dealt with in the next chapter
 (@pxref{Decoding and Viewing}).
 
 @menu
 (@pxref{Decoding and Viewing}).
 
 @menu

+* rfc2045::      Encoding @code{Content-Type} headers.

 * rfc2231::      Parsing @code{Content-Type} headers.
 * ietf-drums::   Handling mail headers defined by RFC822bis.
 * rfc2047::      En/decoding encoded words in headers.
 * rfc2231::      Parsing @code{Content-Type} headers.
 * ietf-drums::   Handling mail headers defined by RFC822bis.
 * rfc2047::      En/decoding encoded words in headers.

@@ -298,6 +305,24 @@ on.  High-level functionality is dealt with in the next chapter
 @end menu
 
 
 @end menu
 
 

+@node rfc2045
+@section rfc2045
+
+RFC2045 is the ``main'' @sc{mime} document, and as such, one would
+imagine that there would be a lot to implement.  But there isn't, since
+most of the implementation details are delegated to the subsequent
+RFCs.
+
+So @file{rfc2045.el} has only a single function:
+
+@table @code
+@item rfc2045-encode-string
+@findex rfc2045-encode-string
+Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
+@var{value} will be quoted if there are non-safe characters in it.
+@end table
+
+

 @node rfc2231
 @section rfc2231
 
 @node rfc2231
 @section rfc2231
 

@@ -327,7 +352,7 @@ elements.
 
 @example
 (rfc2231-parse-string
 
 @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!\"")
  title*0*=us-ascii'en'This%20is%20even%20more%20;
  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
  title*2=\"isn't it!\"")

@@ -337,9 +362,14 @@ elements.
 
 @item rfc2231-get-value
 @findex rfc2231-get-value
 
 @item rfc2231-get-value
 @findex rfc2231-get-value

-Takes one of the lists on the format above and return
+Takes one of the lists on the format above and returns

 the value of the specified attribute.
 
 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}.
+

 @end table
 
 
 @end table
 
 

@@ -429,11 +459,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
 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
 
 @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
 
 
 @end table
 

@@ -821,7 +851,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
 @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
 MML (@sc{mime} Meta Language) and generates @sc{mime} messages.
 
 @findex mml-generate-mime

@@ -833,6 +863,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.
 * Simple MML Example::             An example MML document.
 * MML Definition::                 All valid MML elements.
 * Advanced MML Example::           Another example MML document.

+* Conversion::                     Going from @sc{mime} to MML and vice versa.

 @end menu
 
 
 @end menu
 
 

@@ -909,7 +940,7 @@ The contents of the body of the part are to be encoded in the character
 set speficied (@code{Content-Type}).
 
 @item name
 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
 to a file (@code{Content-Type}).
 
 @item disposition

@@ -971,7 +1002,7 @@ Valid values are @samp{read} and @samp{read-write}
 @section Advanced MML Example
 
 Here's a complex multipart message.  It's a @samp{multipart/mixed} that
 @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>
 
 @example
 <#multipart type=mixed>

@@ -1054,6 +1085,33 @@ This plain text part is an attachment.
 @end example
 
 
 @end example
 
 

+@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
 @chapter Standards
 
 @node Standards
 @chapter Standards

@@ -1109,8 +1167,8 @@ Communicating Presentation Information in Internet Messages: The
 Content-Disposition Header Field
 
 @end table
 Content-Disposition Header Field
 
 @end table

- 
- 
+
+

 @node Index
 @chapter Index
 @printindex cp
 @node Index
 @chapter Index
 @printindex cp