\begindata{text,135390848}
\textdsversion{12}
\template{default}
\center{

\bold{Installation Notes for the AUIS-635L1-MAIL Package

}
}

\bold{FOREWARD}


This is another of several planned versions of "packages" of the 
\bold{Andrew User Interface System} (\bold{\italic{AUIS}}).  AUIS can be 
difficult to describe fully since it encompasses such a large variety of 
applications and uses.  In an effort to break this into something more 
manageable, both in size and scope, I have created this particular package 
which is aimed principally at people interested in those who are seeking a 
\bold{MULTI-MEDIA and BETTER MAIL INTERFACE}.  \italic{Messages} was the 
one of the very first MIME-compliant mailers.


This package requires that you have already installed the AUIS Word 
Processing package, auis635L1-wp.tgz.  Do not mix versions (for example, L1 
with L2), as this can result in surprising and undesirable behavior.  This 
document assumes you already have a working mail system.  I assume you 
already can send mail and have something to receive and display mail sent 
to you.  This software will do nothing for you until that works.  Think of 
this software as a better version of "elm" (for instance).


\italic{Messages} is also a MIME mailer.  It was written by the originator 
of the MIME rfc, Nathaniel Borenstein.  With \italic{messages} you can mail 
pictures and text with fonts to others who have MIME-compliant mailers.  \



Be forewarned.  The \italic{messages} program is \bold{NOT} fully 
compatible with other mailers lile elm.  It saves mail you receive as 
separate (and indexed) files in $HOME/Mailbox, rather than in a single file 
in $HOME/Mail (more on this elsewhere in the document).


You may be interested in a series of articles on AUIS that appeared in the 
Linux Journal in August 1994.


\flushright{Terry Gliedt	\


tpg@cans.com  \


}

\bold{INSTALLATION}


This packaged is distributed as a single tar file of approximately 2.3 MB 
which will expand to approximately 5.3 MB of ADDITIONAL disk space over 
that required for the word processing package.  To install this package, do 
the following as root:


\indent{cd /

tar xzf [path]/auis635L1-mail.tgz

/usr/andrew/etc/complete-setup mail

}
This will add files to \italic{/usr/andrew} that you created earlier with 
the -wp package.



\bold{USING MESSAGES}


This assumes you already know your way around \italic{ez} - because the 
\italic{messages} program uses precisely the same menu-scheme, scroll-bars 
etc.


You MUST also have a working mail system already in place.  If you do not, 
get it working \bold{FIRST} and \bold{THEN} try out \italic{messages}. 
 Messages will not magically start making your e-mail work for your system. 
 In particular this means the /etc/sendmail command works as expected.


\bold{Your First Multi-Media Mail}


I know you're anxious to try your first multi-media mail, so we have 
something all set up for you.  Do the following:


	mkdir $HOME/Mailbox

	cp /usr/andrew/lib/Hello $HOME/Mailbox/mbox \


	cp /usr/andrew/lib/Hello2 $HOME/Mailbox/mbox2


There is a pre-canned folder which demonstrates various aspects of 
\italic{messages}.  To see these in action, do the following:


	/usr/andrew/etc/gendemo -force ~/.MESSAGES/amsdemo

	cd /usr/andrew/.MESSAGES/demo

	tar cf - . | (cd ~/.MESSAGES/amsdemo; tar xf -)


Hold on to your chair and now enter:


	/usr/andrew/bin/messages

	Select "Expose All" on the "Messages Folders" menucard

	Click on the "amsdemo folder"



\bold{Further Information on Messages}



Enter "\bold{auishelp messages}" in your \italic{xterm} for help on the 
mail system.


AUIS applications are highly tailorable for your personal needs and 
preferences.  This is especially so for the mail application, 
\italic{messages}.  After you become accustomed to \italic{messages}, you 
will want to begin enabling some of the options it provides. 
 \italic{Messages} provides its own interface for setting preferences. 
 Begin by selecting the \italic{Set Options} menu item on the \italic{Other} 
menu card.  \italic{Messages} will write the preference settings you select 
to your $HOME/preferences file.


Using \italic{messages} does not prevent you from sending mail with any 
other program or receiving mail with another program.  The only difference 
is that once you \italic{\bold{receive}} mail, the two mailers 
(\italic{messages} and \italic{elm}, for instance) will not know about the 
mail the other received.



