% Run me through LaTeX; see also the accompanying file tutorial.sty.
% $Header: /sparc/users/jsweet/notes/mime/tutorial/mhn-tutorial.tex,v 0.4 93/03/17 02:05:56 jsweet Rel $

\documentstyle[12pt,twoside,tutorial]{article}
\makeindex
\begin{document}

\thispagestyle{empty}

\begin{center}
{\Large\bf A Multi-Media E-Mail Tutorial With MH}\\[\baselineskip]

Jerry Sweet {\tt <jsweet@irvine.com>}
\\[5\baselineskip]


{\sc Abstract}
\end{center}
\begin{quote}
This tutorial document introduces multi-media e-mail facilities to MH users.
In particular, this tutorial discusses how to read and to send
multi-media e-mail messages using MH\@.
The goals are to provide enough information to prepare readers of this
tutorial to customize their multi-media e-mail environments,
and to encourage readers to tackle the manual page for {\tt mhn},
the MH program that handles multi-media messages.
\end{quote}

\vspace{15\baselineskip}

\begin{center}
{\footnotesize{\verb|$Id: mhn-tutorial.tex,v 0.4 93/03/17 02:05:56 jsweet Rel $|}}
\end{center}


\newpage
\tableofcontents
\newpage

\section{Scope}

This document assumes that you have knowledge of UNIX and of MH, although
not necessarily of MIME (Multipurpose Internet Mail Extensions),
the Internet multi-media e-mail specifications.

A few simple ways to use MH to compose and to read multi-media e-mail
are presented.  It's assumed that you have a pre-configured MH mail
system with reasonable defaults.

Skip to the end of this document for some references to books and to
papers supplied with the MH software distribution that may be of some
help to you if you're unfamiliar with MH\@.


\section{Introduction}

Most of MH's multi-media-related functions are implemented in one
program, {\tt mhn}.  {\tt Mhn} performs four functions: message
composition, message display, message scanning, and message
decomposition.

Using {\tt mhn}, you can create and read e-mail messages containing
these things:
\begin{brieflist}
\item images
\item sounds
\item tar files
\item PostScript
\item pointers to FTPable\footnote{FTP: {\it v.,} to transfer a file 
        from a remote Internet host; 
        {\it n.,} 1.\ the Internet file transfer protocol; 
        2.\ the program by which a user performs file transfers via 
        the file transfer protocol;
        --able, {\it adj.,} capable of being transferrable via FTP.} 
        files
\item other stuff
\end{brieflist}

Certain hardware and software resources are needed in conjunction
with {\tt mhn} to make images and sounds from multi-media messages
available to you.
An X terminal makes it possible to view certain standard image types.
A workstation with audio capabilities makes it possible to hear
certain audio formats.
(Unfortunately, as of this writing, the X Window System specification
doesn't accommodate audio data, and only certain types of workstations
will play sounds for you.)

If you don't have these resources, well...you're probably not going to
have quite as much fun, but you can still use some of the most useful
multi-media features of MH.

You'll also need correspondents who can send and receive multi-media
\mbox{e-mail} in MIME format.  Anyone using MH 6.8 will do; even if 
you're just corresponding with yourself for test purposes.

MH version 6.8 was the first major release of MH to contain the MIME
extensions.
To find out whether your version of MH supports MIME, try running this
command:
\begin{quote}
{\tt mhn -help}
\end{quote}
If you see the {\tt mhn} help message, then you've got multi-media MH.
The help message should look something like this:
\begin{verbatim}
syntax: mhn [+folder] [msgs] [switches]
  switches are:
  -[no]auto
  -[no]ebcdicsafe
  -(form) formfile
  -[no]headers
  -[no]list
  -part number
  -[no]realsize
  -[no]rfc934mode
  -[no]serialonly
  -[no]show
  -[no]store
  -type content
  -[no]verbose
  -(help)
\end{verbatim}

If the {\tt mhn} command isn't available, then you'll see something
like this:
\begin{verbatim}
mhn: Command not found.
\end{verbatim}

In this tutorial, we're going to dive right into some examples, and
save the more detailed explanations for later.



\section{Simple Multi-Media Message Composition}

Here's an example of how you can compose a multi-media e-mail message.
The prompts and other MH program outputs are shown in {\tt typewriter} style;
your responses are shown in {\sl slanted} style.

