X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=mime-en.sgml;h=de14cb9831bad467febd6ef044e415989319578f;hb=99c158b34f006c5840785347fc7e711a6b246c0c;hp=a8e0e42a37c0716d47de15ea3035069d791d3488;hpb=f0a9e3c90638ef0c24c80ab431d40ecbdad2d152;p=elisp%2Fflim.git diff --git a/mime-en.sgml b/mime-en.sgml index a8e0e42..de14cb9 100644 --- a/mime-en.sgml +++ b/mime-en.sgml @@ -1,6 +1,6 @@ -FLIM 1.9 Manual about MIME Features +<title>FLIM 1.10 Manual about MIME Features <author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail> <date>1998/07/01 @@ -264,7 +264,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 +280,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 @@ -393,12 +421,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> -(Please read mm*.el) +If <var>PARENTS</var> is specified, <var>type</var> inherits parents. +Each parent must be representation-type. +<p> +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 @@ -424,14 +482,14 @@ Content-Type field. <h2> Format of Content-Type field <node> Content-Type field <p> -Content-Type 欄の形式は以下のように定義されています： +Format of Content-Type field is defined as follows: <quote> ``Content-Type'' ``:'' <concept>type</concept> ``/'' <concept>subtype</concept> *( ``;'' <concept>parameter</concept> ) </quote> <p> -例えば、 +For example: <quote> <verb> @@ -439,25 +497,20 @@ Content-Type: image/jpeg </verb> </quote> -<noindent> -や - <quote> <verb> Content-Type: text/plain; charset=iso-2022-jp </verb> </quote> - -<noindent> -などのように用いられます。 <p> -ここで、`type' と `subtype' は entity の形式を示すもので、両者を総称し -て、`media-type' と呼ぶことにします。上記の例における `image/jpeg' や -`text/plain' は media-type の１つです。 +`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 欄のない entity は +If an entity does not have Content-Type field, it is regarded as +following: <quote> <verb> @@ -466,7 +519,7 @@ Content-Type: text/plain; charset=us-ascii </quote> <noindent> -として解釈される。<cf node="us-ascii"> +<cf node="us-ascii"> </memo> @@ -475,19 +528,20 @@ Content-Type: text/plain; charset=us-ascii <p> <define type="Structure" name="mime-content-type"> <p> -Content-Type 欄の情報を格納するための構造体。 +Structure to store information of a Content-Type field. <p> -この構造体を参照するには <code>mime-content-type-要素名</code> という名 -前の参照関数を用いる。 +Applications should use reference functions +<code>mime-content-type-SLOT</code> to refer information of the +structure. <p> -この構造体の要素は以下の通りである： +Slots of the structure are following: <vl> -<dt>primary-type<dd>media-type の主型 (symbol). +<dt>primary-type<dd>primary type of media-type (symbol). </dd> -<dt>subtype<dd>media-type の副型 (symbol). +<dt>subtype<dd>subtype of media-type (symbol). </dd> -<dt>parameters<dd>Content-Type 欄の parameter (連想 list). +<dt>parameters<dd>parameters of Content-Type field (association-list). </dd> </vl> </define> @@ -495,13 +549,13 @@ Content-Type 欄の情報を格納するための構造体。 <defun name="make-mime-content-type"> <args> type subtype <opts> parameters -<p>content-type の生成子。 +<p>Constructor of content-type. </defun> <defun name="mime-content-type-parameter"> <args> content-type parameter <p> -<var>content-type</var> の <var>parameter</var> の値を返す。 +Return value of <var>parameter</var> of <var>content-type</var>. </defun> @@ -509,16 +563,18 @@ Content-Type 欄の情報を格納するための構造体。 <node> Content-Type parser <p> <defun name="mime-parse-Content-Type"> - <args> string + <args> string <p> -<var>string</var> を content-type として解析した結果を返す。 +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> -現在の buffer の Content-Type 欄を読み取り、解析した結果を返す。 +Parse Content-Type field of the current buffer, and return the result +as <dref>mime-content-type</dref> structure. <p> -Content-Type 欄が存在しない場合は nil を返す。 +Return <code>nil</code> if Content-Type field is not found. </defun> @@ -526,7 +582,7 @@ Content-Type 欄が存在しない場合は nil を返す。 <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>. @@ -536,18 +592,19 @@ Return type/subtype string from <var>type</var> and <h1> Information of Content-Disposition field <node> Content-Disposition <p> -<concept>Content-Disposition 欄</concept> は entity の表示や file 名など -の属性になどに関する情報を記述するためのものです。 +<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 は Content-Disposition 欄を構文解析する関数と Content-Disposition -欄の解析結果を格納する構造体 -<concept>mime-content-disposition</concept> を提供します。 +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 @@ -555,17 +612,19 @@ FLIM は Content-Disposition 欄を構文解析する関数と Content-Dispositi <p> <define type="Structure" name="mime-content-disposition"> <p> -Content-Disposition 欄の解析結果を収めるための構造体。 +Structure to store information of a Content-Disposition field. <p> -この構造体を参照するには <code>mime-content-disposition-要素名</code> と -いう名前の参照関数を用いる。 +Applications should use reference functions +<code>mime-content-disposition-SLOT</code> to refer information of the +structure. <p> -この構造体の要素は以下の通りである： +Slots of the structure are following: <vl> <dt>disposition-type<dd>disposition-type (symbol). </dd> -<dt>parameters<dd>Content-Disposition 欄の parameter (連想 list). +<dt>parameters<dd>parameters of Content-Disposition field +(association-list). </dd> </vl> </define> @@ -573,13 +632,14 @@ Content-Disposition 欄の解析結果を収めるための構造体。 <defun name="mime-content-disposition-parameter"> <args> content-disposition parameter <p> -<var>content-disposition</var> の <var>parameter</var> の値を返す。 +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> の filename の値を返す。 +Return filename of <var>content-disposition</var>. </defun> @@ -589,52 +649,58 @@ Content-Disposition 欄の解析結果を収めるための構造体。 <defun name="mime-parse-Content-Disposition"> <args> string <p> -<var>string</var> を content-disposition として解析した結果を返す。 +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> -現在の buffer の Content-Disposition 欄を読み取り、解析した結果を返す。 +Parse Content-Disposition field of the current buffer, and return the +result as <dref>mime-content-disposition</dref> structure. <p> -Content-Disposition 欄が存在しない場合は nil を返す。 +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 @@ -650,49 +716,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> @@ -708,24 +740,102 @@ 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 @@ -748,28 +858,49 @@ FLIM はこれらを符号化・復号化する機能を提供します。 <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>eword-field-encoding-method-alist</code>. </defun> +<defvar name="eword-field-encoding-method-alist"> +<p> +Association list to specify field encoding method. Each element looks +like (FIELD . METHOD). +<p> +If METHOD is <code>mime</code>, the FIELD will be encoded into MIME +format (encoded-word). +<p> +If METHOD is <code>nil</code>, the FIELD will not be encoded. +<p> +If METHOD is a MIME charset, the FIELD will be encoded as the charset +when it must be convert into network-code. +<p> +Otherwise the FIELD will be encoded as variable +<code>default-mime-charset</code> when it must be convert into +network-code. +</defvar> + <h1> Various Customization <node> custom @@ -781,14 +912,6 @@ MIME 関連機能に関する group. <code>mail</code> と <code>news</code> に属する。 </define> -<defvar name="default-mime-charset"> -<p> -適切な <dref>MIME charset</dref> が見つからなかった場合に用いられる -MIME charset. -<p> -本来は APEL の変数である。 -</defvar> - <defvar name="mime-temp-directory"> <p> MIME 機能に関する実装が一時的に使用する file を作成する directory.