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>