X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=mime-en.sgml;h=35783dff761fa537e39f1b72778574fea366b80e;hb=refs%2Fheads%2Fflim-1_14;hp=1ec17582bc6aaedc9b55a381fd78cec01fb932f5;hpb=1126ce6d802977911ec3eb93a67749ba15609b44;p=elisp%2Fflim.git diff --git a/mime-en.sgml b/mime-en.sgml index 1ec1758..35783df 100644 --- a/mime-en.sgml +++ b/mime-en.sgml @@ -1,8 +1,8 @@ -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> @@ -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> @@ -165,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> @@ -183,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 @@ -264,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>. @@ -276,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 @@ -288,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> @@ -393,12 +450,42 @@ return the result. </defun> -<h3> How to make mm-backend +<h3> Definition of mm-backend <node> mm-backend module <p> -(It is not written yet, sorry. (^_^;) +<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> +Example: <p> -(Please read mm*.el) +<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 @@ -505,15 +592,16 @@ Return value of <var>parameter</var> of <var>content-type</var>. <node> Content-Type parser <p> <defun name="mime-parse-Content-Type"> - <args> string + <args> string <p> -Parse <var>string</var> as field-body of Content-Type field. +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> -Read field-body of Content-Type field from current-buffer, -and return parsed it. +Parse Content-Type field of the current buffer, and return the result +as <dref>mime-content-type</dref> structure. <p> Return <code>nil</code> if Content-Type field is not found. </defun> @@ -523,7 +611,7 @@ Return <code>nil</code> if Content-Type field is not found. <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>. @@ -538,10 +626,10 @@ 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 provides parser for Content-Disposition field and structure <concept>mime-content-disposition</concept> to store information of @@ -591,52 +679,57 @@ Return filename of <var>content-disposition</var>. <args> string <p> Parse <var>string</var> as field-body of Content-Disposition field, -and return the result. +and return the result as <dref>mime-content-disposition</dref> +structure. </defun> <defun name="mime-read-Content-Disposition"> <p> -Read field-body of Content-Disposition field from current-buffer, +Parse Content-Disposition field of the current buffer, and return the +result as <dref>mime-content-disposition</dref> structure. <p> -Return nil if Content-Disposition field is not found. +Return <code>nil</code> if Content-Disposition field is not found. </defun> <h1> Encoding Method <node> Content-Transfer-Encoding <p> -<concept>Content-Transfer-Encoding 欄</concept> は entity の符号化法を記 -述するためのものです。 +<concept>Content-Transfer-Encoding field</concept> is a header field +to indicate body encoding of a entity. <p> -FLIM では Content-Transfer-Encoding 欄を構文解析する関数を提供します。こ -れらの関数は Content-Transfer-Encoding 欄の情報は文字列で表現します。 +FLIM provides parser functions for Content-Transfer-Encoding field. +They represent information of Content-Transfer-Encoding field as +string. <p> -また、Content-Transfer-Encoding に基づいて符号化・復号化を行う関数も提 -供されます。 +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> を content-transfer-encoding として解析した結果を返す。 +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> -現在の buffer の Content-Transfer-Encoding 欄を読み取り、解析した結果を -返す。 +Parse Content-Transfer-Encoding field of the current buffer, and +return the result. <p> -Content-Transfer-Encoding 欄が存在しない場合は -<var>default-encoding</var> を返す。 +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 @@ -652,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> String encoding/decoding -<node> String encoder/decoder -<p> <defun name="mime-decode-string"> - <args> string encoding + <args> string encoding <p> -<var>string</var> を <var>encoding</var> として復号した結果を返します。 +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> @@ -710,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> + + +<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 は header で非 <dref>ASCII</dref> 文字を表現するための形 -式で、<concept>RFC 2047</concept> で定義されています。 +<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> -また、行儀の悪いことだと言えますが、encoded-word を用いずに非 -<dref>ASCII</dref> 文字を header に入れた記事も存在します。 +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 はこれらを符号化・復号化する機能を提供します。 +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 関連機能に関する group. +If METHOD is <code>mime</code>, the FIELD will be encoded into MIME +format (encoded-word). <p> -<code>mail</code> と <code>news</code> に属する。 -</define> - -<defvar name="default-mime-charset"> +If METHOD is <code>nil</code>, the FIELD will not be encoded. <p> -適切な <dref>MIME charset</dref> が見つからなかった場合に用いられる -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> -本来は APEL の変数である。 +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> +<define type="group" name="mime"> <p> -MIME 機能に関する実装が一時的に使用する file を作成する directory. +The group associated with functions related to MIME. <p> -環境変数 <code>MIME_TMP_DIR</code>, <code>TM_TMP_DIR</code>, -<code>TMPDIR</code>, <code>TMP</code> もしくは <code>TEMP</code> が設定 -されていた場合、それを初期値として用いる。何も設定されていない場合、 -<code>"/tmp/"</code> を用いる。 -</defvar> +It belongs to <code>mail</code> and <code>news</code>. +</define> <h1> Appendix @@ -1135,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> @@ -1156,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 の file は CVS を使って管理されています。このため、以下の方法で最 -新の FLIM を入手することができます： +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 を用いた開発に参加したい方は +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> -まで、account 名と UNIX の passwd と同じ形式の crypt 化された password -を沿えて御連絡ください。 +with your account name and your public key for ssh. +cvsroot is :ext:cvs@@cvs.m17n.org:/cvs/root. <h2> History of FLIM