Sync with semi-1_14 branch.
[elisp/semi.git] / mime-ui-en.sgml
1 <!doctype sinfo system>
2 <head>
3 <title>SEMI 1.14 Manual
4 <author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail>
5 <date>1998/07/03
6
7 <toc>
8 </head>
9
10 <body>
11
12 <abstract>
13 <p>
14 This file documents SEMI, a MIME user interface for GNU Emacs.
15 </abstract>
16
17
18 <h1> What is SEMI?
19 <node> Introduction
20 <p>
21 SEMI is a package for GNU Emacs to provide features related with MIME
22 user interface.
23 <p>
24 SEMI provides two user interfaces: MIME-View and MIME-Edit.
25 <p> 
26 MIME-View is a kernel of user interface to display or operate MIME
27 messages, STD 11 messages or ``localized RFC 822'' messages.
28 <p>
29 MIME-Edit is a user interface to compose MIME messages.
30 <p>
31 Each MUA can use powerful MIME features to combine these features.
32
33
34 <h1> MIME message viewing
35 <node> MIME-View
36 <p>
37 MIME-View is a MIME viewer for wide use that runs on GNU Emacs.
38 <p>
39 MIME-View is the kernel of the user interface for browsing MIME
40 messages. You can start some presentation-method which is a program for
41 creating some representation, or some acting-method which is a program
42 for processing the entity. Then you can deal with a variety of entities.
43
44
45 <h2> Basic design
46 <node> Overview of MIME-View
47 <p>
48 The representation form of the internet messages in electric letters
49 or in net news is based on STD 11. The STD 11 message body is a plain
50 text which consists of lines as its only structure, and the character
51 code is fixed as us-ascii. Actually, there are ``localized STD 11''
52 messages that use some character code in their linguistic range
53 instead of using us-ascii. Even in that case, the character code in
54 the message is single. Therefore, Message User Agents have considered
55 (byte row) = (us-ascii string), or (byte row) = (string in the
56 character code in the linguistic range).
57 <p>
58 Although, the MIME message has the tree structure in entity unit.
59 And one message can contain multiple character codes. The content of
60 an entity can be not only a letter or an image that can be displayed
61 simply, but also can be a voice or an animation that are played for
62 some time interval, a data for some specific application, a source
63 code of some program, or an external reference that consists of
64 the usage of ftp or mail service, or some URL. Therefore the simple
65 extension of STD 11 user interface, which only consider displaying
66 the message, cannot treat all of the MIME functionalities.
67 Then it is not sufficient to decode message along its MIME type, but
68 it is also required to consider a playback processing through some
69 dialogue with the user. The format of MIME messages is designed
70 to easily be passed to automatic processing. But some contents in the
71 MIME message should not be passed to automatic processing for security
72 reasons. So it should be designed to ask user in such cases.
73 After all, in order to deal with MIME message, it is required to
74 distinguish the representation for information exchange which is
75 written in STD 11 or MIME construction, and its result
76 after some interpretation which is a display screen or a playback
77 process. It is also needed to converse with user for playback
78 processing.
79 <p>
80 Therefore, MIME-View uses two buffers for one document, one is the
81 mime-raw-buffer that stores the representation for information exchange,
82 and the other is the mime-preview-buffer that stores the representation
83 for displaying.
84 <p>
85 MIME-View provides a mode in the mime-preview-buffer for reading MIME
86 message, which is called as mime-view-mode. User can manipulate each
87 entity there.
88
89
90 <h2> Presentation of mime-preview-buffer
91 <node> MIME-Preview
92 <p>
93 mime-view-mode displays information about each entity as
94 <p>
95 <verb>
96         [entity-button]
97         (header)
98         
99         (body)
100         (separator)
101 </verb>
102 <p>
103 <noindent>
104 You can change their design or inhibit showing some of them, according
105 to some condition
106 <p>
107 See following example
108
109
110 <verb>
111 From: morioka@jaist.ac.jp (MORIOKA Tomohiko)
112 Subject: Re: question?
113 Newsgroups: zxr.message.mime
114 Date: 22 Oct 93 11:02:44
115 Mime-Version: 1.0
116 Organization: Japan Advanced Institute of Science and Technology,
117         Ishikawa, Japan
118
119 [1  (text/plain)]
120   How to compose MIME message in MIME-Edit mode.
121
122   C-c C-x ? shows its help.
123
124 C-c C-x C-t     insert a text message.
125 C-c C-x TAB     insert a (binary) file.
126 C-c C-x C-e     insert a reference to external body.
127 C-c C-x C-v     insert a voice message.
128 C-c C-x C-y     insert a mail or news message.
129 C-c C-x RET     insert a mail message.
130 C-c C-x C-s     insert a signature file at end.
131 C-c C-x t       insert a new MIME tag.
132 C-c C-m C-a     enclose as multipart/alternative.
133 C-c C-m C-p     enclose as multipart/parallel.
134 C-c C-m C-m     enclose as multipart/mixed.
135 C-c C-m C-d     enclose as multipart/digest.
136 C-c C-m C-s     enclose as PGP signed.
137 C-c C-m C-e     enclose as PGP encrypted.
138 C-c C-x C-k     insert PGP public key.
139 C-c C-x p       preview editing MIME message.
140 ...
141
142 therefore, you should type C-c C-x C-i and specify the binary file
143 which you want to insert.
144
145   You should select Base64 as MIME encoding for binary file.
146
147 [2  (image/gif)]
148
149 [3  (text/plain)]
150
151   Like above, you can compose the message with image.
152
153 ==================== Take A Cup Of Russian Tea  ======================
154 =========  ** Not With Jam Nor Marmalade But With Honey **  ==========
155 =========                 MORIOKA TOMOHIKO                  ==========
156 ==============  Internet E-mail: &lt;morioka@@jaist.ac.jp&gt;  ==============
157 </verb>
158
159
160 <h3> entity-button
161 <node> entity-button
162 <p>
163 <concept>entity-button</concept> is a tag on the top of the entity
164 which shows brief information of the part.
165 <p>
166 Normally, it appears as
167
168 <verb>
169         [1.3 test (text/plain)]
170 </verb>
171
172 <p>
173 The number on the head describes the place of the entity in the
174 message (like the section number) and it is called as
175 <concept>entity-number</concept>.
176 <p>
177 The string in the next describes its title. This information is
178 taken from
179
180 <ol>
181 <li>Title described in Content-Description field or Subject field
182 <li>File name specified by filename parameter in Content-Disposition field
183 <li>File name specified by name parameter in Content-Type field
184 <li>File name for uuencode'ing
185 </ol>
186
187 <noindent>
188 If none of them are specified, displays a blank.
189 <p>
190 The 3rd item in the parenthesis describes media-type/subtype of
191 the entity. If it is is not MIME entity, it displays <code>nil</code>.
192 <p>
193 This entity-button plays a role like icon that symbolically
194 shows the content of the entity. For example, push <kbd>v</kbd> on
195
196 <verb>
197         [2  (image/gif)]
198 </verb>
199
200 <noindent>
201 shows up the image contained there.
202 <p>
203 If the mouse operation is possible, you can display the image
204 by pushing 2nd button (the middle button for 3 button mouse) too.
205
206
207 <h3> entity-header
208 <node> entity-header
209 <p>
210 <concept>entity-header</concept> is the header of the entity.
211 (Don't blame me as ``You say nothing more than as it is'',
212 It is no more than that.)
213
214 <h3> entity-body
215 <node> entity-body
216 <p>
217 <concept>entity-body</concept> is the content of the part.
218 <p>
219 Sophistication does not seem enough here also, but it is really such
220 a thing.
221 <p>
222 Though, it actually be twisted a little.
223 <p>
224 The text entity is passed to code conversion according to its charset,
225 and the image entity should be converted on XEmacs.
226 <p>
227 Details will be described later.
228
229
230 <h2> Operation in mime-preview-buffer
231 <node> mime-view-mode
232 <p>
233 mime-preview-buffer posesses following functionalities.
234 <p>
235 <kl>
236 <kt>u
237 <kd>
238 go back to upper part (in the first part of the message,
239 go back to the Summary mode (*1))
240 </kd>
241 <kt>p<kd>go to previous part
242 </kd>
243 <kt>M-TAB<kd>go to previous part
244 </kd>
245 <kt>n<kd>go to next part
246 </kd>
247 <kt>TAB<kd>go to next part
248 </kd>
249 <kt>SPC<kd>scroll up
250 </kd>
251 <kt>M-SPC<kd>scroll down
252 </kd>
253 <kt>DEL<kd>scroll down
254 </kd>
255 <kt>RET<kd>go to next line
256 </kd>
257 <kt>M-RET<kd>go to previous line
258 </kd>
259 <kt>v<kd>play current part (*2)
260 </kd>
261 <kt>e<kd>extract file from current part (*2)
262 </kd>
263 <kt>C-c C-p<kd>print current part (*2)
264 </kd>
265 <kt>mouse-button-2
266 <kd>
267 start the mouse button in preview-buffer
268 <p>
269 on content-button, play current part (*2)
270 <p>
271 on URL-button, start WWW browser
272 </kd>
273 </kl>
274 <p>
275 <memo title="Notice">
276 <p>
277 (*1) Do not go back to Summary mode unless appropriately
278 configured for mime-view in the MUA.
279 <p>
280 (*2) actual behavior depends on the associated method
281 </memo>
282
283
284 <h1> MIME message editing
285 <node> MIME-Edit
286 <p>
287 <concept>MIME-Edit</concept> is a general MIME composer for GNU Emacs.
288
289
290 <h2> Minor-mode to edit MIME message
291 <node> mime-edit-mode
292 <p>
293 <concept>mime-edit-mode</concept> is a minor mode to compose MIME
294 message.  In this mode, <concept>tag</concept> represents various
295 kinds of data, so you can edit multi part message consists of various
296 kinds of data, such as text, image, audio, etc.
297 <p>
298 There are 2 kinds of tags:
299
300 <ul>
301 <li> single-part tag
302 <li> multi-part tag
303 </ul>
304 <p>
305 single-part tag represents single part, this form is following:
306 <p>
307 <verb>
308         --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
309         OPTIONAL-FIELDS]
310 </verb>
311 <p>
312 TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of
313 <dref file="mime-en">Content-Type</dref> field.  TYPE/SUBTYPE is
314 required, PARAMETERS is optional.
315 <p>
316 ENCODING indicates <dref
317 file="mime-ja">Content-Transfer-Encoding</dref> field.  It is optional
318 too.
319 <p>
320 OPTIONAL-FIELDS is to represent another fields except Content-Type
321 field and Content-Transfer-Encoding field.
322 <p>
323 multi-part tags represent <a file="mime-en" node="multipart">multi
324 part</a>.  They consist of a pair of <concept>multi-part beginning
325 tag</concept> and <concept>multi-part ending tag</concept>.
326 <p>
327 multi-part beginning tag's form is following:
328
329 <verb>
330         --<<TYPE>>-{
331 </verb>
332 <p>
333 multi-part ending tag's form is following:
334
335 <verb>
336         --}-<<TYPE>>
337 </verb>
338 <p>
339 A region from multi-part beginning tag to multi-part ending tag is
340 called as <concept>enclosure</concept>.
341
342
343 <h2> Operations for single-part
344 <node> single-part tags
345 <p>
346 Operations to make single-part are following:
347
348 <kl>
349 <kt>C-c C-x C-t
350 <kd>
351 Insert single-part tag indicates text part.
352 </kd>
353 <kt>C-c C-x C-i
354 <kd>
355 Insert file as a MIME attachment.  If <kbd>C-u</kbd> is followed by
356 it, it asks media-type, subtype or encoding even if their default
357 values are specified. <cf node="tag specification for inserted file">
358 </kd>
359 <kt>C-c C-x C-e
360 <kd>
361 Insert external part.
362 </kd>
363 <kt>C-c C-x C-v
364 <kd>
365 Record audio input until <kbd>C-g</kbd> is pressed, and insert as a
366 audio part. (It requires /dev/audio in default.)
367 </kd>
368 <kt>C-c C-x C-y
369 <kd>
370 Insert current (mail or news) message. (It is MUA depended.)
371 </kd>
372 <kt>C-c C-x C-m
373 <kd>
374 Insert mail message. (It is MUA depended.)
375 </kd>
376 <dt><key>C-c C-x C-w</key>, <key>C-c C-x C-s</key>
377 <dd>
378 Insert signature.
379 </dd>
380 <kt>C-c C-x C-k
381 <kd>
382 Insert <dref>PGP</dref> public key.
383 </kd>
384 <kt>C-c C-x t
385 <kd>
386 Insert any single-part tag.
387 </kl>
388
389
390 <h2> Operations for enclosure
391 <node> enclosure tags
392 <p>
393 Operations to make enclosure are following:
394
395 <kl>
396 <kt>C-c C-m C-a
397 <kd>
398 Enclose specified region as multipart/alternative.
399 </kd>
400 <kt>C-c C-m C-p
401 <kd>
402 Enclose specified region as multipart/parallel.
403 </kd>
404 <kt>C-c C-m C-m
405 <kd>
406 Enclose specified region as multipart/mixed.
407 </kd>
408 <kt>C-c C-m C-d
409 <kd>
410 Enclose specified region as multipart/digest.
411 </kd>
412 <kt>C-c C-m C-s
413 <kd>
414 Digital-sign to specified region. <cf node="PGP">
415 </kd>
416 <kt>C-c C-m C-e
417 <kd>
418 Encrypt to specified region. <cf node="PGP">
419 </kd>
420 <kt>C-c C-m C-q
421 <kd>
422 avoid to encode tags in specified region.  In other words, tags is
423 interpreted as such string.  (In current version, it may be
424 incomplete.  Maybe PGP-signature does not work for this enclosure.)
425 </kl>
426
427
428 <h2> Other operations
429 <node> other MIME-Edit operations
430 <p>
431 There are another operations in mime-edit-mode.
432
433 <kl>
434 <kt>C-c C-c
435 <kd>
436 Send current editing message.
437 </kd>
438 <kt>C-c C-x p
439 <kd>
440 Preview current editing message. <cf node="MIME-View">
441 </kd>
442 <kt>C-c C-x C-z
443 <kd>
444 Exit mime-edit-mode without sending.
445 </kd>
446 <kt>C-c C-x /
447 <kd>
448 Set current editing message to enable automatic splitting or not.
449 Form of automatic split messages is message/partial.
450 </kd>
451 <kt>C-c C-x 7
452 <kd>
453 Set <dref file="mime-en">7bit</dref> to <dref>transfer level</dref>.
454 </kd>
455 <kt>C-c C-x 8
456 <kd>
457 Set <dref file="mime-en">8bit</dref> to <dref>transfer level</dref>.
458 </kd>
459 <kt>C-c C-x v
460 <kd>
461 Set current editing message to digital-sign or not. <cf node="PGP">
462 </kd>
463 <kt>C-c C-x h
464 <kd>
465 Set current editing message to encrypt or not. <cf node="PGP">
466 <kt>C-c C-x ?
467 <kd>
468 Display help message.
469 </kl>
470
471
472 <h2> How to detect tag for inserted file
473 <node> file-type specification
474 <p>
475 When <kbd>C-c C-x C-i</kbd> (<code>mime-edit-insert-file</code>) is
476 pressed, tag parameters for inserted file, such as media-type or
477 encoding, are detected by variable <code>mime-file-types</code>.
478 <p>
479 When <kbd>C-u</kbd> is followed by it or parameter is not found from
480 the variable, it asks from user.  (When <kbd>C-u</kbd> is followed by
481 it, detected value is used as default value)
482 <p>
483 If you want to change default value for file names, please change
484 variable <code>mime-file-types</code>.
485
486 <defvar name="mime-file-types">
487 <p>
488 Specification of default value of tag for file name of inserted file.
489 <p>
490 It is a list of following list:
491
492 <lisp>
493         (FILE_PAT TYPE SUBTYPE PARAMS ENCODING
494          DISPOSITION_TYPE DISPOSITION_PARAMS)
495 </lisp>
496
497 Each element of the list is following:
498
499 <dl>
500 <dt>FILE_PAT
501 <dd>regular expression of file name
502 <dt>TYPE
503 <dd>primary-type of media-type
504 <dt>SUBTYPE
505 <dd>subtype of media-type
506 <dt>PARAMS
507 <dd>parameters of Content-Type field
508 <dt>ENCODING
509 <dd>Content-Transfer-Encoding
510 <dt>DISPOSITION_TYPE
511 <dd>disposition-type
512 <dt>DISPOSITION_PARAMS
513 <dd>parameters of Content-Disposition field
514 </dl>
515
516 <noindent>
517 Example: Specify application/rtf as default media type for
518 <file>*.rtf</file>
519
520 <lisp>
521 (eval-after-load
522     "mime-edit"
523   '(set-alist 'mime-file-types
524               "\\.rtf$"
525               '("application" "rtf" nil nil
526                 "attachment" (("filename" . file)))
527               ))
528 </lisp>
529 </defvar>
530
531
532 <h2> transfer level
533 <node> transfer level
534 <p>
535 Each content inserted in a message is represented by <dref
536 file="mime-en">7bit</dref>, <dref file="mime-en">8bit</dref> or <dref
537 file="mime-en">binary</dref>.
538 <p>
539 If a message is translated by 7bit-through <dref
540 file="mime-en">MTA</dref>, there is no need to encode 7bit data, but
541 8bit and binary data must be encoded to 7bit data.
542 <p>
543 Similarly, if a message is translated by 8bit-through MTA, there is no
544 need to encode 7bit or 8bit data, but binary data must be encoded to
545 7bit or 8bit data.
546 <p>
547 <memo>
548 EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
549 encoded by base64.  But I don't know EBCDIC. (^_^;
550 <p>
551 Similarly, I wish ASCII-printable only MTA and code-conversion MTA
552 disappeared. (^_^;
553 <p>
554 Maybe there are binary-through MTA, but I think it is not major.
555 </memo>
556 <p>
557 <concept>transfer level</concept> represents how range data are
558 available.  mime-edit has a variable <code>mime-transfer-level</code>
559 to represent transfer level.
560
561
562 <defvar name="mime-transfer-level">
563 <p>
564 transfer level.
565 <p>
566 If transfer level of a data is over it, a data is encoded to 7bit.
567 <p>
568 Currently, 7 or 8 is available.  Default value is 7.
569 <p>
570 In extension plan, EBCDIC will be 5, ASCII printable only will be 6,
571 binary will be 9.  But it will not be implemented.
572 </defvar>
573
574
575 <memo>
576 transfer level is only for body, not for <a node="header">message
577 header</a>.  MIME extends <dref file="mime-en">RFC 822</dref> to use
578 8bit data in body, but it requires to use <dref
579 file="mime-en">us-ascii</dref> in header.
580 </memo>
581
582
583 <h2> Splitting
584 <node> message/partial sending
585 <p>
586 <defvar name="mime-edit-split-message">
587 <p>
588 Split large message if it is non-nil.
589 </defvar>
590
591 <defvar name="mime-edit-message-default-max-lines">
592 <p>
593 Default maximum lines of a message.
594 </defvar>
595
596 <defvar name="mime-edit-message-max-lines-alist">
597 <p>
598 Alist of major-mode vs maximum lines of a message.
599 <p>
600 If it is not specified for a major-mode,
601 <code>mime-edit-message-default-max-lines</code> is used.
602 </defvar>
603
604 <defvar name="mime-edit-split-blind-field-regexp">
605 <p>
606 Regular expression to match field-name to be ignored when split
607 sending.
608 </defvar>
609
610
611 <h1> Miscellaneous
612 <node> Various
613
614 <h2> PGP
615 <node> PGP
616 <p>
617 mime-edit provides PGP encryption, signature and inserting public-key
618 features based on <concept>PGP/MIME</concept> (RFC 2015) or
619 <concept>PGP-kazu</concept> (draft-kazu-pgp-mime-00.txt).
620 <p>
621 This feature requires your pgp command.
622
623 <defvar name="pgg-default-scheme">
624 <p>
625 Version of PGP or GnuPG command to be used for encryption or sign.
626 The value should be a symbol.  Allowed versions are <code>gpg</code>,
627 <code>pgp</code> or <code>pgp5</code>.
628 </defvar>
629
630 <defvar name="pgg-scheme">
631 <p>
632 Version of PGP or GnuPG command to be used for decryption or verification.
633 The value should be a symbol.  Allowed versions are <code>gpg</code>,
634 <code>pgp</code> or <code>pgp5</code>.
635 </defvar>
636
637 <defvar name="pgg-insert-url-function">
638 <p>
639 The function to fetch public key from the keyserver.
640 Use Emacs/W3 by the default setting. To use emacs-w3m
641 instead, set as follows:
642 <lisp>
643 (setq pgg-insert-url-function #'w3m-retrieve)
644 </lisp>
645 </defvar>
646
647
648 <h2> Mouse button
649 <node> Buttons
650 <p>
651 <defvar name="mime-button-face">
652 <p>
653 Face used for content-button or URL-button of MIME-Preview buffer.
654 </defvar>
655
656 <defvar name="mime-button-mouse-face">
657 <p>
658 Face used for MIME-preview buffer mouse highlighting.
659 </defvar>
660
661 <defvar name="mime-browse-url-function">
662 <p>
663 Function to browse URL.
664 </defvar>
665
666
667 <h2> Utility for configuration
668 <node> Acting-condition configuration
669 <p>
670 <defun name="mime-add-condition">
671             <args> target-type condition <opts> mode file
672 <p>
673 Add <var>condition</var> to database specified by
674 <var>target-type</var>.
675 <p>
676 <var>target-type</var> must be <code>preview</code> or
677 <code>action</code>.
678 <p>
679 If optional argument <var>mode</var> is <code>strict</code> or
680 <code>nil</code> (omitted), <var>condition</var> is added strictly.
681 <p>
682 If optional argument <var>mode</var> is <code>with-default</code>,
683 <var>condition</var> is added with default rule.
684 <p>
685 If optional argument <var>file</var> is specified, it is loaded when
686 <var>condition</var> is activate.
687 </defun>
688
689
690 <h1> Concept Index
691 <node> Concept Index
692
693 <cindex>
694
695
696 <h1> Function Index
697 <node> Function Index
698
699 <findex>
700
701
702 <h1> Variable Index
703 <node> Variable Index
704
705 <vindex>
706
707 </body>