\begin{flushleft}
\footnotesize
{\tt
\% {\sl comp} \\
To: {\sl ghb@white-house.gov}\\
Cc:\\
Subject: {\sl you're sacked!}\\
-------
}
\end{flushleft}
\vspace*{-\baselineskip}
{\footnotesize\sl
As you know, your contract of employment with us contained
an ``at will'' clause.  We have chosen to exercise that clause.
A security guard shall escort you to your desk, from which 
you may obtain your personal effects, and then escort you
from the premises.  A severance check shall be mailed to you
shortly.  Good day to you, sir.
}
\vspace{-0.5\baselineskip}
\begin{flushleft}
{\footnotesize\sl
\#audio/basic\ \ \ /goodies/sounds/rude-noise.au\\[0.5\baselineskip]
\#image/gif\ \ \ /goodies/images/rude-gesture.gif\\[\baselineskip]

\verb+^+D\\[\baselineskip]
}
{\footnotesize\tt What now?} {\footnotesize\sl edit mhn -list}
\end{flushleft}
\vspace*{-\baselineskip}
\begin{verbatim}
msg part  type/subtype               size description                         
  1        multipart/mixed            45K
    1      text/plain                 332
    2      audio/basic               8961
    3      image/gif                  36K
\end{verbatim}
\vspace*{-\baselineskip}
\begin{flushleft}
\footnotesize
{\tt What now?} {\sl send}
\end{flushleft}

As you can see from the output of the {\tt edit mhn} command, this
message has three parts:

\begin{briefenum}
\item a plain text part (the introductory paragraph);
\item an audio part inserted via the line beginning with {\tt \#audio/basic};
\item an image part inserted via the line beginning with {\tt \#image/gif}.
\end{briefenum}

In the interest of good taste, we shan't show you the image, nor play
for you the audio.  The names of the files should be self-explanatory.

The lines beginning with hash marks ({\tt \#}) in the message above are
examples of {\tt mhn}'s special directives.

Each ``{\tt \#}'' directive indicates a message part, and identifies
what type of information is to be carried in that part.  For example,
a message part containing audio data might have either type {\tt
audio/basic} or type {\tt audio/x-next}.  (These are both {\tt audio}
types; the {\it subtypes} are {\tt basic} and {\tt x-next}.)
A list of the pre-defined types and subtypes is given in
appendix~\ref{mimetypes}.

By using variants of the directives shown above, it's possible to tell
{\tt mhn} to collect into a message the audio or image data produced
by running a program.

At the {\tt What Now?} prompt, when you typed the command {\tt edit
mhn}, a new draft was created, replacing your previous draft.
Thereafter, if instead of typing {\tt send}, you had typed {\tt edit
emacs}, you would see MIME constructs in place of your original {\tt
mhn} directives, looking something like this:

\newpage

\begin{verbatim}
To: ghb@white-house.gov
Subject: you're sacked!
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"

As you know, your contract of employment with us contained
... [remainder of introductory paragraph omitted]

------- =_aaaaaaaaaa0
Content-Type: audio/basic
Content-Transfer-Encoding: base64

LnNuZAAAACgAAAk/AAAAAQAAH0AAAAABdGVycmllciBiYXJrAAAAAFdSUVVdcuXc3OLtdmFbWV5r
897Z2d/tfGliYWVu8eHXz8vL0ONdS0ZGTVhq49PMy9X4W05NT1VfftnKyMvQ3vlhTktbeFhIQ0t8
... [ many lines of encoded audio data omitted ]

------- =_aaaaaaaaaa0
Content-Type: image/gif
Content-Transfer-Encoding: base64

R0lGODdhgALgAcMAAAAAAIAAAACAAICAAAAAgIAAgACAgICAgMDAwP8AAAD/AP//AAAA//8A/wD/
... [ many lines of encoded image data omitted ]

------- =_aaaaaaaaaa0--
\end{verbatim}

Looks horrendous, doesn't it?  You may be relieved to know that this
tutorial doesn't explain all the gory details of the MIME format per
se, and you don't really have to know them to use MH's multi-media
features, because {\tt mhn} shields you.  If you're interested, there
are references to documents that cover MIME at the end of the
tutorial.

If you want to make corrections to a draft already processed by {\tt
edit mhn}, you can recover the original draft, containing your
original {\tt mhn} directives, from a file that {\tt mhn} names as
{\tt ,}{\it msg}{.orig}, where {\it msg} is whatever the designation
of the original draft was.  Example: {\tt \~{}/Mail/drafts/,1.orig}.

Using {\tt mhn}'s directives, you don't need a bit-mapped display or a
digital audio device to compose a multi-media e-mail message.  But you
do need a graphical display to view image parts and you do need a
speaker to listen to audio parts.  There are other types of useful
multi-media components that can be displayed and manipulated with
nothing more than a plain old fixed-font 24$\times$80 ASCII terminal.




\section{Multi-Media E-Mail Examples}
\label{examples}

This section gives examples of how more complicated kinds of
multi-media e-mail messages can be created.

Your system administrator has probably set up some reasonable {\tt
mhn} defaults, but if you run into problems when trying to display the
results of these examples, you may need to do some additional setup
work for yourself.  Section \ref{setup} discusses setting up your
profile for {\tt mhn}.


\subsection{Weather Maps}
\label{weather}

Here's a fun thing I did with {\tt mhn}: I wrote a program, {\tt
mail.weather.ext}, which mails out a weather map image of the
continental United States, a key to the weather symbols, and a
corresponding satellite image.

The GIF files\footnote{GIF is a popular interchange format for graphical
data.  GIF is also a service mark of CompuServe, Inc.} containing these
images are obtained freely from an Internet site.  

I view these messages on a Sun IPC workstation with a 17-inch color
display.  Other persons in offices next to mine can view the images on
HP 9000/700 series workstations with 19-inch color displays or on
their monochrome X terminals---although the maps don't look quite as
nice in monochrome.

By using the UNIX {\tt cron} facility, I've arranged for the maps to
be mailed out every weekday morning at 10:30.  This is the line in
my {\tt crontab} that does it:

\begin{verbatim}
30 10 * * 1-5 /home/jsweet/bin/mail.weather.ext weather-fiends \
                >/dev/null 2>&1
\end{verbatim}

Below is an example of an {\tt mhn} draft template produced
automatically by {\tt mail.weather.ext}.  The template contains
two major pieces: an explanation, rendered in {\it richtext} format
(we'll get to that by and by), of the images in the message, and a
collection of {\it external body parts} that refer to GIF-format
image files residing on a remote host.

\begin{verbatim}
To: weather-fiends
Subject: weather report: 02/25 0900 GMT
--------
#<text/richtext [explanation]
<paragraph>You may FTP three images:</paragraph>
<paragraph><indent><fixed>
SA022509.GIF: surface analysis at 0900 GMT 02/25<nl>
WXKEY.GIF:    map symbol key<nl>
CI022508.GIF: satellite photo at 0800 GMT 02/25
</fixed></indent></paragraph>
#
#begin [weather report: 02/25 0900 GMT] parallel
#@image/gif [surface analysis + radar summary] \
        access-type=anon-ftp; \
        name="SA022509.GIF"; \
        directory="wx"; \
        site="vmd.cso.uiuc.edu"; \
        expiration="26 Feb 93 09:00:00 GMT"; \
        size=50000
#@image/gif [weather map symbol key] \
        access-type=anon-ftp; \
        name="WXKEY.GIF"; \
        directory="wx"; \
        site="vmd.cso.uiuc.edu"; \
        size=18867
#@image/gif [satellite photo] \
        access-type=anon-ftp; \
        name="CI022508.GIF"; \
        directory="wx"; \
        site="vmd.cso.uiuc.edu"; \
        expiration="26 Feb 93 09:00:00 GMT"; \
        size=170000
#end
\end{verbatim}

As you may have noted from the {\tt expiration} attributes in the
example above, these particular weather image files are long gone.

The structure of the message appears as follows, as shown using the
command \mbox{{\tt mhn -list}}, with some blank lines and indentation
added for slightly easier reading:

\begin{verbatim}
msg part  type/subtype              size description                         
 1        multipart/mixed           1541

    1     text/richtext              288 explanation                         

    2     multipart/parallel         939 weather report: 02/25 0900 GMT      

      2.1  message/external-body      78
           image/gif                     surface analysis + radar summary    

      2.2  message/external-body      68
           image/gif                     weather map symbol key              

      2.3  message/external-body      61
           image/gif                     satellite photo                     
\end{verbatim}

When this message is shown via the MH command {\tt show}, message part~1,
a {\it richtext} part giving an explanation of the contents of
the message, is displayed.

Then a series of prompts is provided for retrieving the {\it external
bodies} named in part 2.  The retrieval is accomplished
semi-automatically, using anonymous FTP, from Internet host {\tt
vmd.cso.uiu.edu}, where the weather images are stored.

\begin{verbatim}
Date:    Thu, 25 Feb 1993 01:41:13 PST
To:      jsweet@irvine.com

From:    Jerry Sweet <jsweet@irvine.com>
Subject: weather report: 02/25 0900 GMT

Mime-Version: 1.0


You may FTP three images: 


        SA022509.GIF: surface analysis at 0900 GMT 02/25
        WXKEY.GIF:    map symbol key
        CI022508.GIF: satellite photo at 0800 GMT 02/25 


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

Retrieve SA022509.GIF (content 2.1)
    using anonymous FTP from site vmd.cso.uiuc.edu (50000 octets)? y
Make cached, publicly-accessible copy? y

Retrieve WXKEY.GIF (content 2.2)
    using anonymous FTP from site vmd.cso.uiuc.edu (18867 octets)? y
Make cached, publicly-accessible copy? y

Retrieve CI022508.GIF (content 2.3)
    using anonymous FTP from site vmd.cso.uiuc.edu (170000 octets)? y
Make cached, publicly-accessible copy? y
\end{verbatim}

As the different external body parts are retrieved, the images pop up
on the display (assuming that you have a graphical display).  In my
configuration, the {\tt xv} application is given the task of showing
the retrieved images on my X Window System display.

The prompts regarding ``cached, publicly-accessible'' copies have to
do with the caching feature of {\tt mhn} which may or may not be
enabled at your site.  You can enable caching for yourself with an
appropriate {\tt mhn} profile entry, discussed in section~\ref{setup}.
If someone else at your site has already read the same message, and
has made cached, publicly-accessible copies of the images, then you
are likely to see prompts like this one instead:

\begin{verbatim}
Use cached copy /r/mhn-cache/<24860.731615403.1@fester.irvine.com> 
        of size 25551 octets (content 2.1)?
\end{verbatim}

In this example, the cache directory is {\tt /r/mhn-cache/}.  The
horrible-looking file name surrounded by {\tt <}angle brackets{\tt >}
corresponds to the unique {\it Content-ID} of the external body part.
The most useful bit of information is the part number, {\tt 2.1} in
this example.  From the previous listing of the message structure,
you can see that part {\tt 2.1} refers to the ``surface analysis + radar summary.''

If caching isn't enabled, then the relevant prompts don't appear; the
external body parts have to be retrieved from the remote host every
time you want to see them, and the external body parts are deleted as
soon as you're done with viewing them.

The {\it richtext} part of the weather draft message above was this:

\begin{verbatim}
#<text/richtext [explanation]
<paragraph>You may FTP three images:</paragraph>
<paragraph><indent><fixed>
SA022509.GIF: surface analysis at 0900 GMT 02/25<nl>
WXKEY.GIF:    map symbol key<nl>
CI022508.GIF: satellite photo at 0800 GMT 02/25
</fixed></indent></paragraph>
#
\end{verbatim}

As you may have guessed, the {\it richtext} body part consists of text
with some simple format commands, such as {\tt <fixed>} and {\tt
<indent>}.  You can see for yourself above what effects the richtext
formatting commands have.

The richtext area of the message is delimited at the beginning by the
{\tt mhn} directive {\tt \#<text/richtext} and at the end by {\tt \#}
alone on a line.  In contrast, a text area of a message draft not
specifically delimited by {\tt mhn} directives is assumed to be of
type {\tt text/plain}.

The {\it description} of the richtext part is given in square
brackets: {\tt [explanation]}.  The description shows up when the
contents of a MIME message are listed via the {\tt mhn -list} option.

A summary of richtext is given in appendix~\ref{richtext}.

The weather map image retrieval information begins with this
directive:

\begin{verbatim}
#begin [weather report: 02/25 0900 GMT] parallel
\end{verbatim}

The {\tt \#begin parallel} directive (ignoring the description in
square brackets shown above) allows all three images that follow to be
displayed at the same time.  Without the {\tt \#begin parallel}
directive, each image would be shown one at a time, and you would have
to quit the image display application ({\tt xv} in my case) each time
in order to see the next image.

The scope of the {\tt \#begin} directive is ended, naturally enough,
with an {\tt \#end} directive.

As you probably guessed by reading the retrieval prompts above, the
weather map images themselves are not included in the message.
Instead, the message contains references to files available via
anonymous FTP on a remote host, in this case, {\tt vmd.cso.uiuc.edu}.

One of the external file references is this:

\begin{verbatim}
#@image/gif [surface analysis + radar summary] \
        access-type=anon-ftp; \
        name="SA022509.GIF"; \
        directory="wx"; \
        site="vmd.cso.uiuc.edu"; \
        expiration="26 Feb 93 09:00:00 GMT"; \
        size=50000
\end{verbatim}

This directive contains these pieces:
\begin{enumerate}
\item   The external part indicator, the ``{\tt @}'' character.

\item   The {\it type}, {\tt image/gif}, specifying a part containing
GIF format data.

\item   The {\it description}, given in square brackets, describing
the content as ``surface analysis + radar summary.''

\item   A set of {\it attribute}{\tt =}{\it value} pairs:
        \begin{description}
        \item[{\tt access-type=anon-ftp}] specifies that
                the file is to be retrieved via anonymous FTP.

        \item[{\tt name="SA022509.GIF"}] specifies the
                name of the file on the remote Internet host.
                The name happens to refer to the month (02), day (25)
                and hour (09, Greenwich Mean Time) when the weather
                data were assembled to create the image.

        \item[{\tt directory="wx"}] specifies the name of
                the directory in which the file resides.

        \item[{\tt site="vmd.cso.uiuc.edu"}] specifies the
                name of the remote Internet host.  This particular
                host resides with the Department of Computer Science
                at the University of Illinois, Urbana-Champaign.

        \item[{\tt expiration="26 Feb 93 09:00:00 GMT"}] an optional
                attribute, specifies the date and time after which the 
                file isn't expected to be available.  At present, MH 
                ignores this field, but other MIME-capable user agents
                might not.

        \item[{\tt size=50000}] also an optional attribute, is an 
                estimate of the file size in bytes, provided for 
                informational purposes only.
        \end{description}
\end{enumerate}

More is said about external body parts in section~\ref{external}.


\subsection{A Periodical}

Dr.\ Marshall T.~Rose does a useful thing with multi-media e-mail.  He
mails out each issue of his SNMP-related newsletter, {\it The Simple
Times}, in these formats:
\begin{enumerate}
\item in a PostScript form,
with beautiful typesetting and a two-column page layout, suitable for
printing on a laser printer;

\item in {\it richtext} form (to be explained later on),
suitable for display on a mildly intelligent ASCII
terminal;

\item in a plain text form.
\end{enumerate}
When you subscribe to {\it The Simple Times}, you specify in which
form you want to receive the newsletter.

(SNMP is the Simple Network Management Protocol, having naught
to do with MIME or MH per se.)

The process by which Dr.\ Rose creates an issue of {\it The Simple
Times} begins with documents in \LaTeX{} markup language format.  A
filter program is applied to strip the \LaTeX{} constructs to produce
plain ASCII text files. Another filter program is applied to convert
the \LaTeX{} constructs into richtext constructs.  (The plain text and
richtext files may require some additional editing to look
reasonable.)  The PostScript version is the result of applying
\LaTeX{} to the original version of the document followed by an
appropriate PostScript-producing post-processor, such as {\tt dvips}.

Dr.\ Rose was kind enough to provide this {\tt mhn} draft template as
an example of how he created the plain text MIME version of Volume 1,
Number 4 of {\it The Simple Times}:

\begin{verbatim}
Reply-to: The Simple Times <st-editorial@simple-times.org>
To:       The Simple Times Subscribers <st-editorial@simple-times.org>
Dcc:      st-mime-subscribers
Fcc:      outbox, simple-times/1.4, /var/lists/simple-times/mime
Subject:  The Simple Times, volume 1, number 4

#begin      [The Simple Times]
#begin      [Issue Information]
Content-Description: Masthead

The Simple Times(tm)

------------------------------------------------------------------------
The Bi-Monthly Newsletter of SNMP Technology, Comment, and Events   (sm)
Volume 1, Number 4                               September/October, 1992
------------------------------------------------------------------------
#text/plain [READ-ME]                   ../../lib/mime/read-me.txt
#text/plain [Disclaimer]                ../../lib/mime/disclaimer.txt
#end
#begin      [Issue Contents]
#text/plain [Technical Article]         technical.txt
#text/plain [Industry Comment]          comment.txt
#begin      [Featured Columns]
#text/plain [Applications and Directions]applications.txt
#text/plain [Ask Dr. SNMP]              faq.txt
#text/plain [Security and Protocols]    security.txt
#text/plain [Standards]                 standards.txt
#text/plain [Working Group Synopses]    synopses.txt
#end
#begin      [Miscellany]
#text/plain [Announcements]             announcements.txt
#text/plain [Recent Publications]       publications.txt
#text/plain [Activities Calendar]       calendar.txt
#end
#end
#begin      [Administrative Information]
#text/plain [Publication Information]   ../../lib/mime/publication.txt
#text/plain [Submissions]               ../../lib/mime/submissions.txt
#text/plain [Subscriptions Information] ../../lib/mime/subscriptions.txt
#end
#end
\end{verbatim}

The structure of the message appears as follows, as shown using
\mbox{{\tt mhn -list}}, with some blank lines and indentation added
for slightly easier reading:

\begin{verbatim}
msg part  type/subtype          size description

  1        multipart/mixed       93K The Simple Times                 

    1      multipart/mixed      1682 Issue Information                
      1.1   text/plain           314 Masthead                         
      1.2   text/plain           377 READ-ME                          
      1.3   text/plain           668 Disclaimer                       

    2      multipart/mixed       88K Issue Contents                   
      2.1   text/plain           16K Technical Article                
      2.2   text/plain          7864 Industry Comment                 
 
      2.3   multipart/mixed      60K Featured Columns                 
        2.3.1 text/plain        7223 Applications and Directions              
        2.3.2 text/plain        7568 Ask Dr. SNMP                             
        2.3.3 text/plain        7820 Security and Protocols           
        2.3.4 text/plain         14K Standards                        
        2.3.5 text/plain         22K Working Group Synopses           
 
      2.4   multipart/mixed     3172 Miscellany                       
        2.4.1 text/plain        2345 Announcements                            
        2.4.2 text/plain         118 Recent Publications                      
        2.4.3 text/plain         361 Activities Calendar                      

    3      multipart/mixed      3077 Administrative Information       
      3.1   text/plain          1032 Publication Information          
      3.2   text/plain          1155 Submissions                              
      3.3   text/plain           534 Subscriptions Information        
\end{verbatim}

The richtext version has the same structure as the plain text version,
except that richtext-format files are used in place of the plain text
files.

Because the PostScript version is one large file, suitable for
printing, the PostScript message doesn't use the full structure shown
above for the plain text version; just a single part of type {\tt
application/postscript} is specified:

\begin{verbatim}
Reply-to: The Simple Times <st-editorial@simple-times.org>
To:       The Simple Times Subscribers <st-editorial@simple-times.org>
Dcc:      st-postscript-subscribers
Fcc:      outbox, simple-times/1.4, /var/lists/simple-times/postscript
Subject:  The Simple Times, volume 1, number 4

#application/postscript [The Simple Times] stv1n4.ps
\end{verbatim}



\section{Setting Up For MIME}
\label{setup}

Your system administrator has probably set up some reasonable {\tt
mhn} defaults for composing and showing multi-media e-mail messages.
These defaults may or may not be adequate for the kinds of multi-media
e-mail messages that you receive or compose.

To compose multi-media e-mail messages using pre-existing files
requires no special setup; it's displaying them that definitely
requires setup.

When you display a message by using {\tt show} or {\tt mhn -show}, you
might see error messages like this one:

\begin{verbatim}
mhn: don't know how to display content
     (content video/mpeg in message /home/jsweet/Mail/drafts/15)
\end{verbatim}

A ``don't know how to display'' error message like the one above means
that {\tt mhn} hasn't been informed how to display a particular type
of message part.  This problem may or may not be easy to fix,
depending on whether you have a program around that can display the
particular type of data involved.  

{\tt Mhn} looks in several places for information about how to compose
or to display multi-media message parts.  Your {\tt .mh\_profile} is
one such place.

The {\tt .mh\_profile} file in your home directory exists to permit
customizations of the behaviors of MH programs.  Many MH users never
bother changing the defaults.  However, for using {\tt mhn}, changing
the {\tt .mh\_profile} is almost unavoidable.  However, it may not be
necessary to change your {\tt .mh\_profile} if you're happy with the
system defaults.

By using an appropriate display program in an appropriate profile
entry, {\tt mhn} can be informed how to run a program to display a
particular type of message part.

For example, {\tt mhn} can be instructed to use the {\tt xv} program
to display {\tt image/gif} data on an X Window System display.  If you
don't have the {\tt xv} program, it's certainly possible to obtain it
and to compile it for yourself; it's freely available via anonymous
FTP from a number of Internet sites.  However, you may have some other
program on your system capable of displaying GIF files, in which case
you could use that program instead of {\tt xv}.

Profile entries can be overridden in message drafts by using
appropriate program invocations in the place of file names
in the {\tt mhn} directives.

Information about how to obtain various programs that can display
multi-media message parts can be found in appendix~\ref{resources}.
It may also be useful to track down a highly informative document in
the MH source tree, {\tt miscellany/multimedia/READ-ME}.

\subsection{A Simple Setup}

For a plain 24$\times$80 ASCII character terminal, or a plain shell
window with no special X Window System display configuration, here are
some reasonable {\tt mhn}-related lines to place in your {\tt
\~{}/.mh\_profile} file:

\begin{verbatim}
Comment-100: ==================================================
             Global mhn-related parameters:
             ==================================================
lproc:                            show
mhnproc:                          mhn
mhn:                              -list -nomoreproc
mhn-storage:                      /usr/tmp
Comment-200: ==================================================
             File name templates for storing certain types of
             message parts:
             ==================================================
mhn-store-text:                   %m%P.txt
mhn-store-application/PostScript: %m%P.ps
Comment-300: ==================================================
             Shell commands for mhn to invoke when mhn
             encounters certain types of message parts:
             ==================================================
mhn-show-text/plain:              more '%F'
mhn-show-message/rfc822:          show -file '%F'
mhn-show-text/richtext:           richtext -p '%F'
\end{verbatim}


Another profile item that you may find useful is this:
\begin{verbatim}
Comment-400: ==================================================
             Instructions to whatnow(1):
             ==================================================
automhnproc:                      mhn
\end{verbatim}

Each line beginning with {\tt mhn-} has meaning for a different {\tt mhn}
function:
\begin{brieflist}
\item {\tt mhn-compose-} is the prefix for operations to apply when composing messages;
\item {\tt mhn-show-} is the prefix for operations to apply when displaying messages;
\item {\tt mhn-store-} is the prefix for operations to apply when storing messages.
\end{brieflist}

What follows any of these {\tt mhn} function prefixes is a {\it type}.
When {\tt mhn} finds a message part of a particular type, {\tt mhn}
looks for profile entries relevant to that type.  For example, to display
something of type {\tt text/richtext}, {\tt mhn} looks for the profile
entry {\tt mhn-show-text/richtext}.

The list of pre-defined types can be found in appendix~\ref{mimetypes}.

Here is an explanation of each line of the profile:

\begin{comdesc}
\item[lproc:\ show]     ---specifies that the {\tt show} program is to be
        used by {\tt whatnow} when {\tt list} is specified at the 
        ``{\tt What now?}'' prompt.

\item[mhnproc:\ mhn]    ---specifies that {\tt mhn} is to be used by MH programs
        for displaying MIME messages.
        In general, {\tt show} automatically uses {\tt mhn -show}.

\item[mhn:\ -list -nomoreproc]  ---specifies that {\tt mhn} is always to
        list the contents of a MIME message whenever it's invoked by
        {\tt show} or in any other context, and that a pager program (actually,
        an {\em additional} pager program), such as {\tt more}, shouldn't
        be invoked.

\item[mhn-storage:\ /usr/tmp]   ---specifies that when {\tt mhn -store} is
        used, the resulting files (created by extracting the individual message 
        parts from the message) are to be deposited in the {\tt /usr/tmp}
        directory.  You might prefer to specify a directory under your own
        home directory instead.

\item[mhn-store-text:\ \%m\%P.txt]      ---specifies that when {\tt mhn -store}
        is used, and {\tt mhn} finds a message content of type {\tt text}, that the
        file name should have the form 
        {\it message-number}{\tt .}{\it part-number}{\tt .txt}.
        
\item[mhn-store-application/PostScript:\ \%m\%P.ps]     ---specifies that
        when {\tt mhn -store} is used, and {\tt mhn} finds a message part of
        type {\tt application/PostScript}, that the file name should have
        the form {\it message-number}{\tt .}{\it part-number}{\tt .ps}.

\item[mhn-show-text/plain:\ more '\%F'] ---specifies that when {\tt mhn -show}
        is used, and {\tt mhn} finds a message part
        specifically of type {\tt text/plain}, that the {\tt more}
        program should be used  to display that part.  

        The ``\%F'' escape code tells {\tt mhn} to store the text into
        a temporary file and then to give the name of the temporary file
        to the {\tt more} program.

        Some persons prefer the {\tt less} program to the {\tt more}
        program for showing plain text.

\item[mhn-show-message/rfc822:\ show -file '\%F']       ---specifies that
        when {\tt mhn -show} is used, and {\tt mhn} finds a message
        part of type {\tt message/rfc822}, that the {\tt show} program should
        be used to display it.

        The ``\%F'' escape code tells {\tt mhn} to store the message into
        a temporary file and then to give the name of the temporary file
        to the {\tt show} program.

\item[mhn-show-text/richtext:\ richtext -p '\%F']       ---specifies that when
        {\tt mhn -show} is used, and {\tt mhn} finds a message
        part of type {\tt text/richtext}, that the {\tt richtext} program
        should be used to display it.  

        The ``\%F'' escape code tells {\tt mhn} to store the text into
        a temporary file and then to give the name of the temporary file
        to the {\tt richtext} program.

        If the {\tt richtext} program isn't present on your system,
        you can try substituting {\tt rt2raw}.  (See appendix~\ref{resources}
        for information about how to obtain these programs.)

\item[automhnproc:\ mhn] ---tells whatnow(1) that drafts containing {\tt mhn}
        directives should be run through {\tt mhn} automatically, without
        waiting for the user to type {\tt edit mhn} at the ``{\tt What Now?}''
        prompt.
\end{comdesc}



\subsection{Setting Up For An X Window System Display}
\label{security}

For an X Window System display, it's better to create a separate {\tt
mhn}-specific profile in addition to your {\tt .mh\_profile}, and to
refer to that separate profile with the environment variable {\tt
\$MHN}\@.  This allows you to keep different profiles for displays with
different capabilities.

One simple way to set the MHN environment variable for different
displays is to use this command:

\begin{verbatim}
% setenv MHN ~/.mhn_profile.`hostname`
\end{verbatim}

This causes {\tt mhn} to look for its defaults in the named file.  The
\`{}{\tt hostname}\`{} part in backticks turns into the name of your
host.

If you're using an X terminal separate from your host, then you'll
need to use the name of the X terminal instead.

If it hasn't been done for you already, you need to initialize your
environment to use the X Window System.  Methods vary from system to
system, but might be as simple as typing this command:
\begin{verbatim}
% setenv DISPLAY `hostname`:0
\end{verbatim}
...or this:
\begin{verbatim}
% xinit
\end{verbatim}

If your host is named {\tt fungus}, and the {\tt \$MHN} variable is
set as shown in a previous example above, then you can define an {\tt
mhn} profile in your home directory named {\tt .mhn\_profile.fungus}.
The contents of that file might be specific to the console display of
a Sun SPARCstation IPC, designated as X Window System display {\tt
fungus:0}, and could look like this:

\begin{verbatim}
mhn-show-image: xv -geometry =-0+0 -imap -igeom =-0+0 '%f'
mhn-compose-audio/basic:         audiotool '%f' && raw2audio -F < '%f'
mhn-compose-audio/x-next:        audiotool '%f' && adpcm_enc < '%f'
mhn-show-audio/basic:            raw2audio 2>/dev/null | play
mhn-show-audio/x-next:           audiotool -p '%f'
mhn-show-application/PostScript: pageview '%F'
mhn-show-text/richtext:          richtext -p '%F'
mhn-show-video/mpeg:             mpeg_play -quiet -loop '%F'
mhn-cache:                       /r/mhn-cache
\end{verbatim}

The programs specific to the Sun SPARCstation in the example above are
the audio-related programs, {\tt raw2audio}, {\tt play},
{\tt adpcm\_enc}, and {\tt audiotool}; and the PostScript display
tool, {\tt pageview}.

Which audio programs to use and how to set up to use them is highly
dependent on the type of workstation you have.  An explanation is
given in appendix~\ref{audiosetup}.

Here is an explanation of each line in the previous {\tt mhn} profile:

\begin{comdesc}
\item[mhn-show-image:\ xv -geometry =-0+0 -imap -igeom =-0+0 '\%f']
        ---specifies that the {\tt xv} program with the specified options
        is to be used to display all message parts of type {\tt image}
        (including, for example, {\tt image/gif}).

        The ``\%f'' escape code tells {\tt mhn} to store the image
        data into a temporary file and to give the name of the temporary
        file to the {\tt xv} program.

\item[mhn-compose-audio/basic:\ audiotool '\%f' \&\& raw2audio -F < '\%f']
        ---specifies that the {\tt audiotool} program is to be used when
        a ``bare'' {\tt \#audio/basic} directive (without a filename)
        is encountered in a message draft.  The result is
        run through the {\tt raw2audio} program to strip off the
        audio header information.  (Note that these programs
        are specific to Sun SPARCstations.)

\item[mhn-compose-audio/x-next:\ audiotool '\%f' \&\& adpcm\_enc < '\%f']
        ---specifies that the {\tt audiotool} program is to be used when
        a ``bare'' {\tt \#audio/x-next} directive (without a filename)
        is encountered in a message draft.  The result is run through
        {\tt adpcm\_enc} program to convert the data into ADPCM format.
        (An explanation of {\tt adpcm\_enc} is given in 
        appendix~\ref{audiosetup}.  Note that these programs are specific
        to Sun SPARCstations.)

\item[mhn-show-audio/basic:\ raw2audio 2>/dev/null | play]
        ---specifies that when {\tt mhn -show} is used, and a
        message part of type {\tt audio/basic} is encountered,
        that the {\tt raw2audio} program is to be used to process
        the audio data.  Any diagnostic or error message are 
        redirected to the bit bucket.  The result is piped 
        into the {\tt play} program.

        {\tt Mhn} provides the audio data from the message part
        to {\tt raw2audio}'s standard input.

\item[mhn-show-audio/x-next:\ audiotool -p '\%f']
        ---specifies that when {\tt mhn -show} is used, and a
        message part of type {\tt audio/x-next} is encountered,
        that the {\tt audiotool} program is to be used to play
        the audio data.

        The ``\%f'' escape code tells {\tt mhn} to store the image
        data into a temporary file and to give the name of the temporary
        file to the {\tt audiotool} program.

\item[mhn-show-application/PostScript:\ pageview '\%F']
        ---specifies that when {\tt mhn -show} is used, and
        a message part of type {\tt application/PostScript} is
        encountered, that the {\tt pageview} program is to be used
        to display results of running the PostScript program.

        The ``\%F'' escape code tells {\tt mhn} to store the PostScript
        data into a temporary file and to give the name of the temporary
        file to the {\tt pageview} program.

        A publicly available program, GhostScript, aka {\tt gs},
        can be substituted.

        {\it Note that there are some security issues to consider when deciding
        to run PostScript processors automatically.}  It's possible for someone
        to encode a MIME message to do evil things to an unwary mail user.  

        PostScript is a big potential security hole.  One famous example is the 
        ``melting screen'' PostScript program, which destroys screens maintained by
        Display PostScript implementations.  For another example, PostScript
        can be used to change the password on some PostScript printers with
        previously undefined passwords, which denies the use of the printer
        until the printer's password can (somehow) be changed back.  Yet other
        Display PostScript implementations may allow file operations.

        The enumeration of these security holes is not to be interpreted as
        encouragement to exploit the holes.  They are mentioned only because
        they are well known.  Refer to books such as {\it Practical UNIX Security}
        and to news groups such as {\tt comp.security.misc} for general information
        about system security.

\item[mhn-show-text/richtext:\ richtext -p '\%F']
        ---specifies that when {\tt mhn -show} is used, and
        a message part of type {\tt text/richtext} is encountered,
        that the {\tt richtext} program is to be used to display
        the richtext data.

        The ``\%F'' escape code tells {\tt mhn} to store the richtext
        data into a temporary file and to give the name of the temporary
        file to the {\tt richtext} program.

\item[mhn-show-video/mpeg:\ mpeg\_play -quiet -loop '\%F']
        ---specifies that when {\tt mhn -show} is used, and
        a message part of type {\tt video/mpeg} is encountered, 
        that the {\tt mpeg\_play} program is to be used to 
        display the MPEG data.

        The ``\%F'' escape code tells {\tt mhn} to store the video data
        into a temporary file and to give the name of the temporary
        file to the {\tt mpeg\_play} program.

\item[mhn-cache:\ /r/mhn-cache]
        ---specifies in what directory to cache external body parts
        when the parts are retrieved from the remote host.
        (Note: not all MIME messages have the information necessary
        to cause {\tt mhn} to cache external body parts.  However,
        any MIME messages created with {\tt mhn} do have the
        necessary information.)
\end{comdesc}

As you may have guessed from the ``pipe'' symbols and other UNIX shell
metacharacters in the example above, {\tt mhn} invokes {\tt /bin/sh}
to interpret the commands.

The difference between ``\%F'' (upper case) and ``\%f'' (lower case)
elsewhere is that for ``\%F,'' {\tt mhn} runs only one program at a
time, and leaves the program's standard input connected to the
terminal.

There are other ``\%'' escape codes used by {\tt mhn}.  These are
described in section~\ref{mhn}.


\subsection{Examples of {\tt mhn\_defaults}}

The defaults for the ways in which {\tt mhn} displays and stores
multi-media e-mail messages can be found in the file {\tt
mhn\_defaults}, located in the MH library directory.  To find out which
directory is the MH library directory, you can type this command:
\begin{verbatim}
% mhparam mhlproc
\end{verbatim}
This prints out the path of the {\tt mhl} program.  In MH 6.8, {\tt
mhl} is in the MH library directory.  The {\tt mhn\_defaults} file is
in the same directory.

For your perusal, here are some example {\tt mhn\_defaults} files in
use at UC Irvine's ICS Department and at Irvine Compiler Corp.

Any of the lines in these files can be picked up and modified for
inclusion in your {\tt .mh\_profile}, or in your {\tt mhn} profile
named by the environment variable {\tt \$MHN}.

The various ``\%'' escape codes used in these profiles are described
in section~\ref{mhn}.

UCI ICS's {\tt mhn\_defaults}:

\begin{verbatim}
mhn-charset-iso-8859-1: xterm 
                        -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' 
                        -e %s
mhn-show-application/PostScript:  %plpr -Pps
mhn-show-image:                   %p/usr/bs/X11R5/bin/xv -geometry =-0+0 '%f'
mhn-show-text/richtext:           %p/usr/local/lib/mh-6.8/rt2raw '%f'
mhn-store-application/PostScript: %m%P.ps
mhn-store-text:                   %m%P.txt
\end{verbatim}

Note that in the absence of a subtype indicator, the line applies to
all subtypes.  The line for {\tt mhn-show-image} applies to all 
{\tt image} types, such as {\tt image/gif} and {\tt image/jpeg}.


ICC's {\tt mhn\_defaults} for Sun Microsystems SPARCstations:

\begin{verbatim}
mhn-compose-audio/basic:          /usr/local/bin/rec.sparc | 
                                        /usr/demo/SOUND/raw2audio -F
mhn-compose-audio/x-next:         /usr/local/bin/rec.sparc
mhn-show-application/PostScript:  %plpr -Pps
mhn-show-audio/basic:             %p/usr/demo/SOUND/raw2audio 
                                        2>/dev/null | play
mhn-show-audio/x-next:            %p/usr/demo/SOUND/play
mhn-store-application/PostScript: %m%P.ps
mhn-store-audio/basic:            | /usr/demo/SOUND/raw2audio -e ulaw 
                                        -s 8000 -c 1
                                        > %m%P.au
mhn-store-audio/x-next:           %m%P.au
mhn-store-text:                   %m%P.txt
mhn-cache:                        /r/mhn-cache
\end{verbatim}

The {\tt rec.sparc} program, a small perl script, is described
further in appendix~\ref{audiosetup}.

ICC's {\tt mhn\_defaults} for HP 9000/700 series workstations:

\begin{verbatim}
mhn-compose-audio/basic:          recorder '%F' -u -pause
mhn-compose-audio/x-next:         recorder '%F' -au -pause
mhn-show-application/PostScript:  %plp -dpsjetdup
mhn-show-audio/basic:             splayer -u
mhn-show-audio/x-next:            splayer -au
mhn-show-image:                   %pxv -geometry =-0+0 '%f'
mhn-show-message/rfc822:          show -file '%F'
mhn-show-text/richtext:           richtext -p '%F'
mhn-show-text/plain:              more '%F'
mhn-store-application/PostScript: %m%P.ps
mhn-store-audio/basic:            %m%P.u
mhn-store-audio/x-next:           %m%P.au
mhn-store-text:                   %m%P.txt
mhn-cache:                        /r/mhn-cache
\end{verbatim}



\section{MIME and MH}
\label{mimedefined}

The ability to create e-mail messages with audio and other non-textual
contents has been around for a while, but almost always as part of a
vendor-specific ``solution.''  This means that you can't create a
message under a NeXTstep system with PostScript information and {\it
Lip Service} (NeXT's audio e-mail) and directly handle the same
message on an HP 9000/710, a Sun SPARCstation IPC, and a Silicon
Graphics Iris.  That's a problem that MIME helps to solve.

MIME, the Multi-purpose Internet Mail Extensions, is a freely
available specification that offers a way to interchange
multi-media e-mail among many different computer systems.
MIME supports not only several pre-defined types of non-textual
message contents, such as $\mu$-law audio, GIF files and PostScript
images, but also permits you to define your own types of message
parts.

The MIME specification is given in the Internet ``Request for
Comments'' document RFC 1341.  It's one of the more readable RFC
documents, so if you're interested in the details of MIME, I suggest
that you find a copy and read it.  (See section~\ref{resources} for
information about how to obtain copies.)

MIME isn't specific to MH; there are other mail systems that support 
MIME\@.  MH offers one widely available implementation of the MIME 
specification.

If you're curious about what the MIME representation of a message
looks like, try typing {\tt list -noshowproc} after you've run {\tt
edit mhn} on a draft and before you've sent it:

\begin{verbatim}
What now? list -noshowproc
\end{verbatim}

It's also possible to view raw MIME by using a command like this one:
\begin{verbatim}
% show -noshowproc
\end{verbatim}



\section{Mhn Explained}
\label{mhn}

The manual page mhn(1) describes {\tt mhn} in concise detail.  The
manual page should always be consulted for the most up-to-date
information about {\tt mhn}'s features.  This section provides a
simplified synopsis of those features.

The mhn(1) manual page uses the terms {\it content} and {\it
content type} to refer to the data in a multi-media message part and
to the type of that data.  For simplicity, this tutorial has used the
term {\it message part} instead.

The {\tt mhn} program allows you to create and to view MIME messages
in just about any way that meets your needs, using whatever programs
are at hand or whatever programs you invent.

The default configuration, as installed by your system administrator,
most likely comes with some useful means by which to compose and to
display the most common types of multi-media message parts.

The {\tt mhn} program can be invoked directly from the command line to
manipulate MIME messages, using the same kinds of options that
other MH commands use:
\begin{brieflist}
\item The {\tt -list} option enumerates the contents;
\item The {\tt -show} option displays the contents;
\item The {\tt -store} option stores the contents into files.
\end{brieflist}

The synopsis of the {\tt mhn} command from its manual page is this:
\begin{tabbing}
{\tt mhn} \= [ {\tt +}{\it folder} ] [ {\it msgs\/} ] [ {\tt -part} {\it number\/} ]...
     [ {\tt -type} {\it content} ]...\+\\[\baselineskip]{}

     [ {\tt -list} \= [ {\tt -headers} ] [ {\tt -noheaders} ] \\{}
            \> [ {\tt -realsize} ] [ {\tt -norealsize} ] ] \\{}
            \> [ {\tt -nolist} ] \\[\baselineskip]{}

     [ {\tt -show} [ {\tt -serialonly} ] [ {\tt -noserialonly} ] ] \\{}
            \> [ {\tt -form} {\it formfile} ] ] \\{}
            \> [ {\tt -noshow} ] \\[\baselineskip]{}

     [ {\tt -store} [ {\tt -auto} ] [ {\tt -noauto} ] ] \\{}
            \> [ {\tt -nostore} ] \\[\baselineskip]{}
 
     [ {\tt -verbose} ] [ {\tt -noverbose} ]  \\{}
     [ {\tt -rfc934mode} ]  [ {\tt -norfc934mode} ] \\{}
     [ {\tt -ebcdicsafe} ] [ {\tt -noebcdicsafe} ] \\{}
     [ {\tt -help} ]
\end{tabbing}

Some, but not all, of the options are explained here; for more information,
consult mhn(1).

Typically, the MH command {\tt show} is configured with an 
{\tt mhnproc} parameter in the {\tt .mh\_profile} so that it
can automatically invoke {\tt mhn}.  (See section~\ref{setup}.)

Either an entire message can be displayed, or just an individual
part.  To select an individual part, use the {\tt mhn -part}
option, as in this example:
\begin{verbatim}
% mhn -part 1.3 -show
\end{verbatim}


\subsection{Profile Entries}

For each of the different {\tt mhn} functions, {\tt mhn} looks for
certain kinds of profile entries.  {\tt Mhn} obtains profile
information in this order of preference:
\begin{enumerate}
\item From a file named by the {\tt \$MHN} environment variable.
        This allows you to keep different multi-media message handling
        profiles for each type of display or workstation that you use.
        Section~\ref{setup} gives examples of how to do this.

\item From your {\tt .mh\_profile}, or in the profile specified
        by the {\tt \$MH} environment variable.

\item From the MH library file {\tt mhn\_defaults} (created by
        your system administrator).

\item From some built-in defaults for a few simple content types,
        such as {\tt text/plain}.
\end{enumerate}

Here is a list of profile entries for which {\tt mhn} looks:

\begin{comdesc}
\item[mhlproc:]  The program to display message headers
        when {\tt mhn-show} is used.
        The default is {\tt mhl}.

\item[mhn-access-ftp:]  The program to retrieve message parts via FTP
        when {\tt mhn -show} is used with a message containing external
        parts.
        The default is to use a built-in FTP retrieval mechanism.

\item[mhn-cache:]  The directory in which to store cached external parts
        when {\tt mhn -show} is used with a message containing external
        parts.
        The default is not to cache external parts at all, but
        rather to retrieve them each time.  (See section~\ref{external}.)

\item[mhn-charset-{\it charset}:] A shell command to create environment 
        to render  particular kinds of character sets when {\tt mhn -show}
        is used.  For example, {\tt xterm} can be run with an appropriate 
        font designation, or the {\tt less} program can be run with appropriate
        environment variable settings.
        
\item[mhn-compose-{\it type\/}:]  A shell command to compose message parts on 
        the fly when {\tt edit mhn} is used from the {\tt What now?}\ prompt.

\item[mhn-show-{\it type\/}:]   A shell command to display message parts
        of the specified type when {\tt mhn -show} is used.

\item[mhn-storage:] The directory in which to store message parts when
        {\tt mhn -store} is used.
        The default is the current working directory.

\item[mhn-store-{\it type\/}:]  A file name template
        or a shell command (beginning with the pipe symbol ``{\tt |}'')
        for storing message parts of the specified type when {\tt mhn -store} 
        is used.

\item[moreproc:]  The program to display {\tt text/plain} message parts.
        The default is {\tt more}.
\end{comdesc}



\subsection{Displaying Messages}

The {\tt mhn -show} command can be used to display multi-media messages.

Alternatively, the {\tt show} command should use {\tt mhn} by default.
If it doesn't, try using this profile entry:
\begin{verbatim}
mhnproc: mhn
\end{verbatim}

Some examples of {\tt mhn-show-} profile entries are:
\begin{comdesc}
\item[mhn-show-audio/basic]
        ---Audio setups can be tricky.  See appendix~\ref{audiosetup}
        for a detailed explanation.
        This example is for HP 9000/710 workstations.  Your audio 
        playing command may differ.
        \begin{flushleft}
        {\tt mhn-show-audio/basic:\ splayer -u}
        \end{flushleft}
        
\item[mhn-show-image]
        ---Specifying a profile entry for {\tt image} with no subtype
        means that the entry applies to all subtypes.  For example,
        the {\tt xv} program handles both {\tt image/gif} and
        {\tt image/jpeg} types, as well as a number of others:
        \begin{flushleft}
        {\tt mhn-show-image:\ \%pxv -geometry =-0+0 '\%f'}
        \end{flushleft}

\item[mhn-show-application/postscript]
        ---Messages containing {\tt application/postscript} parts can be viewed
        using the freely available GNU GhostScript tools, {\tt gs} and 
        {\tt ghostview}, or using vendor-supplied PostScript viewing tools, 
        such as Sun's {\tt pageview}.  Alternatively, PostScript parts can be 
        viewed by printing them on PostScript printers.
        Any of these examples might do:
        \begin{flushleft}
        {\tt mhn-show-application/PostScript:\ \%ppageview '\%F'} \\
        {\tt mhn-show-application/PostScript:\ \%pgs -} \\
        {\tt mhn-show-application/PostScript:\ \%pghostview -} \\
        {\tt mhn-show-application/PostScript:\ \%plp -dpsjetdup}
        \end{flushleft}

        Note the security issues surrounding PostScript raised in
        section \ref{security}.
\end{comdesc}

Shell commands in {\tt mhn-show-} profile entries may include {\it escape
codes} beginning with a percent sign (``\%'').
The ``\%'' escape codes include these:
\begin{comdesc}
\item[\%f]
    The ``\%f'' escape tells {\tt mhn} to store the
    data into a temporary file and to give the name of the temporary
    file to the display program.

\item[\%F]
    The ``\%F'' escape tells {\tt mhn} to store the
    data into a temporary file and to give the name of the temporary
    file to the display program.

    The difference between \%F (upper case) and \%f (lower case)
    is that for \%F, {\tt mhn} runs only one program at a
    time, and leaves the program's standard input connected to the
    terminal.

    Note that when using the \%f or \%F escapes, it's a good idea to
    use  single quotes  around the escape, as in {\tt '\%F'}.
    This prevents misinterpretation by the shell of any funny characters 
    that might be present in the filename, such as {\tt <} and {\tt >},
    which occur in the names of cached external body part files.

\item[\%p]
    The ``\%p'' escape specifies that the part's description is to be
    listed and then a prompt delivered to ask whether or not the part
    should be shown.
    
    When a \%p causes a prompt for confirmation, typing INTR (usually
    \mbox{control-C}) tells mhn not to display that part.  Typing QUIT (usually
    control-\verb+\+) aborts the entire message display process.
\end{comdesc}

The mhn(1) manual page lists other ``\%'' escapes that may be useful
in {\tt mhn-show-} profile entries.


\subsection{Composing Messages}

MH 6.8 doesn't provide a visual front end for creating MIME messages.
This means that you need to type some simple directives into your
message draft, which takes a little getting used to if, for example,
you've been using NeXTmail.

{\tt Mhn} can be invoked from the ``What now?'' prompt to
create a MIME message:
\begin{verbatim}
What now? edit mhn
\end{verbatim}
Using {\tt edit mhn} invokes the ``compose'' function of {\tt mhn}.

It's also possible to instruct {\tt whatnow} (the MH program
responsible for handling your ``{\tt What now?}'' instructions)
to invoke {\tt mhn} automatically, so that you don't need
to type {\tt edit mhn}.
To do that, use an entry like this in your {\tt .mh\_profile}:
\begin{verbatim}
automhnproc: mhn
\end{verbatim}

When {\tt mhn} is invoked to compose a MIME message,
each {\tt \#} directive in the message draft causes data from a
file or from a command to be inserted.

If a file isn't specified with the directive, then a command is
used to generate the data.
For example, consider this directive:
\begin{flushleft}
{\tt \#audio/basic [record something here]}
\end{flushleft}
Because there's no file specified, {\tt mhn} looks for this
profile entry to record {\tt audio/basic} data to insert into the
draft:
\begin{verbatim}
mhn-compose-audio/basic: recorder '%F' -u -pause
\end{verbatim}
This example is for HP 9000/710 workstations.  Your audio recording
command may differ.  Refer to appendix~\ref{audiosetup} for more
information about audio tools.

Two escape codes relevant to composition commands are these:
\begin{comdesc}
\item[\%f]
    The ``\%f'' escape tells {\tt mhn} to supply the name
    of a temporary file, from which the data are taken
    when the program ends.

\item[\%F]
    The ``\%F'' escape tells {\tt mhn} to supply the name
    of a temporary file, from which the data are taken
    when the program ends.

    The difference between \%F (upper case) and \%f (lower case)
    is that for \%F, {\tt mhn} doesn't redirect standard output
    (typically so that it's left attached to the terminal).
\end{comdesc}

Other escape codes that may be of use are documented in mhn(1).

In an {\tt mhn} directive in a message draft, an
appropriate program invocation (beginning with the pipe symbol, ``{\tt
|}'') in the place of a file name
overrides an {\tt mhn-compose-} profile entry.

Here is a synopsis of the syntax of {\tt mhn} directives:
\begin{tabbing}
plaintext \hspace{2em} \= $\rightarrow$ \hspace{1em} \= \hspace{1em} \= \kill
{\it body}         \>$\rightarrow$\>    ({\it content} {\tt |} {\small\it EOL})$^{+}$\\[\baselineskip]{}

{\it content}      \>$\rightarrow$\>    {\it directive} {\tt |} {\it plaintext}\\[\baselineskip]{}

{\it directive}    \>$\rightarrow$\>    {\tt \#} {\it type} {\bf /} {\it subtype} \+\+\+\\{}
                         ({\bf ;} {\it attribute} {\tt =} {\it value})$^{*}$\\{}
                         [ {\bf (} {\it comment} {\bf )} ]\\{}
                         [ {\bf [} {\it description} {\bf ]} ]\\{}
                         [ {\it filename} ]\\{}
                         {\small\it EOL} \\{}
                        ---For files or programs\-\\{}
                   {\tt |} \+\\{}
                         {\tt \#}{\bf @} {\it type} {\bf /} {\it subtype} \\{}
                         ({\bf ;} {\it attribute} {\tt =} {\it value})$^{*}$ \\{}
                         [ {\bf (} {\it comment} {\bf )} ] \\{}
                         [ {\bf [} {\it description} {\bf ]} ] \\{}
                         {\it external-parameters} \\{}
                         {\small\it EOL} \\{}
                        ---For external body parts \-\\{}
                   {\tt |} \+\\{}
                         {\tt \#}{\bf forw} \\{}
                         [ {\bf [} {\it description} {\bf ]} ] \\{}
                         [ {\tt +}{\it folder} ] [ {\it msg}$^{*}$ ] \\{}
                         {\small\it EOL} \\{}
                        --- For message digests \-\\{}
                   {\tt |} \+\\{}
                         {\tt \#}{\bf begin} \\{}
                         [ {\bf [} {\it description} {\bf ]} ] \\{}
                         [ {\bf alternative} {\tt |} {\bf parallel} ] \\{}
                         {\small\it EOL} \\{}
                         {\it body}$^{+}$ \\{}
                         {\tt \#}{\bf end} {\small\it EOL} \\{}
                        ---For multipart messages \-\-\-\\[\baselineskip]{}

{\it plaintext}    \>$\rightarrow$\>     [ {\bf Content-Description:} \+\+\+\\{}
                         {\it description} {\small\it EOL} {\small\it EOL} ] \\{}
                         {\it line}$^{+}$ \\{}
                         [ {\tt \#} {\small\it EOL} ] \\{}
                         ---Describes and encloses a {\tt text/plain} part \-\\{}
                   {\tt |} \+\\{}
                        {\tt \#{\tt <}} {\it type} {\bf /} {\it subtype} \\{}
                        ({\bf ;} {\it attribute} {\tt =} {\it value})$^{*}$ \\{}
                        [ {\bf (} {\it comment} {\bf )} ] \\{}
                        [ {\bf [} {\it description} {\bf ]} ] \\{}
                        {\small\it EOL} \\{}
                        {\it line}$^{+}$ \\{}
                        [ {\tt \#} {\small\it EOL} ] \\{}
                        ---Encloses plain text representation of data \-\-\-\\[\baselineskip]{}


{\it line}         \>$\rightarrow$\>     {\tt \#\#} {\it text} {\small\it EOL} \+\+\+\\{}
                     ---Interpreted as {\tt \#}{\it text} {\small\it EOL} \- \\{}
                   {\tt |} \+\\{}
                         {\it text} {\small\it EOL}
\end{tabbing}

Examples of various forms of {\tt mhn} directives are scattered
throughout this tutorial, particularly in sections~\ref{examples},
\ref{external}, and appendix~\ref{mimetypes}.

Section \ref{external} has a list of required {\it attribute}{\tt
=}{\it value} pairs to apply to external types.
The MIME specification, RFC 1341, contains more detailed explanations 
of required or optional attributes.
Type names and attributes used with {\tt mhn} directives
correspond to those used in the MIME specification.


\subsection{Storing Message Parts}

The {\tt mhn -store} option stores message parts (all parts if {\tt
-part} isn't specified) in ``native'' (decoded) format.

Here is example of an {\tt mhn -store} command:
\begin{flushleft}
{\tt mhn 11 -part 3.3 -store}
\end{flushleft}
This stores part 3.3 of message number 11 into a file.
The name and location of the file may be specified by profile entries
like these:
\begin{verbatim}
mhn-storage:                      /usr/tmp
mhn-store-application/PostScript: %m%P.ps
mhn-store-audio/basic:            %m%P.u
mhn-store-audio/x-next:           %m%P.au
mhn-store-text:                   %m%P.txt
\end{verbatim}

The {\tt mhn-storage} profile entry specifies the directory in which
to store files.
The default is the current working directory.

In {\tt mhn-store-} profile entries, either a file name formatting
string or a program invocation (beginning with the shell pipe symbol,
``{\tt |}'') may be specified, as in this example:

\begin{verbatim}
mhn-store-audio/basic: | /usr/demo/SOUND/raw2audio
                            -e ulaw -s 8000 -c 1
                            > %m%P.au
\end{verbatim}

This example is for Sun SPARCstations.  The command runs the audio
data through a program that adds descriptive information to the audio
data before storing it into a file.  A more comprehensive explanation
of what's going on is given in appendix~\ref{audiosetup}.

Escape codes beginning with ``\%'' specify what the file names are to
look like.

Given the command at the beginning of this section and the previous
profile entry for storing {\tt audio/basic} parts, the {\tt \%m\%P.au}
specification refers to a file named {\tt 11.3.3.au}.

These are the escape codes for {\tt mhn-store-} profile entries:
\begin{tabbing}
{\tt \%m} \hspace{2em} \= message number \\
{\tt \%P} \>            {\tt .}part \\
{\tt \%p} \>            part \\
{\tt \%s} \>            subtype
\end{tabbing}

There are other file name formatting options described in mhn(1).


\subsection{Other Facilities}

{\tt Mhn} has a number of other facilities for manipulating MIME messages.
Detailed information about how to use the facilities can be found in the
mhn(1) manual page; here is a brief list of some of them:
\begin{description}
\item[Splitting large messages.]
        MIME permits a message to be split among several separate messages.
        The {\tt send -split} option automatically splits a message.
        The {\tt mhn -store} option can be used to reassemble a split message.
        (Split messages, each of which are {\it partial} messages,
	are those using the MIME type {\tt message/partial}.)

\item[Retrieving external body parts.]
        Some examples of external bodies have been given in section~\ref{weather}.
        More examples are given in section~\ref{external}.
        There are several different ways to refer to and to retrieve external body parts.
        One alternative, using mail server references, is explained
        in section~\ref{external}.

\item[Sending file sets.]
        There is a script, {\tt viamail}, available in the MH library directory,
        which sends a set of files via e-mail.  The files are automatically 
        archived into a compressed UNIX tar file format ({\tt .tar.Z}) and
        transported in a MIME message (or in several messages, split automatically,
        if the archive is large).
        The {\tt mhn -store} option is also capable of extracting the files from 
        such MIME messages.

\item[Encoding and extracting arbitrary data.]
        The MIME ``base64'' encoding format is a fairly safe way to transport
        data (such as shell scripts and program binaries) through mail gateways.
        By specifying the {\tt application/octet-stream} type when composing
        a message, {\tt mhn} will encode in base64 any file you specify.
        MIME-capable user agents should be able to decode that file.
        In MH, {\tt mhn -store} can be used to decode an
        {\tt application/octet-stream} message part encoded in base64.

\item[Setting up to use {\tt less}.]
        {\tt Mhn} will use the {\tt less} pager program instead of {\tt more}
        if you so specify in the {\tt moreproc:}\ profile entry.
        Some additional environment setup is required, as described in the
        mhn(1) manual page.
\end{description}



\section{More About External Body Parts}
\label{external}

External body parts---particularly when cached on local systems---have
the advantage that if there are many recipients, less network
bandwidth and disk storage may be consumed than when the complete
image or audio contents are included in every copy of the message.

However, there are some potential pitfalls to using external body
parts:
\begin{enumerate}
\item   Some recipients of {\tt access-type=anon-ftp} parts
might not have Internet access.
Internet FTP per se isn't possible for non-Internet sites.

\item   A file on a remote host might not be accessible at all
times because of transient network problems (an all-too-frequent
occurrence on the Internet).

\item   In the case of the {\tt mail.weather.ext} program mentioned
in section~\ref{weather}, sometimes the image files, whose names are
generated automatically based on the date and the time of day, are
sometimes not present on the remote host, even hours after the files
are expected to be there.
\end{enumerate}

The first limitation can be overcome when files available via
anonymous FTP are also available via a {\it mail server}.  A mail
server is a program that accepts an e-mail message containing a
request for something and returns the requested item to the originator
of the request via e-mail.  Mail servers are especially useful under
circumstances where Internet FTP doesn't work, such as over dial-up
UUCP links.

To permit access to a file either via anonymous FTP or via a mail
server, enclose two external file references inside a {\tt \#begin
alternative} directive, as in this example:

\begin{verbatim}
#begin alternative
#@image/gif [via FTP: surface & radar analysis] \
        access-type=anon-ftp; \
        name="SA022509.GIF"; \
        directory="wx"; \
        site="vmd.cso.uiuc.edu"; \
        expiration="26 Feb 93 09:00:00 GMT"; \
        size=50000
#@image/gif [via mail: surface & radar analysis] \
        access-type=mail-server; \
        expiration="26 Feb 93 09:00:00 GMT"; \
        size=50000; \
        server="wx-server@vmd.cso.uiuc.edu"; \
        body="send wx:SA022509.GIF"
#end
\end{verbatim}

A message containing these directives has this structure, as shown by
{\tt mhn -list}:

\begin{verbatim}
msg part  type/subtype              size description                         
 1        multipart/alternative      697

    1     message/external-body      110
          image/gif                      via mail: surface & radar analysis

    2     message/external-body       87
          image/gif                      via FTP: surface & radar analysis
\end{verbatim}

Note that the order of alternatives listed is the reverse of that in
which the directives occurred in the original draft.

The message, when viewed by the MH command {\tt show}, results in a
session like this one:

\begin{verbatim}
Retrieve content 1 by asking mailbox wx-server@vmd.cso.uiuc.edu

send wx:SA022509.GIF

? y
mhn: request sent
\end{verbatim}

The retrieval message sent by {\tt mhn} looks like this:

\begin{verbatim}
To: wx-server@vmd.cso.uiuc.edu
Subject: cache content as /r/mhn-cache/<24586.731500909.2@fester.irvine.com>

send wx:SA022509.GIF
\end{verbatim}

When the mail server on the remote host receives this message, it
takes action based on the command specified in the body.  The body may
specify any command that the mail server understands.  Note that
unlike FTP, there is no standardization among different mail servers.
The {\tt send} command shown in the example above might need to be a
{\tt get} command, or something completely non-intuitive, for a mail
server at another site.

(By the way, this particular example, although semantically correct,
won't really work, because the site {\tt vmd.cso.uiuc.edu} doesn't
offer files via a mail server---not to mention that the particular
file named has long since been deleted from the system.  FTP is really
the only retrieval method that applies for the weather maps.)

If the answer to the question above had been ``n'' then the usual
FTP retrieval question would have been asked:

\begin{verbatim}
Retrieve SA022509.GIF (content 2)
    using anonymous FTP from site vmd.cso.uiuc.edu (50000 octets)?
\end{verbatim}

In general, alternatives permit users to have different ways to look
at a message.  For those recipients without the necessary resources to
view a particular message part, it helps to offer a ``plain''
alternative---even if it's just to say ``sorry, but you're missing
something neat...''

RFC 1341 (the MIME specification) recommends that the ``plainest''
alternative be placed first in the list, and that the ``fanciest''
alternative be placed last.  The MH {\tt show} command offers the last
alternative first.  In our example above, the {\tt
access-type=mail-server} alternative should have gone second, since it
doesn't offer gratification as immediate as the {\tt
access-type=anon-ftp} alternative does.

Here is a list of the {\tt mhn} directive forms most likely to be used
for inserting external body parts:

\begin{tabbing}
To refer to an external file available via anonymous FTP:\\
\hspace{4em} \= {\tt \#@}{\it type/subtype} {\tt [}{\it description}{\tt ] \verb.\.}\+\\
  \hspace{4em} \= {\tt access-type=anon-ftp; \verb.\.}\+\\
        {\tt name="}{\it remote-filename}{\tt ";  \verb.\.} \\
        {\tt directory="}{\it remote-directory}{\tt ";  \verb.\.} \\
        {\tt site="}{\it remote-ftp-host}{\tt "} \-\-\\[\baselineskip]

To refer to an external file available via mail server:\+\\
  {\tt \#@}{\it type/subtype} {\tt [}{\it description}{\tt ] \verb.\.}\+\\
        {\tt access-type=mail-server; \verb.\.} \\
        {\tt server="}{\it mailbox-address}{\tt ";  \verb.\.} \\
        {\tt body="}{\it retrieval-command}{\tt ";  \verb.\.} \-\-\\[\baselineskip]

To refer to a locally available file:\+\\
  {\tt \#@}{\it type/subtype} {\tt [}{\it description}{\tt ] \verb.\.}\+\\
        {\tt access-type=local-file; \verb.\.} \\
        {\tt name="}{\it local-path}{\tt "}
\end{tabbing}

There are other kinds of {\tt access-type} attributes that may be used
for alternative file access methods.  Refer to the mhn(1) manual page
and to RFC 1341 for information about these other access types.

Also, you don't have to use {\tt mhn}'s built-in FTP retrieval mechanism.
{\tt Mhn} will use an FTP program that you designate in this profile entry:
\begin{flushleft}
{\tt mhn-access-ftp:\ } {\it my-ftp-program}
\end{flushleft}
Information about the requirements for an {\tt mhn}-invoked FTP
retrieval program can be found in the mhn(1) manual page.



\appendix

\section{General Information about MH}

MH is a modular mail system comprised of a set of shell-level
commands.

The MH commands permit you not only to handle your mail in the usual
way, e.g.\ to read messages, to produce scan summaries, and to reply to
messages, but also to cobble together your own mail handling utilities
by invoking MH commands from shell scripts or perl programs.

Here are two handy papers, supplied with the MH software distribution,
that you should seek out and read if you're unfamiliar with MH:
\begin{brieflist}
\item ``The Rand MH Message Handling System: Tutorial'' by Marshall
        Rose and Jerry Sweet

\item ``How to process 200 messages a day and still get some real work done''
        by Marshall Rose and John Romine
\end{brieflist}

...And here are two useful books that cover MH:
\begin{brieflist}
\item {\it MH \& xmh} by Jerry Peek (O'Reilly \& Associates, Inc).

\item {\it The Internet Message} by Marshall Rose (P T R Prentice-Hall, Inc.)
\end{brieflist}

Peek's book, as of the 1992 edition, doesn't cover MH's MIME
facilities, although it's a good reference book for MH users.  Rose's
book isn't specifically about MH, but does include a lengthy
discussion of MH's MIME facilities.

See appendix~\ref{resources} for information about how to
obtain the papers.  See appendix~\ref{references} for ISBN
information for the books.


\section{Pre-Defined MIME Types}
\label{mimetypes}

Each part of a multi-media message identifies what type of information
is carried in the message part.  For example, a message part
containing audio data might have either type {\tt audio/basic} or type
{\tt audio/x-next}.  Both are {\tt audio} types; the {\it subtypes}
are {\tt basic} and {\tt x-next}.

An entire MIME message---as opposed to an individual part of a
multipart message---can also have a type.  For example, a message
might have the type {\tt text/plain}, and consist entirely of plain
text.  A MIME message containing parts of different types has
the umbrella type {\tt multipart/mixed}.

Here are brief summaries of the pre-defined types and subtypes in
MIME~1.0.  
Except where noted, each of these types may be specified in an {\tt mhn}
directive in a message draft, preceded by a hash mark ({\tt \#}) at the
start of a line.

\begin{comdesc}
\item[application/octet-stream] is for ``other'' kinds of
        data, either uninterpreted binary data or information to
        be processed by  a  mail-based  application.
        When {\tt mhn} incorporates the data directly into
        a draft, the data is encoded in MIME's base64 format.
        This is also a good way to send data, such as shell scripts,
        that might suffer unacceptable modifications (e.g.\ long text
        line wraps) in transport.

\item[application/oda] is for ODIF data (open document interchange
        format, ISO/IEC 8613).
        When {\tt mhn} incorporates the data directly into
        a draft, the data is encoded in MIME's base64 format.

\item[application/postscript] is for PostScript programs
        (typically documents represented in PostScript form).
        {\tt Mhn} leaves PostScript data alone when incorporating
        it into a draft.

\item[audio/basic] is for audio data encoded using  8-bit ISDN 
        $\mu$-law (Pulse Code Modulation).   A sample rate of 8000/second
        and a single channel  is assumed.  (This is the ``native''
        format for SPARCstations and for HP 9000/700s.)
        When {\tt mhn} incorporates the audio data directly into
        a draft, the data is encoded in MIME's base64 format.

\item[image/gif] is for GIF (graphical interchange format) image data.
        When {\tt mhn} incorporates the image data directly into
        a draft, the data is encoded in MIME's
        base64 format.

\item[image/jpeg] is for JPEG (joint picture experts group) image data.
        When {\tt mhn} incorporates the image data directly into
        a draft, the data is encoded in MIME's
        base64 format.

\item[message/external-body] is for specifying large
        bodies by reference to an external data source.
        An {\tt mhn} type specification directive beginning with
        {\tt \#@} specifies a {\tt message/external-body} part.

\item[message/partial] is for partial messages, to permit
        the fragmented transmission  of  bodies  that  are
        thought  to be too large to be passed through mail
        transport facilities.  Using the {\tt -split} option
        with {\tt send} creates messages of type 
        {\tt message/partial}.

\item[message/rfc822] is an encapsulated 
        RFC 822 conformant message which may have its
        own type.  The {\tt mhn} directive {\tt \#forw} uses
        the {\tt message/rfc822} type in conjunction with
        the {\tt multipart/digest} type.

\item[multipart/alternative] represents the same data
        in multiple formats.  The {\tt mhn} directive {\tt
        \#begin alternative} uses the {\tt multipart/alternative} type.

\item[multipart/digest] is for multipart entities in which 
        each  part is an encapsulated message.  The {\tt mhn}
        directive {\tt \#forw} uses the {\tt multipart/digest}
        type.

\item[multipart/mixed] is the primary way to represent
        a MIME message containing parts of various different types.
        With {\tt mhn}, a draft (or a part of a draft) containing more  
        than one part is created using the {\tt multipart/mixed} type.

\item[multipart/parallel] is for data intended to be viewed
        simultaneously.  The {\tt mhn} directive
        {\tt \#begin parallel} uses the {\tt multipart/parallel} type.

\item[text/plain] indicates plain (unformatted) text.

\item[text/richtext] is plain text with formatting
        commands to enhance the appearance of  the
        text.  The formatting commands are summarized
        in appendix~\ref{richtext}.

\item[video/mpeg] is for MPEG (motion picture experts group) 
        video data.  Video requires the capability to
        display   moving   images,   typically   including
        specialized hardware and  software.
        When {\tt mhn} incorporates the audio data directly into
        a draft, the video data is encoded in MIME's base64 format.
\end{comdesc}

There may be other registered types and subtypes down the road.
MIME also allows arbitrary subtypes whose names are prefixed with
``x-'', but anything else is reserved for registered types.

The MIME specification, RFC 1341, contains more detailed explanations
of required or optional attributes to be used with particular types.
Type names used with {\tt mhn} correspond to those used in the MIME
specification.

Base64 is a textual encoding used in MIME messages.  Base64 is
designed to permit data to survive the most common sorts of
transformations that mail gateways apply to message bodies, such as
breaking long lines of text into multiple lines.  Base64 is similar in
concept to the encoding used by {\tt uuencode}, except that uuencoded
data doesn't always survive intact when transported through certain
mail gateways.


\section{Richtext}
\label{richtext}

This section summarizes the {\tt text/richtext} type.  A full
explanation of richtext can be found in RFC 1341, the MIME
specification.

Richtext is a simple markup language for plain text, like LaTeX or
nroff or Scribe.  A document in richtext format consists of plain
text ``marked up'' with formatting commands.
The formatting commands are used to change fonts, to format paragraphs,
and to lay out pages.
For those with some word processing experience, MIME richtext isn't
in any way related to Microsoft Richtext.

The formatting commands are words surrounded by angle brackets ({\tt
<>}), such as {\tt <bold>}.
Each occurrence of a command is balanced later on by a negating command
beginning with a forward slash or solidus ({\tt /}), such as {\tt
</bold>}.

There are only three exceptions to this balancing rule:
\begin{enumerate}
\item The command {\tt <lt>}, which represents a literal {\tt <} character.
\item The command {\tt <nl>}, which represents a required line break.
(Otherwise, CRLFs in the data are treated as equivalent to a
single SPACE character.)
\item The command {\tt <np>}, which represents a page break.
\end{enumerate}

The list of pre-defined richtext commands follows.

Font selection commands:
\begin{rtlist}
\item[bigger] -- subsequent text is displayed in a bigger font.
\item[bold] -- subsequent text is displayed in bold font.
\item[fixed] -- subsequent text is displayed in fixed width font.
\item[italic] -- subsequent text is italicized.
\item[smaller] -- subsequent  text  is displayed in a smaller font.
\item[subscript]  --  subsequent  text is interpreted as a subscript.
\item[superscript]  --  subsequent  text is interpreted as a superscript.
\item[underline]  --  subsequent text is underlined.
\end{rtlist}

Paragraph formatting commands:
\begin{rtlist}
\item[center] -- subsequent text is centered.
\item[excerpt] -- subsequent text is interpreted
     as a textual excerpt from another source.  Typically this will be
     displayed using indentation and an alternate font, but such decisions
     are up to the viewer.  In one implementation, each displayed line of the
     excerpt begins with a right angle bracket ({\tt >}) and some horizontal whitespace.
\item[flushleft] -- subsequent  text is left justified.
\item[flushright] -- subsequent text  is right justified.
\item[indent] -- subsequent text is indented at the left margin.
\item[indentright]  --  subsequent  text  is indented at the right margin.
\item[nl] -- causes a line break.  No balancing {\tt </nl>}  is
     allowed.
\item[outdent] -- subsequent text is outdented at the left margin.
\item[outdentright]  --  subsequent  text  is outdented at the right margin.
\item[paragraph]  --  subsequent text is
     interpreted as a single paragraph, with appropriate paragraph
     breaks (typically blank space) before and after.
\item[signature]  --  subsequent text is
     interpreted as a {\it signature}.  Some systems may wish to
     display signatures in a smaller font or otherwise set them apart from
     the main text of the message.
\end{rtlist}

Page layout commands:
\begin{rtlist}
\item[footing] -- subsequent text is interpreted as a page footing.
\item[heading] -- subsequent text is interpreted as a page heading.
\item[np] -- causes a page break.  No balancing {\tt </np>}  is
     allowed.
\item[samepage] -- subsequent text is grouped, if possible, on one page.
\end{rtlist}

Character set selection commands:
\begin{rtlist}
\item[iso-8859-{\it X\/}]  (for any value of {\it X}  that  is  legal  as  a
     {\tt charset} parameter) -- subsequent text is interpreted as
     text in the appropriate character set.
\item[us-ascii]  --  subsequent   text   is 
     interpreted as text in the US-ASCII character set.
\end{rtlist}

Miscellaneous commands:
\begin{rtlist}
\item[comment] -- subsequent text is interpreted
     as a comment, not to be shown to the reader.
\item[lt] -- replaced by a literal {\tt <} character.   No
     balancing {\tt </lt>} is allowed.
\item[no-op] -- has no effect on the subsequent text.
\end{rtlist}

Each positive formatting command affects all subsequent text until the
matching negative formatting command.  Such pairs of formatting
commands must be properly balanced and nested.  Thus, a proper way to
describe text in bold italics is:
\begin{verbatim}
<bold><italic>the-text</italic></bold>
\end{verbatim}

or, alternatively,
\begin{verbatim}
<italic><bold>the-text</bold></italic>
\end{verbatim}

but, in particular, the following is illegal richtext:
\begin{verbatim}
<bold><italic>the-text</bold></italic>
\end{verbatim}

No special behavior is required for the Tab (aka HT or control-I)
character, but when fixed-width fonts are in use, the common semantics
of the TAB character may be observed, i.e.\ that a Tab moves to the
next column position that is a multiple of 8.

A line break (CRLF) is interpreted as a {\it soft} line break, which
is treated as horizontal white space.  To include a {\it hard} line
break (one that must be displayed as such), the {\tt <nl>} or {\tt
<paragraph>} formatting constructs should be used.

Consider this richtext body fragment:

\begin{verbatim}
<bold>Now</bold> is the time for
<italic>all</italic> good men
 <smaller>(and <lt>women>)</smaller> to
<ignoreme></ignoreme> come

to the aid of their
<nl>
beloved <nl><nl>country. <comment> Stupid
quote! </comment> -- the end
\end{verbatim}

The example fragment above represents this formatted text:

\begin{flushleft}
{\tt 
{\bf Now} is the time for {\it all} good men {\footnotesize (and
{\tt <}women{\tt >})} to come to the aid of their\\
beloved\\[\baselineskip]

country. -- the end
}
\end{flushleft}


Note that the final display of a message in richtext format may be
quite different from that which was intended, simply because display
devices and richtext implementations may differ in capabilities.  A
richtext message that may display beautifully with full italic and
bold characters on an X Window System display may look terrible on a
24-by-80 fixed-font ASCII terminal that can only show plain or bold
text blocks.

Richtext message parts are specified with the type {\tt text/richtext}.
To compose a message with richtext parts, these {\tt mhn} directives may be
used:

\begin{tabbing}
To insert a text file containing richtext formatting commands:\\
\hspace{4em} \= {\tt \#text/richtext} {\it filename}\\[\baselineskip]

To compose a portion of a draft with richtext:\+\\
      {\tt \#<text/richtext}\\
      {\it lines of text with richtext formatting commands}\\
      {\tt \#}
\end{tabbing}

Of course, external body parts may also be specified with the
directive {\tt \#@text/richtext} followed by appropriate parameters
(see section~\ref{external}).


\section{Audio Setup}
\label{audiosetup}

Much of the following information is taken primarily from a document
in the MH 6.8 source tree, {\tt miscellany/multimedia/READ-ME}\@.  You
may wish to consult that document to see if it contains more recent
information.

MIME pre-defines one audio type, {\tt audio/basic}.  This is for audio
data encoded using 8-bit ISDN $\mu$-law (Pulse Code Modulation).  A
sample rate of 8000/second and a single channel is assumed.  This is
the ``native'' format for the audio chips included with SPARCstations
and for HP 9000/7xx series workstations.  References to ``u-law'' or
``mu-law'' in other documents mean $\mu$-law.

There are many different types of audio formats, some of which may use
compression, multiple channels, and higher or lower sample rates.
These types may also be used in MIME messages by using unofficial
{\tt x-} subtypes, such as {\tt audio/x-next}.  However, there must
exist pre-agreement among users of {\tt x-} subtypes as to what their
meanings are and how they are handled.

Which audio programs to use and how to set up to use them is highly
dependent on the type of workstation you have.  Information is
presently available for two types of workstations: Sun SPARCstations
and HP 9000/710s.  If other audio-capable workstations come with
programs that can be instructed from the command line to record or to
play particular files, then these programs can be used with MH one way
or another.

If your workstation doesn't come with a built-in microphone, or an
external microphone supplied by the vendor, you'll need to buy one.
If the microphone doesn't have enough gain, you may have to keep the
microphone close to your lips when recording.  The SONY ECM-K7
microphone comes highly recommended; you can put the microphone on
your desk and it will still pick up your voice.

\subsection{SPARCstation}

Most newer models of SPARCstations have a telephone-quality audio chip
and an internal speaker.  The ``native'' encoding for the audio chip is
8-bit $\mu$-law sampled at 8000/second.

Audio data can be manipulated in two formats: ``raw'' and ``self-describing:''
\begin{enumerate}
\item ``Raw'' audio data is the native format used directly by the audio chip.
        This corresponds to the {\tt audio/basic} type.
        Audio files prior to SunOS 4.1 used this format only.

\item ``Self-Describing'' data consists of a header describing
        the type of audio data in the file (e.g.\ native $\mu$-law,
        ISDN A-law, ADPCM, etc.), followed by audio data of that type.
        This format was introduced with SunOS 4.1.0.
        The {\tt audio/x-next} type can be used to refer
        to this self-describing type (so named because NeXT developed 
        this format; Sun supports a subset of it).
\end{enumerate}

A file containing raw audio data can be played by sending it directly
to the audio device, {\tt /dev/audio}, as with this command:
\begin{verbatim}
% cat audio.raw > /dev/audio
\end{verbatim}

The header must be stripped from self-describing audio data when specifying
an {\tt audio/basic} message part.
The header must be present when specifying an {\tt audio/x-next} part.

In support of the {\tt audio/basic} and {\tt audio/x-next} types, it
is possible to convert between the raw format and the self-describing
format by using a patched version of the {\tt raw2audio} program.  The
patches are described a little later on.

The {\tt record} program delivers self-describing data.  The {\tt play}
program plays self-describing data.  These programs are found in the {\tt
/usr/demo/SOUND/} directory when the demo program package is
installed.
However, the {\tt record} program is not suitable for running from {\tt mhn},
because the control-C that terminates a recording session raises havoc.
The {\tt audiotool} program, if available, is more suitable.
In the absence of the {\tt audiotool} program, you can use a little
wrapper program for {\tt record} that prompts for the beginning and
end of the recording session.
An example wrapper, {\tt rec.sparc}, can be obtained as described in
appendix~\ref{resources}.

The {\tt audio/x-next} type may be used with any self-describing audio
data recognized by the SunOS audio programs, such as ADPCM format.
The ADPCM format is compressed $\mu$-law encoding based on the CCITT
G.721 Adaptive Delta Pulse Code Modulation algorithm.  Sun introduced
support for this type of audio data with OpenWindows 3.0.

ADPCM format data cannot be directly played to or recorded from the
audio chip; it must first be converted back to the native 8-bit
$\mu$-law format.  Conversions to and from the two encodings can be
done with the {\tt adpcm\_enc} and {\tt adpcm\_dec} programs found in
the {\tt \$OPENWINHOME/bin/} directory.

Suggested profile entries for {\tt mhn} relevant to recording and playing back audio
data in ADPCM format are these:
\begin{verbatim}
mhn-compose-audio/x-next:        audiotool '%f' && adpcm_enc < '%f'
mhn-show-audio/x-next:           %paudiotool -p '%f'
\end{verbatim}

Suggested profile entries for {\tt mhn} relevant to recording and playing back audio
data in native $\mu$-law format are these:
\begin{verbatim}
mhn-compose-audio/basic: audiotool '%f' && raw2audio -F < '%f'
mhn-show-audio/basic:    %praw2audio 2>/dev/null | play
\end{verbatim}

Because the {\tt raw2audio}, {\tt play}, and {\tt record} programs are
provided in source form with SunOS 4.1, it is possible to compile them
for systems running earlier versios of SunOS\@.  The sources can be
found in the SunOS 4.1 Demos installation.

If these programs are unavailable, then you will be able to manipulate
only the raw, native audio data formats by reading and writing directly
to the {\tt /dev/audio} device via {\tt cat}.

If you do have the {\tt raw2audio}, {\tt play}, and {\tt record}
programs (regardless of which version of SunOS you're running), then
you need to apply some source changes by using the publicly available
{\tt patch} program.  The source patches are part of the MH 6.8 source
tree:
\begin{verbatim}
% (cd /usr/demo/SOUND; patch) < miscellany/multi-media/SPARC/SOUND.diff
% cd /usr/demo/SOUND
% make raw2audio
\end{verbatim}
These patches add a {\tt -F} option to the {\tt raw2audio} program,
and add recognition of types for several different audio data formats.

The {\tt raw2audio -F} option strips the header from self-describing audio
data.  This enables you to compose message drafts with {\tt \#audio/basic}.

Be sure to put the audio programs from {\tt /usr/demo/SOUND} into a
directory named in your {\tt \$PATH} environment variable so that the
audio programs can be found if absolute paths aren't used in the
invocations.

Other useful audio programs supplied with later versions of SunOS 4.1
include these:
\begin{comdesc}
\item[/usr/demo/SOUND/x\_gaintool] ---This program allows you to 
fiddle with the volume controls whenever you like.

\item[\$OPENWINHOME/bin/xview/audiotool] ---This program provides
menus and control panels for playing, recording, and editing different
types of self-describing sound files.
\end{comdesc}

The directory {\tt /usr/demo/SOUND/sounds/} contains various
pre-recorded sound files.  The audio files have the extension {\tt
.au}.



\subsection{HP 9000/710}

The HP-Apollo 9000/710 workstation has a telephone-quality audio chip
and an internal speaker.  Newer workstations in the 9000/700 series
may also be equipped for audio; the 9000/720 and 9000/730 models aren't.

HP provides a number of programs in source form that may be used
with {\tt mhn}:
\begin{brieflist}
\item {\tt player} and {\tt splayer};
\item {\tt recorder} and {\tt srecorder}
\end{brieflist}
The directory {\tt /usr/audio/examples/} contains these programs.
The {\tt README} file in that directory documents the various audio
utility programs for recording and playing sounds.  

The programs from {\tt /usr/audio/examples} should be copied into a
directory named in your {\tt \$PATH} environment variable so that the
audio programs can be found if absolute paths aren't used in the
invocations.

Before any of the aforementioned programs can be used, the audio
device files must be created by running {\tt
/usr/audio/bin/make\_audio\_dev}, and two daemons must be started by
the superuser: {\tt /usr/etc/ncs/llbd} and {\tt
/usr/audio/bin/Aserver}.  Refer to the man page Audio(5) for detailed,
step by step instructions on how to do these things.  Alternatively,
refer to the HP publication ``Audio Users Guide'' (HP order number
A1991-90609, November 1991 version).

The audio devices support several ``native'' encodings that vary as to
which of the audio device files is used: one of {\tt
/dev/audio[BEI][ALU]}, where {\tt E}=external jack, {\tt I}=internal
speaker, {\tt B}=both; {\tt A}=8-bit A-law, {\tt L}=16-bit linear,
{\tt U}=8-bit $\mu$-law.  It is possible to {\tt cat} a raw audio data
file of the appropriate type to or from one of these devices. For
example, a raw SPARC audio file may be played by running this command:
\begin{verbatim}
% cat bark.raw >/dev/audioIU
\end{verbatim}
There is also a raw {\tt /dev/audio} device.

(You must create the audio device files before you can cat anything
to them; again, refer to Audio(5) for information on how to do this.)

In HP-UX 8.07, the audio tools, rather than looking for header
information in the sound data, rely on user-supplied information, such
as preferences, file extensions, or command line options, to inform
the tools about the types and sampling rates of the audio data.  This
means that both {\tt audio/basic} and {\tt audio/x-next} can be used,
but you have to use an appropriate file extension or command line
option as follows:

\begin{tabular}{lcc}
{\it type}              & {\it extension} & {\it option} \\
                        &                 &\\

{\tt audio/basic}       & {\tt .u}        & {\tt -u} \\
{\tt audio/x-next}      & {\tt .au}       & {\tt -au}
\end{tabular}

The relevant {\tt mhn} profile entries for recording and playing
audio parts are these:
\begin{verbatim}
mhn-compose-audio/basic:  recorder '%F' -u -pause
mhn-compose-audio/x-next: recorder '%F' -au -pause
mhn-show-audio/basic:     splayer -u
mhn-show-audio/x-next:    splayer -au
\end{verbatim}

In general, HP audio file names have the form 
\begin{quote}
{\it file name}[[.{\it sample rate}].{\it type}]
\end{quote}
where
\begin{tabbing}
{\it sample rate} \= $\rightarrow$ {\it digit}$^{+}$ 000 {\tt |} {\it digit}$^{+}$ k \\
{\it type}        \> $\rightarrow$ \= u {\tt |} al {\tt |} au {\tt |} wav {\tt |} 
                                        snd {\tt |} l8 {\tt |} lo8 {\tt |} l16
\end{tabbing}

The audio types have these meanings:
\begin{tabbing}
\hspace{4em} \= Sun (self-describing format) \hspace{2em} \= \+\kill
$\mu$-law                       \> u \\
A-law                           \> al \\
Sun (self-describing format)    \> au \\
Microsoft RIFF Waveform         \> wav \\
Macintosh                       \> snd \\
Linear8                         \> l8 \\
Linear8Offset                   \> lo8 \\
Linear16                        \> l16
\end{tabbing}

Examples: 
\begin{comdesc}
\item[bark.au] ---a Sun-format ({\tt audio/x-next}) sound file

\item[bark.8000.u] ---a raw $\mu$-law sound file recorded
        at a sample rate of 8000/second.

\item[bark.8k.u] ---same data as in {\tt bark.8000.u}.
\end{comdesc}

As with the SPARC, the default sample rate is 8000/second.

Other useful programs supplied with HP-UX 8.07 are these:
\begin{comdesc}
\item[/usr/audio/bin/audio\_demo] ---This program provides
menus and control panels for playing, recording, and editing different
types of sound files.
The program  also may be used to convert manually among different sound types.
Unfortunately, the {\tt audio\_demo} program
doesn't accept command line arguments, so it isn't quite as suitable
for invocation from {\tt mhn} as are the {\tt player} and {\tt recorder} programs.

\item[/usr/audio/examples/acontrol] ---This allows you to fiddle with the
volume controls whenever you like.
\end{comdesc}


\section{On-Line Resources}
\label{resources}

This section talks about how to obtain some of the documents mentioned
in this tutorial.  

\begin{arrowdesc}
\item[RFC 1341] --- This is the definition of MIME~1.0.  You can obtain it
via anonymous FTP from a number of sites.  Here are two:
\begin{tabbing}
site:\hspace{4em} \=    {\tt ftp.nisc.sri.com} \\
directory:      \>      {\tt rfc}\\
file:           \>      {\tt rfc1341.txt}\\
file:           \>      {\tt rfc1341.ps}\\
mode:           \>      {\tt ascii}\\[\baselineskip]

site:           \>      {\tt wuarchive.wustl.edu}\\
directory:      \>      {\tt doc/rfc}\\
file:           \>      {\tt rfc1341.txt}\\
file:           \>      {\tt rfc1341.ps}\\
mode:           \>      {\tt ascii}
\end{tabbing}

Here is an example of how to obtain the RFC via anonymous FTP from one
site.  Your input is given in {\sl slanted} style, and responses
are in {\tt typewriter} style.
\begin{flushleft}
{\footnotesize\tt \% {\sl ftp ftp.nisc.sri.com}\\
Connected to phoebus.NISC.SRI.COM.\\
220 phoebus FTP server (SRI Version 1.98 Fri Apr 19 11:57:54 PDT 1991) ready.\\
Name (ftp.nisc.sri.com:jsweet): {\sl anonymous}\\
331 Guest login ok, send ident as password.\\
Password: {\it put your e-mail address here, e.g.\ jsweet@irvine.com}\\[\baselineskip]

230 Guest login ok, access restrictions apply.\\
ftp> {\sl cd rfc}\\
250 CWD command successful.\\
ftp> {\sl get rfc1341.txt}\\
200 PORT command successful.\\
150 Opening ASCII mode data connection for rfc1341.txt (211117 bytes).\\
226 Transfer complete.\\
216382 bytes received in 36 seconds (5.8 Kbytes/s)\\
ftp> {\sl quit}\\
221 Be Excellent to one another!
}
\end{flushleft}
There is also a PostScript version of RFC 1341 in the same place; get
{\tt rfc1341.ps}.

RFC 1341 is also available via mail server from {\tt nisc.sri.com}.
To obtain it, send a message like this one:
\begin{verbatim}
To: mail-server@nisc.sri.com
Subject: send rfc1341.txt

send rfc1341.txt
\end{verbatim}


\item[Documents in the MH source tree] include these:
\begin{enumerate}
\item   {\tt papers/tutorial/} (``The Rand MH Message Handling System: Tutorial'')
\item   {\tt papers/realwork/} (``How to process 200 messages a day and still get some real work done'')
\item   {\tt miscellany/multi-media/READ-ME} (MIME program setup information)
\end{enumerate}

The first two documents are in a somewhat less-well-known TeX format, so you may
prefer to obtain the pre-created versions via anonymous FTP:
\begin{tabbing}
site:\hspace{4em} \=    {\tt ftp.ics.uci.edu} \\
directory:      \>      {\tt pub/mh/doc}\\
file:           \>      {\tt tutorial.txt.Z}\\
file:           \>      {\tt tutorial.ps.Z}\\
file:           \>      {\tt realwork.txt.Z}\\
file:           \>      {\tt realwork.ps.Z}\\
mode:           \>      {\tt binary}\\[\baselineskip]
\end{tabbing}

Here is an abbreviated example of how to obtain the papers and also
the MH source tree via anonymous FTP\@.  A more complete FTP example was
shown previously.
\begin{tabbing}
\footnotesize\tt \% ftp ftp.ics.uci.edu\\
\footnotesize\tt Name (ftp.ics.uci.edu.edu:jsweet): {\sl anonymous}\\
\footnotesize\tt Password: {\it put your e-mail address here, e.g.\ jsweet@irvine.com}\\[\baselineskip]

\footnotesize\tt ftp> {\sl binary} \\
\footnotesize\tt ftp> {\sl cd /pub/mh/doc}\\
\footnotesize\tt ftp> {\sl get tutorial.txt.Z}\hspace{4em} \= {\it ---same as papers/tutorial/ above}\\
\footnotesize\tt ftp> {\sl get realwork.txt.Z} \> {\it ---same as papers/realwork/ above}\\
\footnotesize\tt ftp> {\sl cd /pub/mh}\\
\footnotesize\tt ftp> {\sl get mh-6.8.tar.Z}\\
\footnotesize\tt ftp> {\sl quit}
\end{tabbing}
The papers are also available in PostScript format in the same directory;
get {\tt tutorial.ps.Z} and {\tt realwork.ps.Z}.

Other FTP mirror sites, such as {\tt ftp.uu.net}, may also have the
MH sources available for anonymous FTP.

Files whose names end with {\tt .Z} are compressed.  To read them,
use the {\tt uncompress}, {\tt compress -d}, or {\tt zcat} commands.

Files whose names end with {\tt .tar.Z} are compressed files in {\tt tar}
format.
To find out what's in them, use a command like this one:
\begin{verbatim}
% compress -cd mh-6.8.tar.Z | tar tvf -
\end{verbatim}
To extract their contents, use a command like this one:
\begin{verbatim}
% compress -cd mh-6.8.tar.Z | tar xvf -
\end{verbatim}
Note that the vendor-supplied {\tt tar} command on some 
System V systems may require options in addition
to {\tt xvf} in order to permit sub-directories to be
extracted properly when {\tt tar} is being run by
users other than {\tt root}.

You can also get the MH sources on a 6250 BPI 9-track magtape,
along with a printed MH documentation set (not separately available,
except via FTP) by following these directions:
\begin{quote}
Send \$75 US to the address below.  This covers the cost of a 6250 BPI
9-track magtape, handling, and shipping.  Be sure to include your
USPS address with your check.  Checks must be drawn on U.S. funds and
should be made payable to ``Regents of the University of California.''

The distribution address is:
\begin{flushleft}
University of California at Irvine\\
Office of Academic Computing\\
360 Computer Science\\
Irvine, CA\ \ 92717\ \ USA\\[\baselineskip]

telephone: +1 714 856 5153
\end{flushleft}
\end{quote}




\item[mhn(1)] --- This is the on-line manual page for the {\tt mhn} program.
It's part of the MH software installation.  You should be able to read 
it by typing the command {\tt man mhn}.




\item[{\it The Simple Times}] can be obtained in 
any of its various MIME versions.  To get the most up-to-date
information about how to subscribe,
send an e-mail message like this one:
\begin{flushleft}
To: st-subscriptions@simple-times.org\\
Subject: help
\end{flushleft}



\item[USENET news groups] contain useful information about MIME
and MH.  Articles in MIME format are already appearing.  Two
relevant news groups are {\tt comp.mail.mime} and {\tt comp.mail.mh}.

There is also an Internet discussion mailing list related to MH,
to which you can subscribe by requesting information from
this e-mail address:
\begin{flushleft}
{\tt mh-users-request@ics.uci.edu}
\end{flushleft}



\item[Image and video files] are available from many sources.  
For weather maps, use anonymous FTP to site {\tt vmd.cso.uiuc.edu} 
and look in the directory {\tt wx}.  Many other sites offer image files, such 
as {\tt ftp.uu.net}, in these directories (from a brief survey):
\begin{flushleft}
{\tt doc/literary/obi/Soviet.Archives/images} \\
{\tt doc/music/guitar/Led\_Zeppelin} \\
{\tt networking/mail/metamail} \\
{\tt systems/ibmpc/msdos/simtel20/gif}
\end{flushleft}

Site {\tt ames.arc.nasa.gov} has a number of GIF-format space image
files available for anonymous
FTP, such as {\tt toutatis.gif}, four views of asteroid 4179~Toutatis.
The files can be found in the directory {\tt pub/SPACE/GIF}.

Use the FTP {\tt binary} or {\tt type binary} command when obtaining
GIF files.

Alternatively, simply send a message like this one to yourself:

\begin{verbatim}
To: your-address-here
Subject: 4179 Toutatis
-------
#@text/plain [4179 Toutatis info] \
        access-type=anon-ftp; \
        name="toutatis.txt"; \
        directory="pub/SPACE/GIF"; \
        site="ames.arc.nasa.gov"
#@image/gif [4179 Toutatis photos] \
        access-type=anon-ftp; \
        name="toutatis.gif"; \
        directory="pub/SPACE/GIF"; \
        site="ames.arc.nasa.gov"

^D

What now? edit mhn

What now? send
\end{verbatim}

Some MPEG video files are available for anonymous FTP as follows:
\begin{tabbing}
site:\hspace{4em} \=    {\tt toe.cs.berkeley.edu} \\
directory:      \>      {\tt pub/multimedia/mpeg/movies} \\
files:          \>      {\tt *.mpg}\\
mode:           \>      {\tt binary}
\end{tabbing}


GIF, JPEG, and MPEG pictures also appear in some USENET news groups:
\begin{flushleft}
{\tt alt.binaries.pictures} \\
{\tt alt.binaries.pictures.erotica} \\
{\tt alt.binaries.pictures.fine-art.digitized} \\
{\tt alt.binaries.pictures.fine-art.graphics} \\
{\tt alt.binaries.pictures.fractals} \\
{\tt alt.binaries.pictures.misc} \\
{\tt alt.binaries.pictures.tasteless}
\end{flushleft}
Some sites do not have these groups available.



\item[Audio files] are available on SPARCstations running SunOS 4.x 
in the directory {\tt /usr/demo/SOUND/sounds/} (if installed).
HP 9000/710 workstations running HP-UX 8.x do not appear to include
pre-recorded sound files.

Various sound files for different kinds of workstations are often made
available for anonymous FTP.

Sound files and discussions about them are posted to these USENET news groups:
\begin{flushleft}
{\tt alt.binaries.sounds.misc} \\
{\tt alt.binaries.sounds.d}
\end{flushleft}

Be aware that not all sound files are compatible with the MIME
{\tt audio/basic} format, and may require manual conversion.

The Audio File Formats FAQ (frequently asked question and answer
list), maintained by Guido van Rossum, {\tt <guido@cwi.nl>} is posted
periodically in the USENET news group {\tt news.answers}.



\item[Display Programs] are available from various sites on the
Internet.  Some experience may be required to compile the programs.

The {\tt miscellany/multi-media/READ-ME} document in
the MH source tree contains information about how to compile some of
the simpler programs.  The more complicated programs come with their
own documentation.

\begin{comdesc}
\item[gs]       ---This program (aka GhostScript) is a PostScript interpreter,
        capable of displaying PostScript documents on X Window System displays,
        such as those that occur in {\tt application/postscript} message parts.
        You might also want to obtain {\tt ghostview}, an application
        specifically designed for viewing documents with GhostScript.
        {\tt Gs} and {\tt ghostview} are available via anonymous FTP from a
        number of sites; here is one:
        \begin{tabbing}
        site:\hspace{4em} \=    {\tt ftp.uu.net} \\[\baselineskip]

        directory:      \>      {\tt systems/gnu/ghostscript-2.5.2.tar.Z-split}\\
        files:          \>      {\tt part*}\\
        mode:           \>      {\tt binary}\\[\baselineskip]

        directory:      \>      {\tt systems/gnu}\\
        files:          \>      {\tt ghostview-1.3.tar.Z}\\
        mode:           \>      {\tt binary}
        \end{tabbing}

\item[richtext] ---This program displays {\tt text/richtext} message parts
        using whatever simple display attributes are available for your terminal.  
        It's part of the MetaMail software, but it can be compiled and used separately 
        with MH.  MetaMail is available via anonymous FTP from a number of sites; 
        here are two:
        \begin{tabbing}
        site:\hspace{4em} \=    {\tt ftp.uu.net} \\
        directory:      \>      {\tt networking/mail/metamail}\\
        file:           \>      {\tt mm.tar.Z}\\
        mode:           \>      {\tt binary}\\[\baselineskip]
        
        site:           \>      {\tt thumper.bellcore.com}\\
        directory:      \>      {\tt pub/nsb}\\
        file:           \>      {\tt mm.tar.Z}\\
        mode:           \>      {\tt binary}
        \end{tabbing}

\item[rt2raw] ---This is available in the MH source tree.
        It can be used to display message parts of type {\tt text/richtext}.
        It works by stripping richtext formatting commands,
        leaving plain ASCII text.  Look for it in this directory:
        \begin{quote}
        {\tt miscellany/multi-media/misc/}
        \end{quote}
        It's also available as a very short (1 page) C source program in 
        RFC 1341.

\item[mail.weather.ext] ---This perl program uses {\tt mhn} to mail weather
        images as external body parts.  It's described in section~\ref{weather}.
        It's available via anonymous FTP as follows:
        \begin{tabbing}
        site:\hspace{4em} \=    {\tt ftp.ics.uci.edu} \\
        directory:      \>      {\tt mh/contrib/multi-media}\\
        file:           \>      {\tt mhweather.shar}\\
        mode:           \>      {\tt ascii}\\[\baselineskip]
        \end{tabbing}

\item[mpeg\_play] ---This program plays MPEG video files (as in {\tt video/mpeg})
        on X Window System displays.  It's available via anonymous FTP as follows:
        \begin{tabbing}
        site:\hspace{4em} \=    {\tt toe.cs.berkeley.edu} \\
        directory:      \>      {\tt pub/multimedia/mpeg}\\
        file:           \>      {\tt mpeg\_play-2.0.tar.Z}\\
        mode:           \>      {\tt binary}\\[\baselineskip]
        \end{tabbing}

\item[rec.sparc] ---This perl program can be used to make simple recordings
        on a SPARCstation.
        It prompts for a Return to start the recording and then for another
        Return to end the recording.  The {\tt audiotool} program is better,
        but you can get by with {\tt rec.sparc}.  The program is available
        via anonymous FTP as follows:
        \begin{tabbing}
        site:\hspace{4em} \=    {\tt ftp.ics.uci.edu} \\
        directory:      \>      {\tt mh/contrib/multi-media}\\
        file:           \>      {\tt rec.sparc}\\
        mode:           \>      {\tt ascii}\\[\baselineskip]
        \end{tabbing}


\item[xv]       ---This program displays many different kinds of image
        formats on X Window System displays, including GIF (as in {\tt image/gif})
        and JPEG (as in {\tt image/jpeg}).
        {\tt Xv} is available via anonymous FTP from a number of sites; here are two:
        \begin{tabbing}
        site:\hspace{4em} \=    {\tt ftp.cis.upenn.edu} \\
        directory:      \>      {\tt pub}\\
        files:          \>      {\tt xv-2.21.tar.Z}\\
        mode:           \>      {\tt binary}\\[\baselineskip]

        site:\hspace{4em} \=    {\tt ftp.uu.net} \\
        directory:      \>      {\tt pub/window-sys/X/contrib/xv-2.21.tar.Z-split}\\
        files:          \>      {\tt part*}\\
        mode:           \>      {\tt binary}\\[\baselineskip]
        \end{tabbing}
\end{comdesc}

\end{arrowdesc}


\section{Acknowledgements}

Thanks go to Marshall T. Rose of Dover Beach Consulting for
contributing {\it Simple Times} material to this tutorial, for making
comments about this tutorial, for answering my questions, and for
producing the MIME extensions to MH in the first place!

Three persons in the Support Group of the Department of Information
and Computer Science at the University of California, Irvine, were
very helpful: John Romine and David Harnick-Shapiro shared their
thoughts on MH and MIME with me, and provided comments about this
tutorial; Tim Morgan provided pointers to {\tt mpeg\_play}.

A {\tt getweather} shell script, by a gentleman named John Bradley,
provided the inspiration for the weather map mailer program.

Irvine Compiler Corporation provided the computer resources for this
tutorial.


\section{References}
\label{references}

Borenstein, N. and Freed, N., ``MIME (Multipurpose Internet Mail
Extensions),'' June 1992, Bellcore and Innosoft, RFC 1341.

Garfinkel, S. and Spafford, G., {\it Practical UNIX Security},
June, 1991, O'Reilly \& Associates, Inc., ISBN \mbox{0-937175-72-2}.

Krol, Ed, {\it The Whole Internet User's Guide \& Catalog},
1992, O'Reilly \& Associates, Inc., ISBN \mbox{1-56592-025-2}.

Peek, Jerry, {\it MH \& xmh}, 1991, O'Reilly \& Associates, Inc.,
ISBN \mbox{0-937175-64-1}.

Rose, Marshall T. and Romine, John L., {\it The Rand MH Message Handling
System: User's Manual, 6.8 \#1}, December 1992, University of
California, Irvine.

Rose, Marshall T., {\it The Internet Message}, 1993, P T R
Prentice-Hall, Inc., ch. 6., ISBN \mbox{0-13-092941-7}.

van Rossum, Guido, ``FAQ: Audio File Formats (version 2.3),''
July, 1992, USENET {\tt news.answers}.

Vielmetti, Edward, ``Frequently Asked Questions about MIME,''
February, 1993, USENET {\tt comp.mail.mime}.
\end{document}
