This file describes how to use EMY, MIME user interface which implements SEMI API.

Copyright (C) 1993, 94, 95, 96, 97, 98, 99 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

EMY: An Introduction
********************

EMY is a MIME interface for Emacs. EMY provides SEMI API, which is specified in a separate document.

This manual correspond to EMY version 1.13.

Overview of MIME
****************

MIME stands for Multipurpose Internet Mail Extensions.

MIME is built on top of STD11.  MIME enhances semantics of STD11 so that you can send messages other than text/plain and US-ASCII.  MIME does not prohibit use of local conventions.  However, its use is discouraged. It would be nice if all MUA uses MIME to specify character set etc. Then you don't have to be aware of all local conventions in the world.

Don't assume every MUA can handle MIME correctly.  They might even don't understand MIME.  EMY takes interoperability the first priority.  You must be carefull to choose format that is easy to understand for everyone.  But you don't have to be afraid.  MIME is written in such a way that it can be viewed with non-MIME MUA if its well written.

EMY is here to make your life easier.  It provides some way to ignore standards to cooperate with broken world.  However, it doesn't allow you to send broken MIME messages.  If you want to same brokenness like them, EMY is not a candidate.  If you really thinks it's needed, you can try persuading me.  Warning: `It's de facto standard' is not enough.

Writing text
============

(I'll write this sections later).

Types of message you can use
============================

How things are interpretes with each types
------------------------------------------

Some basic things about EMY
***************************

(Not yet written).

What you should care
====================

Viewing MIME messages
*********************

Right now only differences between SEMI and EMY are documented.

Playing with an entity
======================

You can change the representation of given part in the preview buffer. Following commands are available in preview buffer.

c
     Display the part as text/plain with automatic MIME charset detection.  You can specify coding-system if you give a numerical prefix (mime-preview-text).

i
     Show the contents of the part without code-conversion.  C-u c binary RET does the same thing (mime-preview-inline).

t
     Represent the part using the method specified by mime-preview-condition.  When there's no presentation method for given part, nothing is performed (mime-preview-type).

e
     Save content of the part to a file.  It will prompt for you to enter file name (mime-preview-extract-current-entity).

v
     Pass the entity to an external program specified by mailcap file (mime-preview-play-current-entity).

b
     Buttonize article (mime-preview-buttonize).

B
     Unbuttonize article (mime-preview-unbuttonize).

C-c C-t C-h

     Toggle display of entity header.

C-c C-t C-c

     Toggle display of entity body.

How buttons look like
=====================

Not yet written.

Add button before, after or around an entity
============================================

You can customize where to add buttons and where to not with mime-view-button-place-alist.  Unfortunately, there's no variable to change content of the button. It must be an alist of type or type/subtype vs. keywords.

Three valid keywords are:

before
     Add button before given types.

after
     Add button when another part follows that type.

around
     Do both before and after.

Notice when deciding whether inserting button or not, an entity of same level is consulted as a previous entity.  Let's say a message has following structure and nothing is specified for text/xml.

     message/rfc822
       multipart/mixed
         text/plain
         image/jpeg
       text/xml

When MIME-View decides text/xml part should have button or not, it checks multipart/mixed has after or around, not image/jpeg. This behaviour may be confusing.  In the future version, the very last part's value will be used as well.

Default value is:

     ((message . around)
      (application . before)
      (multipart/alternative . around))

This means you will have buttons around message/* and multipart/alternative, and before application/*.

Invalid MIME messages
=====================

Some MUAs send totally broken MIME messages.  According to the standard, it's perfectly fine for EMY not to grok those message.  However, EMY tries to extract as much information as possible.  Here's some functions that might help you.

Some MUAs localized to Japanese sends these strings as a filename parameter of Content-Disposition.

     =?ISO-2022-JP?B?GyRCRnxLXDhsGyhC?=

It looks like encoded-words. This usage is strictly prohibited by RFC 2047.  Instead, you should use mechanism described in RFC 2231. If you really want to ``decode'' it when saving it to file, you can use something like this.

     (mime-add-condition
      'action
      '((mode . "extract")
        (method . mime-save-content-for-broken-message)))

Unfortunately, there's no easy way to customize looking of buttons. It's on EMY's TODO list.

If you are desperate, you can redefine mime-view-insert-entity-button.

     (defun mime-view-insert-entity-button (entity &optional body-is-invisible)
       "Insert entity-button of ENTITY."
       (let ((entity-node-id (mime-entity-node-id entity))
     	(params (mime-entity-parameters entity))
     	(subject (eword-decode-string (mime-view-entity-title entity))))
         (mime-insert-button
          (concat
           (let ((access-type (assoc "access-type" params))
     	    (num (or (cdr (assoc "x-part-number" params))
     		     (if (consp entity-node-id)
     			 (mapconcat (function
     				     (lambda (num)
     				       (format "%s" (1+ num))))
     				    (reverse entity-node-id) ".")
     		       "0"))))
     	(cond (access-type
     	       (let ((server (assoc "server" params)))
     		 (setq access-type (cdr access-type))
     		 (if server
     		     (format "%s %s ([%s] %s)"
     			     num subject access-type (cdr server))
     		   (let ((site (cdr (assoc "site" params)))
     			 (dir (cdr (assoc "directory" params)))
     			 (url (cdr (assoc "url" params))))
     		     (if url
     			 (format "%s %s ([%s] %s)"
     				 num subject access-type url)
     		       (format "%s %s ([%s] %s:%s)"
     			       num subject access-type site dir))))))
     	      (t
     	       (let ((media-type (mime-entity-media-type entity))
     		     (media-subtype (mime-entity-media-subtype entity))
     		     (charset (cdr (assoc "charset" params)))
     		     (encoding (mime-entity-encoding entity)))
     		 (concat
     		  num " " subject
     		  (let ((rest
     			 (format " <%s/%s%s%s>"
     				 media-type media-subtype
     				 (if charset
     				     (concat "; " charset)
     				   "")
     				 (if encoding
     				     (concat " (" encoding ")")
     				   ""))))
     		    (if (>= (+ (current-column)(length rest))(window-width))
     			"\n\t")
     		    rest))))))
           (if body-is-invisible
     	  " ..."
     	""))
          (function mime-preview-play-current-entity))))

Note: These settings are unsupported until better way is implemented.

Composing MIME messages
***********************

When you are editing MIME message, you might want to insert some part at the end of your message.  Some MUA are known to have some problems when last part is not an attachment.

If you want to do this, mime-edit-attach-at-end-type is your friend. This variable is list of MIME types or type/subtypes inserted at the last part. When only type is specified, it will affect all subtypes of that type.

If you want insert application/* and message/rfc822 at the end, you can do like this:

     (setq mime-edit-attach-at-end-types
           '(application message/rfc822))