(Content-Type field): Translate.
[elisp/flim.git] / mime-en.sgml
1 <!doctype sinfo system>
2 <head>
3 <title>FLIM 1.9 Manual about MIME Features
4 <author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail>
5 <date>1998/07/01
6
7 <toc>
8 </head>
9
10 <body>
11
12 <abstract>
13 <p>
14 This file documents MIME features of FLIM, a Internet message
15 parsing/encoding library for GNU Emacs.
16 </abstract>
17
18
19 <h1> What is FLIM?
20 <node> Introduction
21 <p>
22 FLIM is a library to provide basic features about message
23 representation or encoding.
24
25
26 <h1> How to use MIME features
27 <node> How to use
28 <p>
29 Please eval following to use MIME features provided by FLIM:
30
31 <lisp>
32 (require 'mime)
33 </lisp>
34
35
36 <h1> Message and Entity
37 <node> Entity
38 <p>
39 According to <dref>RFC 2045</dref>, `The term ``entity'', refers
40 specifically to the MIME-defined header fields and contents of either
41 a message or one of the parts in the body of a multipart entity.'  In
42 this document, the term <concept>entity</concept> indicates all of
43 header fields and body.
44 <p>
45 The definition of RFC 2045 indicates that a MIME message is a tree,
46 and each node of the tree is an entity.  Namely MIME extends message
47 to tree structure.
48 <p>
49 FLIM uses <concept>mime-entity</concept> structure to represent
50 information of entity.  In this document, it is called simply
51 `mime-entity'.
52
53
54 <h2> Functions to create mime-entity
55 <node> Entity creation
56 <p>
57 <defun name="mime-open-entity">
58           <opts> type location
59 <p>
60 Open an entity and return it.
61 <p>
62 <var>type</var> is representation-type. <cf node="mm-backend">
63 <p>
64 <var>location</var> is location of entity.  Specification of it is
65 depended on representation-type.
66 </defun>
67
68 <defun name="mime-parse-buffer">
69           <opts> buffer type
70 <p>
71 Parse <var>buffer</var> as message, and set the result to buffer local
72 variable <code>mime-message-structure</code> of <var>buffer</var> as
73 mime-entity.
74 <p>
75 If <var>buffer</var> is omitted, current buffer is used.
76 <p>
77 <var>type</var> is representation-type of created mime-entity. <cf
78 node="mm-backend"> Default value is <var>buffer</var>.
79 </defun>
80
81
82 <h2> Features about message tree
83 <node> Entity hierarchy
84 <p>
85 Structure of a MIME message is tree.
86 <p>
87 In the tree, root node is the entity indicates all of the message.  In
88 this document, it is called <concept>root-entity</concept> or
89 <concept>message</concept>.  In FLIM, it is indicated by buffer local
90 variable <code>mime-message-structure</code>.
91 <p>
92 Each entity except root-entity has a parent.  An entity may have
93 children.  We can indicate an entity by relative position from a base
94 entity, based on the parent-child relationship.
95 <p>
96 In addition, we can indicate an entity by absolute position of the
97 message.
98 <p>
99 Each entity, which is a node of the tree, can be numbered by
100 depth and left-to-right order of the depth.
101 <verb>
102
103                               +-------+
104                               |  nil  |
105                               +---+---+
106               +-------------------+-------------------+
107             +-+-+               +-+-+               +-+-+
108             | 0 |               | 1 |               | 2 |
109             +-+-+               +-+-+               +-+-+
110               |         +---------+---------+         |
111            +--+--+   +--+--+   +--+--+   +--+--+   +--+--+
112            | 0.0 |   | 1.0 |   | 1.1 |   | 1.2 |   | 2.0 |
113            +-----+   +-----+   +-----+   +-----+   +-----+
114
115 </verb>
116 <p>
117 Namely, if depth of a node is n, the node has a node-number, which is
118 consists of n integers.  In this document, it is called
119 <concept>entity-number</concept>.  An entity-number is represented by
120 list of integer, like <code>(1 2 3)</code>.
121 <p>
122 mime-entity has also <concept>node-id</concept>.  A node-id is
123 represented by reversed list of entity-number.  For example, node-id
124 corresponding with 1.2.3 is <code>(3 2 1)</code>.
125 <p>
126 Each entity can be indicated by entity-number or node-id in
127 <code>mime-message-structure</code>.
128
129 <defvar name="mime-message-structure">
130 <p>
131 Buffer local variable to store mime-entity structure of message.
132 </defvar>
133
134 <defun name="mime-entity-children">
135           <args> entity
136 <p>
137 Return list of entities included in the <var>entity</var>.
138 </defun>
139
140 <defun name="mime-entity-parent">
141           <args> entity <opts> message
142 <p>
143 Return parent entity of the <var>entity</var>.
144 <p>
145 If <var>message</var> is specified, it is regarded as root instead of
146 <code>mime-message-structure</code>.
147 </defun>
148
149 <defun name="mime-root-entity-p">
150           <args> entity
151 <p>
152 Return non-<code>nil</code> if <var>entity</var> is root entity
153 (message).
154 </defun>
155
156 <defun name="mime-entity-node-id">
157           <args> entity
158 <p>
159 Return node-id of <var>entity</var>.
160 </defun>
161
162 <defun name="mime-entity-number">
163           <args> entity
164 <p>
165 Return entity-number of <var>entity</var>.
166 </defun>
167
168 <defun name="mime-find-entity-from-number">
169             <args> entity-number <opts> message
170 <p>
171 Return entity from <var>entity-number</var> in <var>message</var>.
172 <p>
173 If <var>message</var> is not specified,
174 <code>mime-message-structure</code> is used.
175 </defun>
176
177 <defun name="mime-find-entity-from-node-id">
178             <args> entity-node-id <opts> message
179 <p>
180 Return entity from <var>entity-node-id</var> in <var>message</var>.
181 <p>
182 If <var>message</var> is not specified,
183 <code>mime-message-structure</code> is used.
184 </defun>
185
186
187 <h2> Functions about attributes of mime-entity
188 <node> Entity Attributes
189 <p>
190 <defun name="mime-entity-content-type">
191             <args> entity
192 <p>
193 Return content-type of <var>entity</var>.
194 <cf node="mime-content-type">
195 </defun>
196
197 <defun name="mime-entity-content-disposition">
198             <args> entity
199 <p>
200 Return content-disposition of <var>entity</var>. <cf
201 node="mime-content-disposition">
202 </defun>
203
204 <defun name="mime-entity-filename">
205             <args> entity
206 <p>
207 Return file name of <var>entity</var>.
208 </defun>
209
210 <defun name="mime-entity-encoding">
211             <args> entity <opts> default-encoding
212 <p>
213 Return content-transfer-encoding of <var>entity</var>.
214 <cf node="Content-Transfer-Encoding">
215 <p>
216 If the <var>entity</var> does not have Content-Transfer-Encoding
217 field, this function returns <var>default-encoding</var>.  If it is
218 nil, <code>"7bit"</code> is used as default value.
219 </defun>
220
221 <defun name="mime-entity-cooked-p">
222             <args> entity
223 <p>
224 Return non-nil if contents of <var>entity</var> has been already
225 code-converted.
226 </defun>
227
228
229 <h2> Information of entity header
230 <node> Entity-header
231 <p>
232 <defun name="mime-fetch-field">
233             <args> field-name <opts> entity
234 <p>
235 Return field-body of <var>field-name</var> field in header of
236 <var>entity</var>.
237 <p>
238 The results is network representation.
239 <p>
240 If <var>entity</var> is omitted, <code>mime-message-structure</code>
241 is used as default value.
242 <p>
243 If <var>field-name</var> field is not found, this function returns
244 <code>nil</code>.
245 </defun>
246
247 <defun name="mime-read-field">
248             <args> field-name <opts> entity
249 <p>
250 Parse <var>field-name</var> field in header of <var>entity</var>, and
251 return the result.
252 <p>
253 Format of result is depended on kind of field.  For non-structured
254 field, this function returns string.  For structured field, it returns
255 list corresponding with structure of the field.
256 <p>
257 Strings in the result will be converted to internal representation of
258 Emacs.
259 <p>
260 If <var>entity</var> is omitted, <code>mime-message-structure</code>
261 is used as default value.
262 <p>
263 If <var>field-name</var> field is not found, this function returns
264 <code>nil</code>.
265 </defun>
266
267 <defun name="mime-insert-decoded-header">
268             <args> entity <opts> invisible-fields visible-fields
269 <p>
270 Insert before point a decoded contents of header of <var>entity</var>.
271 <p>
272 <var>invisible-fields</var> is list of regexps to match field-name to
273 hide.  <var>visible-fields</var> is list of regexps to match
274 field-name to hide.
275 <p>
276 If a field-name is matched with some elements of
277 <var>invisible-fields</var> and matched with none of
278 <var>visible-fields</var>, this function don't insert the field.
279 </defun>
280
281
282 <h2> Contents of Entity
283 <node> Entity-content
284 <p>
285 <defun name="mime-entity-content">
286             <args> entity
287 <p>
288 Return content of <var>entity</var> as byte sequence.
289 </defun>
290
291 <defun name="mime-write-entity-content">
292             <args> entity filename
293 <p>
294 Write content of <var>entity</var> into <var>filename</var>.
295 </defun>
296
297 <defun name="mime-write-entity">
298             <args> entity filename
299 <p>
300 Write representation of <var>entity</var> into <var>filename</var>.
301 </defun>
302
303 <defun name="mime-write-entity-body">
304             <args> entity filename
305 <p>
306 Write body of <var>entity</var> into <var>filename</var>.
307 </defun>
308
309
310 <h2> Entity as buffer representation
311 <node> Entity buffer
312 <p>
313 <defun name="mime-entity-buffer">
314             <args> entity
315 <p>
316 Return buffer, which contains <var>entity</var>.
317 </defun>
318
319 <defun name="mime-entity-point-min">
320             <args> entity
321 <p>
322 Return the start point of <var>entity</var> in the buffer which
323 contains <var>entity</var>.
324 </defun>
325
326 <defun name="mime-entity-point-max">
327             <args> entity
328 <p>
329 Return the end point of <var>entity</var> in the buffer which
330 contains <var>entity</var>.
331 </defun>
332
333 <defun name="mime-entity-header-start">
334             <args> entity
335 <p>
336 Return the start point of header of <var>entity</var> in the buffer
337 which contains <var>entity</var>.
338 </defun>
339
340 <defun name="mime-entity-header-end">
341             <args> entity
342 <p>
343 Return the end point of header of <var>entity</var> in the buffer
344 which contains <var>entity</var>.
345 </defun>
346
347 <defun name="mime-entity-body-start">
348             <args> entity
349 <p>
350 Return the start point of body of <var>entity</var> in the buffer
351 which contains <var>entity</var>.
352 </defun>
353
354 <defun name="mime-entity-body-end">
355             <args> entity
356 <p>
357 Return the end point of body of <var>entity</var> in the buffer which
358 contains <var>entity</var>.
359 </defun>
360
361
362 <h2> Entity representations and implementations
363 <node> mm-backend
364 <p>
365 Entity is an abstraction.  It is designed to use various data
366 representations for their purposes.
367 <p>
368 Each entity has <concept>representation-type</concept>.  It must be
369 specified when an entity is created. <cf node="Entity Creation">
370 <p>
371 Functions about entity are implemented by request processing to the
372 entity.  Each entity knows its representation-type.  Each entity calls
373 processing function corresponding with the representation-type.  Such
374 kind of function is called <concept>entity processing
375 method</concept>.  A module, consists of them corresponding with a
376 representation-type, is called <concept>mm-backend</concept>.
377 <p>
378 Module name of each mm-backend consists of the prefix <code>mm</code>
379 and its representation-type.  The module is required automatically
380 when its entity is created at first.
381
382
383 <h3> Message-passing for entity
384 <node> Request for entity
385 <p>
386 <defun name="mime-entity-send">
387               <args> entity message <rest> args
388 <p>
389 Send <var>message</var> to <var>entity</var> with <var>args</var>, and
390 return the result.
391 <p>
392 <var>args</var> is arguments of the <var>message</var>.
393 </defun>
394
395
396 <h3> How to make mm-backend
397 <node> mm-backend module
398 <p>
399 (It is not written yet, sorry. (^_^;)
400 <p>
401 (Please read mm*.el)
402
403
404 <h1> Information of Content-Type field
405 <node> Content-Type
406 <p>
407 <concept>Content-Type field</concept> is a field to indicate kind of
408 contents or data format, such as <dref>media-type</dref> and MIME
409 charset.  It is defined in <dref>RFC 2045</dref>.
410
411 <memo>
412 <p>
413 Historically, Content-Type field was proposed in RFC 1049.  In it,
414 Content-Type did not distinguish type and subtype, and there are no
415 mechanism to represent kind of character code like MIME charset.
416 </memo>
417
418 <p>
419 FLIM provides parser for Content-Type field and structure
420 <concept>mime-content-type</concept> to store information of
421 Content-Type field.
422
423
424 <h2> Format of Content-Type field
425 <node> Content-Type field
426 <p>
427 Format of Content-Type field is defined as follows:
428
429 <quote>
430 ``Content-Type'' ``:'' <concept>type</concept> ``/''
431 <concept>subtype</concept> *( ``;'' <concept>parameter</concept> )
432 </quote>
433 <p>
434 For example:
435
436 <quote>
437 <verb>
438 Content-Type: image/jpeg
439 </verb>
440 </quote>
441
442 <quote>
443 <verb>
444 Content-Type: text/plain; charset=iso-2022-jp
445 </verb>
446 </quote>
447 <p>
448 `type' and `subtype' indicate format of an entity.  In this document,
449 pair of them is called `media-type'.  `image/jpeg' or `text/plain' is
450 a media-type.
451
452 <memo>
453 <p>
454 If an entity does not have Content-Type field, it is regarded as
455 following:
456
457 <quote>
458 <verb>
459 Content-Type: text/plain; charset=us-ascii
460 </verb>
461 </quote>
462
463 <noindent>
464 <cf node="us-ascii">
465 </memo>
466
467
468 <h2> mime-content-type structure
469 <node> mime-content-type
470 <p>
471 <define type="Structure" name="mime-content-type">
472 <p>
473 Structure to store information of a Content-Type field.
474 <p>
475 Applications should use reference functions
476 <code>mime-content-type-SLOT</code> to refer information of the
477 structure.
478 <p>
479 Slots of the structure are following:
480
481 <vl>
482 <dt>primary-type<dd>primary type of media-type (symbol).
483 </dd>
484 <dt>subtype<dd>subtype of media-type (symbol).
485 </dd>
486 <dt>parameters<dd>parameters of Content-Type field (association-list).
487 </dd>
488 </vl>
489 </define>
490
491 <defun name="make-mime-content-type">
492           <args> type subtype
493           <opts> parameters
494 <p>Constructor of content-type.
495 </defun>
496
497 <defun name="mime-content-type-parameter">
498 <args> content-type parameter
499 <p>
500 Return value of <var>parameter</var> of <var>content-type</var>.
501 </defun>
502
503
504 <h2> Parser
505 <node> Content-Type parser
506 <p>
507 <defun name="mime-parse-Content-Type">
508           <args> string
509 <p>
510 Parse <var>string</var> as field-body of Content-Type field.
511 </defun>
512
513 <defun name="mime-read-Content-Type">
514 <p>
515 Read field-body of Content-Type field from current-buffer,
516 and return parsed it.
517 <p>
518 Return <code>nil</code> if Content-Type field is not found.
519 </defun>
520
521
522 <h2> Utility functions
523 <node> Content-Type utility
524 <p>
525 <defun name="mime-type/subtype-string">
526           <args> type <opts> subtype
527 <p>
528 Return type/subtype string from <var>type</var> and
529 <var>subtype</var>.
530 </defun>
531
532
533 <h1> Information of Content-Disposition field
534 <node> Content-Disposition
535 <p>
536 <concept>Content-Disposition field</concept> is an optional field to
537 specify presentation of an entity or attributes of an entity, such as
538 file name.
539
540 <rfc number="2183" type="Standards Track"
541               author="S. Dorner, K. Moore and R. Troost"
542               title="Communicating Presentation Information in
543               Internet Messages: The Content-Disposition Header"
544               date="August 1997">
545 <p>
546 FLIM provides parser for Content-Disposition field and structure
547 <concept>mime-content-disposition</concept> to store information of
548 Content-Disposition field.
549
550
551 <h2> mime-content-disposition structure
552 <node> mime-content-disposition
553 <p>
554 <define type="Structure" name="mime-content-disposition">
555 <p>
556 Structure to store information of a Content-Disposition field.
557 <p>
558 Applications should use reference functions
559 <code>mime-content-disposition-SLOT</code> to refer information of the
560 structure.
561 <p>
562 Slots of the structure are following:
563
564 <vl>
565 <dt>disposition-type<dd>disposition-type (symbol).
566 </dd>
567 <dt>parameters<dd>parameters of Content-Disposition field
568 (association-list).
569 </dd>
570 </vl>
571 </define>
572
573 <defun name="mime-content-disposition-parameter">
574 <args> content-disposition parameter
575 <p>
576 Return value of <var>parameter</var> of
577 <var>content-disposition</var>.
578 </defun>
579
580 <defun name="mime-content-disposition-filename">
581 <args> content-disposition
582 <p>
583 Return filename of <var>content-disposition</var>.
584 </defun>
585
586
587 <h2> Parser for Content-Disposition field
588 <node> Content-Disposition parser
589 <p>
590 <defun name="mime-parse-Content-Disposition">
591             <args> string
592 <p>
593 Parse <var>string</var> as field-body of Content-Disposition field,
594 and return the result.
595 </defun>
596
597 <defun name="mime-read-Content-Disposition">
598 <p>
599 Read field-body of Content-Disposition field from current-buffer,
600 <p>
601 Return nil if Content-Disposition field is not found.
602 </defun>
603
604
605 <h1> Encoding Method
606 <node> Content-Transfer-Encoding
607 <p>
608 <concept>Content-Transfer-Encoding \e$BMs\e(B</concept> \e$B$O\e(B entity \e$B$NId9f2=K!$r5-\e(B
609 \e$B=R$9$k$?$a$N$b$N$G$9!#\e(B
610 <p>
611 FLIM \e$B$G$O\e(B Content-Transfer-Encoding \e$BMs$r9=J82r@O$9$k4X?t$rDs6!$7$^$9!#$3\e(B
612 \e$B$l$i$N4X?t$O\e(B Content-Transfer-Encoding \e$BMs$N>pJs$OJ8;zNs$GI=8=$7$^$9!#\e(B
613 <p>
614 \e$B$^$?!"\e(BContent-Transfer-Encoding \e$B$K4p$E$$$FId9f2=!&I|9f2=$r9T$&4X?t$bDs\e(B
615 \e$B6!$5$l$^$9!#\e(B
616
617
618 <h2> Parser
619 <node> Content-Transfer-Encoding parser
620 <p>
621 <defun name="mime-parse-Content-Transfer-Encoding">
622           <args> string
623 <p>
624 <var>string</var> \e$B$r\e(B content-transfer-encoding \e$B$H$7$F2r@O$7$?7k2L$rJV$9!#\e(B
625 </defun>
626
627 <defun name="mime-read-Content-Transfer-Encoding">
628           <opts>default-encoding
629 <p>
630 \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
631 \e$BJV$9!#\e(B
632 <p>
633 Content-Transfer-Encoding \e$BMs$,B8:_$7$J$$>l9g$O\e(B
634 <var>default-encoding</var> \e$B$rJV$9!#\e(B
635 </defun>
636
637
638 <h2> Region encoding/decoding
639 <node> Region encoder/decoder
640 <p>
641 <defun name="mime-encode-region">
642             <args> start end encoding
643 <p>
644 Encode region <var>start</var> to <var>end</var> of current buffer
645 using <var>encoding</var>.
646 </defun>
647
648 <defun name="mime-decode-region">
649             <args> start end encoding
650 <p>
651 Decode region <var>start</var> to <var>end</var> of current buffer
652 using <var>encoding</var>.
653 </defun>
654
655 <defvar name="mime-encoding-method-alist">
656 <p>
657 Alist of encoding vs. corresponding method to encode region.
658 <p>
659 Each element looks like <code>(STRING . FUNCTION)</code> or
660 <code>(STRING . nil)</code>.  <var>string</var> is
661 content-transfer-encoding.  <code>function</code> is region encoder
662 and <code>nil</code> means not to encode.
663 </defvar>
664
665 <defvar name="mime-decoding-method-alist">
666 <p>
667 Alist of encoding vs. corresponding method to decode region.
668 <p>
669 Each element looks like <code>(STRING . FUNCTION)</code> or
670 <code>(STRING . nil)</code>.  <var>string</var> is
671 content-transfer-encoding.  <code>function</code> is region decoder
672 and <code>nil</code> means not to decode.
673 </defvar>
674
675
676 <h2> String encoding/decoding
677 <node> String encoder/decoder
678 <p>
679 <defun name="mime-decode-string">
680               <args> string encoding
681 <p>
682 <var>string</var> \e$B$r\e(B <var>encoding</var> \e$B$H$7$FI|9f$7$?7k2L$rJV$7$^$9!#\e(B
683 </defun>
684
685 <defvar name="mime-string-decoding-method-alist">
686 <p>
687 Alist of encoding vs. corresponding method to decode string.
688 <p>
689 Each element looks like <code>(STRING . FUNCTION)</code>.
690 STRING is content-transfer-encoding.
691 FUNCTION is string decoder.
692 </defvar>
693
694
695 <h2> File encoding/decoding
696 <node> File encoder/decoder
697 <p>
698 <defun name="mime-insert-encoded-file">
699             <args> filename encoding
700 <p>
701 Insert file <var>FILENAME</var> encoded by <var>ENCODING</var> format.
702 </defun>
703
704 <defun name="mime-write-decoded-region">
705               <args> start end filename encoding
706 <p>
707 Decode and write current region encoded by <var>encoding</var> into
708 <var>filename</var>.
709 <p>
710 <var>start</var> and <var>end</var> are buffer positions.
711 </defun>
712
713 <defvar name="mime-file-encoding-method-alist">
714 <p>
715 Alist of encoding vs. corresponding method to insert encoded file.
716 <p>
717 Each element looks like <code>(STRING . FUNCTION)</code>.  STRING is
718 content-transfer-encoding.  FUNCTION is function to insert encoded
719 file.
720 </defvar>
721
722 <defvar name="mime-file-decoding-method-alist">
723 <p>
724 Alist of encoding vs. corresponding method to write decoded region to
725 file.
726 <p>
727 Each element looks like <code>(STRING . FUNCTION)</code>.  STRING is
728 content-transfer-encoding.  FUNCTION is function to write decoded
729 region to file.
730 </defvar>
731
732
733 <h1> Network representation of header
734 <node> encoded-word
735 <p>
736 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
737 \e$B<0$G!"\e(B<concept>RFC 2047</concept> \e$B$GDj5A$5$l$F$$$^$9!#\e(B
738 <p>
739 <rfc number="2047" type="Standards Track" author="K. Moore"
740               title="MIME (Multipurpose Internet Mail Extensions) Part
741               Three: Message Header Extensions for Non-ASCII Text"
742               date="November 1996" obsolete="1521,1522,1590">
743 <p>
744 \e$B$^$?!"9T57$N0-$$$3$H$@$H8@$($^$9$,!"\e(Bencoded-word \e$B$rMQ$$$:$KHs\e(B 
745 <dref>ASCII</dref> \e$BJ8;z$r\e(B header \e$B$KF~$l$?5-;v$bB8:_$7$^$9!#\e(B
746 <p>
747 FLIM \e$B$O$3$l$i$rId9f2=!&I|9f2=$9$k5!G=$rDs6!$7$^$9!#\e(B
748
749
750 <h2> Header encoding/decoding
751 <node> Header encoder/decoder
752 <p>
753 <defun name="eword-encode-header">
754               <opts> code-conversion separator
755 <p>
756 Decode MIME encoded-words in header fields.
757 <p>
758 If <var>code-conversion</var> is <code>nil</code>, it decodes only
759 encoded-words.  If it is mime-charset, it decodes non-ASCII bit
760 patterns as the mime-charset.  Otherwise it decodes non-ASCII bit
761 patterns as the default-mime-charset.
762 <p>
763 If <var>separator</var> is not nil, it is used as header separator.
764 </defun>
765
766 <defun name="eword-encode-header">
767               <opts> code-conversion
768 <p>
769 Encode header fields to network representation, such as MIME
770 encoded-word.
771 <p>
772 It refer variable <code>eword-field-encoding-method-alist</code>.
773 </defun>
774
775
776 <h1> Various Customization
777 <node> custom
778 <p>
779 <define type="group" name="mime">
780 <p>
781 MIME \e$B4XO"5!G=$K4X$9$k\e(B group.
782 <p>
783 <code>mail</code> \e$B$H\e(B <code>news</code> \e$B$KB0$9$k!#\e(B
784 </define>
785
786 <defvar name="default-mime-charset">
787 <p>
788 \e$BE,@Z$J\e(B <dref>MIME charset</dref> \e$B$,8+$D$+$i$J$+$C$?>l9g$KMQ$$$i$l$k\e(B
789 MIME charset.
790 <p>
791 \e$BK\Mh$O\e(B APEL \e$B$NJQ?t$G$"$k!#\e(B
792 </defvar>
793
794 <defvar name="mime-temp-directory">
795 <p>
796 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.
797 <p>
798 \e$B4D6-JQ?t\e(B <code>MIME_TMP_DIR</code>, <code>TM_TMP_DIR</code>,
799 <code>TMPDIR</code>, <code>TMP</code> \e$B$b$7$/$O\e(B <code>TEMP</code> \e$B$,@_Dj\e(B
800 \e$B$5$l$F$$$?>l9g!"$=$l$r=i4|CM$H$7$FMQ$$$k!#2?$b@_Dj$5$l$F$$$J$$>l9g!"\e(B
801 <code>"/tmp/"</code> \e$B$rMQ$$$k!#\e(B
802 </defvar>
803
804
805 <h1> Appendix
806 <node> Appendix
807
808 <h2> Glossary
809 <node> Glossary
810
811 <h3> 7bit
812 <node> 7bit
813 <p>
814 <concept>7bit</concept> means any integer between 0 .. 127.
815 <p>
816 Any data represented by 7bit integers is called <concept>7bit
817 data</concept>.
818 <p>
819 Textual string consisted of Control characters between 0 .. 31 and
820 127, and space represented by 32, and graphic characters between 33
821 .. 236 are called <concept>7bit (textual) string</concept>.
822 <p>
823 Conventional Internet <a node="MTA">MTA</a> can translate 7bit data,
824 so it is no need to translate by <a
825 node="Quoted-Printable">Quoted-Printable</a> or <a
826 node="Base64">Base64</a> for 7bit data.
827 <p>
828 However if there are too long lines, it can not translate by 7bit MTA
829 even if it is 7bit data.  <dref>RFC 821</dref> and <dref>RFC
830 2045</dref> require lines in 7bit data must be less than 998 bytes.
831 So if a ``7bit data'' has a line more than 999 bytes, it is regarded
832 as <dref>binary</dref>.  For example, Postscript file should be
833 encoded by Quoted-Printable.
834
835
836 <h3> 8bit
837 <node> 8bit
838 <p>
839 <concept>8bit</concept> means any integer between 0 .. 255.
840 <p>
841 Any data represented by 8bit integers is called <concept>8bit
842 data</concept>.
843 <p>
844 Textual string consisted of Control characters between 0 .. 31, 127,
845 and 128 .. 159, and space represented by 32, and graphic characters
846 between 33 .. 236 and 160 .. 255 are called <concept>8bit (textual)
847 string</concept>.
848 <p>
849 For example, <dref>iso-8859-1</dref> or <dref>euc-kr</dref> are
850 coded-character-set represented by 8bit textual string.
851 <p>
852 Traditional Internet <a node="MTA">MTA</a> can translate only
853 <dref>7bit</dref> data, so if a 8bit data will be translated such MTA,
854 it must be encoded by <dref>Quoted-Printable</dref> or
855 <dref>Base64</dref>.
856 <p>
857 However 8bit MTA are increasing today.
858 <p>
859 However if there are too long lines, it can not translate by 8bit MTA
860 even if it is 8bit data.  <dref>RFC 2045</dref> require lines in 8bit
861 data must be less than 998 bytes.  So if a ``8bit data'' has a line
862 more than 999 bytes, it is regarded as <dref>binary</dref>, so it must
863 be encoded by Base64 or Quoted-Printable.
864
865
866 <h3> ASCII
867 <node> ASCII
868 <p>
869 <concept>ASCII</concept> is a 94-character set contains primary latin
870 characters (A-Z, a-z), numbers and some characters.  It is a standard
871 of the United States of America.  It is a variant of <a node="ISO
872 646">ISO 646</a>.
873
874 <standard abbrev="ASCII" title-en="Coded Character Set -- 7-Bit
875               American Standard Code for Information Interchange"
876               number="ANSI X3.4" year="1986">
877
878
879 <h3> Base64
880 <node> Base64
881 <p>
882 <concept>Base64</concept> is a transfer encoding method of
883 <dref>MIME</dref> defined in <dref>RFC 2045</dref>.
884 <p>
885 The encoding process represents 24-bit groups of input bits as output
886 strings of 4 encoded characters.  Encoded characters represent integer
887 0 .. 63 or <concept>pad</concept>.  Base64 data must be 4 * n bytes,
888 so pad is used to adjust size.
889 <p>
890 These 65 characters are subset of all versions of ISO 646, including
891 US-ASCII, and all versions of EBCDIC.  So it is safe even if it is
892 translated by non-Internet gateways.
893
894
895 <h3> binary
896 <node> binary
897 <p>
898 Any byte stream is called <concept>binary</concept>.
899 <p>
900 It does not require structureof lines.  It differs from from <a
901 node="8bit">8bit</a>.
902 <p>
903 In addition, if line structured data contain too long line (more than
904 998 bytes), it is regarded as binary.
905
906
907 <h3> Coded character set, Character code
908 <node> coded character set
909 <p>
910 A set of unambiguous rules that establishes a character set and the
911 one-to-one relationship between the characters of the set and their
912 bit combinations.
913
914
915 <h3> media-type
916 <node> media-type
917 <p>
918 <concept>media-type</concept> specifies the nature of the data in the
919 body of <dref>MIME</dref> <dref>entity</dref>.  It consists of
920 <concept>type</concept> and <concept>subtype</concept>.  It is defined
921 in <dref>RFC 2046</dref>.
922 <p>
923 Currently there are following standard primary-types:
924
925 <ul>
926 <li><concept>text</concept>
927 </li>
928 <li><concept>image</concept>
929 </li>
930 <li><concept>audio</concept>
931 </li>
932 <li><concept>video</concept>
933 </li>
934 <li><concept>application</concept>
935 </li>
936 <li><a node="multipart"><concept>multipart</concept></a>
937 </li>
938 <li><concept>message</concept>
939 </ul>
940
941 <p>
942 And there are various subtypes, for example, application/octet-stream,
943 audio/basic, image/jpeg, <dref>multipart/mixed</dref>,
944 <dref>text/plain</dref>, video/mpeg...
945
946 <p>
947 You can refer registered media types at <a
948 href="ftp://ftp.isi.edu/in-notes/iana/assignments/media-types">MEDIA
949 TYPES</a>.
950 <p>
951 In addition, you can use private type or subtype using
952 <concept>x-token</concept>, which as the prefix `x-'.  However you can
953 not use them in public.
954 <p>
955 <cf node="Content-Type field">
956
957
958 <h3> message
959 <node> message
960 <p>
961 In this document, it means mail defined in <dref>RFC 822</dref> and
962 news message defined in <dref>RFC 1036</dref>.
963
964
965 <h3> MIME
966 <node> MIME
967 <p>
968 MIME stands for <concept>Multipurpose Internet Mail
969 Extensions</concept>, it is an extension for <dref>RFC 822</dref>.
970 <p>
971 According to RFC 2045:
972 <p>
973 STD 11, RFC 822, defines a message representation protocol specifying
974 considerable detail about US-ASCII message headers, and leaves the
975 message content, or message body, as flat US-ASCII text.  This set of
976 documents, collectively called the Multipurpose Internet Mail
977 Extensions, or MIME, redefines the format of messages to allow for
978
979 <ol>
980 <li>textual message bodies in character sets other than US-ASCII,
981 </li>
982 <li>an extensible set of different formats for non-textual message
983 bodies,
984 </li>
985 <li>multi-part message bodies, and
986 </li>
987 <li>textual header information in character sets other than US-ASCII.
988 </ol>
989
990 <p>
991 It is defined in <dref>RFC 2045</dref>, <dref>RFC 2046</dref>, <a
992 node="encoded-word">RFC 2047</a>, <dref>RFC 2048</dref> and <dref>RFC
993 2049</dref>.
994
995
996 <h3> MIME charset
997 <node> MIME charset
998 <p>
999 <a node="coded character set">Coded character set</a> used in
1000 <dref>Content-Type field</dref> or charset parameter of <a
1001 node="encoded-word">encoded-word</a>.
1002 <p>
1003 It is defined in <dref>RFC 2045</dref>.
1004 <p>
1005 <dref>iso-2022-jp</dref> or <dref>euc-kr</dref> are kinds of it.  (In
1006 this document, MIME charsets are written by small letters to
1007 distinguish <dref>graphic character set</dref>.  For example, ISO
1008 8859-1 is a graphic character set, and iso-8859-1 is a MIME charset)
1009
1010
1011 <h3> MTA
1012 <node> MTA
1013 <p>
1014 <concept>Message Transfer Agent</concept>.  It means mail transfer
1015 programs (ex. sendmail) and news servers.
1016 <p>
1017 <cf node="MUA">
1018
1019
1020 <h3> MUA
1021 <node> MUA
1022 <p>
1023 <concept>Message User Agent</concept>.  It means mail readers and news
1024 readers.
1025 <p>
1026 <cf node="MTA">
1027
1028
1029 <h3> Quoted-Printable
1030 <node> Quoted-Printable
1031 <p>
1032 <concept>Quoted-Printable</concept> is a transfer encoding method of
1033 <dref>MIME</dref> defined in <dref>RFC 2045</dref>.
1034 <p>
1035 If the data being encoded are mostly US-ASCII text, the encoded form
1036 of the data remains largely recognizable by humans.
1037 <p>
1038 <cf node="Base64">
1039
1040
1041 <h3> RFC 822
1042 <node> RFC 822
1043 <p>
1044 A RFC defines format of Internet mail message, mainly <concept>message
1045 header</concept>.
1046
1047 <memo>
1048 <p>
1049 news message is based on RFC 822, so <concept>Internet
1050 message</concept> may be more suitable than <concept>Internet
1051 mail</concept> .
1052 </memo>
1053
1054 <rfc number="822" type="STD 11" author="D. Crocker" title="Standard
1055               for the Format of ARPA Internet Text Messages"
1056               date="August 1982">
1057
1058
1059 <h3> RFC 1036
1060 <node> RFC 1036
1061 <p>
1062 A RFC defines format of USENET message.  It is a subset of <dref>RFC
1063 822</dref>.  It is not Internet standard, but a lot of netnews
1064 excepting Usenet uses it.
1065
1066 <rfc name="USENET" number="1036" author="M. Horton and R. Adams"
1067               title="Standard for Interchange of USENET Messages"
1068               date="December 1987" obsolete="850">
1069
1070
1071 <h3> RFC 2045
1072 <node> RFC 2045
1073 <p>
1074 <rfc number="2045" type="Standards Track" author="N. Freed and
1075               N. Borenstein" title="Multipurpose Internet Mail
1076               Extensions (MIME) Part One: Format of Internet Message
1077               Bodies" date="November 1996" obsolete="1521, 1522,
1078               1590">
1079
1080
1081 <h3> RFC 2046
1082 <node> RFC 2046
1083 <p>
1084 <rfc number="2046" type="Standards Track" author="N. Freed and
1085               N. Borenstein" title="Multipurpose Internet Mail
1086                  Extensions (MIME) Part Two: Media Types"
1087                  date="November 1996" obsolete="1521, 1522, 1590">
1088
1089
1090 <h3> RFC 2048
1091 <node> RFC 2048
1092 <p>
1093 <rfc number="2048" type="Standards Track" author="N. Freed, J. Klensin
1094               and J. Postel" title="Multipurpose Internet Mail
1095               Extensions (MIME) Part Four: Registration Procedures"
1096               date="November 1996" obsolete="1521, 1522, 1590">
1097
1098
1099 <h3> RFC 2049
1100 <node> RFC 2049
1101 <p>
1102 <rfc number="2049" type="Standards Track" author="N. Freed and
1103               N. Borenstein" title="Multipurpose Internet Mail
1104               Extensions (MIME) Part Five: Conformance Criteria and
1105               Examples" date="November 1996" obsolete="1521, 1522,
1106               1590">
1107
1108
1109 <h3> plain text
1110 <node> plain text
1111 <p>
1112 A textual data represented by only <dref>coded character set</dref>.
1113 It does not have information about font or typesetting.
1114 <cf node="text/plain">
1115
1116
1117 <h3> us-ascii
1118 <node> us-ascii
1119 <p>
1120 A <a node="MIME charset">MIME charset</a> for primary Latin script
1121 mainly written by English or other languages.
1122 <p>
1123 It is a 7bit <dref>coded character set</dref> based on <dref>ISO
1124 2022</dref>, it contains only
1125 <dref>ASCII</dref> and <dref>code extension</dref> is not allowed.
1126 <p>
1127 It is standard coded character set of Internet mail.  If MIME charset
1128 is not specified, <concept>us-ascii</concept> is used as default.
1129 <p>
1130 In addition, <concept>ASCII</concept> of <dref>RFC 822</dref> should
1131 be interpreted as us-ascii.
1132
1133
1134 <h2> How to report bugs
1135 <node> Bug report
1136 <p>
1137 If you write bug-reports and/or suggestions for improvement, please
1138 send them to the tm Mailing List:
1139
1140 <ul>
1141 <li> Japanese <mail>bug-tm-ja@chamonix.jaist.ac.jp</mail>
1142 <li> English <mail>bug-tm-en@chamonix.jaist.ac.jp</mail>
1143 </ul>
1144
1145 <p>
1146 Notice that, we do not welcome bug reports about too old version.
1147 Bugs in old version might be fixed.  So please try latest version at
1148 first.
1149 <p>
1150 You should write <concept>good bug report</concept>.  If you write
1151 only ``FLIM does not work'', we can not find such situations.  At
1152 least, you should write name, type, variants and version of OS, emacs,
1153 APEL, FLIM, SEMI and MUA, and setting.  In addition, if error occurs,
1154 to send backtrace is very important. <cf file="emacs" node="Bugs">
1155 <p>
1156 Bug may not appear only your environment, but also in a lot of
1157 environment (otherwise it might not bug).  Therefor if you send mail
1158 to author directly, we must write a lot of mails.  So please send mail
1159 to address for tm bugs instead of author.
1160
1161 <p>
1162 Via the tm ML, you can report FLIM bugs, obtain the latest release of
1163 FLIM, and discuss future enhancements to FLIM.  To join the tm ML,
1164 send empty e-mail to:
1165
1166 <ul>
1167 <li> Japanese <mail>tm-ja-help@chamonix.jaist.ac.jp</mail>
1168 <li> English  <mail>tm-en-help@chamonix.jaist.ac.jp</mail>
1169 </ul>
1170
1171
1172 <h2> CVS based development
1173 <node> CVS
1174 <p>
1175 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
1176 \e$B?7$N\e(B FLIM \e$B$rF~<j$9$k$3$H$,$G$-$^$9!'\e(B
1177
1178 <verb>
1179 (0) cvs login
1180
1181     % cvs -d :pserver:anonymous@chamonix.jaist.ac.jp:/hare/cvs/root \
1182         login
1183
1184     CVS password: [CR] # NULL string
1185
1186 (1) checkout
1187
1188     % cvs -d :pserver:anonymous@chamonix.jaist.ac.jp:/hare/cvs/root \
1189         checkout [-r TAG] flim
1190 </verb>
1191
1192 <p>
1193 CVS \e$B$rMQ$$$?3+H/$K;22C$7$?$$J}$O\e(B
1194
1195 <ul>
1196 <li> <mail>cvs@chamonix.jaist.ac.jp</mail>
1197 </ul>
1198
1199 <noindent>
1200 \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
1201 \e$B$r1h$($F8fO"Mm$/$@$5$$!#\e(B
1202
1203
1204 <h2> History of FLIM
1205 <node> History
1206 <p>
1207 FLIM \e$B$N\e(B code \e$B$N:G8E$NItJ,$O\e(B \e$B1]JB\e(B \e$B;LCR\e(B \e$B;a$,=q$$$?\e(B <file>mime.el</file>
1208 \e$B$K5/8;$7$^$9!#$3$N>.$5$J\e(B program \e$B$O\e(B Nemacs \e$B$GF0:n$9$k\e(B iso-2022-jp \e$B$N\e(B 
1209 B-encoding \e$B@lMQ$N\e(B encoded-word \e$B$NI|9f2=%W%m%0%i%`$G$7$?!#\e(B
1210 <p>
1211 \e$B$=$N8e!"<i2,\e(B \e$BCNI'\e(B \e$B$O\e(B <file>mime.el</file> \e$B$r85$K\e(B
1212 <file>tiny-mime.el</file> \e$B$H$$$&%W%m%0%i%`$r=q$-$^$9!#$3$l$O!"\e(BNemacs 
1213 \e$B$H\e(B Mule \e$B$GF0:n$9$k\e(B encoded-word \e$B$NId9f2=!&I|9f2=%W%m%0%i%`$G$7$?!#\e(B
1214 <file>tiny-mime.el</file> \e$B$O\e(B B-encoding \e$B$@$1$G$J$/\e(B Q-encoding \e$B$b\e(B
1215 support \e$B$7!"$^$?!"\e(BMULE \e$B$G07$&$3$H$,$G$-$k$5$^$6$^$J\e(B <dref>MIME
1216 charset</dref> \e$B$rF1;~$K;H$&$3$H$,$G$-$^$7$?!#$3$N;~!"\e(BNemacs \e$B$H\e(B Mule \e$B$N\e(B
1217 \e$BAPJ}$r\e(B support \e$B$9$k$?$a$KMQ$$$i$l$?%F%/%K%C%/$O8e$K\e(B emu package \e$B$K$^$H\e(B
1218 \e$B$a$i$l$^$9!#\e(B
1219 <p>
1220 \e$B$3$N:"!"<i2,\e(B \e$BCNI'\e(B \e$B$O\e(B <file>tiny-mime.el</file> \e$B$r$5$^$6$^$J\e(B MUA \e$B$G;H$&\e(B
1221 \e$B$?$a$N@_Dj=8$bG[I[$7$F$$$^$7$?$,!"$=$l$i$O8e$K\e(B
1222 <file>tiny-mime.el</file> \e$B$H$H$b$K#1$D$N\e(B package \e$B$K$^$H$a$i$l!"\e(Btm \e$B$H$$\e(B
1223 \e$B$&L>A0$GG[I[$5$l$^$9!#\e(B
1224 <p>
1225 \e$B<i2,\e(B \e$BCNI'\e(B \e$B$O$d$,$F!"\e(BMIME message \e$B$r1\Mw$9$k$?$a$N%W%m%0%i%`$G$"$k\e(B
1226 <file>tm-body.el</file> \e$B$r=q$-$^$9!#$3$l$O!"$9$0$K\e(B
1227 <file>tm-view.el</file> \e$B$H$$$&L>A0$KJQ$o$j$^$7$?$,!"$d$,$F!"$3$l$,\e(B
1228 <file>tiny-mime.el</file> \e$B$KBe$o$C$F!"\e(Btm \e$B$NCf3K$H$J$j$^$9!#\e(B
1229 <p>
1230 <file>tm-view.el</file> \e$B$OEvA3!"\e(BContent-Transfer-Encoding \e$B$r07$&I,MW$,\e(B
1231 \e$B$"$j$^$9!#$3$NL\E*$N$?$a$K!"\e(BMEL \e$B$,@0Hw$5$l$O$8$a$^$7$?!#\e(BBase64 \e$B$K4X$7\e(B
1232 \e$B$F$O\e(B <file>tiny-mime.el</file> \e$B$N\e(B code \e$B$,0\$5$l!"$^$?!"?7$?$K\e(B
1233 Quoted-Printable \e$B$N\e(B code \e$B$,DI2C$5$l$^$7$?!#$3$l$i$,\e(B
1234 <file>mel-b.el</file> \e$B$H\e(B <file>mel-q.el</file> \e$B$K$J$j$^$7$?!#\e(B
1235 <p>
1236 \e$B$^$?!"8e$K!"<i2,\e(B \e$BCNI'\e(B \e$B$K$h$C$F\e(B uuencode \e$BMQ$N\e(B <file>mel-u.el</file> \e$B$,\e(B
1237 \e$BDI2C$5$l!"$=$N8e$K!">.NS\e(B \e$B=$J?\e(B \e$B;a$K$h$C$F\e(B x-gzip64 \e$BMQ$N\e(B
1238 <file>mel-g.el</file> \e$B$,DI2C$5$l$^$7$?!#\e(B
1239 <p>
1240 tm \e$B$G$O8e$K!"<i2,\e(B \e$BCNI'\e(B \e$B$K$h$C$F\e(B <file>tiny-mime.el</file> \e$B$N:F<BAu$,9T\e(B
1241 \e$B$o$l!"$3$N2aDx$G!"\e(BSTD 11 \e$B$N\e(B parser \e$B$,=q$+$l$^$7$?!#$3$l$O!"8=:_$N\e(B 
1242 <file>std11.el</file> \e$B$KEv$?$j$^$9!#$^$?!"$3$N2aDx$G\e(B 
1243 <file>tiny-mime.el</file> \e$B$OI|9f2=$r9T$&\e(B <file>tm-ew-d.el</file> \e$B$HId\e(B
1244 \e$B9f2=$r9T$&\e(B <file>tm-ew-e.el</file> \e$B$KJ,$1$i$l$^$7$?!#$3$NN><T$,8=:_$N\e(B 
1245 <file>eword-decode.el</file> \e$B$H\e(B <file>eword-encode.el</file> \e$B$N@hAD$K\e(B
1246 \e$BEv$?$j$^$9!#\e(B
1247 <p>
1248 \e$B8e$K!"<i2,\e(B \e$BCNI'\e(B \e$B$i$K$h$C$F\e(B tm \e$B$NA4LL=q$-49$(:n6H$,9T$o$l!"$3$N2aDx$G!"\e(B
1249 tm \e$B$O\e(B APEL, MEL, SEMI, EMH, RMAIL-MIME, Gnus-MIME \e$B$J$I$KJ,$1$i$l$^$7$?!#\e(B
1250 \e$B$3$N$&$A$N\e(B MEL \e$B$,\e(B FLIM \e$B$ND>@\$N@hAD$KEv$?$j$^$9!#\e(B
1251 <p>
1252 \e$B8e$K!"\e(BAPEL \e$B$+$i\e(B <file>std11.el</file> \e$B$,0\$5$l!"$^$?!"\e(B
1253 <file>mailcap.el</file>, <file>eword-decode.el</file> \e$B$*$h$S\e(B 
1254 <file>eword-encode.el</file> \e$B$,\e(B SEMI \e$B$+$i0\$5$l!"\e(Bpackage \e$B$NL>A0$,\e(B FLIM
1255 \e$B$H$J$j$^$9!#\e(B
1256 <p>
1257 \e$B$3$ND>A0$+$iEDCf\e(B \e$BE/\e(B \e$B;a$,$h$j\e(B RFC \e$B$KCi<B$J<BAu$r=q$-;O$a!"$3$l$O!"8=:_!"\e(B
1258 FLIM \e$B$N;^$G$"$k\e(B ``FLIM-FLAM'' \e$B$H$J$C$F$$$^$9!#\e(B
1259
1260
1261 <h1> Concept Index
1262 <node> Concept Index
1263
1264 <cindex>
1265
1266
1267 <h1> Function Index
1268 <node> Function Index
1269
1270 <findex>
1271
1272
1273 <h1> Variable Index
1274 <node> Variable Index
1275
1276 <vindex>
1277
1278 </body>