\bold{NOW WHAT'S THIS ABOUT COMPATIBILITY?}


\italic{Messages} is part of a very complex set of software called the 
Andrew Message System (AMS).  This has the ability to act as a news reader, 
has support for bulletin boards and can deliver mail directly to other 
Andrew File System cells (without using \italic{sendmail}).  Most of this 
function has been disabled in the version you have here.


The reason for telling you this all is that in doing all this, the original 
designers chose to not keep \italic{messages} compatible with 
\italic{mail}/\italic{elm} mailers with respect to its database.  In 
conventional Un*x mailers (e.g. mail) when mail is received, it is stored 
in /usr/spool/mail/$USER as a conventional "flat" file.  All the mail is 
mashed together as one physical file.  Its up to the mailer to sort these 
out. This works fine when the file is small, but when you have 100 pieces 
of multi-media mail, each 50K in size, it starts getting unwieldy and slow.


Now when you invoke your mailer (e.g. \italic{elm}), the mailer shows you 
whats in /usr/spool/mail/$USER.  When you save the mail to a folder, the 
mail is appended to some file in $HOME/Mail  (e.g. ~/Mail/tpg in my case). 
Just as with the mail in /usr/spool/mail, this is also a simple file with 
many logical files (pieces of mail) in it.  It will suffer even more from 
performance problems as you keep more and more mail around.


In the world where AUIS was developed, it is not unusal for one to have 
thousands of pieces of mail (and large multi-media mail at that). So 
another, incompatible approach was taken.  Messages keeps each individual 
piece of mail as a separate file in a folder (i.e. directory) and builds an 
index so it can quickly show whats in the folder. Each of these folders is 
kept in the directory $HOME/.MESSAGES.  When you file a piece of mail in a 
"folder", it really is saving the mail as a file in a directory under 
$HOME/.MESSAGES.



\bold{SWITCHING to MESSAGES}


After you've tried \italic{messages} for a little bit, you might want to 
"convert" your existing mail to \italic{messages}.  Here's a technique I 
have found workable.  Now be careful here! This is not guarenteed to work 
in all cases. It worked for me.  Be careful.  If you don't erase any files, 
the worst case is that you will mess up some copies of mail.  Here's the 
approach I have used:


\bold{Goal}:  Get mail I have received from \italic{elm} into 
\italic{messages}


\indent{\italic{Elm} saves my mail in the folder $HOME/Mail/$USER (or 
unread mail in $HOME/Mail/received). This looks pretty much like it did 
when it was originally in /usr/spool/mail/tpg.  So the trick is to copy it 
there and tell \italic{messages} to read the "new" mail.


\description{1. Be sure no mail is in /usr/spool/mail/$USER.  This should 
be a file of zero bytes.


2. cp $HOME/Mail/$USER /usr/spool/mail/$USER


3. Select "Read Mail" on the "messages" menu card.  This will copy the mail 
from /usr/spool/mail to $HOME/.MESSAGES/mail and show you the "new" mail. 
Just like it just arrived the first time.

}}

\bold{Goal}:  Get mail I have received by \italic{messages} back to 
something \italic{elm} understands


\indent{\italic{Elm} saves my unread mail in $HOME/Mail/received as one 
large file (just like it was in /usr/spool/mail/$USER).  \italic{Messages} 
has saved my mail in some folder like $HOME/.MESSAGES/mail as a set of 
individual files.  These files all have strange names (since you are 
normally not supposed to even look at these, that's as expected).  So 
suppose you want to "convert" all of these back to \italic{elm}? The trick 
is to copy the individual files to $HOME/Mail/received in the right format.


\description{1. Be sure no mail is in /usr/spool/mail/$USER.  This should 
be a file of zero bytes.


2. Copy the files to /usr/spool/mail/$USER with something like the 
following:


\example{/bin/csh

cd $HOME/.MESSAGES/mail

foreach f (*)

  echo $f

  echo "From dummy Sat May 28 11:32:01 1994" >> /usr/spool/mail/$USER

  cat $f >> /usr/spool/mail/$USER

  echo "" >> /usr/spool/mail/$USER

end

}
3.  Invoke \italic{elm} (or whatever your mail reader is) and with any 
luck, they will all be recognized.

}}
Hopefully these notes will make you more comfortable with trying another 
mailer.  As long as you do not delete any mail (in either \italic{elm} or 
\italic{messages}), you still have it.  Give it a try.  I think 
\italic{messages} is by far the best mailer I have seen and I hope you'll 
agree. \




\bold{CHANGELOG}


Release auis635L1-mail has the following changes:


\indent{- This was built on Slackware 3.0


- This version uses ELF format binaries and libaries


- This version requires XFree 3.1 shared libraries


- Now based on AUIS 6.3.5


}Release auis63L4-mail has the following changes:


\indent{- This was built on Slackware 2.1.0


- This version requires XFree 3.x shared libraries


- Functionally this has almost nothing new compared to auis63L3-mail


}Release auis63L3-mail has the following changes:


\indent{- This was built on Slackware 2.0.1


- This version requires XFree 2.x shared libraries


- Now based on AUIS 6.3.1 - which has only fixes to 6.2.

}
Release auis63L2-mail has the following changes:


\indent{- Contains a very few fixes to AUIS 6.3.1


- This was built on Slackware 2.0

}
Release auis63L1-mail has the following changes:


\indent{- Contains a very few fixes to AUIS 6.3


- This was built on Slackware 2.0


- Messages will no longer fail with some MIME mail.

}
Release auis63L0-mail has the following changes:


\indent{- Now based on AUIS 6.3


- An animator object called \italic{fad} is available in this package.  I 
did not have room in the -wp package and still be able to keep the tgz file 
small evough to fit  on one diskette.


- Minor changes made to some menus


- UseNewShadows enabled to provide better shadowing in scrollbars


- MIME mailcap supports TIFF now

}

\bold{SOME THINGS YOU MIGHT LIKE TO KNOW}

\description{
If you use some sort of POP server, you might want to configure 
\italic{messages} to call your POP client code (to fetch your mail) 
directly.  This can be done by setting the \bold{AMS_MailCollectionCommand} 
entry in \italic{/usr/andrew/etc/AndrewSetup}. An example of what this 
shell might look like follows (your mileage may vary):


\indent{#!/bin/csh

#

#	Bring up slip if need be

#	Get whatever mail is queued for me

#	Invoke pgm to copy from /usr/spool/mail/$USER to $HOME/Mailbox

#

if (! -e /etc/dip.pid) then	# First time, bring up SLIP if you can

  /usr/local/bin/slipup

endif

#	Check if SLIP is up now.  If not this time, exit with error,

#	causing messages to generate a somewhat-bogus-looking error

if (! -e /etc/dip.pid) then

  echo "SLIP connection failed."	\


  exit 2

endif

sleep 2 		# Just give it a little bit of time


#	Get mail from SLIP server

#	Option -v is verbose; -c put data to stdout; -k keep mail at MR.NET

/usr/local/bin/popclient -3 -o /usr/spool/mail/$USER -u slipuserid -p 
slippasswd sliphost.domain


#	Last step, Get mail into $HOME/Mailbox

/usr/andrew/bin/eatmail

}

Now that you are into multi-media mail, you might want to follow the 
newsgroup comp.mail.mime.


If you try \italic{messages} and get the error message "There are no 
messages in your incoming mailbox.", then you do not have /usr/andrew/bin 
on your PATH or your PATH is set up so that /usr/bin/messages is found 
before /usr/andrew/bin/messages.


\italic{Messages} has lots and lots of very useful options. Be sure to 
select Other ->Set Options and look at all the options.  Give serious 
consideration to enabling "Keystroke commands", "Basic folder 
menus/features", "File into...menus", "Hide after sending", "Clear after 
sending", "Sign mail", and "Hide by Vanishing". \



When you first bring up mail, if you get an error dialog box with the 
message "\italic{Messages in ...../Mailbox could not be properly read and 
delivered (.....))}", then be sure to check the permissions of 
\bold{/usr/spool/mail/$USER}.  This should be owned and writable by you 
(not \italic{root}).  This is because \italic{messages} runs under your 
authority and it tries to remove this file (after copying the data). If 
this fails, messages \italic{generates} the error you see.


When you first bring up mail, if you get an error dialog box with the 
message "\italic{Messages in ...../Mailbox could not be properly read and 
delivered (.....))}", then the problem is that you have a "\italic{set 
hold}" in your \bold{/usr/lib/Mail.rc}. You may edit this file and remove 
it, or If you do not want to modify \bold{Mail.rc}, you can add the line 
"unset hold" to your \bold{$HOME/.mailrc}.


