Using MIME

[previous] [next] [table of contents] [index]

If your version of MH is set up for MIME (the multipurpose mail extensions introduced in an earlier chapter, you can try MIME features by reading this section.

Can You Use MIME?

MIME support was introduced in MH 6.8 and improved in MH 6.8.3. If you have an earlier version of MH, it probably doesn't handle MIME. MH has to be configured for MIME when the system is installed; if you have version 6.8 or later, it still may not support MIME. To check your version, first run any MH command with its -help switch. If the version is 6.8 or higher, and if you see the [MIME] option, you're halfway there. The [MIME] option is no guarantee that the other supporting programs and files are ready. The Section on Configuring mhn should help. For now, the best answer is to try reading a message and see what happens.

How well MIME works also depends on the terminal or window system you're using. For example, some character-based terminals can display only ASCII text. If your computer tries to display a MIME message with non-ASCII characters like ñ, your terminal may show garbage or some other unrelated character. Or, if you're using a workstation or X terminal with a window system, but the system can't play sounds, a MIME message with audio content will be useless. If your system's fonts aren't set up correctly, you may not be able to read messages in other character sets. If you have trouble with MIME messages, you might go to someone else's more-sophisticated setup and try displaying the message there. The section Configuring mhn has much more information about MIME setup.

Listing MIME Message Contents

MH uses a "Swiss Army Knife" utility called mhn to handle MIME messages. mhn does message composition, display, storage, listing, and more. Some programs start mhn for you -- show does, for example. But you'll also run mhn directly sometimes. Let's use it to list the contents of the sample MIME message you got in Section Sending Some Mail: comp, send. The -list switch lists the contents of the current message or of the messages you name on its command line:

% mhn -list 6
 msg part  type/subtype              size description
   6       multipart/mixed            52K
     1     multipart/alternative     1330
     1.1   text/enriched              539 Introduction in enriched text
     1.2   text/plain                 454 Introduction in plain text
     2     audio/basic                20K Hello from the author
     3     image/gif                  17K Book cover

The first line describes the columns of information underneath it. Next comes a line that tells you about the overall message: Message 6 has a content type and subtype of multipart/mixed, and it's approximately 52,000 octets (bytes) long. (If you're quick at math, you can see that the sizes of the parts don't add up to 52k. Curious? Read ahead about the -norealsize switch.) The second line describes part 1 of the message; it is multipart/alternative. That means part 1 will have at least two subparts; they're numbered 1.1 and 1.2. Part 1.1, text/enriched, is "richer" than text/plain, so it'll be shown if your MH setup can. Otherwise, show will show you part 1.2. After the first part are two more: part 2 has sound and the third has an image. The Section Listing MIME Message Parts has more about mhn -list.

Reading MIME Mail

You don't need to do anything special to read a MIME message. If a message header has MIME fields, the show command will see them and do the right thing (if your system is set up correctly). To find out what your system will do, start by reading the sample MIME message you requested earlier.

Reading the Header

Different MH systems are configured differently. When you read the sample message, you may not see the same things I show here. You'll probably start by seeing the message header and a prompt:

% show 6
(Message inbox:6)
Date:    Mon, 09 Jan 1995
To:      Angela Corning <angelac@xyz.edu>

From:    mh-mime-sample@online.oreilly.com (Sample MH/MIME message server)
Subject: Sample MIME message for "MH & xmh" Nutshell Handbook

X-Face:  4'>h,#cS;REmrM.0o;MLO(rQ\6!tC3|K"`%_&L/5r'?`z?YFA'^?O_2;uhD
         j}[Ezd'KN;UN]JY>}7NI!3#)pemuo^HLsy?e&d;~eMDvq{tVqg<Dj,:;J_+=`G9:Av
         (qc1~%PPox??]:2o`7kWKem,99A>_JaK.QQ>aXK,)ruQhThx8,.X|_@Foa75CW:E[=
         @U@5dA'(H`V>Vm{d[)S8AcVpGs1Jw,p6w{LFc?o(}7$@3ani]G[joNpQsJ%^kZhox%
         7\gVhT%uu|8"WXlT=U1:opS-:9hL{kZgxhGvUf?bJ4E
MIME-Version: 1.0

(END)

The X-Face: field isn't part of MIME. It's a bitmap image of my face that exmh can display. If you won't be using exmh, you can tell mhn not to display X-Face: fields by editing the mhl.headers file.

Your cursor may be sitting at the end of the last line. If it is, when you press RETURN, MH will probably print a line of information about the first part of the MIME message. You're done with the message header, ready to read the body.

Reading the Body

The sample message starts with a multipart/alternative section that has both plain text and enriched text. If you're set up to display enriched text, that's what the information line should show (as this one does):

part 1.1   text/enriched              539 Introduction in enriched text
Press <return> to show content...

Otherwise, you should be prompted with a line that says "text/plain 454 Introduction in plain text." Press RETURN to read the part:

Welcome to MIME mail!


This is a sample MIME message for the third edition of the book MH & xmh:
Email for Users & Programmers from O'Reilly & Associates.

Right now, you're reading enriched text from the second subpart of a
multipart/alternative content.  If your MH setup hadn't been able to show
enriched text, you would have seen plain text instead.

Next, if your MH setup can render them, are an audio greeting card and a
GIF-format picture of the book's cover.  Have fun!

--Jerry


Press RETURN to continue (or 'q' to quit):

Depending on your setup, the boldface and italic text may be shown underlined, highlighted, or displayed in some other way. That depends on your terminal, the termcap or terminfo setting, the program that displays the enriched text, and more. (If it works, just be glad it does! :-))

The next part of the sample message is a short audio message from me that says "Hi. This is Jerry Peek. Have fun with MIME!" You don't have to listen to it, though. Any time you see a Press <return> to show content... prompt, you can skip that part by pressing your interrupt key -- often, that's CTRL-C.

You have another choice: You can skip the rest of the message and get back to a shell prompt by pressing your QUIT key -- typically CTRL-\ (control-backslash). But remember that those only work when your cursor is at the prompt Press <return> to show content...; at other times, those keys' effects depend on the program you're running to display the message part. At those times, you should use the "quit" command that the particular program understands.

A Multipart Body

If the sample MIME message had just one part, you'd get another shell prompt (like $ or %) on your screen. But this is a multipart message, so MH will start to process the next part.

The next part of the sample message is audio. If you try to listen to it, what happens will depend on your setup, of course. The simplest case is that the sound plays after you press RETURN:

part 2     audio/basic                20K Hello from the author
Press <return> to show content...

...my dulcet tones float into your room...

Before MH describes a message part and prompts you to show it, it checks to see whether it's been configured to display that content-type on your setup. In a multipart/alternative message, MH will silently skip parts it can't display; if you keep track of the Part numbers it's showing, you'll notice that a part was skipped. In a multipart/mixed message, you'll get an error message like this:

mhn: don't know how to display content
     (content audio/basic in message 6, part 2)

You also can get an error from a program that MH calls to display content. For example, the third part of the sample message is a GIFformat picture of this book's cover. Most graphical setups that show images are based on the X Window System. An X program needs your DISPLAY environment variable. In the example below, mhn has started the xv program to show the GIF image. But xv quits because it can't find or open your display:

part 3     image/gif                  17K Book cover
Press <return> to show content...
/usr/local/bin/xv: Can't open display
Exit 1

Otherwise, a window will probably pop up on your screen. If you're using the xv program, you can quit by pointing to the window and pressing the `q' key. Or, if you click the third mouse button in that window, you'll get a menu window with quite a few choices -- including a quit button. After you quit xv, the image window should go away; then, the window where you were displaying the sample message should return to a shell prompt (like %). You're ready to remove the sample message or go on to other work.

For more information about what MH does to display MIME messages, and some tips for fixing problems, see the Section Reading MIME Messages.

By default, show shows all the parts of a message it can (actually, it calls mhn -show). You can also use mhn -part n, where n is the part number, to see one part of a message; the Section Showing Part of a MIME Message explains.

Sending MIME Mail

Composing a MIME message starts out the same way as a non-MIME message: type comp (or repl or forw), fill in the header, and enter the message body. You don't put any MIME-specific fields in the header; MH does that for you. In the body of a MIME message, you'll usually add directives that are converted into MIME body parts. Finally, to convert the directives into MIME parts, you run mhn (is that name starting to sound familiar? :-)) by going to the What now? prompt and typing edit mhn. If you almost always send MIME messages, you can automate that last step: see Section mhn Editing and automhnproc.

For this tour, let's compose a simple message. To do this on your own, you'll need to know something about the structure of a MIME message.

Here's what to type to make the sample message. Fill in the addresses you'd like to use. Type the directives in the body (on lines starting with #) as I've shown them. You can replace the italic text with whatever fits your system; if you have questions about what fits where, read the description below:

% comp
To: yourfriend
cc: you
Subject: Sample MIME message
--------
This test message has three more parts: enriched text,
a copy of my .mh_profile file, and my signature file.

The part ends at the first directive (the first line starting with #).
#<text/enriched [Sample enriched text]
This part has <italic>italic text</italic>, <bold>bold text</bold>,
and, if we're lucky, <bold><italic>bold italic text</italic></bold>.
#application/octet-stream [My MH profile] /home/jerry/.mh_profile
#text/plain [signature] /home/jerry/.signature

^D
--------
What now? e mhn

What now?

When you're done with the message body and the directives in it, typing edit mhn turns the directives into parts, reads the specified files, and checks for any other errors in the draft. When mhn is done, you'll get another What now? prompt; you can send the draft, list it, or any of the usual choices. If you list the draft, you may see the raw MIME-encoded message (if you need a reminder of an encoded multipart draft, look at the Example Sample multipart message, encoded). Or if you list it and your lproc: has been set to show, you'll see the message as the recipient should see it.

What if you type edit mhn and get an error? Start a text editor from the What now? prompt, edit the directives and save the draft, then use edit mhn again. On the other hand, if you want to edit the draft after you've run mhn with no errors, the draft will have been encoded; you'll need to recover the original draft with the directives.

Let's take a closer look at the message body and the directives it gave mhn. The message body starts with a plain text part. The part doesn't start with a directive, so mhn automatically makes its content-type text/plain. Each part ends at the next directive.

A directive tells mhn to start a new body part. Each directive starts with the character #. You can split a long directive onto more than one line by putting a backslash (\) at the end of the continued line.

The list in the following Table shows the most common directives. If you want to send one of the items in the first column, use a directive like the one shown in the second column. The second column starts with the syntax of the directive, then shows an example. To keep the table simple, I've only listed commonly-used features. Also, of course, the short explanations in the "What's in the Part" column may not give you enough information to understand completely. The Section Composing and Sending MIME Messages has lots of information and several more examples.

Table: Examples of mhn directives

Data (usually text) you enter on lines after the directive: #<

#<type/subtype [description]
lines of text

Example:

#<text/plain [Overview of this message]
This message has three parts.
The first part is blah, blah, blah...

Location of external data that recipient will get by FTP, etc.: #@

#@type/subtype [description] external-parameters

Example:

#@image/gif [Charlie Jones] \
access-type=anon-ftp; name="chuck_jones.gif"; \
directory="pub/staff_pix"; site="ftp.foo.bar"

An existing MH message of yours: #forw

#forw +folder message(s)

Example:

#forw +meetings 38

Data from a file to copy into the message: # ... filename

#type/subtype [description] filename

Example:

#application/postscript [Chapter 5] /doc/nutshell/MHxmh/ch05.ps

A multipart message (not required for multipart/mixed unless you're creating subparts): #begin ... #end

#begin alternative-or- parallel-or-whatever
put the subparts here
#end

Example:

#begin alternative
#<text/plain [Party invitation]
This is the plain-text version
#<text/enriched [Party invitation]
This is the <bold>enriched-text</bold> version
#application/postscript [Party invitation] \ 
/u/leah/invite.ps
#end

In all of the directives, the [description] is optional.

The exmh MH front-end (intoduced in this Chapter) handles message composition in a different way. It only runs on the X Window System; mhn works anywhere.

mhn Can Also Do...

This tour is only a brief introduction to the MIME support in MH. The mhn utility can also:

Adapt to the capabilities of each terminal and workstation you use. (Profiles that mhn Reads, Making an MHN Profile.)
Fetch external body parts -- by FTP, from a mail server, or from a local cache. (External Parts, Getting External Body Parts by FTP: mhn-access-ftp.)
Split long messages into parts before they're sent (Partial Messages) and put the parts together again (Partial Messages).
Store external body parts in a local cache so other users won't need to fetch them (Cached Contents).
Send messages with a checksum so the recipient can tell that the message wasn't corrupted (Adding an Integrity Check).
Control the way that directives (Table Examples of mhn directives) are handled as you compose a message. (Also see the Section Composing Content: mhn-compose-.)
Handle many character sets. (Displaying Other Character Sets: mhn-charset-.)

And more.

[Table of Contents] [Index] [Previous: Cleanup: rmm] [Next: The -help Switches]

Last change $Date: 1996/06/06 15:14:50 $

This file is from the third edition of the book MH & xmh: Email for Users & Programmers, ISBN 1-56592-093-7, by Jerry Peek. Copyright © 1991, 1992, 1995 by O'Reilly & Associates, Inc. This file is freely-available; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. For more information, see the file copying.htm.

Suggestions are welcome: Jerry Peek <jpeek@jpeek.com>