# Using MIME

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?

If you use nmh, you have MIME support. If you use MH, 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 MIME Configuration 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 MIME Configuration 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.

In nmh version 1.0 and above, mhn has been split into several smaller commands that each do one operation.

Let's use mhn to list the contents of the sample MIME message you got in the Section Sending Some Mail: comp, send. The mhn -list switch lists the contents of the current message or of the messages you name on its command line. If you're using nmh-1.0 or above, use mhlist instead of mhn -list:

        % mhn -list 6
         msg part  type/subtype              size description
           6       multipart/mixed            52K
             1     multipart/alternative     1510
             1.1   text/enriched              633 Introduction in enriched text
             1.2   text/plain                 529 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 and mhlist.

## 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, of course. (Under MH and nmh before version 1.0, "the right thing" is to give the message to mhn -show. In nmh 1.0 and above, the message is handed to mhshow. But you don't need to worry about that.)

To find out what your system will do, start by giving yourself a sample MIME message provided by this book. First use your browser's Save As command to save examples/mh-mime-sample into /tmp. Then copy it into your inbox with the command:

        % cp /tmp/mh-mime-sample `mhpath new +inbox`

Be sure to use backquotes (```), not single quotes (`'`).)

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@ics.uci.edu (Sample MH/MIME message server)
        Subject: Sample MIME message for online MH book

        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 skip `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, you'll probably see 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              633 Introduction in enriched text
        Press <return> to show content...

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

Welcome to MIME mail!

        This is a sample MIME message for the online edition of the MH book.
        The original is on the Web at: http://www.oreilly.com/freebooks/mh/
        This version came from:
        http://rand-mh.sourceforge.net/book/examples/mh-mime-sample.

        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 GIF-format 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 or mhshow). You can also use mhn -part `n` (or mhshow -part `n` in nmh version 1.0 and above), 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` -- or, if you use nmh, you can type `mime` instead. Then you'll have a MIME draft that's ready to send.

If you almost always send MIME messages, you can automate that last step: see the Section Building MIME Drafts Automatically.

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?

If you're using nmh, you can type `mime` instead of `e mhn`.

When you're done with the message body and the directives in it, typing edit mhn (or, in nmh, typing `mime`) turns the directives into parts, reads the specified files, and checks for any other errors in the draft. When MIME processing 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 or mime and get an error? Start a text editor from the `What now?` prompt, edit the directives and save the draft, then use edit mhn or mime 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 (under MH and nmh before version 0.21) or mhbuild (in nmh-0.21+). The message body starts with a plain text part. The part doesn't start with a directive, so its content-type automatically becomes text/plain. Each part ends at the next directive.

A directive tells mhn or mhbuild 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 MIME Draft 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. Note that -- in MH 6.8.3, 6.8.4 (others?) and nmh before version 0.22 -- the `[description]` is ignored after a `#forw` directive. This is a bug. So, also, when you use repl -mime to include a copy of the original message in your reply, you won't see a `Content-Description:` header field with the directive text `[original message]`.

The exmh MH front-end (see the exmh introduction) handles message composition in a different way. It only runs on the X Window System. mhn and mhbuild, though, work anywhere.

## Other MIME Operations

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

- Adapt to the capabilities of each terminal and workstation you use. (MIME Profiles, Making a MIME Profile.)
- Fetch external body parts -- by FTP, from a mail server, or from a local cache. (External Parts, Getting External Body Parts by 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 MIME Draft Directives) are handled as you compose a message. (Also see the Section Composing MIME Content.)
- Handle many character sets. (Displaying Other Character Sets.)

And more.