emacs-mime-ja.texi

   1 \input texinfo
   2
   3 @setfilename emacs-mime-ja
   4 @settitle Emacs MIME Manual
   5 @synindex fn cp
   6 @synindex vr cp
   7 @synindex pg cp
   8
   9 @copying
  10 \e$B$3$N%U%!%$%k$O\e(B Emacs MIME \e$B%$%s%?!<%U%'!<%9$N5!G=$rJ8=q2=$7$?$b$N$G$9!#\e(B
  11
  12 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
  13           Free Software Foundation, Inc.
  14
  15 @quotation
  16 Permission is granted to copy, distribute and/or modify this document
  17 under the terms of the GNU Free Documentation License, Version 1.1 or
  18 any later version published by the Free Software Foundation; with no
  19 Invariant Sections, with the Front-Cover texts being ``A GNU
  20 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
  21 license is included in the section entitled ``GNU Free Documentation
  22 License'' in the Emacs manual.
  23
  24 \e$B$3$NJ8=q$r!"%U%j!<%=%U%H%&%'%":bCDH/9T$N\e(B GNU \e$B%U%j!<J8=qMxMQ5vBz7@Ls=q\e(B
  25 \e$BBh\e(B 1.1 \e$BHG$^$?$O$=$l0J9_$NHG$,Dj$a$k>r7o$N2<$GJ#@=!"G[I[!"$"$k$$$OJQ99$9\e(B
  26 \e$B$k$3$H$r5v2D$7$^$9!#JQ99IT2DItJ,$O;XDj$7$^$;$s!#!V\e(BA GNU Manual\e$B!W$OI=I=;f\e(B
  27 \e$B%F%-%9%H!"0J2<$N\e(B (a) \e$B$ON"I=;f%F%-%9%H$G$9!#$3$NMxMQ5vBz7@Ls=q$NJ#<L$O\e(B
  28 \e$B!V\e(BEmacs manual\e$B!W$N!V\e(BGNU \e$B%U%j!<J8=qMxMQ5vBz7@Ls=q!W$H$$$&>O$K4^$^$l$F$$$^\e(B
  29 \e$B$9!#\e(B
  30
  31 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  32 this GNU Manual, like GNU software.  Copies published by the Free
  33 Software Foundation raise funds for GNU development.''
  34
  35 (a) FSF \e$B$NN"I=;f%F%-%9%H\e(B:\e$B!V$"$J$?$K$O$3$N\e(B GNU Manual \e$B$r\e(B GNU \e$B%=%U%H%&%'%"\e(B
  36 \e$B$N$h$&$KJ#@=$7$?$jJQ99$9$k<+M3$,$"$j$^$9!#J#@=$O%U%j!<%=%U%H%&%'%":bCD$K\e(B
  37 \e$B$h$C$F=PHG$5$l$^$7$?!#\e(B(\e$B%U%j!<%=%U%H%&%'%":bCD$O\e(B) GNU \e$B$N3+H/$N$?$a$KI,MW\e(B
  38 \e$B$J;q6b$r=8$a$F$$$^$9!#!W\e(B
  39
  40 This document is part of a collection distributed under the GNU Free
  41 Documentation License.  If you want to distribute this document
  42 separately from the collection, you can do so by adding a copy of the
  43 license to the document, as described in section 6 of the license.
  44
  45 \e$B$3$NJ8=q$O!V\e(BGNU \e$B%U%j!<J8=qMxMQ5vBz7@Ls=q!W$K4p$E$$$FG[I[$5$l$?<}=8Cx:nJ*\e(B
  46 \e$B$N0lIt$G$9!#$b$7$"$J$?$,$3$NJ8=q$r<}=8Cx:nJ*$+$iJ,N%$7$FG[I[$7$?$$$H$-$O!"\e(B
  47 \e$B7@Ls=q$NBh\e(B 6 \e$B9`$K5-=R$5$l$F$$$k$h$&$K!"J8=q$K7@Ls=q$NJ#<L$rIU2C$9$k$3$H\e(B
  48 \e$B$K$h$C$F!"9T$J$&$3$H$,$G$-$^$9!#\e(B
  49 @end quotation
  50 @end copying
  51
  52 @dircategory Emacs
  53 @direntry
  54 * Emacs MIME-ja: (emacs-mime-ja). Emacs MIME de/composition library (Japanese).
  55 @end direntry
  56 @iftex
  57 @finalout
  58 @end iftex
  59 @setchapternewpage odd
  60
  61 @titlepage
  62 @title Emacs MIME Manual
  63
  64 @author by Lars Magne Ingebrigtsen
  65 @page
  66 @vskip 0pt plus 1filll
  67 @insertcopying
  68 @end titlepage
  69
  70 @node Top
  71 @top Emacs MIME
  72
  73 \e$B$3$N%^%K%e%"%k$O\e(B @acronym{MIME} \e$B%a%C%;!<%8$NI=<($H:n@.$K;H$o$l$k%i%$%V%i\e(B
  74 \e$B%j!<$rJ8=q2=$7$?$b$N$G$9!#\e(B
  75
  76 \e$B$3$N%^%K%e%"%k$O!"\e(B@acronym{MIME} \e$B$N%(%s%3!<%I\e(B/\e$B%G%3!<%I!&%W%m%;%9$N?6$kIq\e(B
  77 \e$B$$$rJQ99$7$?$$$+!"\e(BEmacs @acronym{MIME} \e$B%i%$%V%i%j!<$,$I$N$h$&$KF0:n$9$k\e(B
  78 \e$B$+$N$b$C$H>\:Y$JIA<L$rK>$`%f!<%6!"$*$h$S\e(B @acronym{MIME} \e$B$NMWAG$rA`:n$9$k\e(B
  79 \e$B4X?t$*$h$S%3%^%s%I$r=q$-$?$$?M$?$A$rBP>]$K$7$F$$$^$9!#\e(B
  80
  81 @acronym{MIME} \e$B$O\e(B @dfn{Multipurpose Internet Mail Extensions} \e$B$N>JN,I=5-\e(B
  82 \e$B$G$9!#$3$NI8=`$OB??t$N\e(B RFC \e$B$KJ8=q2=$5$l$F$$$F!"<g$J$b$N$O<!$NDL$j$G$9\e(B:
  83 RFC2045 (\e$B%$%s%?!<%M%C%H!&%a%C%;!<%8K\J8$N=q<0\e(B), RFC2046 (\e$B%a%G%#%"%?%$%W\e(B),
  84 RFC2047 (\e$B%a%C%;!<%8%X%C%@!<$NHs\e(B-@acronym{ASCII} \e$B%F%-%9%H3HD%\e(B),
  85 RFC2048 (\e$BEPO?<jB3\e(B), RFC2049 (\e$BE,9g4p=`$H;vNc\e(B)\e$B!#\e(B@acronym{MIME} \e$B$K=`5r$7$?\e(B
  86 \e$B%=%U%H%&%'%"$r=q$3$&$H;W$C$F$$$k?M$OC/$G$b!">/$J$/$H\e(B
  87 \e$B$b\e(B RFC2045 \e$B$H\e(B RFC2047 \e$B$OFI$s$G$*$/$3$H$r6/$/4+$a$^$9!#\e(B
  88
  89 @menu
  90 * Decoding and Viewing::  \e$B%G%3!<%I$HI=<($N$?$a$NOHAH$_\e(B
  91 * Composing::             @acronym{MML}; @acronym{MIME} \e$B%Q!<%H5-=RMQ8@8l\e(B
  92 * Interface Functions::   \e$B4pK\E*$J4X?t$K4X$9$kCj>]35G0\e(B
  93 * Basic Functions::       \e$B%f!<%F%#%j%F%#!<$*$h$S4pK\E*$J2r@O$N$?$a$N4X?t\e(B
  94 * Standards::             \e$B;H$o$l$F$$$k\e(B RFC \e$B$H:n6HJ8=q$N35N,\e(B
  95 * Index::                 \e$B4X?t$*$h$SJQ?t$N:w0z\e(B
  96 @end menu
  97
  98 @node Decoding and Viewing
  99 @chapter \e$B%G%3!<%I$HI=<(\e(B
 100
 101 \e$B$3$N>O$O!">e0L3,AX$G$N\e(B @acronym{MIME} \e$B%a%C%;!<%8$N%G%3!<%I$HI=<($r07$$$^\e(B
 102 \e$B$9!#\e(B
 103
 104 \e$B$=$N<g$JL\E*$O!":G=i$K\e(B @acronym{MIME} \e$B$N5-;v$r2r@O$7!"<!$K$=$N2r@O$N7k2L\e(B
 105 \e$BJV$5$l$k!V\e(B@dfn{\e$B%O%s%I%k\e(B}\e$B!W\e(B \e$B$N%j%9%H$K4p$E$$$F!"B>$N%W%m%0%i%`$,J*;v$r9T\e(B
 106 \e$B$J$&$3$H$r2DG=$K$9$k$3$H$G$9!#\e(B
 107
 108 @menu
 109 * Dissection::             @acronym{MIME} \e$B%a%C%;!<%8$N2r@O\e(B
 110 * Non-MIME::               \e$BHs\e(B-@acronym{MIME} \e$B%a%C%;!<%8$N2r@O\e(B
 111 * Handles::                \e$B%O%s%I%k$N<h$j07$$\e(B
 112 * Display::                \e$B%O%s%I%k$NI=<(\e(B
 113 * Display Customization::  \e$BI=<($K1F6A$9$kJQ?t\e(B
 114 * Files and Directories::  \e$BE:IU$NJ]B8$HL?L>\e(B
 115 * New Viewers::            \e$B<+J,MQ%S%e!<%o!<$N=q$-J}\e(B
 116 @end menu
 117
 118 @node Dissection
 119 @section \e$B2rBN\e(B
 120
 121 @code{mm-dissect-buffer} \e$B$O\e(B @acronym{MIME} \e$B5-;v$N2rBN$rC4Ev$9$k4X?t$G$9!#\e(B
 122 \e$B%^%k%A%Q!<%H$N%a%C%;!<%8$,M?$($i$l$k$H!"%a%C%;!<%8$r:F5"E*$K7!$j2<$2!"9=\e(B
 123 \e$BB$$K=>$C$F!"$=$N%a%C%;!<%8$N9=B$$rIA<L$9$k\e(B @acronym{MIME} \e$B%O%s%I%k$NLZ9=\e(B
 124 \e$BB$$rJV$7$^$9!#\e(B
 125
 126 @node Non-MIME
 127 @section \e$BHs\e(B-MIME
 128 @vindex mm-uu-configure-list
 129
 130 Gnus \e$B$O$$$/$D$+$NHs\e(B-@acronym{MIME} \e$B$NE:IU$bM}2r$7$^$9!#$=$l$i\e(B
 131 \e$B$O\e(B postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp,
 132 diff \e$B$N$h$&$J$b$N$G$9!#$=$l$>$l$N5!G=$O\e(B @code{mm-uu-configure-list} \e$B$K9`\e(B
 133 \e$BL\$rDI2C$9$k$3$H$K$h$C$F!"L58z$K$9$k$3$H$,$G$-$^$9!#Nc$G$9!#\e(B
 134
 135 @lisp
 136 (require 'mm-uu)
 137 (add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
 138 @end lisp
 139
 140 @table @code
 141 @item postscript
 142 @findex postscript
 143 \e$B%]%9%H%9%/%j%W%H$N%U%!%$%k!#\e(B
 144
 145 @item uu
 146 @findex uu
 147 Uuencode \e$B$5$l$?%U%!%$%k!#\e(B
 148
 149 @item binhex
 150 @findex binhex
 151 Binhex \e$B$G%(%s%3!<%I$5$l$?%U%!%$%k!#\e(B
 152
 153 @item yenc
 154 @findex yenc
 155 Yenc \e$B$G%(%s%3!<%I$5$l$?%U%!%$%k!#\e(B
 156
 157 @item shar
 158 @findex shar
 159 Shar \e$B=q8K%U%!%$%k!#\e(B
 160
 161 @item forward
 162 @findex forward
 163 \e$BHs\e(B-@acronym{MIME} \e$B$GE>Aw$5$l$?%a%C%;!<%8!#\e(B
 164
 165 @item gnatsweb
 166 @findex gnatsweb
 167 Gnatsweb \e$B$NE:IU!#\e(B
 168
 169 @item pgp-signed
 170 @findex pgp-signed
 171 @acronym{PGP} \e$B$G=pL>$5$l$?J?J8\e(B (clear text)\e$B!#\e(B
 172
 173 @item pgp-encrypted
 174 @findex pgp-encrypted
 175 @acronym{PGP} \e$B$G0E9f2=$5$l$?J?J8\e(B (clear text)\e$B!#\e(B
 176
 177 @item pgp-key
 178 @findex pgp-key
 179 @acronym{PGP} \e$B$N8x3+80!#\e(B
 180
 181 @item emacs-sources
 182 @findex emacs-sources
 183 @vindex mm-uu-emacs-sources-regexp
 184 Emacs \e$B$N%=!<%9%3!<%I!#$3$N9`L\$O\e(B @code{mm-uu-emacs-sources-regexp} \e$B$K9g\e(B
 185 \e$BCW$9$k%0%k!<%W$G$N$_F0:n$7$^$9!#\e(B
 186
 187 @item diff
 188 @vindex diff
 189 @vindex mm-uu-diff-groups-regexp
 190 \e$B%Q%C%A!#$3$l$O!"%3%_%C%H$5$l$?%U%!%$%k$N:9J,$,<+F0E*$KAw$i$l$k%0%k!<%W$r\e(B
 191 \e$BBP>]$K$7$?$b$N$G$9!#\e(B@code{mm-uu-diff-groups-regexp} \e$B$K9gCW$9$k%0%k!<%W$G\e(B
 192 \e$B$N$_F0:n$7$^$9!#\e(B
 193 @end table
 194
 195 @node Handles
 196 @section \e$B%O%s%I%k\e(B
 197
 198 @acronym{MIME} \e$B%O%s%I%k$O!"\e(B@acronym{MIME} \e$B$N9=@.MWAG$r40A4$K5-=R$9$k%j%9\e(B
 199 \e$B%H$G$9!#\e(B
 200
 201 \e$B%O%s%I%k$NMWAG$r%"%/%;%9$9$k$?$a$K!"0J2<$N%^%/%m$r;H$&$3$H$,$G$-$^$9\e(B:
 202
 203 @table @code
 204 @item mm-handle-buffer
 205 @findex mm-handle-buffer
 206 \e$B%G%3!<%I$5$l$F$$$J$$\e(B @acronym{MIME} \e$B%Q!<%H$NFbMFJ*$rJ];}$7$F$$$k%P%C%U%!\e(B
 207 \e$B$rJV$7$^$9!#\e(B
 208
 209 @item mm-handle-type
 210 @findex mm-handle-type
 211 \e$B2r@O:Q$_$N!"%Q!<%H$N\e(B @code{Content-Type} \e$B$rJV$7$^$9!#\e(B
 212
 213 @item mm-handle-encoding
 214 @findex mm-handle-encoding
 215 \e$B%Q!<%H$N\e(B @code{Content-Transfer-Encoding} \e$B$rJV$7$^$9!#\e(B
 216
 217 @item mm-handle-undisplayer
 218 @findex mm-handle-undisplayer
 219 \e$BI=<($5$l$F$$$k%Q!<%H$r>C$9$3$H$,$G$-$k$b$N\e(B (\e$BLuCm\e(B: \e$B4X?t$J$I\e(B) \e$B$r\e(B (\e$B$=$l$,I=\e(B
 220 \e$B<($5$l$F$$$k>l9g$K\e(B) \e$BJV$7$^$9!#\e(B
 221
 222 @item mm-handle-set-undisplayer
 223 @findex mm-handle-set-undisplayer
 224 \e$BI=<($5$l$F$$$k%Q!<%H$r>C$9$3$H$,$G$-$k$b$N\e(B (\e$BLuCm\e(B: \e$B4X?t$J$I\e(B) \e$B$r@_Dj$7$^$9!#\e(B
 225
 226 @item mm-handle-disposition
 227 @findex mm-handle-disposition
 228 \e$B2r@O:Q$_$N!"%Q!<%H$N\e(B @code{Content-Disposition} \e$B$rJV$7$^$9!#\e(B
 229
 230 @item mm-get-content-id
 231 @code{Content-ID} \e$B$G;2>H$5$l$k%O%s%I%k\e(B (\e$BC1?t$^$?$OJ#?t\e(B) \e$B$rJV$7$^$9!#\e(B
 232 @end table
 233
 234 @node Display
 235 @section \e$BI=<(\e(B
 236
 237 \e$BI=<($7!">C5n$7!"J]B8$9$k$?$a$N4X?t!#\e(B
 238
 239 @table @code
 240 @item mm-display-part
 241 @findex mm-display-part
 242 \e$B%Q!<%H$rI=<($7$^$9!#\e(B
 243
 244 @item mm-remove-part
 245 @findex mm-remove-part
 246 \e$B%Q!<%H$r\e(B (\e$B$=$l$,I=<($5$l$F$$$?$i\e(B) \e$B>C5n$7$^$9!#\e(B
 247
 248 @item mm-inlinable-p
 249 @findex mm-inlinable-p
 250 @acronym{MIME} \e$B%?%$%W$,%$%s%i%$%s$GI=<(2DG=$+$I$&$+$rJV$7$^$9!#\e(B
 251
 252 @item mm-automatic-display-p
 253 @findex mm-automatic-display-p
 254 @acronym{MIME} \e$B%?%$%W$,<+F0E*$KI=<($5$l$k$Y$-$+$I$&$+$rJV$7$^$9!#\e(B
 255
 256 @item mm-destroy-part
 257 @findex mm-destroy-part
 258 \e$B%Q!<%H$K$h$C$F;H$o$l$F$$$k$9$Y$F$N;q8;$r3+J|$7$^$9\e(B (\e$BLuCm\e(B: \e$B%Q!<%H$NI=<(!"\e(B
 259 \e$B$*$h$S%Q!<%H$r2rBN$7$FF@$?8D!9$NItIJ$r0l;~E*$KJ];}$7$F$$$k%P%C%U%!$d%U%!\e(B
 260 \e$B%$%k$r>C5n$7$^$9\e(B)\e$B!#\e(B
 261
 262 @item mm-save-part
 263 @findex mm-save-part
 264 \e$B%Q!<%H$r%U%!%$%k$KJ]B8$7$^$9!#\e(B
 265
 266 @item mm-pipe-part
 267 @findex mm-pipe-part
 268 \e$B%Q!<%H$r$"$k%W%m%;%9$K%Q%$%W$7$^$9!#\e(B
 269
 270 @item mm-interactively-view-part
 271 @findex mm-interactively-view-part
 272 \e$B%Q!<%H$rI=<($9$k$?$a$K;H$&\e(B mailcap \e$B$N<jCJ$r?R$M$^$9!#\e(B
 273 @end table
 274
 275 @node Display Customization
 276 @section \e$BI=<($N%+%9%?%^%$%:\e(B
 277
 278 @table @code
 279 @item mm-inline-media-tests
 280 @vindex mm-inline-media-tests
 281 \e$B$3$l$OO"A[%j%9%H$G$9!#80\e(B (\e$BBh0lMWAG\e(B) \e$B$O\e(B @acronym{MIME} \e$B%?%$%W!"BhFsMWAG$O\e(B
 282 \e$B%Q!<%H$r\e(B @dfn{\e$B%$%s%i%$%s\e(B} \e$B$G\e(B (\e$B$9$J$o$A\e(B Emacs \e$B$N2hLL$KKd$a9~$s$G\e(B) \e$BI=<($9\e(B
 283 \e$B$k$?$a$N4X?t!"$=$7$FBh;0MWAG$O$=$N%Q!<%H$,%$%s%i%$%s$GI=<($9$k$3$H$,2DG=\e(B
 284 \e$B$+$I$&$+$rD4$Y$k$?$a$KI>2A\e(B (@code{eval}) \e$B$5$l$k%U%)!<%`$G$9!#\e(B
 285
 286 \e$B$3$NJQ?t$O!"$"$k%Q!<%H$,%$%s%i%$%sI=<(2DG=$+$I$&$+$H!"$b$72DG=$J$i$=$N$d\e(B
 287 \e$B$jJ}$r;XDj$7$^$9!#%Q!<%H$,8=<B$K%$%s%i%$%sI=<($5$l$F$$$k$+$I$&$+$r<($9$b\e(B
 288 \e$B$N$G$O$"$j$^$;$s!#\e(B
 289
 290 @item mm-inlined-types
 291 @vindex mm-inlined-types
 292 \e$B0lJ}$3$l$O!">e5-$NJQ?t$K$h$C$F@_Dj$5$l$?>r7o$rK~B-$9$k!"%$%s%i%$%sI=<(2D\e(B
 293 \e$BG=$J%?%$%W$r<($7$^$9!#$3$l$O\e(B @acronym{MIME} \e$B%a%G%#%"%?%$%W$N%j%9%H$G$9!#\e(B
 294 (\e$BLuCm\e(B: \e$B$=$l$>$l$NMWAG$O@55,I=8=$G$9!#\e(B)
 295
 296 @item mm-automatic-display
 297 @vindex mm-automatic-display
 298 \e$B$3$l$O>e5-$NJQ?t$,G'$a$k%?%$%W$N$&$A$G!"!V<+F0E*!W$KI=<($5$l$k%?%$%W$N%j\e(B
 299 \e$B%9%H$G$9!#$D$^$j!"%$%s%i%$%sI=<($,2DG=$J%Q!<%H$@$1$,<+F0E*$KI=<($5$l$^$9!#\e(B
 300
 301 @item mm-automatic-external-display
 302 @vindex mm-automatic-external-display
 303 \e$B$3$l$O30It%S%e!<%o!<$G<+F0E*$KI=<($5$l$k%?%$%W$N%j%9%H$G$9!#\e(B
 304
 305 @item mm-keep-viewer-alive-types
 306 @vindex mm-keep-viewer-alive-types
 307 \e$B$3$l$O!"JL$N5-;v$rA*Br$7$F$b!"30It%S%e!<%o!<$,\e(B kill \e$B$5$l$J$$%a%G%#%"%?%$\e(B
 308 \e$B%W$N%j%9%H$G$9!#\e(B
 309
 310 \e$BLuCm\e(B: postscript \e$B$d\e(B dvi \e$B$J$I\e(B (\e$BJQ?t$N%G%#%U%)%k%HCM$r;2>H$N$3$H\e(B) \e$B$N$h$&$K!"\e(B
 311 \e$BFI$`$N$K;~4V$,$+$+$k$+$b$7$l$J$$%Q!<%H$N%?%$%W$r4^$`%j%9%H$G$9!#0lJ}!"$3\e(B
 312 \e$B$l$K4^$^$l$J$$C1=c$J2hA|$N%Q!<%H$J$I$O!"$=$l$,4^$^$l$F$$$?5-;v$NI=<($r$d\e(B
 313 \e$B$a$?$H$-$K!"<+F0E*$K30It%S%e!<%o!<$,\e(B kill \e$B$5$l$^$9!#\e(B
 314
 315 @item mm-attachment-override-types
 316 @vindex mm-attachment-override-types
 317 \e$B$$$/$D$+$N\e(B @acronym{MIME} \e$B%(!<%8%'%s%H$O!"G[CV;X\e(B
 318 \e$BDj\e(B (content-disposition) \e$B$H$7$F\e(B @samp{\e$BE:IU\e(B} (@samp{attachment}) \e$B$r@_Dj$7\e(B
 319 \e$B$?%Q!<%H$r@8@.$7$^$9!#$3$NJQ?t$O$=$s$JG[CV;XDj$r>e=q$-$7$F!"$=$N%Q!<%H$r\e(B
 320 \e$B%$%s%i%$%sI=<($9$k$3$H$r5v$7$^$9!#\e(B(\e$B$=$N%Q!<%H$N%$%s%i%$%sI=<($9$k$3$H$,\e(B
 321 \e$B2DG=$G!";d$?$A$,$=$&$9$k$3$H$rK>$`>l9g$@$1!"G[CV;XDj$,>e=q$-$5$l$k$3$H$K\e(B
 322 \e$BCm0U$7$F2<$5$$!#\e(B)
 323
 324 @item mm-discouraged-alternatives
 325 @vindex mm-discouraged-alternatives
 326 @samp{multipart/alternative} \e$B$rI=<($9$k$3$H$,7y$o$l$k\e(B @acronym{MIME} \e$B%?\e(B
 327 \e$B%$%W$N%j%9%H$G$9!#$=$l$,:G$b6=L#?<$$$b$N$G$"$k$HA[Dj$7$F$$$k$?$a$K!"I=<(\e(B
 328 \e$B%(!<%8%'%s%H$O%a%C%;!<%8$N8eH>$K$"$k2D;k$J%Q!<%H$rI=<($9$k$3$H$K$J$C$F$$\e(B
 329 \e$B$^$9!#$7$+$7!"%f!<%6!<$OBe$o$j$KB>$N%?%$%W$r9%$`$+$b$7$l$^$;$s!#$3$N%j%9\e(B
 330 \e$B%H$O!"2?$N%?%$%W$,:G$bK>$^$l$J$$$+$r<($7$^$9!#Nc$($P$b$7!"\e(B
 331 @samp{text/html} \e$B%Q!<%H$OHs>o$KK>$^$:!"$+$D\e(B @samp{text/richtext} \e$B%Q!<%H\e(B
 332 \e$B$r$d$dK>$^$J$$$H$$$&$3$H$G$"$l$P!"0J2<$N$h$&$K@k8@$9$k$3$H$,$G$-$^$9\e(B:
 333
 334 @lisp
 335 (setq mm-discouraged-alternatives
 336       '("text/html" "text/richtext")
 337       mm-automatic-display
 338       (remove "text/html" mm-automatic-display))
 339 @end lisp
 340
 341 @item mm-inline-large-images
 342 @vindex mm-inline-large-images
 343 \e$B%&%#%s%I%&$h$jBg$-$J%$%s%i%$%s2hA|$rI=<($9$k$H!"\e(BEmacs \e$B$O%9%/%m!<%k$9$k$3\e(B
 344 \e$B$H$,$G$-$J$$!"$D$^$j2hA|$NA4BN$r8+$k$3$H$,$G$-$^$;$s!#$3$l$rHr$1$k$?$a!"\e(B
 345 \e$B%i%$%V%i%j!<$O$=$l$r%$%s%i%$%sI=<($9$kA0$K2hA|$N%5%$%:$r7W$C$F!"$=$l$,\e(B
 346 \e$B%&%#%s%I%&$K9g$o$J$$>l9g$O!"%i%$%V%i%j!<$O$=$l$r30It$G\e(B (\e$BNc$(\e(B
 347 \e$B$P\e(B @samp{ImageMagick} \e$B$d\e(B @samp{xv} \e$B$G\e(B) \e$BI=<($7$^$9!#$3$NJQ?t\e(B
 348 \e$B$r\e(B @code{t} \e$B$K@_Dj$9$k$H$3$N8!::$r$5$;$J$/$7$F!"%i%$%V%i%j!<$K$9$Y$F$N%$\e(B
 349 \e$B%s%i%$%s2hA|$r%5%$%:$K4X$o$j$J$/%$%s%i%$%s$GI=<($5$;$^$9!#\e(B
 350
 351 @item mm-inline-override-types
 352 @vindex mm-inline-override-types
 353 @code{mm-inlined-types} \e$B$O!"Nc$($P$9$Y$F$N\e(B @samp{text/.*} \e$B%Q!<%H$r%$%s%i\e(B
 354 \e$B%$%s$GI=<($9$k$3$H$r;X<($9$k$h$&$J!"@55,I=8=$r4^$`$3$H$,$G$-$^$9!#0lJ}!"\e(B
 355 \e$B%$%s%i%$%sI=<($,2DG=$@$1$l$I$bE:IU$H$7$F07$$$?$$%?%$%W$,$"$k$J$i$P!"$=$N\e(B
 356 \e$B%?%$%W$K9gCW$9$k@55,I=8=$N%j%9%H$r!"$3$NJQ?t$K@_Dj$9$k$3$H$K$h$C$F@.$7?k\e(B
 357 \e$B$2$k$3$H$,$G$-$^$9!#Nc$($P\e(B @code{mm-inlined-types} \e$B$,\e(B @samp{text/.*} \e$B$r\e(B
 358 \e$B4^$s$G$$$k$b$N$H$9$k$H!"$3$NJQ?t$K\e(B @samp{text/html} \e$B$r4^$^$;$k$3$H$K$h$C\e(B
 359 \e$B$F!"\e(B@samp{text/html} \e$B%Q!<%H$OE:IU$H$7$F07$o$l$k$h$&$K$J$j$^$9!#\e(B
 360
 361 @item mm-text-html-renderer
 362 @vindex mm-text-html-renderer
 363 @acronym{HTML} \e$B$rIA2h$9$k$?$a$K;H$&4X?t$rA*Br$7$^$9!#$9$G$KMQ0U$7$F$"$k\e(B
 364 \e$BIA2h%W%m%0%i%`$O!"\e(B@code{w3}, @code{w3m}@footnote{emacs-w3m \e$B$K$D$$$F$N>\\e(B
 365 \e$B:Y$O\e(B @uref{http://emacs-w3m.namazu.org/} \e$B$r8+$F2<$5$$!#\e(B}, @code{links},
 366 @code{lynx}, @code{w3m-standalone} \e$B$^$?$O\e(B @code{html2text} \e$B$N%7%s%\%k72\e(B
 367 \e$B$N$&$A$N0l$D$r;XDj$9$k$3$H$K$h$C$FA*Br$7$^$9!#$b$7\e(B @code{nil} \e$B$@$C$?$i!"\e(B
 368 \e$B30It%S%e!<%o!<$r;H$$$^$9!#$5$i$K4X?t\e(B (\e$B0z?t$H$7$F\e(B @acronym{MIME} \e$B%O%s%I%k\e(B
 369 \e$B$,M?$($i$l$F8F$P$l$k\e(B) \e$B$r@_Dj$9$k$3$H$b$G$-$^$9!#\e(B
 370
 371 @item mm-inline-text-html-with-images
 372 @vindex mm-inline-text-html-with-images
 373 @acronym{HTML} \e$B%a!<%k$K$O\e(B @samp{<img>} \e$B%?%0$r;H$C$?\e(B spammers (spam \e$B$r$P\e(B
 374 \e$B$i$^$/$d$+$i\e(B) \e$B$NH\Nt$J0-9*$_$,4^$^$l$F$$$k$+$b$7$l$^$;$s!#:G$b$"$j$=$&$J\e(B
 375 \e$B$N$O!"$"$J$?$,$=$N%a!<%k$rFI$s$@$3$H$r3NG'$9$k$?$a$N0U?^$,$"$k$3$H$G$9!#\e(B
 376 \e$B$3$N%*%W%7%g%s$r\e(B @code{nil} \e$B$K@_Dj$9$k\e(B (\e$B$=$l$,%G%#%U%)%k%H$G$9\e(B) \e$B$3$H$K$h$C\e(B
 377 \e$B$F!"$"$J$?$N8D?M>pJs$,N.=P$9$k$N$rKI$0$3$H$,$G$-$^$9!#8=:_\e(B Emacs/w3 \e$B$O!"\e(B
 378 \e$B$3$l$rL5;k$7$^$9!#\e(BEmacs-w3m \e$B$G$O!"$3$l$,\e(B @code{nil} \e$B$G$"$C$F$b!"2hA|$rI=\e(B
 379 \e$B<($9$k$?$a$K!"$=$l$,Kd$a9~$^$l$?>l=j$G\e(B @kbd{t} \e$B%3%^%s%I$r;H$&$3$H$,$G$-\e(B
 380 \e$B$^$9!#\e(B@footnote{@kbd{T} \e$B%3%^%s%I$O$9$Y$F$N2hA|$r<h$j9~$_$^$9!#\e(B
 381 @code{w3m-key-binding} \e$B%*%W%7%g%s$r\e(B @code{info} \e$B$K@_Dj$7$?$J$i$P!"Be$o$j\e(B
 382 \e$B$K\e(B @kbd{i} \e$B$+\e(B @kbd{I} \e$B$r;H$C$F2<$5$$!#\e(B}
 383
 384 @item mm-w3m-safe-url-regexp
 385 @vindex mm-w3m-safe-url-regexp
 386 \e$B0BA4$J\e(B URL \e$BL>!"$9$J$o$A\e(B @acronym{HTML} \e$B%a!<%k$rIA2h$9$k$H$-$K8D?M>pJs$,\e(B
 387 \e$BN.=P$7$=$&$b$J$$\e(B URL \e$B$K9gCW$9$k@55,I=8=$G$9\e(B (\e$B%G%#%U%)%k%HCM\e(B
 388 \e$B$O\e(B @samp{\\`cid:} \e$B$G$9\e(B)\e$B!#\e(B@code{nil} \e$B$G$"$k$H!"$9$Y$F$N\e(B URL \e$B$,0BA4$@$HH=\e(B
 389 \e$BCG$7$^$9!#\e(B
 390
 391 @item mm-inline-text-html-with-w3m-keymap
 392 @vindex mm-inline-text-html-with-w3m-keymap
 393 \e$B$3$N%*%W%7%g%s$rHs\e(B-@code{nil} \e$B$K@_Dj$9$k$3$H$K$h$C$F!"%$%s%i%$%sI=<($5$l\e(B
 394 \e$B$?\e(B text/html \e$B%Q!<%H$G\e(B emacs-w3m \e$B$N%3%^%s%I%-!<$r;H$&$3$H$,$G$-$^$9!#%G%#\e(B
 395 \e$B%U%)%k%HCM$O\e(B @code{t} \e$B$G$9!#\e(B
 396
 397 @item mm-external-terminal-program
 398 @vindex mm-external-terminal-program
 399 \e$B30It$NC<Kv$r5/F0$9$k$?$a$K;H$o$l$k%W%m%0%i%`$G$9!#\e(B
 400
 401 @item mm-enable-external
 402 @vindex mm-enable-external
 403 \e$B30It$N\e(B @acronym{MIME} \e$B%O%s%I%i!<$r;H$&$Y$-$+$I$&$+$r;XDj$7$^$9!#\e(B
 404
 405 @code{t} \e$B$G$"$k$H!"Dj5A$5$l$?$9$Y$F$N30It$N\e(B @acronym{MIME} \e$B%O%s%I%i!<$,\e(B
 406 \e$B;H$o$l$^$9!#\e(B@code{nil} \e$B$@$C$?$i!"%U%!%$%k$O%G%#%9%/$KJ]B8$5$l$^\e(B
 407 \e$B$9\e(B (@code{mailcap-save-binary-file})\e$B!#$3$l$,\e(B @code{ask} \e$B$H$$$&%7%s%\%k$G\e(B
 408 \e$B$"$C$?$J$i$P!"30It$N\e(B @acronym{MIME} \e$B%O%s%I%i!<$,5/F0$5$l$kA0$K?R$M$i$l$k\e(B
 409 \e$B$G$7$g$&!#\e(B
 410
 411 Mailcap (@pxref{mailcap}) \e$B$r2p$7$FE:IU$NI=<($r;O$a$k$H!":G$b0BA4$J%*%W%7%g\e(B
 412 \e$B%s$G0BA4$J%S%e!<%o!<$r;H$&$3$H$r;n$_$^$9\e(B (\e$BE:IU$r%G%#%9%/$KJ]B8$7$F!"0[$J\e(B
 413 \e$B$k<jCJ\e(B (\e$B%3%^%s%I%i%$%s$+%@%V%k%/%j%C%/\e(B) \e$B$G$=$NI=<($r;O$a$k>l9g$H$O0c$$$^\e(B
 414 \e$B$9\e(B)\e$B!#$H$K$+$/!"$I$s$J30It%W%m%0%i%`$b;H$$$?$/$J$$$N$G$"$l$P!"$3$NJQ?t\e(B
 415 \e$B$r\e(B @code{nil} \e$B$+\e(B @code{ask} \e$B$K@_Dj$7$F2<$5$$!#\e(B
 416 @end table
 417
 418 @node Files and Directories
 419 @section Files and Directories
 420
 421 @table @code
 422
 423 @item mm-default-directory
 424 @vindex mm-default-directory
 425 The default directory for saving attachments.  If @code{nil} use
 426 @code{default-directory}.
 427
 428 @item mm-tmp-directory
 429 @vindex mm-tmp-directory
 430 Directory for storing temporary files.
 431
 432 @item mm-file-name-rewrite-functions
 433 @vindex mm-file-name-rewrite-functions
 434 A list of functions used for rewriting file names of @acronym{MIME}
 435 parts.  Each function is applied successively to the file name.
 436 Ready-made functions include
 437
 438 @table @code
 439 @item mm-file-name-delete-control
 440 @findex mm-file-name-delete-control
 441 Delete all control characters.
 442
 443 @item mm-file-name-delete-gotchas
 444 @findex mm-file-name-delete-gotchas
 445 Delete characters that could have unintended consequences when used
 446 with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and
 447 @samp{-}, @samp{.} as the first character.
 448
 449 @item mm-file-name-delete-whitespace
 450 @findex mm-file-name-delete-whitespace
 451 Remove all whitespace.
 452
 453 @item mm-file-name-trim-whitespace
 454 @findex mm-file-name-trim-whitespace
 455 Remove leading and trailing whitespace.
 456
 457 @item mm-file-name-collapse-whitespace
 458 @findex mm-file-name-collapse-whitespace
 459 Collapse multiple whitespace characters.
 460
 461 @item mm-file-name-replace-whitespace
 462 @findex mm-file-name-replace-whitespace
 463 @vindex mm-file-name-replace-whitespace
 464 Replace whitespace with underscores.  Set the variable
 465 @code{mm-file-name-replace-whitespace} to any other string if you do
 466 not like underscores.
 467 @end table
 468
 469 The standard Emacs functions @code{capitalize}, @code{downcase},
 470 @code{upcase} and @code{upcase-initials} might also prove useful.
 471
 472 @item mm-path-name-rewrite-functions
 473 @vindex mm-path-name-rewrite-functions
 474 List of functions used for rewriting the full file names of @acronym{MIME}
 475 parts.  This is used when viewing parts externally, and is meant for
 476 transforming the absolute name so that non-compliant programs can find
 477 the file where it's saved.
 478
 479 @end table
 480
 481 @node New Viewers
 482 @section New Viewers
 483
 484 Here's an example viewer for displaying @code{text/enriched} inline:
 485
 486 @lisp
 487 (defun mm-display-enriched-inline (handle)
 488   (let (text)
 489     (with-temp-buffer
 490       (mm-insert-part handle)
 491       (save-window-excursion
 492         (enriched-decode (point-min) (point-max))
 493         (setq text (buffer-string))))
 494     (mm-insert-inline handle text)))
 495 @end lisp
 496
 497 We see that the function takes a @acronym{MIME} handle as its parameter.  It
 498 then goes to a temporary buffer, inserts the text of the part, does some
 499 work on the text, stores the result, goes back to the buffer it was
 500 called from and inserts the result.
 501
 502 The two important helper functions here are @code{mm-insert-part} and
 503 @code{mm-insert-inline}.  The first function inserts the text of the
 504 handle in the current buffer.  It handles charset and/or content
 505 transfer decoding.  The second function just inserts whatever text you
 506 tell it to insert, but it also sets things up so that the text can be
 507 ``undisplayed'' in a convenient manner.
 508
 509
 510 @node Composing
 511 @chapter Composing
 512 @cindex Composing
 513 @cindex MIME Composing
 514 @cindex MML
 515 @cindex MIME Meta Language
 516
 517 Creating a @acronym{MIME} message is boring and non-trivial.  Therefore,
 518 a library called @code{mml} has been defined that parses a language
 519 called @acronym{MML} (@acronym{MIME} Meta Language) and generates
 520 @acronym{MIME} messages.
 521
 522 @findex mml-generate-mime
 523 The main interface function is @code{mml-generate-mime}.  It will
 524 examine the contents of the current (narrowed-to) buffer and return a
 525 string containing the @acronym{MIME} message.
 526
 527 @menu
 528 * Simple MML Example::             An example @acronym{MML} document.
 529 * MML Definition::                 All valid @acronym{MML} elements.
 530 * Advanced MML Example::           Another example @acronym{MML} document.
 531 * Encoding Customization::         Variables that affect encoding.
 532 * Charset Translation::            How charsets are mapped from @sc{mule} to @acronym{MIME}.
 533 * Conversion::                     Going from @acronym{MIME} to @acronym{MML} and vice versa.
 534 * Flowed text::                    Soft and hard newlines.
 535 @end menu
 536
 537
 538 @node Simple MML Example
 539 @section Simple MML Example
 540
 541 Here's a simple @samp{multipart/alternative}:
 542
 543 @example
 544 <#multipart type=alternative>
 545 This is a plain text part.
 546 <#part type=text/enriched>
 547 <center>This is a centered enriched part</center>
 548 <#/multipart>
 549 @end example
 550
 551 After running this through @code{mml-generate-mime}, we get this:
 552
 553 @example
 554 Content-Type: multipart/alternative; boundary="=-=-="
 555
 556
 557 --=-=-=
 558
 559
 560 This is a plain text part.
 561
 562 --=-=-=
 563 Content-Type: text/enriched
 564
 565
 566 <center>This is a centered enriched part</center>
 567
 568 --=-=-=--
 569 @end example
 570
 571
 572 @node MML Definition
 573 @section MML Definition
 574
 575 The @acronym{MML} language is very simple.  It looks a bit like an SGML
 576 application, but it's not.
 577
 578 The main concept of @acronym{MML} is the @dfn{part}.  Each part can be of a
 579 different type or use a different charset.  The way to delineate a part
 580 is with a @samp{<#part ...>} tag.  Multipart parts can be introduced
 581 with the @samp{<#multipart ...>} tag.  Parts are ended by the
 582 @samp{<#/part>} or @samp{<#/multipart>} tags.  Parts started with the
 583 @samp{<#part ...>} tags are also closed by the next open tag.
 584
 585 There's also the @samp{<#external ...>} tag.  These introduce
 586 @samp{external/message-body} parts.
 587
 588 Each tag can contain zero or more parameters on the form
 589 @samp{parameter=value}.  The values may be enclosed in quotation marks,
 590 but that's not necessary unless the value contains white space.  So
 591 @samp{filename=/home/user/#hello$^yes} is perfectly valid.
 592
 593 The following parameters have meaning in @acronym{MML}; parameters that have no
 594 meaning are ignored.  The @acronym{MML} parameter names are the same as the
 595 @acronym{MIME} parameter names; the things in the parentheses say which
 596 header it will be used in.
 597
 598 @table @samp
 599 @item type
 600 The @acronym{MIME} type of the part (@code{Content-Type}).
 601
 602 @item filename
 603 Use the contents of the file in the body of the part
 604 (@code{Content-Disposition}).
 605
 606 @item charset
 607 The contents of the body of the part are to be encoded in the character
 608 set specified (@code{Content-Type}). @xref{Charset Translation}.
 609
 610 @item name
 611 Might be used to suggest a file name if the part is to be saved
 612 to a file (@code{Content-Type}).
 613
 614 @item disposition
 615 Valid values are @samp{inline} and @samp{attachment}
 616 (@code{Content-Disposition}).
 617
 618 @item encoding
 619 Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
 620 @samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset
 621 Translation}.
 622
 623 @item description
 624 A description of the part (@code{Content-Description}).
 625
 626 @item creation-date
 627 RFC822 date when the part was created (@code{Content-Disposition}).
 628
 629 @item modification-date
 630 RFC822 date when the part was modified (@code{Content-Disposition}).
 631
 632 @item read-date
 633 RFC822 date when the part was read (@code{Content-Disposition}).
 634
 635 @item recipients
 636 Who to encrypt/sign the part to.  This field is used to override any
 637 auto-detection based on the To/CC headers.
 638
 639 @item sender
 640 Identity used to sign the part.  This field is used to override the
 641 default key used.
 642
 643 @item size
 644 The size (in octets) of the part (@code{Content-Disposition}).
 645
 646 @item sign
 647 What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp}
 648 or @code{pgpmime})
 649
 650 @item encrypt
 651 What technology to encrypt this @acronym{MML} part with (@code{smime},
 652 @code{pgp} or @code{pgpmime})
 653
 654 @end table
 655
 656 Parameters for @samp{text/plain}:
 657
 658 @table @samp
 659 @item format
 660 Formatting parameter for the text, valid values include @samp{fixed}
 661 (the default) and @samp{flowed}.  Normally you do not specify this
 662 manually, since it requires the textual body to be formatted in a
 663 special way described in RFC 2646.  @xref{Flowed text}.
 664 @end table
 665
 666 Parameters for @samp{application/octet-stream}:
 667
 668 @table @samp
 669 @item type
 670 Type of the part; informal---meant for human readers
 671 (@code{Content-Type}).
 672 @end table
 673
 674 Parameters for @samp{message/external-body}:
 675
 676 @table @samp
 677 @item access-type
 678 A word indicating the supported access mechanism by which the file may
 679 be obtained.  Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
 680 @samp{localfile}, and @samp{mailserver}.  (@code{Content-Type}.)
 681
 682 @item expiration
 683 The RFC822 date after which the file may no longer be fetched.
 684 (@code{Content-Type}.)
 685
 686 @item size
 687 The size (in octets) of the file.  (@code{Content-Type}.)
 688
 689 @item permission
 690 Valid values are @samp{read} and @samp{read-write}
 691 (@code{Content-Type}).
 692
 693 @end table
 694
 695 Parameters for @samp{sign=smime}:
 696
 697 @table @samp
 698
 699 @item keyfile
 700 File containing key and certificate for signer.
 701
 702 @end table
 703
 704 Parameters for @samp{encrypt=smime}:
 705
 706 @table @samp
 707
 708 @item certfile
 709 File containing certificate for recipient.
 710
 711 @end table
 712
 713
 714 @node Advanced MML Example
 715 @section Advanced MML Example
 716
 717 Here's a complex multipart message.  It's a @samp{multipart/mixed} that
 718 contains many parts, one of which is a @samp{multipart/alternative}.
 719
 720 @example
 721 <#multipart type=mixed>
 722 <#part type=image/jpeg filename=~/rms.jpg disposition=inline>
 723 <#multipart type=alternative>
 724 This is a plain text part.
 725 <#part type=text/enriched name=enriched.txt>
 726 <center>This is a centered enriched part</center>
 727 <#/multipart>
 728 This is a new plain text part.
 729 <#part disposition=attachment>
 730 This plain text part is an attachment.
 731 <#/multipart>
 732 @end example
 733
 734 And this is the resulting @acronym{MIME} message:
 735
 736 @example
 737 Content-Type: multipart/mixed; boundary="=-=-="
 738
 739
 740 --=-=-=
 741
 742
 743
 744 --=-=-=
 745 Content-Type: image/jpeg;
 746  filename="~/rms.jpg"
 747 Content-Disposition: inline;
 748  filename="~/rms.jpg"
 749 Content-Transfer-Encoding: base64
 750
 751 /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
 752 Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
 753 AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
 754 BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
 755 RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
 756 qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
 757 AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
 758 AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
 759 sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
 760 2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
 761 5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
 762 L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
 763 34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
 764 tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
 765 7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
 766 pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
 767 jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
 768
 769 --=-=-=
 770 Content-Type: multipart/alternative; boundary="==-=-="
 771
 772
 773 --==-=-=
 774
 775
 776 This is a plain text part.
 777
 778 --==-=-=
 779 Content-Type: text/enriched;
 780  name="enriched.txt"
 781
 782
 783 <center>This is a centered enriched part</center>
 784
 785 --==-=-=--
 786
 787 --=-=-=
 788
 789 This is a new plain text part.
 790
 791 --=-=-=
 792 Content-Disposition: attachment
 793
 794
 795 This plain text part is an attachment.
 796
 797 --=-=-=--
 798 @end example
 799
 800 @node Encoding Customization
 801 @section Encoding Customization
 802
 803 @table @code
 804
 805 @item mm-body-charset-encoding-alist
 806 @vindex mm-body-charset-encoding-alist
 807 Mapping from @acronym{MIME} charset to encoding to use.  This variable is
 808 usually used except, e.g., when other requirements force a specific
 809 encoding (digitally signed messages require 7bit encodings).  The
 810 default is
 811
 812 @lisp
 813 ((iso-2022-jp . 7bit)
 814  (iso-2022-jp-2 . 7bit)
 815  (utf-16 . base64)
 816  (utf-16be . base64)
 817  (utf-16le . base64))
 818 @end lisp
 819
 820 As an example, if you do not want to have ISO-8859-1 characters
 821 quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to
 822 this variable.  You can override this setting on a per-message basis
 823 by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}).
 824
 825 @item mm-coding-system-priorities
 826 @vindex mm-coding-system-priorities
 827 Prioritize coding systems to use for outgoing messages.  The default
 828 is @code{nil}, which means to use the defaults in Emacs.  It is a list of
 829 coding system symbols (aliases of coding systems are also allowed, use
 830 @kbd{M-x describe-coding-system} to make sure you are specifying correct
 831 coding system names).  For example, if you have configured Emacs
 832 to prefer UTF-8, but wish that outgoing messages should be sent in
 833 ISO-8859-1 if possible, you can set this variable to
 834 @code{(iso-8859-1)}.  You can override this setting on a per-message
 835 basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}).
 836
 837 @item mm-content-transfer-encoding-defaults
 838 @vindex mm-content-transfer-encoding-defaults
 839 Mapping from @acronym{MIME} types to encoding to use.  This variable is usually
 840 used except, e.g., when other requirements force a safer encoding
 841 (digitally signed messages require 7bit encoding).  Besides the normal
 842 @acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for
 843 each case the most efficient of quoted-printable and base64 should be
 844 used.
 845
 846 @code{qp-or-base64} has another effect.  It will fold long lines so that
 847 MIME parts may not be broken by MTA.  So do @code{quoted-printable} and
 848 @code{base64}.
 849
 850 Note that it affects body encoding only when a part is a raw forwarded
 851 message (which will be made by @code{gnus-summary-mail-forward} with the
 852 arg 2 for example) or is neither the @samp{text/*} type nor the
 853 @samp{message/*} type.  Even though in those cases, you can override
 854 this setting on a per-message basis by using the @code{encoding}
 855 @acronym{MML} tag (@pxref{MML Definition}).
 856
 857 @item mm-use-ultra-safe-encoding
 858 @vindex mm-use-ultra-safe-encoding
 859 When this is non-@code{nil}, it means that textual parts are encoded as
 860 quoted-printable if they contain lines longer than 76 characters or
 861 starting with "From " in the body.  Non-7bit encodings (8bit, binary)
 862 are generally disallowed.  This reduce the probability that a non-8bit
 863 clean MTA or MDA changes the message.  This should never be set
 864 directly, but bound by other functions when necessary (e.g., when
 865 encoding messages that are to be digitally signed).
 866
 867 @end table
 868
 869 @node Charset Translation
 870 @section Charset Translation
 871 @cindex charsets
 872
 873 During translation from @acronym{MML} to @acronym{MIME}, for each
 874 @acronym{MIME} part which has been composed inside Emacs, an appropriate
 875 charset has to be chosen.
 876
 877 @vindex mail-parse-charset
 878 If you are running a non-@sc{mule} Emacs, this process is simple: If the
 879 part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset
 880 given by @code{mail-parse-charset} (a symbol) is used.  (Never set this
 881 variable directly, though.  If you want to change the default charset,
 882 please consult the documentation of the package which you use to process
 883 @acronym{MIME} messages.
 884 @xref{Various Message Variables, , Various Message Variables, message,
 885       Message Manual}, for example.)
 886 If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is
 887 used, of course.
 888
 889 @cindex MULE
 890 @cindex UTF-8
 891 @cindex Unicode
 892 @vindex mm-mime-mule-charset-alist
 893 Things are slightly more complicated when running Emacs with @sc{mule}
 894 support.  In this case, a list of the @sc{mule} charsets used in the
 895 part is obtained, and the @sc{mule} charsets are translated to @acronym{MIME}
 896 charsets by consulting the variable @code{mm-mime-mule-charset-alist}.
 897 If this results in a single @acronym{MIME} charset, this is used to encode
 898 the part.  But if the resulting list of @acronym{MIME} charsets contains more
 899 than one element, two things can happen: If it is possible to encode the
 900 part via UTF-8, this charset is used.  (For this, Emacs must support
 901 the @code{utf-8} coding system, and the part must consist entirely of
 902 characters which have Unicode counterparts.)  If UTF-8 is not available
 903 for some reason, the part is split into several ones, so that each one
 904 can be encoded with a single @acronym{MIME} charset.  The part can only be
 905 split at line boundaries, though---if more than one @acronym{MIME} charset is
 906 required to encode a single line, it is not possible to encode the part.
 907
 908 When running Emacs with @sc{mule} support, the preferences for which
 909 coding system to use is inherited from Emacs itself.  This means that
 910 if Emacs is set up to prefer UTF-8, it will be used when encoding
 911 messages.  You can modify this by altering the
 912 @code{mm-coding-system-priorities} variable though (@pxref{Encoding
 913 Customization}).
 914
 915 The charset to be used can be overridden by setting the @code{charset}
 916 @acronym{MML} tag (@pxref{MML Definition}) when composing the message.
 917
 918 The encoding of characters (quoted-printable, 8bit etc) is orthogonal
 919 to the discussion here, and is controlled by the variables
 920 @code{mm-body-charset-encoding-alist} and
 921 @code{mm-content-transfer-encoding-defaults} (@pxref{Encoding
 922 Customization}).
 923
 924 @node Conversion
 925 @section Conversion
 926
 927 @findex mime-to-mml
 928 A (multipart) @acronym{MIME} message can be converted to @acronym{MML}
 929 with the @code{mime-to-mml} function.  It works on the message in the
 930 current buffer, and substitutes @acronym{MML} markup for @acronym{MIME}
 931 boundaries.  Non-textual parts do not have their contents in the buffer,
 932 but instead have the contents in separate buffers that are referred to
 933 from the @acronym{MML} tags.
 934
 935 @findex mml-to-mime
 936 An @acronym{MML} message can be converted back to @acronym{MIME} by the
 937 @code{mml-to-mime} function.
 938
 939 These functions are in certain senses ``lossy''---you will not get back
 940 an identical message if you run @code{mime-to-mml} and then
 941 @code{mml-to-mime}.  Not only will trivial things like the order of the
 942 headers differ, but the contents of the headers may also be different.
 943 For instance, the original message may use base64 encoding on text,
 944 while @code{mml-to-mime} may decide to use quoted-printable encoding, and
 945 so on.
 946
 947 In essence, however, these two functions should be the inverse of each
 948 other.  The resulting contents of the message should remain equivalent,
 949 if not identical.
 950
 951
 952 @node Flowed text
 953 @section Flowed text
 954 @cindex format=flowed
 955
 956 The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines}
 957 variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines,
 958 emacs, Emacs Manual}) when encoding a message, and the
 959 ``format=flowed'' Content-Type parameter when decoding a message.
 960
 961 On encoding text, regardless of @code{use-hard-newlines}, lines
 962 terminated by soft newline characters are filled together and wrapped
 963 after the column decided by @code{fill-flowed-encode-column}.
 964 Quotation marks (matching @samp{^>* ?}) are respected.  The variable
 965 controls how the text will look in a client that does not support
 966 flowed text, the default is to wrap after 66 characters.  If hard
 967 newline characters are not present in the buffer, no flow encoding
 968 occurs.
 969
 970 On decoding flowed text, lines with soft newline characters are filled
 971 together and wrapped after the column decided by
 972 @code{fill-flowed-display-column}.  The default is to wrap after
 973 @code{fill-column}.
 974
 975 @table @code
 976 @item mm-fill-flowed
 977 @vindex mm-fill-flowed
 978 If non-@code{nil} a format=flowed article will be displayed flowed.
 979 @end table
 980
 981
 982 @node Interface Functions
 983 @chapter Interface Functions
 984 @cindex interface functions
 985 @cindex mail-parse
 986
 987 The @code{mail-parse} library is an abstraction over the actual
 988 low-level libraries that are described in the next chapter.
 989
 990 Standards change, and so programs have to change to fit in the new
 991 mold.  For instance, RFC2045 describes a syntax for the
 992 @code{Content-Type} header that only allows @acronym{ASCII} characters in the
 993 parameter list.  RFC2231 expands on RFC2045 syntax to provide a scheme
 994 for continuation headers and non-@acronym{ASCII} characters.
 995
 996 The traditional way to deal with this is just to update the library
 997 functions to parse the new syntax.  However, this is sometimes the wrong
 998 thing to do.  In some instances it may be vital to be able to understand
 999 both the old syntax as well as the new syntax, and if there is only one
1000 library, one must choose between the old version of the library and the
1001 new version of the library.
1002
1003 The Emacs @acronym{MIME} library takes a different tack.  It defines a
1004 series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el}
1005 and so on) that parses strictly according to the corresponding
1006 standard.  However, normal programs would not use the functions
1007 provided by these libraries directly, but instead use the functions
1008 provided by the @code{mail-parse} library.  The functions in this
1009 library are just aliases to the corresponding functions in the latest
1010 low-level libraries.  Using this scheme, programs get a consistent
1011 interface they can use, and library developers are free to create
1012 write code that handles new standards.
1013
1014 The following functions are defined by this library:
1015
1016 @table @code
1017 @item mail-header-parse-content-type
1018 @findex mail-header-parse-content-type
1019 Parse a @code{Content-Type} header and return a list on the following
1020 format:
1021
1022 @lisp
1023 ("type/subtype"
1024  (attribute1 . value1)
1025  (attribute2 . value2)
1026  ...)
1027 @end lisp
1028
1029 Here's an example:
1030
1031 @example
1032 (mail-header-parse-content-type
1033  "image/gif; name=\"b980912.gif\"")
1034 @result{} ("image/gif" (name . "b980912.gif"))
1035 @end example
1036
1037 @item mail-header-parse-content-disposition
1038 @findex mail-header-parse-content-disposition
1039 Parse a @code{Content-Disposition} header and return a list on the same
1040 format as the function above.
1041
1042 @item mail-content-type-get
1043 @findex mail-content-type-get
1044 Takes two parameters---a list on the format above, and an attribute.
1045 Returns the value of the attribute.
1046
1047 @example
1048 (mail-content-type-get
1049  '("image/gif" (name . "b980912.gif")) 'name)
1050 @result{} "b980912.gif"
1051 @end example
1052
1053 @item mail-header-encode-parameter
1054 @findex mail-header-encode-parameter
1055 Takes a parameter string and returns an encoded version of the string.
1056 This is used for parameters in headers like @code{Content-Type} and
1057 @code{Content-Disposition}.
1058
1059 @item mail-header-remove-comments
1060 @findex mail-header-remove-comments
1061 Return a comment-free version of a header.
1062
1063 @example
1064 (mail-header-remove-comments
1065  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1066 @result{} "Gnus/5.070027  "
1067 @end example
1068
1069 @item mail-header-remove-whitespace
1070 @findex mail-header-remove-whitespace
1071 Remove linear white space from a header.  Space inside quoted strings
1072 and comments is preserved.
1073
1074 @example
1075 (mail-header-remove-whitespace
1076  "image/gif; name=\"Name with spaces\"")
1077 @result{} "image/gif;name=\"Name with spaces\""
1078 @end example
1079
1080 @item mail-header-get-comment
1081 @findex mail-header-get-comment
1082 Return the last comment in a header.
1083
1084 @example
1085 (mail-header-get-comment
1086  "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
1087 @result{} "Finnish Landrace"
1088 @end example
1089
1090 @item mail-header-parse-address
1091 @findex mail-header-parse-address
1092 Parse an address and return a list containing the mailbox and the
1093 plaintext name.
1094
1095 @example
1096 (mail-header-parse-address
1097  "Hrvoje Niksic <hniksic@@srce.hr>")
1098 @result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
1099 @end example
1100
1101 @item mail-header-parse-addresses
1102 @findex mail-header-parse-addresses
1103 Parse a string with list of addresses and return a list of elements like
1104 the one described above.
1105
1106 @example
1107 (mail-header-parse-addresses
1108  "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
1109 @result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
1110      ("sb@@metis.no" . "Steinar Bang"))
1111 @end example
1112
1113 @item mail-header-parse-date
1114 @findex mail-header-parse-date
1115 Parse a date string and return an Emacs time structure.
1116
1117 @item mail-narrow-to-head
1118 @findex mail-narrow-to-head
1119 Narrow the buffer to the header section of the buffer.  Point is placed
1120 at the beginning of the narrowed buffer.
1121
1122 @item mail-header-narrow-to-field
1123 @findex mail-header-narrow-to-field
1124 Narrow the buffer to the header under point.  Understands continuation
1125 headers.
1126
1127 @item mail-header-fold-field
1128 @findex mail-header-fold-field
1129 Fold the header under point.
1130
1131 @item mail-header-unfold-field
1132 @findex mail-header-unfold-field
1133 Unfold the header under point.
1134
1135 @item mail-header-field-value
1136 @findex mail-header-field-value
1137 Return the value of the field under point.
1138
1139 @item mail-encode-encoded-word-region
1140 @findex mail-encode-encoded-word-region
1141 Encode the non-@acronym{ASCII} words in the region.  For instance,
1142 @samp{Na@"{@dotless{i}}ve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
1143
1144 @item mail-encode-encoded-word-buffer
1145 @findex mail-encode-encoded-word-buffer
1146 Encode the non-@acronym{ASCII} words in the current buffer.  This function is
1147 meant to be called narrowed to the headers of a message.
1148
1149 @item mail-encode-encoded-word-string
1150 @findex mail-encode-encoded-word-string
1151 Encode the words that need encoding in a string, and return the result.
1152
1153 @example
1154 (mail-encode-encoded-word-string
1155  "This is na@"{@dotless{i}}ve, baby")
1156 @result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
1157 @end example
1158
1159 @item mail-decode-encoded-word-region
1160 @findex mail-decode-encoded-word-region
1161 Decode the encoded words in the region.
1162
1163 @item mail-decode-encoded-word-string
1164 @findex mail-decode-encoded-word-string
1165 Decode the encoded words in the string and return the result.
1166
1167 @example
1168 (mail-decode-encoded-word-string
1169  "This is =?iso-8859-1?q?na=EFve,?= baby")
1170 @result{} "This is na@"{@dotless{i}}ve, baby"
1171 @end example
1172
1173 @end table
1174
1175 Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
1176 @code{rfc2047}, @code{rfc2045} and @code{rfc2231}.  These are documented
1177 in the subsequent sections.
1178
1179
1180
1181 @node Basic Functions
1182 @chapter Basic Functions
1183
1184 This chapter describes the basic, ground-level functions for parsing and
1185 handling.  Covered here is parsing @code{From} lines, removing comments
1186 from header lines, decoding encoded words, parsing date headers and so
1187 on.  High-level functionality is dealt with in the next chapter
1188 (@pxref{Decoding and Viewing}).
1189
1190 @menu
1191 * rfc2045::      Encoding @code{Content-Type} headers.
1192 * rfc2231::      Parsing @code{Content-Type} headers.
1193 * ietf-drums::   Handling mail headers defined by RFC822bis.
1194 * rfc2047::      En/decoding encoded words in headers.
1195 * time-date::    Functions for parsing dates and manipulating time.
1196 * qp::           Quoted-Printable en/decoding.
1197 * base64::       Base64 en/decoding.
1198 * binhex::       Binhex decoding.
1199 * uudecode::     Uuencode decoding.
1200 * yenc::         Yenc decoding.
1201 * rfc1843::      Decoding HZ-encoded text.
1202 * mailcap::      How parts are displayed is specified by the @file{.mailcap} file
1203 @end menu
1204
1205
1206 @node rfc2045
1207 @section rfc2045
1208
1209 RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would
1210 imagine that there would be a lot to implement.  But there isn't, since
1211 most of the implementation details are delegated to the subsequent
1212 RFCs.
1213
1214 So @file{rfc2045.el} has only a single function:
1215
1216 @table @code
1217 @item rfc2045-encode-string
1218 @findex rfc2045-encode-string
1219 Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
1220 @var{value} will be quoted if there are non-safe characters in it.
1221 @end table
1222
1223
1224 @node rfc2231
1225 @section rfc2231
1226
1227 RFC2231 defines a syntax for the @code{Content-Type} and
1228 @code{Content-Disposition} headers.  Its snappy name is @dfn{MIME
1229 Parameter Value and Encoded Word Extensions: Character Sets, Languages,
1230 and Continuations}.
1231
1232 In short, these headers look something like this:
1233
1234 @example
1235 Content-Type: application/x-stuff;
1236  title*0*=us-ascii'en'This%20is%20even%20more%20;
1237  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1238  title*2="isn't it!"
1239 @end example
1240
1241 They usually aren't this bad, though.
1242
1243 The following functions are defined by this library:
1244
1245 @table @code
1246 @item rfc2231-parse-string
1247 @findex rfc2231-parse-string
1248 Parse a @code{Content-Type} header and return a list describing its
1249 elements.
1250
1251 @example
1252 (rfc2231-parse-string
1253  "application/x-stuff;
1254  title*0*=us-ascii'en'This%20is%20even%20more%20;
1255  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
1256  title*2=\"isn't it!\"")
1257 @result{} ("application/x-stuff"
1258     (title . "This is even more ***fun*** isn't it!"))
1259 @end example
1260
1261 @item rfc2231-get-value
1262 @findex rfc2231-get-value
1263 Takes one of the lists on the format above and returns
1264 the value of the specified attribute.
1265
1266 @item rfc2231-encode-string
1267 @findex rfc2231-encode-string
1268 Encode a parameter in headers likes @code{Content-Type} and
1269 @code{Content-Disposition}.
1270
1271 @end table
1272
1273
1274 @node ietf-drums
1275 @section ietf-drums
1276
1277 @dfn{drums} is an IETF working group that is working on the replacement
1278 for RFC822.
1279
1280 The functions provided by this library include:
1281
1282 @table @code
1283 @item ietf-drums-remove-comments
1284 @findex ietf-drums-remove-comments
1285 Remove the comments from the argument and return the results.
1286
1287 @item ietf-drums-remove-whitespace
1288 @findex ietf-drums-remove-whitespace
1289 Remove linear white space from the string and return the results.
1290 Spaces inside quoted strings and comments are left untouched.
1291
1292 @item ietf-drums-get-comment
1293 @findex ietf-drums-get-comment
1294 Return the last most comment from the string.
1295
1296 @item ietf-drums-parse-address
1297 @findex ietf-drums-parse-address
1298 Parse an address string and return a list that contains the mailbox and
1299 the plain text name.
1300
1301 @item ietf-drums-parse-addresses
1302 @findex ietf-drums-parse-addresses
1303 Parse a string that contains any number of comma-separated addresses and
1304 return a list that contains mailbox/plain text pairs.
1305
1306 @item ietf-drums-parse-date
1307 @findex ietf-drums-parse-date
1308 Parse a date string and return an Emacs time structure.
1309
1310 @item ietf-drums-narrow-to-header
1311 @findex ietf-drums-narrow-to-header
1312 Narrow the buffer to the header section of the current buffer.
1313
1314 @end table
1315
1316
1317 @node rfc2047
1318 @section rfc2047
1319
1320 RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how
1321 non-@acronym{ASCII} text in headers are to be encoded.  This is actually rather
1322 complicated, so a number of variables are necessary to tweak what this
1323 library does.
1324
1325 The following variables are tweakable:
1326
1327 @table @code
1328 @item rfc2047-header-encoding-alist
1329 @vindex rfc2047-header-encoding-alist
1330 This is an alist of header / encoding-type pairs.  Its main purpose is
1331 to prevent encoding of certain headers.
1332
1333 The keys can either be header regexps, or @code{t}.
1334
1335 The values can be @code{nil}, in which case the header(s) in question
1336 won't be encoded, @code{mime}, which means that they will be encoded, or
1337 @code{address-mime}, which means the header(s) will be encoded carefully
1338 assuming they contain addresses.
1339
1340 @item rfc2047-charset-encoding-alist
1341 @vindex rfc2047-charset-encoding-alist
1342 RFC2047 specifies two forms of encoding---@code{Q} (a
1343 Quoted-Printable-like encoding) and @code{B} (base64).  This alist
1344 specifies which charset should use which encoding.
1345
1346 @item rfc2047-encode-function-alist
1347 @vindex rfc2047-encode-function-alist
1348 This is an alist of encoding / function pairs.  The encodings are
1349 @code{Q}, @code{B} and @code{nil}.
1350
1351 @item rfc2047-encoded-word-regexp
1352 @vindex rfc2047-encoded-word-regexp
1353 When decoding words, this library looks for matches to this regexp.
1354
1355 @item rfc2047-encode-encoded-words
1356 @vindex rfc2047-encode-encoded-words
1357 The boolean variable specifies whether encoded words
1358 (e.g. @samp{=?hello?=}) should be encoded again.
1359
1360 @end table
1361
1362 Those were the variables, and these are this functions:
1363
1364 @table @code
1365 @item rfc2047-narrow-to-field
1366 @findex rfc2047-narrow-to-field
1367 Narrow the buffer to the header on the current line.
1368
1369 @item rfc2047-encode-message-header
1370 @findex rfc2047-encode-message-header
1371 Should be called narrowed to the header of a message.  Encodes according
1372 to @code{rfc2047-header-encoding-alist}.
1373
1374 @item rfc2047-encode-region
1375 @findex rfc2047-encode-region
1376 Encodes all encodable words in the region specified.
1377
1378 @item rfc2047-encode-string
1379 @findex rfc2047-encode-string
1380 Encode a string and return the results.
1381
1382 @item rfc2047-decode-region
1383 @findex rfc2047-decode-region
1384 Decode the encoded words in the region.
1385
1386 @item rfc2047-decode-string
1387 @findex rfc2047-decode-string
1388 Decode a string and return the results.
1389
1390 @item rfc2047-encode-parameter
1391 @findex rfc2047-encode-parameter
1392 Encode a parameter in the RFC2047-like style.  This is a replacement for
1393 the @code{rfc2231-encode-string} function.  @xref{rfc2231}.
1394
1395 When attaching files as @acronym{MIME} parts, we should use the RFC2231
1396 encoding to specify the file names containing non-@acronym{ASCII}
1397 characters.  However, many mail softwares don't support it in practice
1398 and recipients won't be able to extract files with correct names.
1399 Instead, the RFC2047-like encoding is acceptable generally.  This
1400 function provides the very RFC2047-like encoding, resigning to such a
1401 regrettable trend.  To use it, put the following line in your
1402 @file{~/.gnus.el} file:
1403
1404 @lisp
1405 (defalias 'mail-header-encode-parameter 'rfc2047-encode-parameter)
1406 @end lisp
1407
1408 @end table
1409
1410
1411 @node time-date
1412 @section time-date
1413
1414 While not really a part of the @acronym{MIME} library, it is convenient to
1415 document this library here.  It deals with parsing @code{Date} headers
1416 and manipulating time.  (Not by using tesseracts, though, I'm sorry to
1417 say.)
1418
1419 These functions convert between five formats: A date string, an Emacs
1420 time structure, a decoded time list, a second number, and a day number.
1421
1422 Here's a bunch of time/date/second/day examples:
1423
1424 @example
1425 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
1426 @result{} (54 21 12 12 9 1998 6 nil 7200)
1427
1428 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
1429 @result{} (13818 19266)
1430
1431 (time-to-seconds '(13818 19266))
1432 @result{} 905595714.0
1433
1434 (seconds-to-time 905595714.0)
1435 @result{} (13818 19266 0)
1436
1437 (time-to-days '(13818 19266))
1438 @result{} 729644
1439
1440 (days-to-time 729644)
1441 @result{} (961933 65536)
1442
1443 (time-since '(13818 19266))
1444 @result{} (0 430)
1445
1446 (time-less-p '(13818 19266) '(13818 19145))
1447 @result{} nil
1448
1449 (subtract-time '(13818 19266) '(13818 19145))
1450 @result{} (0 121)
1451
1452 (days-between "Sat Sep 12 12:21:54 1998 +0200"
1453               "Sat Sep 07 12:21:54 1998 +0200")
1454 @result{} 5
1455
1456 (date-leap-year-p 2000)
1457 @result{} t
1458
1459 (time-to-day-in-year '(13818 19266))
1460 @result{} 255
1461
1462 (time-to-number-of-days
1463  (time-since
1464   (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
1465 @result{} 4.146122685185185
1466 @end example
1467
1468 And finally, we have @code{safe-date-to-time}, which does the same as
1469 @code{date-to-time}, but returns a zero time if the date is
1470 syntactically malformed.
1471
1472 The five data representations used are the following:
1473
1474 @table @var
1475 @item date
1476 An RFC822 (or similar) date string.  For instance: @code{"Sat Sep 12
1477 12:21:54 1998 +0200"}.
1478
1479 @item time
1480 An internal Emacs time.  For instance: @code{(13818 26466)}.
1481
1482 @item seconds
1483 A floating point representation of the internal Emacs time.  For
1484 instance: @code{905595714.0}.
1485
1486 @item days
1487 An integer number representing the number of days since 00000101.  For
1488 instance: @code{729644}.
1489
1490 @item decoded time
1491 A list of decoded time.  For instance: @code{(54 21 12 12 9 1998 6 t
1492 7200)}.
1493 @end table
1494
1495 All the examples above represent the same moment.
1496
1497 These are the functions available:
1498
1499 @table @code
1500 @item date-to-time
1501 Take a date and return a time.
1502
1503 @item time-to-seconds
1504 Take a time and return seconds.
1505
1506 @item seconds-to-time
1507 Take seconds and return a time.
1508
1509 @item time-to-days
1510 Take a time and return days.
1511
1512 @item days-to-time
1513 Take days and return a time.
1514
1515 @item date-to-day
1516 Take a date and return days.
1517
1518 @item time-to-number-of-days
1519 Take a time and return the number of days that represents.
1520
1521 @item safe-date-to-time
1522 Take a date and return a time.  If the date is not syntactically valid,
1523 return a ``zero'' date.
1524
1525 @item time-less-p
1526 Take two times and say whether the first time is less (i. e., earlier)
1527 than the second time.
1528
1529 @item time-since
1530 Take a time and return a time saying how long it was since that time.
1531
1532 @item subtract-time
1533 Take two times and subtract the second from the first.  I. e., return
1534 the time between the two times.
1535
1536 @item days-between
1537 Take two days and return the number of days between those two days.
1538
1539 @item date-leap-year-p
1540 Take a year number and say whether it's a leap year.
1541
1542 @item time-to-day-in-year
1543 Take a time and return the day number within the year that the time is
1544 in.
1545
1546 @end table
1547
1548
1549 @node qp
1550 @section qp
1551
1552 This library deals with decoding and encoding Quoted-Printable text.
1553
1554 Very briefly explained, qp encoding means translating all 8-bit
1555 characters (and lots of control characters) into things that look like
1556 @samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
1557 string.
1558
1559 The following functions are defined by the library:
1560
1561 @table @code
1562 @item quoted-printable-decode-region
1563 @findex quoted-printable-decode-region
1564 QP-decode all the encoded text in the specified region.
1565
1566 @item quoted-printable-decode-string
1567 @findex quoted-printable-decode-string
1568 Decode the QP-encoded text in a string and return the results.
1569
1570 @item quoted-printable-encode-region
1571 @findex quoted-printable-encode-region
1572 QP-encode all the encodable characters in the specified region.  The third
1573 optional parameter @var{fold} specifies whether to fold long lines.
1574 (Long here means 72.)
1575
1576 @item quoted-printable-encode-string
1577 @findex quoted-printable-encode-string
1578 QP-encode all the encodable characters in a string and return the
1579 results.
1580
1581 @end table
1582
1583
1584 @node base64
1585 @section base64
1586 @cindex base64
1587
1588 Base64 is an encoding that encodes three bytes into four characters,
1589 thereby increasing the size by about 33%.  The alphabet used for
1590 encoding is very resistant to mangling during transit.
1591
1592 The following functions are defined by this library:
1593
1594 @table @code
1595 @item base64-encode-region
1596 @findex base64-encode-region
1597 base64 encode the selected region.  Return the length of the encoded
1598 text.  Optional third argument @var{no-line-break} means do not break
1599 long lines into shorter lines.
1600
1601 @item base64-encode-string
1602 @findex base64-encode-string
1603 base64 encode a string and return the result.
1604
1605 @item base64-decode-region
1606 @findex base64-decode-region
1607 base64 decode the selected region.  Return the length of the decoded
1608 text.  If the region can't be decoded, return @code{nil} and don't
1609 modify the buffer.
1610
1611 @item base64-decode-string
1612 @findex base64-decode-string
1613 base64 decode a string and return the result.  If the string can't be
1614 decoded, @code{nil} is returned.
1615
1616 @end table
1617
1618
1619 @node binhex
1620 @section binhex
1621 @cindex binhex
1622 @cindex Apple
1623 @cindex Macintosh
1624
1625 @code{binhex} is an encoding that originated in Macintosh environments.
1626 The following function is supplied to deal with these:
1627
1628 @table @code
1629 @item binhex-decode-region
1630 @findex binhex-decode-region
1631 Decode the encoded text in the region.  If given a third parameter, only
1632 decode the @code{binhex} header and return the filename.
1633
1634 @end table
1635
1636 @node uudecode
1637 @section uudecode
1638 @cindex uuencode
1639 @cindex uudecode
1640
1641 @code{uuencode} is probably still the most popular encoding of binaries
1642 used on Usenet, although @code{base64} rules the mail world.
1643
1644 The following function is supplied by this package:
1645
1646 @table @code
1647 @item uudecode-decode-region
1648 @findex uudecode-decode-region
1649 Decode the text in the region.
1650 @end table
1651
1652
1653 @node yenc
1654 @section yenc
1655 @cindex yenc
1656
1657 @code{yenc} is used for encoding binaries on Usenet.  The following
1658 function is supplied by this package:
1659
1660 @table @code
1661 @item yenc-decode-region
1662 @findex yenc-decode-region
1663 Decode the encoded text in the region.
1664
1665 @end table
1666
1667
1668 @node rfc1843
1669 @section rfc1843
1670 @cindex rfc1843
1671 @cindex HZ
1672 @cindex Chinese
1673
1674 RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages.  In
1675 essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this:
1676
1677 @example
1678 This sentence is in @acronym{ASCII}.
1679 The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
1680 @end example
1681
1682 Simple enough, and widely used in China.
1683
1684 The following functions are available to handle this encoding:
1685
1686 @table @code
1687 @item rfc1843-decode-region
1688 Decode HZ-encoded text in the region.
1689
1690 @item rfc1843-decode-string
1691 Decode a HZ-encoded string and return the result.
1692
1693 @end table
1694
1695
1696 @node mailcap
1697 @section mailcap
1698
1699 The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message
1700 handlers and describes how elements are supposed to be displayed.
1701 Here's an example file:
1702
1703 @example
1704 image/*; gimp -8 %s
1705 audio/wav; wavplayer %s
1706 application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc
1707 @end example
1708
1709 This says that all image files should be displayed with @code{gimp},
1710 that WAVE audio files should be played by @code{wavplayer}, and that
1711 MS-WORD files should be inlined by @code{catdoc}.
1712
1713 The @code{mailcap} library parses this file, and provides functions for
1714 matching types.
1715
1716 @table @code
1717 @item mailcap-mime-data
1718 @vindex mailcap-mime-data
1719 This variable is an alist of alists containing backup viewing rules.
1720
1721 @end table
1722
1723 Interface functions:
1724
1725 @table @code
1726 @item mailcap-parse-mailcaps
1727 @findex mailcap-parse-mailcaps
1728 Parse the @file{~/.mailcap} file.
1729
1730 @item mailcap-mime-info
1731 Takes a @acronym{MIME} type as its argument and returns the matching viewer.
1732
1733 @end table
1734
1735
1736
1737
1738 @node Standards
1739 @chapter Standards
1740
1741 The Emacs @acronym{MIME} library implements handling of various elements
1742 according to a (somewhat) large number of RFCs, drafts and standards
1743 documents.  This chapter lists the relevant ones.  They can all be
1744 fetched from @uref{http://quimby.gnus.org/notes/}.
1745
1746 @table @dfn
1747 @item RFC822
1748 @itemx STD11
1749 Standard for the Format of ARPA Internet Text Messages.
1750
1751 @item RFC1036
1752 Standard for Interchange of USENET Messages
1753
1754 @item RFC2045
1755 Format of Internet Message Bodies
1756
1757 @item RFC2046
1758 Media Types
1759
1760 @item RFC2047
1761 Message Header Extensions for Non-@acronym{ASCII} Text
1762
1763 @item RFC2048
1764 Registration Procedures
1765
1766 @item RFC2049
1767 Conformance Criteria and Examples
1768
1769 @item RFC2231
1770 @acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets,
1771 Languages, and Continuations
1772
1773 @item RFC1843
1774 HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
1775 @acronym{ASCII} characters
1776
1777 @item draft-ietf-drums-msg-fmt-05.txt
1778 Draft for the successor of RFC822
1779
1780 @item RFC2112
1781 The @acronym{MIME} Multipart/Related Content-type
1782
1783 @item RFC1892
1784 The Multipart/Report Content Type for the Reporting of Mail System
1785 Administrative Messages
1786
1787 @item RFC2183
1788 Communicating Presentation Information in Internet Messages: The
1789 Content-Disposition Header Field
1790
1791 @item RFC2646
1792 Documentation of the text/plain format parameter for flowed text.
1793
1794 @end table
1795
1796
1797 @node Index
1798 @chapter Index
1799 @printindex cp
1800
1801 @summarycontents
1802 @contents
1803 @bye
1804
1805 @c Local Variables:
1806 @c coding: iso-2022-7bit
1807 @c fill-column: 72
1808 @c mode: texinfo
1809 @c use-kuten-for-period: t
1810 @c use-touten-for-comma: t
1811 @c End: