<!doctype sinfo system>
<head>
-<title>FLIM 1.9 Manual about MIME Features
+<title>FLIM 1.14 Reference Manual about MIME Features
<author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail>
-<date>1998/07/01
+<date>1999-01-27
<toc>
</head>
<abstract>
<p>
-This file documents MIME features of FLIM, a Internet message
-parsing/encoding library for GNU Emacs.
+This file documents MIME features of FLIM, a fundamental library to
+process Internet Messages for GNU Emacsen.
</abstract>
this document, the term <concept>entity</concept> indicates all of
header fields and body.
<p>
-The definition of RFC 2045 indicates that a MIME message is a tree.
-An message is a tree, each node is an entity, like following figure.
-Namely MIME extends message to tree structure.
+The definition of RFC 2045 indicates that a MIME message is a tree,
+and each node of the tree is an entity. Namely MIME extends message
+to tree structure.
<p>
FLIM uses <concept>mime-entity</concept> structure to represent
information of entity. In this document, it is called simply
`mime-entity'.
-<p>
-\e$BA0=R$N$h$&$K!"\e(Bmessage \e$BCf$N3F\e(B entity \e$B$OLZ$N@a$KEv$?$j$^$9$,!"$3$NLZ$K$O\e(B
-\e$B?<$5$HF1$8?<$5$NCf$N=gHV$K=>$C$FHV9f$,IU$1$k$3$H$,$G$-$^$9!#B($A!"\e(B
-<verb>
-
- \e$B(#(!(!(!($\e(B
- \e$B("\e(B nil \e$B("\e(B
- \e$B(&(!(((!(%\e(B
- \e$B(#(!(!(!(!(!(!(!(!(!(+(!(!(!(!(!(!(!(!(!($\e(B
- \e$B(#(*($\e(B \e$B(#(*($\e(B \e$B(#(*($\e(B
- \e$B("#0("\e(B \e$B("#1("\e(B \e$B("#2("\e(B
- \e$B(&(((%\e(B \e$B(&(((%\e(B \e$B(&(((%\e(B
- \e$B("\e(B \e$B(#(!(!(!(!(+(!(!(!(!($\e(B \e$B("\e(B
- \e$B(#(!(*(!($(#(!(*(!($(#(!(*(!($(#(!(*(!($(#(!(*(!($\e(B
- \e$B("\e(B \e$B#0\e(B.\e$B#0("("\e(B \e$B#1\e(B.\e$B#0("("\e(B \e$B#1\e(B.\e$B#1("("\e(B \e$B#1\e(B.\e$B#2("("\e(B \e$B#2\e(B.\e$B#0("\e(B
- \e$B(&(!(!(!(%(&(!(!(!(%(&(!(!(!(%(&(!(!(!(%(&(!(!(!(%\e(B
-
-</verb>
-<p>
-<noindent>\e$B$N$h$&$K?<$5\e(B n \e$B$N@a$K$OD9$5\e(B n \e$B$N@0?tNs$N@aHV9f$,?6$l$^$9!#$3$l\e(B
-\e$B$r\e(B <concept>entity-number</concept> \e$B$H8F$S$^$9!#\e(Bentity-number \e$B$O\e(B S \e$B<0$H\e(B
-\e$B$7$F$O\e(B <code>(1 2 3)</code> \e$B$N$h$&$J@0?t$N%j%9%H$H$7$FI=8=$5$l$^$9!#\e(B
-<p>
-mime-entity \e$B$G$O!"$3$l$HF1MM$N\e(B <concept>node-id</concept> \e$B$rMQ$$$^$9!#\e(B
-node-id \e$B$O$A$g$&$I\e(B entity-number \e$B$r5U$K$7$?%j%9%H$G!"\e(Bentity-number
-1.2.3 \e$B$KBP1~$9$k\e(B node-id \e$B$O\e(B <code>(3 2 1)</code> \e$B$G$9!#\e(B
-<p>
-\e$BA0=R$N$h$&$K!"\e(BMIME message \e$B$O\e(B entity \e$B$rC10L$H$7$?LZ9=B$$K$J$C$F$$$k$N$G!"\e(B
-\e$B$3$N:,$G$"$k\e(B message \e$BA4BN$b\e(B mime-entity \e$B$GI=8=$9$k$3$H$,$G$-!"\e(Bbuffer
-local \e$BJQ?t\e(B <code>mime-message-structure</code> \e$B$K3JG<$9$k$3$H$K$7$^$9!#\e(B
-\e$B$=$7$F!"\e(Bentity-number \e$B$d\e(B node-id \e$B$rMQ$$$k$3$H$G\e(B
-<code>mime-message-structure</code> \e$B$K$*$1$k\e(B entity \e$B$NAjBPE*$J0LCV4X78$r\e(B
-\e$B07$&$3$H$,$G$-$^$9!#\e(B
<h2> Functions to create mime-entity
<h2> Features about message tree
<node> Entity hierarchy
<p>
+Structure of a MIME message is tree.
+<p>
+In the tree, root node is the entity indicates all of the message. In
+this document, it is called <concept>root-entity</concept> or
+<concept>message</concept>. In FLIM, it is indicated by buffer local
+variable <code>mime-message-structure</code>.
+<p>
+Each entity except root-entity has a parent. An entity may have
+children. We can indicate an entity by relative position from a base
+entity, based on the parent-child relationship.
+<p>
+In addition, we can indicate an entity by absolute position of the
+message.
+<p>
+Each entity, which is a node of the tree, can be numbered by
+depth and left-to-right order of the depth.
+<verb>
+
+ +-------+
+ | nil |
+ +---+---+
+ +-------------------+-------------------+
+ +-+-+ +-+-+ +-+-+
+ | 0 | | 1 | | 2 |
+ +-+-+ +-+-+ +-+-+
+ | +---------+---------+ |
+ +--+--+ +--+--+ +--+--+ +--+--+ +--+--+
+ | 0.0 | | 1.0 | | 1.1 | | 1.2 | | 2.0 |
+ +-----+ +-----+ +-----+ +-----+ +-----+
+
+</verb>
+<p>
+Namely, if depth of a node is n, the node has a node-number, which is
+consists of n integers. In this document, it is called
+<concept>entity-number</concept>. An entity-number is represented by
+list of integer, like <code>(1 2 3)</code>.
+<p>
+mime-entity has also <concept>node-id</concept>. A node-id is
+represented by reversed list of entity-number. For example, node-id
+corresponding with 1.2.3 is <code>(3 2 1)</code>.
+<p>
+Each entity can be indicated by entity-number or node-id in
+<code>mime-message-structure</code>.
+
<defvar name="mime-message-structure">
<p>
Buffer local variable to store mime-entity structure of message.
Return entity-number of <var>entity</var>.
</defun>
+
+<h2> Find Entity
+<node> Entity Search
+<p>
<defun name="mime-find-entity-from-number">
<args> entity-number <opts> message
<p>
<code>mime-message-structure</code> is used.
</defun>
+<defun name="mime-find-entity-from-content-id">
+ <args> cid <opts> message
+<p>
+Return entity from <var>cid</var> in <var>message</var>.
+<p>
+If <var>message</var> is not specified,
+<code>mime-message-structure</code> is used.
+</defun>
+
<h2> Functions about attributes of mime-entity
<node> Entity Attributes
<code>nil</code>.
</defun>
-<defun name="mime-insert-decoded-header">
+
+<h2> Text presentation of entity
+<node> entity formatting
+<p>
+<defun name="mime-insert-header">
<args> entity <opts> invisible-fields visible-fields
<p>
Insert before point a decoded contents of header of <var>entity</var>.
If a field-name is matched with some elements of
<var>invisible-fields</var> and matched with none of
<var>visible-fields</var>, this function don't insert the field.
+<p>
+Each <dref>encoded-word</dref> in the header is decoded. ``Raw non
+us-ascii characters'' are also decoded as
+<code>default-mime-charset</code>.
+</defun>
+
+<defun name="mime-insert-text-content">
+ <args> entity
+<p>
+Insert before point a contents of <var>entity</var> as text entity.
+<p>
+Contents of the <var>entity</var> are decoded as <dref>MIME
+charset</dref>. If the <var>entity</var> does not have charset
+parameter of Content-Type field, <code>default-mime-charset</code> is
+used as default value.
</defun>
+<defvar name="default-mime-charset">
+<p>
+Symbol to indicate default value of <dref>MIME charset</dref>.
+<p>
+It is used when MIME charset is not specified.
+<p>
+It is originally variable of APEL.
+</defvar>
+
<h2> Contents of Entity
<node> Entity-content
Return content of <var>entity</var> as byte sequence.
</defun>
+<defun name="mime-insert-entity-content">
+ <args> entity
+<p>
+Insert content of <var>entity</var> at point.
+</defun>
+
<defun name="mime-write-entity-content">
<args> entity filename
<p>
Write content of <var>entity</var> into <var>filename</var>.
</defun>
+
+<h2> Network representation of Entity
+<node> Entity-network-representation
+<p>
+<defun name="mime-insert-entity">
+ <args> entity
+<p>
+Insert header and body of <var>entity</var> at point.
+</defun>
+
<defun name="mime-write-entity">
<args> entity filename
<p>
Each entity has <concept>representation-type</concept>. It must be
specified when an entity is created. <cf node="Entity Creation">
<p>
-\e$BA0@a$^$G$K=R$Y$FMh$?\e(B entity \e$B$KBP$9$k=hM}$O!"\e(Bentity \e$B$KBP$7$F$=$N=hM}$r0M\e(B
-\e$BMj$9$k$3$H$K$h$C$F<B8=$5$l$F$$$^$9!#\e(BEntity \e$B$O<+J,$N\e(B
-representation-type \e$B$rCN$C$F$*$j!"$=$N\e(B representation-type \e$B$K1~$8$F<B:]\e(B
-\e$B$N=hM}$r9T$&4X?t$r8F$S=P$7$^$9!#$3$N$h$&$J4X?t$r\e(B <concept>entity \e$B=hM}\e(B
-method</concept> \e$B$H8F$S$^$9!#$^$?!"\e(Brepresentation-type \e$BKh$K$3$N$h$&$J4X\e(B
-\e$B?t$r$^$H$a$?$b$N$r\e(B <concept>mm-backend</concept> \e$B$H8F$S$^$9!#\e(B
+Functions about entity are implemented by request processing to the
+entity. Each entity knows its representation-type. Each entity calls
+processing function corresponding with the representation-type. Such
+kind of function is called <concept>entity processing
+method</concept>. A module, consists of them corresponding with a
+representation-type, is called <concept>mm-backend</concept>.
<p>
-mm-backend \e$B$O\e(B representation-type \e$B$NL>A0$N@hF,$K\e(B <code>mm</code> \e$B$H$$$&\e(B
-\e$B@\F,<-$rIU$1$?4X?tL>$+$i$J$k\e(B module \e$B$G!"$=$N\e(B module \e$BL>$OF1MM$K\e(B
-representation-type \e$B$NL>A0$N@hF,$K\e(B <code>mm</code> \e$B$rIU$1$?$b$N$K$J$C$F\e(B
-\e$B$$$^$9!#$3$N\e(B module \e$B$O\e(B representation-type \e$B$N\e(B entity \e$B$,:G=i$K@8@.$5$l$k\e(B
-\e$B;~$K<+F0E*$K\e(B require \e$B$5$l$^$9!#\e(B
+Module name of each mm-backend consists of the prefix <code>mm</code>
+and its representation-type. The module is required automatically
+when its entity is created at first.
<h3> Message-passing for entity
<defun name="mime-entity-send">
<args> entity message <rest> args
<p>
-<var>entity</var> \e$B$K\e(B <var>message</var> \e$B$rAw$k!#\e(B
+Send <var>message</var> to <var>entity</var> with <var>args</var>, and
+return the result.
<p>
-<var>args</var> \e$B$O\e(B <var>message</var> \e$B$N0z?t$G$"$k!#\e(B
+<var>args</var> is arguments of the <var>message</var>.
</defun>
-<h3> How to make mm-backend
+<h3> Definition of mm-backend
<node> mm-backend module
<p>
-\e$B!J$9$_$^$;$s!#$=$N$&$A=q$-$^$9\e(B (^_^;\e$B!K\e(B
+<defmacro name="mm-define-backend">
+<args> type
+<opts> parents
+<p>
+Define <var>type</var> as a mm-backend.
+<p>
+If <var>PARENTS</var> is specified, <var>type</var> inherits parents.
+Each parent must be representation-type.
<p>
-\e$B!J$H$j$"$($:!"\e(Bmm*.el \e$B$r;29M$K$7$F$/$@$5$$!K\e(B
+Example:
+<p>
+<lisp>
+(mm-define-backend chao (generic))
+</lisp>
+</defmacro>
+
+<defmacro name="mm-define-method">
+<args> name args <rest> body
+<p>
+Define <var>name</var> as a method function of (nth 1 (car
+<var>args</var>)) backend.
+<p>
+<var>args</var> is like an argument list of lambda, but (car
+<var>args</var>) must be specialized parameter. (car (car
+<var>args</var>)) is name of variable and (nth 1 (car
+<var>args</var>)) is name of backend (representation-type).
+<p>
+Example:
+<p>
+<lisp>
+(mm-define-method entity-cooked-p ((entity chao)) nil)
+</lisp>
+</defmacro>
<h1> Information of Content-Type field
<h2> Format of Content-Type field
<node> Content-Type field
<p>
-Content-Type \e$BMs$N7A<0$O0J2<$N$h$&$KDj5A$5$l$F$$$^$9!'\e(B
+Format of Content-Type field is defined as follows:
<quote>
``Content-Type'' ``:'' <concept>type</concept> ``/''
<concept>subtype</concept> *( ``;'' <concept>parameter</concept> )
</quote>
<p>
-\e$BNc$($P!"\e(B
+For example:
<quote>
<verb>
</verb>
</quote>
-<noindent>
-\e$B$d\e(B
-
<quote>
<verb>
Content-Type: text/plain; charset=iso-2022-jp
</verb>
</quote>
-
-<noindent>
-\e$B$J$I$N$h$&$KMQ$$$i$l$^$9!#\e(B
<p>
-\e$B$3$3$G!"\e(B`type' \e$B$H\e(B `subtype' \e$B$O\e(B entity \e$B$N7A<0$r<($9$b$N$G!"N><T$rAm>N$7\e(B
-\e$B$F!"\e(B`media-type' \e$B$H8F$V$3$H$K$7$^$9!#>e5-$NNc$K$*$1$k\e(B `image/jpeg' \e$B$d\e(B
-`text/plain' \e$B$O\e(B media-type \e$B$N#1$D$G$9!#\e(B
+`type' and `subtype' indicate format of an entity. In this document,
+pair of them is called `media-type'. `image/jpeg' or `text/plain' is
+a media-type.
<memo>
<p>
-Content-Type \e$BMs$N$J$$\e(B entity \e$B$O\e(B
+If an entity does not have Content-Type field, it is regarded as
+following:
<quote>
<verb>
</quote>
<noindent>
-
\e$B$H$7$F2r<a$5$l$k!#
\e(B<cf node="us-ascii">
+<cf node="us-ascii">
</memo>
<p>
<define type="Structure" name="mime-content-type">
<p>
-Content-Type \e$BMs$N>pJs$r3JG<$9$k$?$a$N9=B$BN!#\e(B
+Structure to store information of a Content-Type field.
<p>
-\e$B$3$N9=B$BN$r;2>H$9$k$K$O\e(B <code>mime-content-type-\e$BMWAGL>\e(B</code> \e$B$H$$$&L>\e(B
-\e$BA0$N;2>H4X?t$rMQ$$$k!#\e(B
+Applications should use reference functions
+<code>mime-content-type-SLOT</code> to refer information of the
+structure.
<p>
-\e$B$3$N9=B$BN$NMWAG$O0J2<$NDL$j$G$"$k!'\e(B
+Slots of the structure are following:
<vl>
-<dt>primary-type<dd>media-type \e$B$N<g7?\e(B (symbol).
+<dt>primary-type<dd>primary type of media-type (symbol).
</dd>
-<dt>subtype<dd>media-type \e$B$NI{7?\e(B (symbol).
+<dt>subtype<dd>subtype of media-type (symbol).
</dd>
-<dt>parameters<dd>Content-Type \e$BMs$N\e(B parameter (\e$BO"A[\e(B list).
+<dt>parameters<dd>parameters of Content-Type field (association-list).
</dd>
</vl>
</define>
<defun name="make-mime-content-type">
<args> type subtype
<opts> parameters
-<p>content-type \e$B$N@8@.;R!#\e(B
+<p>Constructor of content-type.
</defun>
<defun name="mime-content-type-parameter">
<args> content-type parameter
<p>
-<var>content-type</var> \e$B$N\e(B <var>parameter</var> \e$B$NCM$rJV$9!#\e(B
+Return value of <var>parameter</var> of <var>content-type</var>.
</defun>
<node> Content-Type parser
<p>
<defun name="mime-parse-Content-Type">
- <args> string
+ <args> string
<p>
-<var>string</var> \e$B$r\e(B content-type \e$B$H$7$F2r@O$7$?7k2L$rJV$9!#\e(B
+Parse <var>string</var> as a field-body of Content-Type field, and
+return the result as <dref>mime-content-type</dref> structure.
</defun>
<defun name="mime-read-Content-Type">
<p>
-\e$B8=:_$N\e(B buffer \e$B$N\e(B Content-Type \e$BMs$rFI$_<h$j!"2r@O$7$?7k2L$rJV$9!#\e(B
+Parse Content-Type field of the current buffer, and return the result
+as <dref>mime-content-type</dref> structure.
<p>
-Content-Type \e$BMs$,B8:_$7$J$$>l9g$O\e(B nil \e$B$rJV$9!#\e(B
+Return <code>nil</code> if Content-Type field is not found.
</defun>
<node> Content-Type utility
<p>
<defun name="mime-type/subtype-string">
- <args> type <opts> subtype
+ <args> type <opts> subtype
<p>
Return type/subtype string from <var>type</var> and
<var>subtype</var>.
<h1> Information of Content-Disposition field
<node> Content-Disposition
<p>
-<concept>Content-Disposition \e$BMs\e(B</concept> \e$B$O\e(B entity \e$B$NI=<($d\e(B file \e$BL>$J$I\e(B
-\e$B$NB0@-$K$J$I$K4X$9$k>pJs$r5-=R$9$k$?$a$N$b$N$G$9!#\e(B
+<concept>Content-Disposition field</concept> is an optional field to
+specify presentation of an entity or attributes of an entity, such as
+file name.
<rfc number="2183" type="Standards Track"
- author="S. Dorner, K. Moore and R. Troost"
- title="Communicating Presentation Information in
- Internet Messages: The Content-Disposition Header"
- date="August 1997">
+ author="S. Dorner, K. Moore and R. Troost"
+ title="Communicating Presentation Information in Internet
+ Messages: The Content-Disposition Header" date="August
+ 1997">
<p>
-FLIM \e$B$O\e(B Content-Disposition \e$BMs$r9=J82r@O$9$k4X?t$H\e(B Content-Disposition
-\e$BMs$N2r@O7k2L$r3JG<$9$k9=B$BN\e(B
-<concept>mime-content-disposition</concept> \e$B$rDs6!$7$^$9!#\e(B
+FLIM provides parser for Content-Disposition field and structure
+<concept>mime-content-disposition</concept> to store information of
+Content-Disposition field.
<h2> mime-content-disposition structure
<p>
<define type="Structure" name="mime-content-disposition">
<p>
-Content-Disposition \e$BMs$N2r@O7k2L$r<}$a$k$?$a$N9=B$BN!#\e(B
+Structure to store information of a Content-Disposition field.
<p>
-\e$B$3$N9=B$BN$r;2>H$9$k$K$O\e(B <code>mime-content-disposition-\e$BMWAGL>\e(B</code> \e$B$H\e(B
-\e$B$$$&L>A0$N;2>H4X?t$rMQ$$$k!#\e(B
+Applications should use reference functions
+<code>mime-content-disposition-SLOT</code> to refer information of the
+structure.
<p>
-\e$B$3$N9=B$BN$NMWAG$O0J2<$NDL$j$G$"$k!'\e(B
+Slots of the structure are following:
<vl>
<dt>disposition-type<dd>disposition-type (symbol).
</dd>
-<dt>parameters<dd>Content-Disposition \e$BMs$N\e(B parameter (\e$BO"A[\e(B list).
+<dt>parameters<dd>parameters of Content-Disposition field
+(association-list).
</dd>
</vl>
</define>
<defun name="mime-content-disposition-parameter">
<args> content-disposition parameter
<p>
-<var>content-disposition</var> \e$B$N\e(B <var>parameter</var> \e$B$NCM$rJV$9!#\e(B
+Return value of <var>parameter</var> of
+<var>content-disposition</var>.
</defun>
<defun name="mime-content-disposition-filename">
<args> content-disposition
<p>
-<var>content-disposition</var> \e$B$N\e(B filename \e$B$NCM$rJV$9!#\e(B
+Return filename of <var>content-disposition</var>.
</defun>
<defun name="mime-parse-Content-Disposition">
<args> string
<p>
-<var>string</var> \e$B$r\e(B content-disposition \e$B$H$7$F2r@O$7$?7k2L$rJV$9!#\e(B
+Parse <var>string</var> as field-body of Content-Disposition field,
+and return the result as <dref>mime-content-disposition</dref>
+structure.
</defun>
<defun name="mime-read-Content-Disposition">
<p>
-\e$B8=:_$N\e(B buffer \e$B$N\e(B Content-Disposition \e$BMs$rFI$_<h$j!"2r@O$7$?7k2L$rJV$9!#\e(B
+Parse Content-Disposition field of the current buffer, and return the
+result as <dref>mime-content-disposition</dref> structure.
<p>
-Content-Disposition \e$BMs$,B8:_$7$J$$>l9g$O\e(B nil \e$B$rJV$9!#\e(B
+Return <code>nil</code> if Content-Disposition field is not found.
</defun>
<h1> Encoding Method
<node> Content-Transfer-Encoding
<p>
-<concept>Content-Transfer-Encoding \e$BMs\e(B</concept> \e$B$O\e(B entity \e$B$NId9f2=K!$r5-\e(B
-\e$B=R$9$k$?$a$N$b$N$G$9!#\e(B
+<concept>Content-Transfer-Encoding field</concept> is a header field
+to indicate body encoding of a entity.
<p>
-FLIM \e$B$G$O\e(B Content-Transfer-Encoding \e$BMs$r9=J82r@O$9$k4X?t$rDs6!$7$^$9!#$3\e(B
-\e$B$l$i$N4X?t$O\e(B Content-Transfer-Encoding \e$BMs$N>pJs$OJ8;zNs$GI=8=$7$^$9!#\e(B
+FLIM provides parser functions for Content-Transfer-Encoding field.
+They represent information of Content-Transfer-Encoding field as
+string.
<p>
-\e$B$^$?!"\e(BContent-Transfer-Encoding \e$B$K4p$E$$$FId9f2=!&I|9f2=$r9T$&4X?t$bDs\e(B
-\e$B6!$5$l$^$9!#\e(B
+In addition, FLIM provides encoder/decoder functions by
+Content-Transfer-Encoding.
<h2> Parser
<node> Content-Transfer-Encoding parser
<p>
<defun name="mime-parse-Content-Transfer-Encoding">
- <args> string
+ <args> string
<p>
-<var>string</var> \e$B$r\e(B content-transfer-encoding \e$B$H$7$F2r@O$7$?7k2L$rJV$9!#\e(B
+Parse <var>string</var> as a field-body of Content-Transfer-Encoding
+field, and return the result.
</defun>
<defun name="mime-read-Content-Transfer-Encoding">
- <opts>default-encoding
+ <opts>default-encoding
<p>
-\e$B8=:_$N\e(B buffer \e$B$N\e(B Content-Transfer-Encoding \e$BMs$rFI$_<h$j!"2r@O$7$?7k2L$r\e(B
-\e$BJV$9!#\e(B
+Parse Content-Transfer-Encoding field of the current buffer, and
+return the result.
<p>
-Content-Transfer-Encoding \e$BMs$,B8:_$7$J$$>l9g$O\e(B
-<var>default-encoding</var> \e$B$rJV$9!#\e(B
+Return <var>default-encoding</var> if Content-Transfer-Encoding field
+is not found. If it is not specified, <code>nil</code> is used as the
+default value.
</defun>
-<h2> Region encoding/decoding
-<node> Region encoder/decoder
+<h2> Encoder/decoder
+<node> encoder/decoder
<p>
<defun name="mime-encode-region">
<args> start end encoding
using <var>encoding</var>.
</defun>
-<defvar name="mime-encoding-method-alist">
-<p>
-Alist of encoding vs. corresponding method to encode region.
-<p>
-Each element looks like <code>(STRING . FUNCTION)</code> or
-<code>(STRING . nil)</code>. <var>string</var> is
-content-transfer-encoding. <code>function</code> is region encoder
-and <code>nil</code> means not to encode.
-</defvar>
-<defvar name="mime-decoding-method-alist">
-<p>
-Alist of encoding vs. corresponding method to decode region.
-<p>
-Each element looks like <code>(STRING . FUNCTION)</code> or
-<code>(STRING . nil)</code>. <var>string</var> is
-content-transfer-encoding. <code>function</code> is region decoder
-and <code>nil</code> means not to decode.
-</defvar>
-
-
-<h2> String encoding/decoding
-<node> String encoder/decoder
-<p>
<defun name="mime-decode-string">
- <args> string encoding
+ <args> string encoding
<p>
-<var>string</var> \e$B$r\e(B <var>encoding</var> \e$B$H$7$FI|9f$7$?7k2L$rJV$7$^$9!#\e(B
+Decode <var>string</var> which is encoded in <var>encoding</var>, and
+return the result.
</defun>
-<defvar name="mime-string-decoding-method-alist">
-<p>
-Alist of encoding vs. corresponding method to decode string.
-<p>
-Each element looks like <code>(STRING . FUNCTION)</code>.
-STRING is content-transfer-encoding.
-FUNCTION is string decoder.
-</defvar>
-
-<h2> File encoding/decoding
-<node> File encoder/decoder
-<p>
<defun name="mime-insert-encoded-file">
<args> filename encoding
<p>
<var>start</var> and <var>end</var> are buffer positions.
</defun>
-<defvar name="mime-file-encoding-method-alist">
+
+<h2> Other utilities
+<node> Encoding information
<p>
-Alist of encoding vs. corresponding method to insert encoded file.
+<defun name="mime-encoding-list">
+ <opts> SERVICE
<p>
-Each element looks like <code>(STRING . FUNCTION)</code>. STRING is
-content-transfer-encoding. FUNCTION is function to insert encoded
-file.
-</defvar>
+Return list of Content-Transfer-Encoding.
+<p>
+If <var>service</var> is specified, it returns available list of
+Content-Transfer-Encoding for it.
+</defun>
-<defvar name="mime-file-decoding-method-alist">
+<defun name="mime-encoding-alist">
+ <opts> SERVICE
<p>
-Alist of encoding vs. corresponding method to write decoded region to
-file.
+Return table of Content-Transfer-Encoding for completion.
<p>
-Each element looks like <code>(STRING . FUNCTION)</code>. STRING is
-content-transfer-encoding. FUNCTION is function to write decoded
-region to file.
-</defvar>
+If <var>service</var> is specified, it returns available list of
+Content-Transfer-Encoding for it.
+</defun>
+
+
+<h2> How to write encoder/decoder module
+<node> mel-backend
+<p>
+<defmacro name="mel-define-method">
+<args> name args <rest> body
+<p>
+Define <var>name</var> as a method function of (nth 1 (car (last
+<var>args</var>))) backend.
+<p>
+<var>args</var> is like an argument list of lambda, but (car (last
+<var>args</var>)) must be specialized parameter. (car (car (last
+<var>args</var>))) is name of variable and (nth 1 (car (last
+<var>args</var>))) is name of backend (encoding).
+<p>
+Example:
+<p>
+<lisp>
+(mel-define-method mime-write-decoded-region (start end filename
+ (nil "base64"))
+ "Decode and write current region encoded by base64 into FILENAME.
+START and END are buffer positions."
+ (interactive
+ (list (region-beginning) (region-end)
+ (read-file-name "Write decoded region to file: ")))
+ (let ((str (buffer-substring start end)))
+ (with-temp-buffer
+ (insert (decode-base64-string str))
+ (write-region-as-binary (point-min) (point-max) filename)
+ )))
+</lisp>
+</defmacro>
+
+<defmacro name="mel-define-method-function">
+<args> spec function
+<p>
+Set <var>spec</var>'s function definition to <var>function</var>.
+<p>
+First element of <var>spec</var> is service.
+<p>
+Rest of <var>args</var> is like an argument list of lambda, but (car
+(last <var>args</var>)) must be specialized parameter. (car (car
+(last <var>args</var>))) is name of variable and (nth 1 (car (last
+<var>args</var>))) is name of backend (encoding).
+<p>
+Example:
+<p>
+<lisp>
+(mel-define-method-function (mime-encode-string string (nil "base64"))
+ 'encode-base64-string)
+</lisp>
+</defmacro>
+
+
+<h2> How to add encoding/decoding service
+<node> generic function for mel-backend
+<p>
+<defmacro name="mel-define-service">
+<args> name
+<opts> args doc-string
+<p>
+Define <var>name</var> as a service for Content-Transfer-Encodings.
+<p>
+If <var>args</var> is specified, <var>name</var> is defined as a
+generic function for the service.
+<p>
+Example:
+<p>
+<lisp>
+(mel-define-service encoded-text-encode-string (string encoding)
+ "Encode STRING as encoded-text using ENCODING.
+ENCODING must be string.")
+</lisp>
+</defmacro>
<h1> Network representation of header
<node> encoded-word
<p>
-encoded-word \e$B$O\e(B header \e$B$GHs\e(B <dref>ASCII</dref> \e$BJ8;z$rI=8=$9$k$?$a$N7A\e(B
-\e$B<0$G!"\e(B<concept>RFC 2047</concept> \e$B$GDj5A$5$l$F$$$^$9!#\e(B
+<concept>RFC 2047</concept> defines the
+<concept>encoded-word</concept> which is a format to represent
+non-<dref>ASCII</dref> characters in a header.
<p>
<rfc number="2047" type="Standards Track" author="K. Moore"
title="MIME (Multipurpose Internet Mail Extensions) Part
Three: Message Header Extensions for Non-ASCII Text"
date="November 1996" obsolete="1521,1522,1590">
<p>
-\e$B$^$?!"9T57$N0-$$$3$H$@$H8@$($^$9$,!"\e(Bencoded-word \e$B$rMQ$$$:$KHs\e(B
-<dref>ASCII</dref> \e$BJ8;z$r\e(B header \e$B$KF~$l$?5-;v$bB8:_$7$^$9!#\e(B
+The encoded-word is the only valid format to represent
+non-<dref>ASCII</dref> characters in a header, but there are also
+invalid styles. Such kinds of evil messages represent
+non-<dref>ASCII</dref> characters in headers without encoded-words (it
+is called "raw" non-<dref>ASCII</dref> characters).
<p>
-FLIM \e$B$O$3$l$i$rId9f2=!&I|9f2=$9$k5!G=$rDs6!$7$^$9!#\e(B
+FLIM provides encoding/decoding features of both encoded-word and
+invalid "raw" non-<dref>ASCII</dref> characters.
<h2> Header encoding/decoding
<node> Header encoder/decoder
<p>
-<defun name="eword-encode-header">
- <opts> code-conversion separator
+<defun name="eword-decode-header">
+ <opts> code-conversion separator
<p>
Decode MIME encoded-words in header fields.
<p>
-If <var>code-conversion</var> is <code>nil</code>, it decodes only
-encoded-words. If it is mime-charset, it decodes non-ASCII bit
-patterns as the mime-charset. Otherwise it decodes non-ASCII bit
-patterns as the default-mime-charset.
+If <var>code-conversion</var> is <code>nil</code>, only encoded-words
+are decoded. If <var>code-conversion</var> is a <dref>MIME
+charset</dref>, non-ASCII bit patterns are decoded as the MIME
+charset. Otherwise non-ASCII bit patterns are decoded as the
+<code>default-mime-charset</code>. <cf node="entity formatting">
<p>
-If <var>separator</var> is not nil, it is used as header separator.
+If <var>separator</var> is not <code>nil</code>, it is used as header
+separator.
</defun>
<defun name="eword-encode-header">
- <opts> code-conversion
+ <opts> code-conversion
<p>
Encode header fields to network representation, such as MIME
encoded-word.
<p>
-It refer variable <code>eword-field-encoding-method-alist</code>.
+Each field is encoded as corresponding method specified by variable
+<code>mime-field-encoding-method-alist</code>.
</defun>
-
-<h1> Various Customization
-<node> custom
+<defvar name="mime-field-encoding-method-alist">
<p>
-<define type="group" name="mime">
+Association list to specify field encoding method. Each element looks
+like (FIELD . METHOD).
<p>
-MIME \e$B4XO"5!G=$K4X$9$k\e(B group.
+If METHOD is <code>mime</code>, the FIELD will be encoded into MIME
+format (encoded-word).
<p>
-<code>mail</code> \e$B$H\e(B <code>news</code> \e$B$KB0$9$k!#\e(B
-</define>
-
-<defvar name="default-mime-charset">
+If METHOD is <code>nil</code>, the FIELD will not be encoded.
<p>
-\e$BE,@Z$J\e(B <dref>MIME charset</dref> \e$B$,8+$D$+$i$J$+$C$?>l9g$KMQ$$$i$l$k\e(B
-MIME charset.
+If METHOD is a MIME charset, the FIELD will be encoded as the charset
+when it must be convert into network-code.
<p>
-\e$BK\Mh$O\e(B APEL \e$B$NJQ?t$G$"$k!#\e(B
+Otherwise the FIELD will be encoded as variable
+<code>default-mime-charset</code> when it must be convert into
+network-code.
</defvar>
-<defvar name="mime-temp-directory">
+
+<h1> Various Customization
+<node> custom
<p>
-MIME \e$B5!G=$K4X$9$k<BAu$,0l;~E*$K;HMQ$9$k\e(B file \e$B$r:n@.$9$k\e(B directory.
+<define type="group" name="mime">
<p>
-\e$B4D6-JQ?t\e(B <code>MIME_TMP_DIR</code>, <code>TM_TMP_DIR</code>,
-<code>TMPDIR</code>, <code>TMP</code> \e$B$b$7$/$O\e(B <code>TEMP</code> \e$B$,@_Dj\e(B
-\e$B$5$l$F$$$?>l9g!"$=$l$r=i4|CM$H$7$FMQ$$$k!#2?$b@_Dj$5$l$F$$$J$$>l9g!"\e(B
-<code>"/tmp/"</code> \e$B$rMQ$$$k!#\e(B
-</defvar>
+The group associated with functions related to MIME.
+<p>
+It belongs to <code>mail</code> and <code>news</code>.
+</define>
<h1> Appendix
<p>
Any byte stream is called <concept>binary</concept>.
<p>
-It does not require structureof lines. It differs from from <a
+It does not require structure of lines. It differs from from <a
node="8bit">8bit</a>.
<p>
In addition, if line structured data contain too long line (more than
<node> Bug report
<p>
If you write bug-reports and/or suggestions for improvement, please
-send them to the tm Mailing List:
+send them to the EMACS-MIME Mailing List:
<ul>
-<li> Japanese <mail>bug-tm-ja@chamonix.jaist.ac.jp</mail>
-<li> English <mail>bug-tm-en@chamonix.jaist.ac.jp</mail>
+<li> English <mail>emacs-mime-en@m17n.org</mail>
+<li> Japanese <mail>emacs-mime-ja@m17n.org</mail>
</ul>
<p>
Bug may not appear only your environment, but also in a lot of
environment (otherwise it might not bug). Therefor if you send mail
to author directly, we must write a lot of mails. So please send mail
-to address for tm bugs instead of author.
+to address for EMACS-MIME Mailing List instead of author.
<p>
-Via the tm ML, you can report FLIM bugs, obtain the latest release of
-FLIM, and discuss future enhancements to FLIM. To join the tm ML,
-send empty e-mail to:
+Via the EMACS-MIME ML, you can report FLIM bugs, obtain the latest
+release of FLIM, and discuss future enhancements to FLIM. To join the
+EMACS-MIME ML, send an empty e-mail to:
<ul>
-<li> Japanese <mail>tm-ja-help@chamonix.jaist.ac.jp</mail>
-<li> English <mail>tm-en-help@chamonix.jaist.ac.jp</mail>
+<li> English <mail>emacs-mime-en-ctl@m17n.org</mail>
+<li> Japanese <mail>emacs-mime-ja-ctl@m17n.org</mail>
</ul>
<h2> CVS based development
<node> CVS
<p>
-FLIM \e$B$N\e(B file \e$B$O\e(B CVS \e$B$r;H$C$F4IM}$5$l$F$$$^$9!#$3$N$?$a!"0J2<$NJ}K!$G:G\e(B
-\e$B?7$N\e(B FLIM \e$B$rF~<j$9$k$3$H$,$G$-$^$9!'\e(B
+Files in FLIM are managed under CVS. Therefore you can obtain the
+newest FLIM by the following method:
<verb>
(0) cvs login
- % cvs -d :pserver:anonymous@chamonix.jaist.ac.jp:/hare/cvs/root \
- login
+ % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
CVS password: [CR] # NULL string
(1) checkout
- % cvs -d :pserver:anonymous@chamonix.jaist.ac.jp:/hare/cvs/root \
+ % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root \
checkout [-r TAG] flim
</verb>
<p>
-CVS \e$B$rMQ$$$?3+H/$K;22C$7$?$$J}$O\e(B
+If you would like to join CVS based development, please send mail to
<ul>
-<li> <mail>cvs@chamonix.jaist.ac.jp</mail>
+<li> <mail>cvs@cvs.m17n.org</mail>
</ul>
<noindent>
-\e$B$^$G!"\e(Baccount \e$BL>$H\e(B UNIX \e$B$N\e(B passwd \e$B$HF1$87A<0$N\e(B crypt \e$B2=$5$l$?\e(B password
-\e$B$r1h$($F8fO"Mm$/$@$5$$!#\e(B
+with your account name and your public key for ssh.
+cvsroot is :ext:cvs@@cvs.m17n.org:/cvs/root.
<h2> History of FLIM
projects / elisp / flim.git / blobdiff