One of the things that MIME's \italic{metamail} will be looking for is a 
"mailcap" entry.  This tells \italic{metamail} what to do with various 
kinds of data.  A sample mailcap file can be found in 
\bold{/usr/andrew/etc}.  You should copy this to 
\italic{\bold{$HOME/.mailcap}} or \italic{\bold{/etc/mailcap}}.  See 
"a\italic{uishelp mime}" for more details.


If you have audio support on your system and want MIME to properly handle 
\bold{audio insets}, you will likely need to modify 
\italic{\bold{/usr/andrew/bin/showaudio}}.  Once you have this working, 
please tell me what you did so I can consider providing it to others.


The MIME \italic{metamail} command will invoke \italic{xv} for tiff insets. 
To change this modify the \bold{mailcap} file mention above.


Using \italic{efax} 0.6 and some simple shell scripts, its pretty easy to 
receive a fax and have it converted into MIME mail.  Contact the author for 
some details if you are interested in pursuing this further.


If you build your UCB \italic{sendmail} with the ``DBM'' option set, 
aliases in \bold{/usr/lib/aliases} are case-sensitive; if you build it 
without that option, they're case-insensitive. For purposes of validating 
user names, \italic{Messages} assumes that aliases in 
\bold{/usr/lib/aliases} are case-insensitive. This might mean that a name 
that validates OK with AMS might be rejected by UCB \italic{sendmail}, if 
that \italic{sendmail} uses DBM to do its alias lookup.


