****************************************************************
Copyright (c) 1991 Bell Communications Research, Inc. (Bellcore)

Permission to use, copy, modify, and distribute this material 
for any purpose and without fee is hereby granted, provided 
that the above copyright notice and this permission notice 
appear in all copies, and that the name of Bellcore not be 
used in advertising or publicity pertaining to this 
material without the specific, prior written permission 
of an authorized representative of Bellcore.  BELLCORE 
MAKES NO REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY 
OF THIS MATERIAL FOR ANY PURPOSE.  IT IS PROVIDED "AS IS", 
WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
****************************************************************

I. INTRODUCTION

This is a tree of files that will build the metamail program, which can
be used to turn virtually any mail-reading program into a multimedia
mail reader, as well as programs that will allow metamail to display
several specific types of multimedia mail.

Metamail is an implementation of MIME, the Multipurpose Internet 
Mail Extensions, a proposed standard for multimedia mail on the Internet.
Metamail implements MIME, and also implements extensibility and
configuration via the "mailcap" mechanism described in an informational
RFC that is a companion to the MIME document.

II. BUILDING METAMAIL

To compile metamail and a few useful applications, just type "make" in 
the top-level directory.  Note that you may need to change the line in 
the top-level Makefile that defines the ATOMICMAIL constant.  
This should be the empty string if you have the metamail distribution 
WITHOUT the ATOMICMAIL software, and should be set to
"atomicmail" if you have the fuller, more proprietary distribution.

II.a.  SITE CONFIGURATION

There are a few things that are site-configurable before the build.
If you want to check them over, look in "config.h" in the top-level 
directory.  Also, if you need to change the CFLAGS Makefile variable,
you can just change it in the top-level Makefile and it will propogate
to the subdirectories as long as you always do a top-level make instead
of cd'ing to a subdirectory and typing make.  Similarly, you can change 
the LDLIBS variable in the top-level Makefile and it will be passed 
down automatically.    LDLIBS may be necessary in order to get the 
gethostname() call to compile, in particular.  Users of System V or
other systems without symbolic links should also remove the "-s"
from the definition of "LN" in the top-level Makefile.  If you're using
the non-ASCII fonts from the fonts directory, and you plan to install
them in a system font directory, you'll probably want to change the value
for MYFONTDIR in each of the '*.source" files in the "fonts" directory.

If you're using a version of UNIX that is System-V based but doe not 
define "SYSV" as a C preprocessor constant, you'll need to add the line 
"#define SYSV" near the top of config.h.  (One notable operating system 
in this category is some versions of AIX.   However, config.h will 
automatically turn on "SYSV" if "AIX" is defined, as it is in recent 
releases of AIX.)

Finally, if you have the distribution that includes the ATOMICMAIL system, 
there is a file called "site.h" in the top-level ATOMICMAIL directory, 
in which further customization is possible.

II.b.  THE DIRECTORY STRUCTURE

Although you probably don't need to know such details, the distribution comes 
with 4 or 5 source directories:  "metamail" contains the metamail
program itself.  "richmail" contains the programs for dealing with
email's "richtext" format.  "ezview" contains a simple program for
transforming Andrew-format mail to plain text.  "fonts" contains data
and scripts for display non-ASCII mail bodies, about which more is 
said in a special section below.   "misc" contains a 
number of shell scripts for viewing images, audio, partial messages,
external messages, etc., and rudimentary shell scripts for SENDING
non-text mail.  Finally, if you have the version of the distribution that
includes the ATOMICMAIL software, this is contained in the
"atomicmail" subdirectory.

III.  INSTALLING THE METAMAIL BINARIES

The easiest way to build the system is "make install-all".  This should 
install everything except the mailcap file in a reasonable place if you've 
set the INSTROOT variable to point where you want the installation to be done.

For convenience, the make process installs SYMBOLIC 
LINKS to all the needed binaries (or copies, in the case of shell 
scripts) in the top-level "bin" directory, and man entries in the 
top-level "man" directory.  

