X-Git-Url: http://git.chise.org/gitweb/?p=elisp%2Fflim.git;a=blobdiff_plain;f=mime-en.sgml;h=6e5b959058ff22ff880075a654f7b10126bea98c;hp=264996e0b6983f007101babaa8c59a31148e1d67;hb=HEAD;hpb=1a36deaa34af2165688dfec337e925575e690506 diff --git a/mime-en.sgml b/mime-en.sgml index 264996e..6e5b959 100644 --- a/mime-en.sgml +++ b/mime-en.sgml @@ -1,8 +1,8 @@ -FLIM 1.8 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> @@ -11,8 +11,8 @@ <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> @@ -42,46 +42,13 @@ a message or one of the parts in the body of a multipart entity.' In 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> -$BA0=R$N$h$&$K!"(Bmessage $BCf$N3F(B entity $B$OLZ$N@a$KEv$?$j$^$9$,!"$3$NLZ$K$O(B -$B?<$5$HF1$8?<$5$NCf$N=gHV$K=>$C$FHV9f$,IU$1$k$3$H$,$G$-$^$9!#B($A!"(B -<verb> - - $B(#(!(!(!($(B - $B("(B nil $B("(B - $B(&(!(((!(%(B - $B(#(!(!(!(!(!(!(!(!(!(+(!(!(!(!(!(!(!(!(!($(B - $B(#(*($(B $B(#(*($(B $B(#(*($(B - $B("#0("(B $B("#1("(B $B("#2("(B - $B(&(((%(B $B(&(((%(B $B(&(((%(B - $B("(B $B(#(!(!(!(!(+(!(!(!(!($(B $B("(B - $B(#(!(*(!($(#(!(*(!($(#(!(*(!($(#(!(*(!($(#(!(*(!($(B - $B("(B $B#0(B.$B#0("("(B $B#1(B.$B#0("("(B $B#1(B.$B#1("("(B $B#1(B.$B#2("("(B $B#2(B.$B#0("(B - $B(&(!(!(!(%(&(!(!(!(%(&(!(!(!(%(&(!(!(!(%(&(!(!(!(%(B - -</verb> -<p> -<noindent>$B$N$h$&$K?<$5(B n $B$N@a$K$OD9$5(B n $B$N@0?tNs$N@aHV9f$,?6$l$^$9!#$3$l(B -$B$r(B <concept>entity-number</concept> $B$H8F$S$^$9!#(Bentity-number $B$O(B S $B<0$H(B -$B$7$F$O(B <code>(1 2 3)</code> $B$N$h$&$J@0?t$N%j%9%H$H$7$FI=8=$5$l$^$9!#(B -<p> -mime-entity $B$G$O!"$3$l$HF1MM$N(B <concept>node-id</concept> $B$rMQ$$$^$9!#(B -node-id $B$O$A$g$&$I(B entity-number $B$r5U$K$7$?%j%9%H$G!"(Bentity-number -1.2.3 $B$KBP1~$9$k(B node-id $B$O(B <code>(3 2 1)</code> $B$G$9!#(B -<p> -$BA0=R$N$h$&$K!"(BMIME message $B$O(B entity $B$rC10L$H$7$?LZ9=B$$K$J$C$F$$$k$N$G!"(B -$B$3$N:,$G$"$k(B message $BA4BN$b(B mime-entity $B$GI=8=$9$k$3$H$,$G$-!"(Bbuffer -local $BJQ?t(B <code>mime-message-structure</code> $B$K3JG<$9$k$3$H$K$7$^$9!#(B -$B$=$7$F!"(Bentity-number $B$d(B node-id $B$rMQ$$$k$3$H$G(B -<code>mime-message-structure</code> $B$K$*$1$k(B entity $B$NAjBPE*$J0LCV4X78$r(B -$B07$&$3$H$,$G$-$^$9!#(B <h2> Functions to create mime-entity @@ -98,26 +65,67 @@ Open an entity and return it. depended on representation-type. </defun> -<defun name="mime-parse-message"> - <opts> default-ctl node-id -<p> -Parse current buffer as message, and return the result as mime-entity. -</defun> - <defun name="mime-parse-buffer"> - <opts> buffer + <opts> buffer type <p> Parse <var>buffer</var> as message, and set the result to buffer local variable <code>mime-message-structure</code> of <var>buffer</var> as mime-entity. <p> If <var>buffer</var> is omitted, current buffer is used. +<p> +<var>type</var> is representation-type of created mime-entity. <cf +node="mm-backend"> Default value is <var>buffer</var>. </defun> <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. @@ -157,6 +165,10 @@ Return node-id of <var>entity</var>. 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> @@ -175,6 +187,15 @@ If <var>message</var> is not specified, <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 @@ -200,10 +221,14 @@ Return file name of <var>entity</var>. </defun> <defun name="mime-entity-encoding"> - <args> entity + <args> entity <opts> default-encoding <p> Return content-transfer-encoding of <var>entity</var>. <cf node="Content-Transfer-Encoding"> +<p> +If the <var>entity</var> does not have Content-Transfer-Encoding +field, this function returns <var>default-encoding</var>. If it is +nil, <code>"7bit"</code> is used as default value. </defun> <defun name="mime-entity-cooked-p"> @@ -252,7 +277,11 @@ If <var>field-name</var> field is not found, this function returns <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>. @@ -264,8 +293,32 @@ field-name to hide. 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 @@ -276,12 +329,28 @@ If a field-name is matched with some elements of 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> @@ -350,25 +419,22 @@ contains <var>entity</var>. <h2> Entity representations and implementations <node> mm-backend <p> -Entity $B$OCj>]2=$5$l$?%G!<%?I=8=$G!"<B:]$N%G!<%?I=8=$H$7$F$OMQES$K1~$8$F(B -$B$5$^$6$^$J$b$N$,MxMQ$G$-$k$h$&$K@_7W$5$l$F$$$^$9!#(B +Entity is an abstraction. It is designed to use various data +representations for their purposes. <p> -$B$3$3$G!"(Bentity $B$,$I$&$$$&<oN`$NI=8=$r9T$C$F$$$k$+$r<($9$N$,(B -<concept>representation-type</concept> $B$G!"(Bentity $B$r@8@.$9$k;~$K$O$3$l$r(B -$B;XDj$7$^$9!#(B<cf node="Entity Creation"> +Each entity has <concept>representation-type</concept>. It must be +specified when an entity is created. <cf node="Entity Creation"> <p> -$BA0@a$^$G$K=R$Y$FMh$?(B entity $B$KBP$9$k=hM}$O!"(Bentity $B$KBP$7$F$=$N=hM}$r0M(B -$BMj$9$k$3$H$K$h$C$F<B8=$5$l$F$$$^$9!#(BEntity $B$O<+J,$N(B -representation-type $B$rCN$C$F$*$j!"$=$N(B representation-type $B$K1~$8$F<B:](B -$B$N=hM}$r9T$&4X?t$r8F$S=P$7$^$9!#$3$N$h$&$J4X?t$r(B <concept>entity $B=hM}(B -method</concept> $B$H8F$S$^$9!#$^$?!"(Brepresentation-type $BKh$K$3$N$h$&$J4X(B -$B?t$r$^$H$a$?$b$N$r(B <concept>mm-backend</concept> $B$H8F$S$^$9!#(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 $B$O(B representation-type $B$NL>A0$N@hF,$K(B <code>mm</code> $B$H$$$&(B -$B@\F,<-$rIU$1$?4X?tL>$+$i$J$k(B module $B$G!"$=$N(B module $BL>$OF1MM$K(B -representation-type $B$NL>A0$N@hF,$K(B <code>mm</code> $B$rIU$1$?$b$N$K$J$C$F(B -$B$$$^$9!#$3$N(B module $B$O(B representation-type $B$N(B entity $B$,:G=i$K@8@.$5$l$k(B -$B;~$K<+F0E*$K(B require $B$5$l$^$9!#(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 @@ -377,18 +443,49 @@ representation-type $B$NL>A0$N@hF,$K(B <code>mm</code> $B$rIU$1$?$b$N$K$J$C$F <defun name="mime-entity-send"> <args> entity message <rest> args <p> -<var>entity</var> $B$K(B <var>message</var> $B$rAw$k!#(B +Send <var>message</var> to <var>entity</var> with <var>args</var>, and +return the result. <p> -<var>args</var> $B$O(B <var>message</var> $B$N0z?t$G$"$k!#(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> -$B!J$9$_$^$;$s!#$=$N$&$A=q$-$^$9(B (^_^;$B!K(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> -$B!J$H$j$"$($:!"(Bmm*.el $B$r;29M$K$7$F$/$@$5$$!K(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 @@ -406,21 +503,22 @@ mechanism to represent kind of character code like MIME charset. </memo> <p> -FLIM $B$O(B Content-Type $BMs$r9=J82r@O$9$k4X?t$H(B Content-Type $BMs$N2r@O7k2L$r(B -$B3JG<$9$k9=B$BN(B <concept>mime-content-type</concept> $B$rDs6!$7$^$9!#(B +FLIM provides parser for Content-Type field and structure +<concept>mime-content-type</concept> to store information of +Content-Type field. <h2> Format of Content-Type field <node> Content-Type field <p> -Content-Type $BMs$N7A<0$O0J2<$N$h$&$KDj5A$5$l$F$$$^$9!'(B +Format of Content-Type field is defined as follows: <quote> ``Content-Type'' ``:'' <concept>type</concept> ``/'' <concept>subtype</concept> *( ``;'' <concept>parameter</concept> ) </quote> <p> -$BNc$($P!"(B +For example: <quote> <verb> @@ -428,25 +526,20 @@ Content-Type: image/jpeg </verb> </quote> -<noindent> -$B$d(B - <quote> <verb> Content-Type: text/plain; charset=iso-2022-jp </verb> </quote> - -<noindent> -$B$J$I$N$h$&$KMQ$$$i$l$^$9!#(B <p> -$B$3$3$G!"(B`type' $B$H(B `subtype' $B$O(B entity $B$N7A<0$r<($9$b$N$G!"N><T$rAm>N$7(B -$B$F!"(B`media-type' $B$H8F$V$3$H$K$7$^$9!#>e5-$NNc$K$*$1$k(B `image/jpeg' $B$d(B -`text/plain' $B$O(B media-type $B$N#1$D$G$9!#(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 $BMs$N$J$$(B entity $B$O(B +If an entity does not have Content-Type field, it is regarded as +following: <quote> <verb> @@ -455,7 +548,7 @@ Content-Type: text/plain; charset=us-ascii </quote> <noindent> -$B$H$7$F2r<a$5$l$k!#(B<cf node="us-ascii"> +<cf node="us-ascii"> </memo> @@ -464,19 +557,20 @@ Content-Type: text/plain; charset=us-ascii <p> <define type="Structure" name="mime-content-type"> <p> -Content-Type $BMs$N>pJs$r3JG<$9$k$?$a$N9=B$BN!#(B +Structure to store information of a Content-Type field. <p> -$B$3$N9=B$BN$r;2>H$9$k$K$O(B <code>mime-content-type-$BMWAGL>(B</code> $B$H$$$&L>(B -$BA0$N;2>H4X?t$rMQ$$$k!#(B +Applications should use reference functions +<code>mime-content-type-SLOT</code> to refer information of the +structure. <p> -$B$3$N9=B$BN$NMWAG$O0J2<$NDL$j$G$"$k!'(B +Slots of the structure are following: <vl> -<dt>primary-type<dd>media-type $B$N<g7?(B (symbol). +<dt>primary-type<dd>primary type of media-type (symbol). </dd> -<dt>subtype<dd>media-type $B$NI{7?(B (symbol). +<dt>subtype<dd>subtype of media-type (symbol). </dd> -<dt>parameters<dd>Content-Type $BMs$N(B parameter ($BO"A[(B list). +<dt>parameters<dd>parameters of Content-Type field (association-list). </dd> </vl> </define> @@ -484,77 +578,82 @@ Content-Type $BMs$N>pJs$r3JG<$9$k$?$a$N9=B$BN!#(B <defun name="make-mime-content-type"> <args> type subtype <opts> parameters -<p>content-type $B$N@8@.;R!#(B +<p>Constructor of content-type. </defun> <defun name="mime-content-type-parameter"> <args> content-type parameter <p> -<var>content-type</var> $B$N(B <var>parameter</var> $B$NCM$rJV$9!#(B +Return value of <var>parameter</var> of <var>content-type</var>. </defun> -<h2> Content-Type $BMs$N2r@O4o(B +<h2> Parser <node> Content-Type parser <p> <defun name="mime-parse-Content-Type"> - <args> string + <args> string <p> -<var>string</var> $B$r(B content-type $B$H$7$F2r@O$7$?7k2L$rJV$9!#(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> -$B8=:_$N(B buffer $B$N(B Content-Type $BMs$rFI$_<h$j!"2r@O$7$?7k2L$rJV$9!#(B +Parse Content-Type field of the current buffer, and return the result +as <dref>mime-content-type</dref> structure. <p> -Content-Type $BMs$,B8:_$7$J$$>l9g$O(B nil $B$rJV$9!#(B +Return <code>nil</code> if Content-Type field is not found. </defun> -<h2> Content-Type $B$K4X$9$kM-MQ$J4X?t(B +<h2> Utility functions <node> Content-Type utility <p> <defun name="mime-type/subtype-string"> - <args> type <opts> subtype + <args> type <opts> subtype <p> -<var>type</var> $B$H(B <var>subtype</var> $B$+$i(B type/subtype $B7A<0$NJ8;zNs$rJV(B -$B$9!#(B +Return type/subtype string from <var>type</var> and +<var>subtype</var>. </defun> -<h1> Content-Disposition $BMs$N>pJs(B +<h1> Information of Content-Disposition field <node> Content-Disposition <p> -<concept>Content-Disposition $BMs(B</concept> $B$O(B entity $B$NI=<($d(B file $BL>$J$I(B -$B$NB0@-$K$J$I$K4X$9$k>pJs$r5-=R$9$k$?$a$N$b$N$G$9!#(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 $B$O(B Content-Disposition $BMs$r9=J82r@O$9$k4X?t$H(B Content-Disposition -$BMs$N2r@O7k2L$r3JG<$9$k9=B$BN(B -<concept>mime-content-disposition</concept> $B$rDs6!$7$^$9!#(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 $B9=B$BN(B +<h2> mime-content-disposition structure <node> mime-content-disposition <p> <define type="Structure" name="mime-content-disposition"> <p> -Content-Disposition $BMs$N2r@O7k2L$r<}$a$k$?$a$N9=B$BN!#(B +Structure to store information of a Content-Disposition field. <p> -$B$3$N9=B$BN$r;2>H$9$k$K$O(B <code>mime-content-disposition-$BMWAGL>(B</code> $B$H(B -$B$$$&L>A0$N;2>H4X?t$rMQ$$$k!#(B +Applications should use reference functions +<code>mime-content-disposition-SLOT</code> to refer information of the +structure. <p> -$B$3$N9=B$BN$NMWAG$O0J2<$NDL$j$G$"$k!'(B +Slots of the structure are following: <vl> <dt>disposition-type<dd>disposition-type (symbol). </dd> -<dt>parameters<dd>Content-Disposition $BMs$N(B parameter ($BO"A[(B list). +<dt>parameters<dd>parameters of Content-Disposition field +(association-list). </dd> </vl> </define> @@ -562,68 +661,75 @@ Content-Disposition $BMs$N2r@O7k2L$r<}$a$k$?$a$N9=B$BN!#(B <defun name="mime-content-disposition-parameter"> <args> content-disposition parameter <p> -<var>content-disposition</var> $B$N(B <var>parameter</var> $B$NCM$rJV$9!#(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> $B$N(B filename $B$NCM$rJV$9!#(B +Return filename of <var>content-disposition</var>. </defun> -<h2> Content-Disposition $BMs$N2r@O4o(B +<h2> Parser for Content-Disposition field <node> Content-Disposition parser <p> <defun name="mime-parse-Content-Disposition"> <args> string <p> -<var>string</var> $B$r(B content-disposition $B$H$7$F2r@O$7$?7k2L$rJV$9!#(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> -$B8=:_$N(B buffer $B$N(B Content-Disposition $BMs$rFI$_<h$j!"2r@O$7$?7k2L$rJV$9!#(B +Parse Content-Disposition field of the current buffer, and return the +result as <dref>mime-content-disposition</dref> structure. <p> -Content-Disposition $BMs$,B8:_$7$J$$>l9g$O(B nil $B$rJV$9!#(B +Return <code>nil</code> if Content-Disposition field is not found. </defun> -<h1> $BId9f2=K!(B +<h1> Encoding Method <node> Content-Transfer-Encoding <p> -<concept>Content-Transfer-Encoding $BMs(B</concept> $B$O(B entity $B$NId9f2=K!$r5-(B -$B=R$9$k$?$a$N$b$N$G$9!#(B +<concept>Content-Transfer-Encoding field</concept> is a header field +to indicate body encoding of a entity. <p> -FLIM $B$G$O(B Content-Transfer-Encoding $BMs$r9=J82r@O$9$k4X?t$rDs6!$7$^$9!#$3(B -$B$l$i$N4X?t$O(B Content-Transfer-Encoding $BMs$N>pJs$OJ8;zNs$GI=8=$7$^$9!#(B +FLIM provides parser functions for Content-Transfer-Encoding field. +They represent information of Content-Transfer-Encoding field as +string. <p> -$B$^$?!"(BContent-Transfer-Encoding $B$K4p$E$$$FId9f2=!&I|9f2=$r9T$&4X?t$bDs(B -$B6!$5$l$^$9!#(B +In addition, FLIM provides encoder/decoder functions by +Content-Transfer-Encoding. -<h2> Content-Transfer-Encoding $BMs$N2r@O4o(B +<h2> Parser <node> Content-Transfer-Encoding parser <p> <defun name="mime-parse-Content-Transfer-Encoding"> - <args> string + <args> string <p> -<var>string</var> $B$r(B content-transfer-encoding $B$H$7$F2r@O$7$?7k2L$rJV$9!#(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> -$B8=:_$N(B buffer $B$N(B Content-Transfer-Encoding $BMs$rFI$_<h$j!"2r@O$7$?7k2L$r(B -$BJV$9!#(B +Parse Content-Transfer-Encoding field of the current buffer, and +return the result. <p> -Content-Transfer-Encoding $BMs$,B8:_$7$J$$>l9g$O(B -<var>default-encoding</var> $B$rJV$9!#(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> $BNN0h$NId9f2=!&I|9f2=(B -<node> Region encoder/decoder +<h2> Encoder/decoder +<node> encoder/decoder <p> <defun name="mime-encode-region"> <args> start end encoding @@ -639,49 +745,15 @@ Decode region <var>start</var> to <var>end</var> of current buffer 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> $BJ8;zNs$NId9f2=!&I|9f2=(B -<node> String encoder/decoder -<p> <defun name="mime-decode-string"> - <args> string encoding + <args> string encoding <p> -<var>string</var> $B$r(B <var>encoding</var> $B$H$7$FI|9f$7$?7k2L$rJV$7$^$9!#(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 $B$NId9f2=!&I|9f2=(B -<node> File encoder/decoder -<p> <defun name="mime-insert-encoded-file"> <args> filename encoding <p> @@ -697,96 +769,182 @@ Decode and write current region encoded by <var>encoding</var> into <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> -<h1> Header $B$N(B network $BI=8=(B +<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 $B$O(B header $B$GHs(B <dref>ASCII</dref> $BJ8;z$rI=8=$9$k$?$a$N7A(B -$B<0$G!"(B<concept>RFC 2047</concept> $B$GDj5A$5$l$F$$$^$9!#(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> -$B$^$?!"9T57$N0-$$$3$H$@$H8@$($^$9$,!"(Bencoded-word $B$rMQ$$$:$KHs(B -<dref>ASCII</dref> $BJ8;z$r(B header $B$KF~$l$?5-;v$bB8:_$7$^$9!#(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 $B$O$3$l$i$rId9f2=!&I|9f2=$9$k5!G=$rDs6!$7$^$9!#(B +FLIM provides encoding/decoding features of both encoded-word and +invalid "raw" non-<dref>ASCII</dref> characters. -<h2> Header $B$NId9f2=!&I|9f2=(B +<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> $B0lHL@_Dj(B -<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 $B4XO"5!G=$K4X$9$k(B group. +If METHOD is <code>mime</code>, the FIELD will be encoded into MIME +format (encoded-word). <p> -<code>mail</code> $B$H(B <code>news</code> $B$KB0$9$k!#(B -</define> - -<defvar name="default-mime-charset"> +If METHOD is <code>nil</code>, the FIELD will not be encoded. <p> -$BE,@Z$J(B <dref>MIME charset</dref> $B$,8+$D$+$i$J$+$C$?>l9g$KMQ$$$i$l$k(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> -$BK\Mh$O(B APEL $B$NJQ?t$G$"$k!#(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 $B5!G=$K4X$9$k<BAu$,0l;~E*$K;HMQ$9$k(B file $B$r:n@.$9$k(B directory. +<define type="group" name="mime"> <p> -$B4D6-JQ?t(B <code>MIME_TMP_DIR</code>, <code>TM_TMP_DIR</code>, -<code>TMPDIR</code>, <code>TMP</code> $B$b$7$/$O(B <code>TEMP</code> $B$,@_Dj(B -$B$5$l$F$$$?>l9g!"$=$l$r=i4|CM$H$7$FMQ$$$k!#2?$b@_Dj$5$l$F$$$J$$>l9g!"(B -<code>"/tmp/"</code> $B$rMQ$$$k!#(B -</defvar> +The group associated with functions related to MIME. +<p> +It belongs to <code>mail</code> and <code>news</code>. +</define> <h1> Appendix @@ -884,7 +1042,7 @@ translated by non-Internet gateways. <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 @@ -1122,11 +1280,11 @@ be interpreted as us-ascii. <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> @@ -1143,49 +1301,48 @@ to send backtrace is very important. <cf file="emacs" node="Bugs"> 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 $B$N(B file $B$O(B CVS $B$r;H$C$F4IM}$5$l$F$$$^$9!#$3$N$?$a!"0J2<$NJ}K!$G:G(B -$B?7$N(B FLIM $B$rF~<j$9$k$3$H$,$G$-$^$9!'(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 $B$rMQ$$$?3+H/$K;22C$7$?$$J}$O(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> -$B$^$G!"(Baccount $BL>$H(B UNIX $B$N(B passwd $B$HF1$87A<0$N(B crypt $B2=$5$l$?(B password -$B$r1h$($F8fO"Mm$/$@$5$$!#(B +with your account name and your public key for ssh. +cvsroot is :ext:cvs@@cvs.m17n.org:/cvs/root. <h2> History of FLIM