2 @setfilename mime-ui-en.info
3 @settitle{SEMI 1.14 Manual}
5 @title SEMI 1.14 Manual
6 @author MORIOKA Tomohiko <morioka@@jaist.ac.jp>
9 @node Top, Introduction, (dir), (dir)
14 This file documents SEMI, a MIME user interface for GNU Emacs.
18 * Introduction:: What is SEMI?
19 * MIME-View:: MIME message viewing
20 * MIME-Edit:: MIME message editing
21 * Various:: Miscellaneous
27 @node Introduction, MIME-View, Top, Top
28 @chapter What is SEMI?
30 SEMI is a package for GNU Emacs to provide features related with MIME
31 user interface.@refill
33 SEMI provides two user interfaces: MIME-View and MIME-Edit.@refill
36 MIME-View is a kernel of user interface to display or operate MIME
37 messages, STD 11 messages or ``localized RFC 822'' messages.@refill
39 MIME-Edit is a user interface to compose MIME messages.@refill
41 Each MUA can use powerful MIME features to combine these features.
44 @node MIME-View, MIME-Edit, Introduction, Top
45 @chapter MIME message viewing
47 MIME-View is a MIME viewer for wide use that runs on GNU Emacs.@refill
49 MIME-View is the kernel of the user interface for browsing MIME
50 messages. You can start some presentation-method which is a program for
51 creating some representation, or some acting-method which is a program
52 for processing the entity. Then you can deal with a variety of entities.
56 * Overview of MIME-View:: Basic design
57 * MIME-Preview:: Presentation of mime-preview-buffer
58 * mime-view-mode:: Operation in mime-preview-buffer
61 @node Overview of MIME-View, MIME-Preview, MIME-View, MIME-View
64 The representation form of the internet messages in electric letters
65 or in net news is based on STD 11. The STD 11 message body is a plain
66 text which consists of lines as its only structure, and the character
67 code is fixed as us-ascii. Actually, there are ``localized STD 11''
68 messages that use some character code in their linguistic range
69 instead of using us-ascii. Even in that case, the character code in
70 the message is single. Therefore, Message User Agents have considered
71 (byte row) = (us-ascii string), or (byte row) = (string in the
72 character code in the linguistic range).@refill
74 Although, the MIME message has the tree structure in entity unit.
75 And one message can contain multiple character codes. The content of
76 an entity can be not only a letter or an image that can be displayed
77 simply, but also can be a voice or an animation that are played for
78 some time interval, a data for some specific application, a source
79 code of some program, or an external reference that consists of
80 the usage of ftp or mail service, or some URL. Therefore the simple
81 extension of STD 11 user interface, which only consider displaying
82 the message, cannot treat all of the MIME functionalities.
83 Then it is not sufficient to decode message along its MIME type, but
84 it is also required to consider a playback processing through some
85 dialogue with the user. The format of MIME messages is designed
86 to easily be passed to automatic processing. But some contents in the
87 MIME message should not be passed to automatic processing for security
88 reasons. So it should be designed to ask user in such cases.
89 After all, in order to deal with MIME message, it is required to
90 distinguish the representation for information exchange which is
91 written in STD 11 or MIME construction, and its result
92 after some interpretation which is a display screen or a playback
93 process. It is also needed to converse with user for playback
96 Therefore, MIME-View uses two buffers for one document, one is the
97 mime-raw-buffer that stores the representation for information exchange,
98 and the other is the mime-preview-buffer that stores the representation
99 for displaying.@refill
101 MIME-View provides a mode in the mime-preview-buffer for reading MIME
102 message, which is called as mime-view-mode. User can manipulate each
106 @node MIME-Preview, mime-view-mode, Overview of MIME-View, MIME-View
107 @section Presentation of mime-preview-buffer
109 mime-view-mode displays information about each entity as@refill
120 You can change their design or inhibit showing some of them, according
123 See following example
127 From: morioka@@jaist.ac.jp (MORIOKA Tomohiko)
128 Subject: Re: question?
129 Newsgroups: zxr.message.mime
130 Date: 22 Oct 93 11:02:44
132 Organization: Japan Advanced Institute of Science and Technology,
136 How to compose MIME message in MIME-Edit mode.
138 C-c C-x ? shows its help.
140 C-c C-x C-t insert a text message.
141 C-c C-x TAB insert a (binary) file.
142 C-c C-x C-e insert a reference to external body.
143 C-c C-x C-v insert a voice message.
144 C-c C-x C-y insert a mail or news message.
145 C-c C-x RET insert a mail message.
146 C-c C-x C-s insert a signature file at end.
147 C-c C-x t insert a new MIME tag.
148 C-c C-m C-a enclose as multipart/alternative.
149 C-c C-m C-p enclose as multipart/parallel.
150 C-c C-m C-m enclose as multipart/mixed.
151 C-c C-m C-d enclose as multipart/digest.
152 C-c C-m C-s enclose as PGP signed.
153 C-c C-m C-e enclose as PGP encrypted.
154 C-c C-x C-k insert PGP public key.
155 C-c C-x p preview editing MIME message.
158 therefore, you should type C-c C-x C-i and specify the binary file
159 which you want to insert.
161 You should select Base64 as MIME encoding for binary file.
167 Like above, you can compose the message with image.
169 ==================== Take A Cup Of Russian Tea ======================
170 ========= ** Not With Jam Nor Marmalade But With Honey ** ==========
171 ========= MORIOKA TOMOHIKO ==========
172 ============== Internet E-mail: <morioka@@jaist.ac.jp> ==============
183 @node entity-button, entity-header, MIME-Preview, MIME-Preview
184 @subsection entity-button
185 @cindex entity-number
186 @cindex entity-button
188 @strong{entity-button} is a tag on the top of the entity
189 which shows brief information of the part.@refill
191 Normally, it appears as
194 [1.3 test (text/plain)]
199 The number on the head describes the place of the entity in the
200 message (like the section number) and it is called as
201 @strong{entity-number}.@refill
203 The string in the next describes its title. This information is
208 Title described in Content-Description field or Subject field
210 File name specified by filename parameter in Content-Disposition field
212 File name specified by name parameter in Content-Type field
214 File name for uuencode'ing
218 If none of them are specified, displays a blank.
220 The 3rd item in the parenthesis describes media-type/subtype of
221 the entity. If it is is not MIME entity, it displays @code{nil}.
224 This entity-button plays a role like icon that symbolically
225 shows the content of the entity. For example, push @kbd{v} on
232 shows up the image contained there.
234 If the mouse operation is possible, you can display the image
235 by pushing 2nd button (the middle button for 3 button mouse) too.
238 @node entity-header, entity-body, entity-button, MIME-Preview
239 @subsection entity-header
240 @cindex entity-header
242 @strong{entity-header} is the header of the entity.
243 (Don't blame me as ``You say nothing more than as it is'',
244 It is no more than that.)
246 @node entity-body, , entity-header, MIME-Preview
247 @subsection entity-body
250 @strong{entity-body} is the content of the part.@refill
252 Sophistication does not seem enough here also, but it is really such
255 Though, it actually be twisted a little.@refill
257 The text entity is passed to code conversion according to its charset,
258 and the image entity should be converted on XEmacs.@refill
260 Details will be described later.
263 @node mime-view-mode, , MIME-Preview, MIME-View
264 @section Operation in mime-preview-buffer
266 mime-preview-buffer posesses following functionalities.@refill
270 go back to upper part (in the first part of the message,
271 go back to the Summary mode (*1))
301 play current part (*2)
304 extract file from current part (*2)
307 print current part (*2)
309 @item @key{mouse-button-2}
310 start the mouse button in preview-buffer
312 on content-button, play current part (*2)@refill
314 on URL-button, start WWW browser@refill
322 (*1) Do not go back to Summary mode unless appropriately
323 configured for mime-view in the MUA.@refill
325 (*2) actual behavior depends on the associated method
330 @node MIME-Edit, Various, MIME-View, Top
331 @chapter MIME message editing
334 @strong{MIME-Edit} is a general MIME composer for GNU Emacs.
338 * mime-edit-mode:: Minor-mode to edit MIME message
339 * single-part tags:: Operations for single-part
340 * enclosure tags:: Operations for enclosure
341 * other MIME-Edit operations:: Other operations
342 * file-type specification:: How to detect tag for inserted file
344 * message/partial sending:: Splitting
347 @node mime-edit-mode, single-part tags, MIME-Edit, MIME-Edit
348 @section Minor-mode to edit MIME message
350 @cindex multi-part ending tag
351 @cindex multi-part beginning tag
353 @cindex mime-edit-mode
355 @strong{mime-edit-mode} is a minor mode to compose MIME message. In
356 this mode, @strong{tag} represents various kinds of data, so you can
357 edit multi part message consists of various kinds of data, such as text,
358 image, audio, etc.@refill
360 There are 2 kinds of tags:
369 single-part tag represents single part, this form is following:@refill
372 --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
376 TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of
377 Content-Type (@ref{(mime-en)Content-Type}) field. TYPE/SUBTYPE is
378 required, PARAMETERS is optional.@refill
380 ENCODING indicates Content-Transfer-Encoding
381 (@ref{(mime-ja)Content-Transfer-Encoding}) field. It is optional
384 OPTIONAL-FIELDS is to represent another fields except Content-Type field
385 and Content-Transfer-Encoding field.@refill
387 multi-part tags represent multi part (@ref{(mime-en)multipart}). They
388 consist of a pair of @strong{multi-part beginning tag} and
389 @strong{multi-part ending tag}.@refill
391 multi-part beginning tag's form is following:
397 multi-part ending tag's form is following:
403 A region from multi-part beginning tag to multi-part ending tag is
404 called as @strong{enclosure}.
407 @node single-part tags, enclosure tags, mime-edit-mode, MIME-Edit
408 @section Operations for single-part
410 Operations to make single-part are following:
413 @item @key{C-c C-x C-t}
414 Insert single-part tag indicates text part.
416 @item @key{C-c C-x C-i}
417 Insert file as a MIME attachment. If @kbd{C-u} is followed by it, it
418 asks media-type, subtype or encoding even if their default values are
419 specified. (cf. @ref{tag specification for inserted file})
421 @item @key{C-c C-x C-e}
422 Insert external part.
424 @item @key{C-c C-x C-v}
425 Record audio input until @kbd{C-g} is pressed, and insert as a
426 audio part. (It requires /dev/audio in default.)
428 @item @key{C-c C-x C-y}
429 Insert current (mail or news) message. (It is MUA depended.)
431 @item @key{C-c C-x C-m}
432 Insert mail message. (It is MUA depended.)
434 @item @key{C-c C-x C-w}, @key{C-c C-x C-s}
437 @item @key{C-c C-x C-k}
438 Insert PGP (@ref{PGP}) public key. (It requires Mailcrypt package.)
440 @item @key{C-c C-x t}
441 Insert any single-part tag.
447 @node enclosure tags, other MIME-Edit operations, single-part tags, MIME-Edit
448 @section Operations for enclosure
450 Operations to make enclosure are following:
453 @item @key{C-c C-m C-a}
454 Enclose specified region as multipart/alternative.
456 @item @key{C-c C-m C-p}
457 Enclose specified region as multipart/parallel.
459 @item @key{C-c C-m C-m}
460 Enclose specified region as multipart/mixed.
462 @item @key{C-c C-m C-d}
463 Enclose specified region as multipart/digest.
465 @item @key{C-c C-m C-s}
466 Digital-sign to specified region. (cf. @ref{PGP})
468 @item @key{C-c C-m C-e}
469 Encrypt to specified region. (cf. @ref{PGP})
471 @item @key{C-c C-m C-q}
472 avoid to encode tags in specified region. In other words, tags is
473 interpreted as such string. (In current version, it may be
474 incomplete. Maybe PGP-signature does not work for this enclosure.)
480 @node other MIME-Edit operations, file-type specification, enclosure tags, MIME-Edit
481 @section Other operations
483 There are another operations in mime-edit-mode.
487 Send current editing message.
489 @item @key{C-c C-x p}
490 Preview current editing message. (cf. @ref{MIME-View})
492 @item @key{C-c C-x C-z}
493 Exit mime-edit-mode without sending.
495 @item @key{C-c C-x /}
496 Set current editing message to enable automatic splitting or not.
497 Form of automatic split messages is message/partial.
499 @item @key{C-c C-x 7}
500 Set 7bit (@ref{(mime-en)7bit}) to transfer level (@ref{transfer level}).
502 @item @key{C-c C-x 8}
503 Set 8bit (@ref{(mime-en)8bit}) to transfer level (@ref{transfer level}).
505 @item @key{C-c C-x v}
506 Set current editing message to digital-sign or not. (cf. @ref{PGP})
508 @item @key{C-c C-x h}
509 Set current editing message to encrypt or not. (cf. @ref{PGP})
511 @item @key{C-c C-x ?}
512 Display help message.
518 @node file-type specification, transfer level, other MIME-Edit operations, MIME-Edit
519 @section How to detect tag for inserted file
521 When @kbd{C-c C-x C-i} (@code{mime-edit-insert-file}) is pressed, tag
522 parameters for inserted file, such as media-type or encoding, are
523 detected by variable @code{mime-file-types}.@refill
525 When @kbd{C-u} is followed by it or parameter is not found from the
526 variable, it asks from user. (When @kbd{C-u} is followed by it,
527 detected value is used as default value)@refill
529 If you want to change default value for file names, please change
530 variable @code{mime-file-types}.
532 @defvar mime-file-types
534 Specification of default value of tag for file name of inserted
537 It is a list of following list:
540 (FILE_PAT TYPE SUBTYPE PARAMS ENCODING
541 DISPOSITION_TYPE DISPOSITION_PARAMS)
545 Each element of the list is following:
549 regular expression of file name
552 primary-type of media-type
555 subtype of media-type
558 parameters of Content-Type field
561 Content-Transfer-Encoding
563 @item DISPOSITION_TYPE
566 @item DISPOSITION_PARAMS
567 parameters of Content-Disposition field
572 Example: Specify application/rtf as default media type for
578 '(set-alist 'mime-file-types
580 '("application" "rtf" nil nil
581 "attachment" (("filename" . file)))
588 @node transfer level, message/partial sending, file-type specification, MIME-Edit
589 @section transfer level
590 @cindex transfer level
592 Each content inserted in a message is represented by 7bit
593 (@ref{(mime-en)7bit}), 8bit (@ref{(mime-en)8bit}) or binary
594 (@ref{(mime-en)binary}).@refill
596 If a message is translated by 7bit-through MTA (@ref{(mime-en)MTA}),
597 there is no need to encode 7bit data, but 8bit and binary data must be
598 encoded to 7bit data.@refill
600 Similarly, if a message is translated by 8bit-through MTA, there is no
601 need to encode 7bit or 8bit data, but binary data must be encoded to
602 7bit or 8bit data.@refill
607 EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
608 encoded by base64. But I don't know EBCDIC. (^_^;
610 Similarly, I wish ASCII-printable only MTA and code-conversion MTA
611 disappeared. (^_^;@refill
613 Maybe there are binary-through MTA, but I think it is not major.
616 @strong{transfer level} represents how range data are
617 available. mime-edit has a variable @code{mime-transfer-level}
618 to represent transfer level.
621 @defvar mime-transfer-level
623 transfer level.@refill
625 If transfer level of a data is over it, a data is encoded to
628 Currently, 7 or 8 is available. Default value is 7.@refill
630 In extension plan, EBCDIC will be 5, ASCII printable only will be 6,
631 binary will be 9. But it will not be implemented.
639 transfer level is only for body, not for message header (@ref{header}).
640 MIME extends RFC 822 (@ref{(mime-en)RFC 822}) to use 8bit data in body,
641 but it requires to use us-ascii (@ref{(mime-en)us-ascii}) in header.
646 @node message/partial sending, , transfer level, MIME-Edit
649 @defvar mime-edit-split-message
651 Split large message if it is non-nil.
655 @defvar mime-edit-message-default-max-lines
657 Default maximum lines of a message.
661 @defvar mime-edit-message-max-lines-alist
663 Alist of major-mode vs maximum lines of a message.@refill
665 If it is not specified for a major-mode,
666 @code{mime-edit-message-default-max-lines} is used.
670 @defvar mime-edit-split-blind-field-regexp
672 Regular expression to match field-name to be ignored when split sending.
677 @node Various, Concept Index, MIME-Edit, Top
678 @chapter Miscellaneous
682 * PGP:: Encryption, Sign
683 * Buttons:: Mouse button
684 * Acting-condition configuration:: Utility for configuration
687 @node PGP, Buttons, Various, Various
692 mime-edit provides PGP encryption, signature and inserting public-key
693 features based on @strong{PGP/MIME} (RFC 2015) or @strong{PGP-kazu}
694 (draft-kazu-pgp-mime-00.txt).@refill
696 This feature requires your pgp command.
698 @defvar pgg-default-scheme
700 Version of PGP or GnuPG command to be used for encryption or sign.
701 The value should be a symbol. Allowed versions are @code{gpg},
702 @code{pgp} or @code{pgp5}.@refill
708 Version of PGP or GnuPG command to be used for decryption or verification.
709 The value should be a symbol. Allowed versions are @code{gpg},
710 @code{pgp} or @code{pgp5}.@refill
714 @defvar pgg-insert-url-function
716 The function to fetch public key from the keyserver.
717 Use Emacs/W3 by the default setting. To use emacs-w3m
718 instead, set as follows:
720 (setq pgg-insert-url-function #'w3m-retrieve)
726 @node Buttons, Acting-condition configuration, PGP, Various
727 @section Mouse button
729 @defvar mime-button-face
731 Face used for content-button or URL-button of MIME-Preview buffer.
735 @defvar mime-button-mouse-face
737 Face used for MIME-preview buffer mouse highlighting.
741 @defvar mime-browse-url-function
743 Function to browse URL.
748 @node Acting-condition configuration, , Buttons, Various
749 @section Utility for configuration
751 @defun mime-add-condition target-type condition &optional mode file
753 Add @var{condition} to database specified by @var{target-type}.@refill
755 @var{target-type} must be @code{preview} or @code{action}.@refill
757 If optional argument @var{mode} is @code{strict} or @code{nil}
758 (omitted), @var{condition} is added strictly.@refill
760 If optional argument @var{mode} is @code{with-default}, @var{condition}
761 is added with default rule.@refill
763 If optional argument @var{file} is specified, it is loaded when
764 @var{condition} is activate.
769 @node Concept Index, Function Index, Various, Top
770 @chapter Concept Index
774 @node Function Index, Variable Index, Concept Index, Top
775 @chapter Function Index
779 @node Variable Index, , Function Index, Top
780 @chapter Variable Index