1 <!doctype sinfo system>
3 <title>SEMI 1.14 Manual
4 <author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail>
14 This file documents SEMI, a MIME user interface for GNU Emacs.
21 SEMI is a package for GNU Emacs to provide features related with MIME
24 SEMI provides two user interfaces: MIME-View and MIME-Edit.
26 MIME-View is a kernel of user interface to display or operate MIME
27 messages, STD 11 messages or ``localized RFC 822'' messages.
29 MIME-Edit is a user interface to compose MIME messages.
31 Each MUA can use powerful MIME features to combine these features.
34 <h1> MIME message viewing
37 MIME-View is a MIME viewer for wide use that runs on GNU Emacs.
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.
46 <node> Overview of MIME-View
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).
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
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
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
90 <h2> Presentation of mime-preview-buffer
93 mime-view-mode displays information about each entity as
104 You can change their design or inhibit showing some of them, according
107 See following example
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
116 Organization: Japan Advanced Institute of Science and Technology,
120 How to compose MIME message in MIME-Edit mode.
122 C-c C-x ? shows its help.
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.
142 therefore, you should type C-c C-x C-i and specify the binary file
143 which you want to insert.
145 You should select Base64 as MIME encoding for binary file.
151 Like above, you can compose the message with image.
153 ==================== Take A Cup Of Russian Tea ======================
154 ========= ** Not With Jam Nor Marmalade But With Honey ** ==========
155 ========= MORIOKA TOMOHIKO ==========
156 ============== Internet E-mail: <morioka@@jaist.ac.jp> ==============
163 <concept>entity-button</concept> is a tag on the top of the entity
164 which shows brief information of the part.
166 Normally, it appears as
169 [1.3 test (text/plain)]
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>.
177 The string in the next describes its title. This information is
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
188 If none of them are specified, displays a blank.
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>.
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
201 shows up the image contained there.
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.
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.)
217 <concept>entity-body</concept> is the content of the part.
219 Sophistication does not seem enough here also, but it is really such
222 Though, it actually be twisted a little.
224 The text entity is passed to code conversion according to its charset,
225 and the image entity should be converted on XEmacs.
227 Details will be described later.
230 <h2> Operation in mime-preview-buffer
231 <node> mime-view-mode
233 mime-preview-buffer posesses following functionalities.
238 go back to upper part (in the first part of the message,
239 go back to the Summary mode (*1))
241 <kt>p<kd>go to previous part
243 <kt>M-TAB<kd>go to previous part
245 <kt>n<kd>go to next part
247 <kt>TAB<kd>go to next part
251 <kt>M-SPC<kd>scroll down
253 <kt>DEL<kd>scroll down
255 <kt>RET<kd>go to next line
257 <kt>M-RET<kd>go to previous line
259 <kt>v<kd>play current part (*2)
261 <kt>e<kd>extract file from current part (*2)
263 <kt>C-c C-p<kd>print current part (*2)
267 start the mouse button in preview-buffer
269 on content-button, play current part (*2)
271 on URL-button, start WWW browser
275 <memo title="Notice">
277 (*1) Do not go back to Summary mode unless appropriately
278 configured for mime-view in the MUA.
280 (*2) actual behavior depends on the associated method
284 <h1> MIME message editing
287 <concept>MIME-Edit</concept> is a general MIME composer for GNU Emacs.
290 <h2> Minor-mode to edit MIME message
291 <node> mime-edit-mode
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.
298 There are 2 kinds of tags:
305 single-part tag represents single part, this form is following:
308 --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
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.
316 ENCODING indicates <dref
317 file="mime-ja">Content-Transfer-Encoding</dref> field. It is optional
320 OPTIONAL-FIELDS is to represent another fields except Content-Type
321 field and Content-Transfer-Encoding field.
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>.
327 multi-part beginning tag's form is following:
333 multi-part ending tag's form is following:
339 A region from multi-part beginning tag to multi-part ending tag is
340 called as <concept>enclosure</concept>.
343 <h2> Operations for single-part
344 <node> single-part tags
346 Operations to make single-part are following:
351 Insert single-part tag indicates text part.
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">
361 Insert external part.
365 Record audio input until <kbd>C-g</kbd> is pressed, and insert as a
366 audio part. (It requires /dev/audio in default.)
370 Insert current (mail or news) message. (It is MUA depended.)
374 Insert mail message. (It is MUA depended.)
376 <dt><key>C-c C-x C-w</key>, <key>C-c C-x C-s</key>
382 Insert <dref>PGP</dref> public key.
386 Insert any single-part tag.
390 <h2> Operations for enclosure
391 <node> enclosure tags
393 Operations to make enclosure are following:
398 Enclose specified region as multipart/alternative.
402 Enclose specified region as multipart/parallel.
406 Enclose specified region as multipart/mixed.
410 Enclose specified region as multipart/digest.
414 Digital-sign to specified region. <cf node="PGP">
418 Encrypt to specified region. <cf node="PGP">
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.)
428 <h2> Other operations
429 <node> other MIME-Edit operations
431 There are another operations in mime-edit-mode.
436 Send current editing message.
440 Preview current editing message. <cf node="MIME-View">
444 Exit mime-edit-mode without sending.
448 Set current editing message to enable automatic splitting or not.
449 Form of automatic split messages is message/partial.
453 Set <dref file="mime-en">7bit</dref> to <dref>transfer level</dref>.
457 Set <dref file="mime-en">8bit</dref> to <dref>transfer level</dref>.
461 Set current editing message to digital-sign or not. <cf node="PGP">
465 Set current editing message to encrypt or not. <cf node="PGP">
468 Display help message.
472 <h2> How to detect tag for inserted file
473 <node> file-type specification
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>.
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)
483 If you want to change default value for file names, please change
484 variable <code>mime-file-types</code>.
486 <defvar name="mime-file-types">
488 Specification of default value of tag for file name of inserted file.
490 It is a list of following list:
493 (FILE_PAT TYPE SUBTYPE PARAMS ENCODING
494 DISPOSITION_TYPE DISPOSITION_PARAMS)
497 Each element of the list is following:
501 <dd>regular expression of file name
503 <dd>primary-type of media-type
505 <dd>subtype of media-type
507 <dd>parameters of Content-Type field
509 <dd>Content-Transfer-Encoding
512 <dt>DISPOSITION_PARAMS
513 <dd>parameters of Content-Disposition field
517 Example: Specify application/rtf as default media type for
523 '(set-alist 'mime-file-types
525 '("application" "rtf" nil nil
526 "attachment" (("filename" . file)))
533 <node> transfer level
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>.
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.
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
548 EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
549 encoded by base64. But I don't know EBCDIC. (^_^;
551 Similarly, I wish ASCII-printable only MTA and code-conversion MTA
554 Maybe there are binary-through MTA, but I think it is not major.
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.
562 <defvar name="mime-transfer-level">
566 If transfer level of a data is over it, a data is encoded to 7bit.
568 Currently, 7 or 8 is available. Default value is 7.
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.
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.
584 <node> message/partial sending
586 <defvar name="mime-edit-split-message">
588 Split large message if it is non-nil.
591 <defvar name="mime-edit-message-default-max-lines">
593 Default maximum lines of a message.
596 <defvar name="mime-edit-message-max-lines-alist">
598 Alist of major-mode vs maximum lines of a message.
600 If it is not specified for a major-mode,
601 <code>mime-edit-message-default-max-lines</code> is used.
604 <defvar name="mime-edit-split-blind-field-regexp">
606 Regular expression to match field-name to be ignored when split
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).
621 This feature requires your pgp command.
623 <defvar name="pgg-default-scheme">
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>.
630 <defvar name="pgg-scheme">
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>.
637 <defvar name="pgg-insert-url-function">
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:
643 (setq pgg-insert-url-function #'w3m-retrieve)
651 <defvar name="mime-button-face">
653 Face used for content-button or URL-button of MIME-Preview buffer.
656 <defvar name="mime-button-mouse-face">
658 Face used for MIME-preview buffer mouse highlighting.
661 <defvar name="mime-browse-url-function">
663 Function to browse URL.
667 <h2> Utility for configuration
668 <node> Acting-condition configuration
670 <defun name="mime-add-condition">
671 <args> target-type condition <opts> mode file
673 Add <var>condition</var> to database specified by
674 <var>target-type</var>.
676 <var>target-type</var> must be <code>preview</code> or
679 If optional argument <var>mode</var> is <code>strict</code> or
680 <code>nil</code> (omitted), <var>condition</var> is added strictly.
682 If optional argument <var>mode</var> is <code>with-default</code>,
683 <var>condition</var> is added with default rule.
685 If optional argument <var>file</var> is specified, it is loaded when
686 <var>condition</var> is activate.
697 <node> Function Index
703 <node> Variable Index