You might be interested in always using MIME format for your mail. Issue 
the command "auishelp preferences" and check out the entries under 
\bold{mailsendingformat}. \



You can automate the reply-to header insertion down to one keystroke.  For 
example create a $HOME/messages.init file and add this line (changing the 
reply-to field of course):


\example{addkey sendmessage-add-header ^Xr sendmessage sendmessage inherit 
"reply-to: robr@cmu.edu"

}
\indent{And now when you are composing mail, all you need do is press 
"control-x" plus an "r" and the header will be inserted in your message.

}
As configured for this package, \italic{messages} can compose mail from 
either "\italic{uid@host.domain}" or "\italic{uid@domain}".  The software 
defaults to the "\italic{uid@host.domain}" format. Look at 
/usr/andrew/etc/AndrewSetup for the \italic{ThisDomain} and 
\italic{ThisDomainSuffix} keywords


Messages can't be directly used as a replacement for news.  At CMU they 
have invented an elaborate process to convert news articles into folders 
for messages. It's not a simple task - and I have never gotten anyone to 
reveal the secrets.  So for mere mortals, messages remains a MAIL system.

}

\bold{Sending MIME mail}


When you send mail with messages, you have the choice to send the mail in 
MIME format. But just how do you get unusual data into the mail body?  The 
answer is that you use insets - as with everything else in AUIS. One 
serious deficiency is that you can't easily know what inset you need. 
Select Media -> MIME to insert a mailobj inset.


This presents you with a button labelled "Push Me". Click on the button and 
you will begin a dialogue. First you are asked for the filename. Then you 
get an obscure prompt "Content/type:". This wants you to enter the MIME 
keyword which describes the type of data. You probably want to use one of 
the following:


\indent{text/plain	if its just plain text

application/octet-stream	if it is real binary data

image/gif	if it is a GIF image

image/tiff	if it is a TIFF image etc.

audio/basic	if it is an audio stream

}
You can also specify the name of the flle to be created at the Content/type 
prompt with something like this:


	application/octet-stream ; name="test.tar.gz"


When the file is received at the other end, it will be saved in /tmp as 
/tmp/test.tar.gz.


Finally you are prompted for "Content Description:", which becomes the 
label of the button as you see it in the mail message.


That's it. Send your mail in MIME format and it should work with all the 
other MIME-compliant mailers you find.



\bold{DISCLAIMER}


Permission to use, copy, modify, and distribute this software and its 
 documentation for any purpose is hereby granted without fee,  provided 
that the above copyright notice appear in all copies and that  both that 
copyright notice, this permission notice, and the following  disclaimer 
appear in supporting documentation, and that the names of  IBM, Carnegie 
Mellon University, and other copyright holders, not be  used in advertising 
or publicity pertaining to distribution of the software  without specific, 
written prior permission.


IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS  DISCLAIM 
ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING  ALL IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT  SHALL IBM, CARNEGIE 
MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER  BE LIABLE FOR ANY 
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY  DAMAGES WHATSOEVER 
RESULTING FROM LOSS OF USE, DATA OR PROFITS,  WHETHER IN AN ACTION OF 
CONTRACT, NEGLIGENCE OR OTHER TORTIOUS  ACTION, ARISING OUT OF OR IN 
CONNECTION WITH THE USE OR PERFORMANCE  OF THIS SOFTWARE.

\enddata{text,135390848}
