**************************************************************** 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 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/-