IV.  YOUR MAILCAP FILE

You'll also need to install a mailcap file.  A prototype mailcap file is 
included in the top level directory, but you might want to modify it 
(see metamail.1 for details about mailcap files).  

By default, the mailcap file should be installed in either /etc or 
/usr/etc/ or /usr/local/etc.  However, you can easily 
change this default location in the metamail source code.
(This code is found in metamail/metamail.c.)

The Makefile is set up so that "make install-all" will install the prototype 
mailcap file in $INSTROOT/etc, but this is unlikely to be both the ideal 
makefile and the ideal location at many sites.

For testing purposes, on UNIX, you can install the mailcap file in your home 
directory under the name ".mailcap".

If you have acquired the version of the metamail distribution that includes 
the Bellcore "ATOMICMAIL" software, you should uncomment the appropriate 
line in the prototype mailcap file in order to make it work.

V. MODIFYING YOUR MAIL-READING PROGRAMS

The hardest part of metamail installation, by far, is the modification of 
your local mail-reading programs to make them use metamail for non-text 
mail.  This has been done for over a dozen of the most commonly-used 
UNIX mail reading programs.  An explanation of how to modify these mail
readers can be found (in various formats) in the file(s) mailers.txt.

Once you have installed all the binaries AND the modified versions of 
the mail-reading programs, you should have a very extensible multimedia 
mail system installed at your site.  Metamail and related software are 
discussed on the INFO-METAMAIL mailing list.  If you want to sign up for this
mailing list, send mail to info-metamail-request@thumper.bellcore.com.
If you do not wish to join the mailing list, but you DO want to know about 
future releases of metamail, please send mail indicating this interest to 
Nathaniel Borenstein <nsb@bellcore.com>

VI.  The "fonts" directory.

The fonts directory contains software for non-ASCII mail.  It initially only
supports ISO-8859-8 (Hebrew) and an alias for a fairly common Adobe
font that supports ISO-8859-1 (W. Europe), but also provides a template for
how other character sets can be supported, given the right fonts.  NOTE THAT
 IF YOU DO NOT USE X11 THE "fonts" DIRECTORY IS USELESS, AND 
THAT IF YOU DO NOT HAVE "bdftosnf" INSTALLED THE BUILD
MAY FAIL IN THE FONTS DIRECTORY.  FOR NON-X SITES, IF
YOU GET RID OF ANY REFERENCE TO IT IN THE TOP LEVEL 
MAKEFILE, IT WILL NEVER GET IN YOUR WAY. 

Note also that the "fonts" directory builds but does not install the snf, 
fonts.alias, and fonts.dir files.  It builds a fe scripts that make
reference the build directory.  If you are installing things elsewhere,
you will need to change the path reference in the "*.source" scripts
(the MYFONTDIR variable) if you want non-ASCII mail to work properly.

VII.  FUTURE VERSIONS OF METAMAIL

The metamail software is being given away freely by Bellcore in the
interest of promoting a wide user community for the emerging
Interent standards for multimedia mail.  The metamail software is by
no means a finished product, nor is it as polished as software
produced for commercial purposes.  It is our hope that users will
be tolerant of any warts they may find, and will contribute their
own improvements, via the INFO-METAMAIL mailing list, for incorporation
into future releases of the metamail software.

VIII.  TESTING METAMAIL & MIME SUPPORT

If you want a set of test messages in MIME format, exercising various 
features of mtamail and MIME, you may ftp them from thumper.bellcore.com,
where there is a directory called "pub/nsb/samples".  Each file in
that directory is a separate MIME-compliant message which should
do something interesting if viewed with a metamail-modified mail-reader.

IX.  FURTHER DOCUMENTATION

Drafts of the MIME and mailcap documents are available in the
pub/nsb directory on thumper.bellcore.com.  Other documents may also
become available from time to time in that directory -- feel free to 
browse.

The anonymous ftp directory from thumper is mirrored for the
Scandinavian countries on  ftp.funet.fi, where it can be found in
 /pub/unix/mail/metamail/-
