
           Installation Notes for the AUIS-635L1-MAIL Package



FOREWARD

This is another of several planned versions of "packages" of the Andrew
User Interface System (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 MULTI-MEDIA and BETTER
MAIL INTERFACE.  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).

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

Be forewarned.  The messages program is 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.

                                                            Terry Gliedt	
                                                           tpg@cans.com  


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:

    cd /
    tar xzf [path]/auis635L1-mail.tgz
    /usr/andrew/etc/complete-setup mail

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


USING MESSAGES

This assumes you already know your way around ez - because the 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 FIRST and THEN try out 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.

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
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"


Further Information on Messages


Enter "auishelp messages" in your 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, messages. 
After you become accustomed to messages, you will want to begin enabling
some of the options it provides.  Messages provides its own interface
for setting preferences.  Begin by selecting the Set Options menu item
on the Other menu card.  Messages will write the preference settings you
select to your $HOME/preferences file.

Using 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 receive mail, the two mailers (messages and elm, for
instance) will not know about the mail the other received.


NOW WHAT'S THIS ABOUT COMPATIBILITY?

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 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 messages compatible with mail/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. 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.


SWITCHING to MESSAGES

After you've tried messages for a little bit, you might want to
"convert" your existing mail to 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:

Goal:  Get mail I have received from elm into messages

    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 messages to read the "new" mail.

    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.


Goal:  Get mail I have received by messages back to something elm understands

    Elm saves my unread mail in $HOME/Mail/received as one large
    file (just like it was in /usr/spool/mail/$USER).  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 elm? The trick is to copy the individual files to
    $HOME/Mail/received in the right format.

    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:

            /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 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 elm or
messages), you still have it.  Give it a try.  I think messages is by
far the best mailer I have seen and I hope you'll agree. 


CHANGELOG

Release auis635L1-mail has the following changes:

    - 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:

    - 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:

    - 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:

    - Contains a very few fixes to AUIS 6.3.1

    - This was built on Slackware 2.0

Release auis63L1-mail has the following changes:

    - 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:

    - Now based on AUIS 6.3

    - An animator object called 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


SOME THINGS YOU MIGHT LIKE TO KNOW

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

        #!/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 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.

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 "Messages in ...../Mailbox could not be properly read
    and delivered (.....))", then be sure to check the permissions of
    /usr/spool/mail/$USER.  This should be owned and writable by you
    (not root).  This is because messages runs under your authority and
    it tries to remove this file (after copying the data). If this
    fails, messages generates the error you see.

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

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

If you have audio support on your system and want MIME to properly
    handle audio insets, you will likely need to modify
    /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 metamail command will invoke xv for tiff insets. To change
    this modify the mailcap file mention above.

Using 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 sendmail with the ``DBM'' option set, aliases
    in /usr/lib/aliases are case-sensitive; if you build it without that
    option, they're case-insensitive. For purposes of validating user
    names, Messages assumes that aliases in /usr/lib/aliases are
    case-insensitive. This might mean that a name that validates OK with
    AMS might be rejected by UCB sendmail, if that 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 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):

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

        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, messages can compose mail from
    either "uid@host.domain" or "uid@domain".  The software defaults to
    the "uid@host.domain" format. Look at /usr/andrew/etc/AndrewSetup
    for the ThisDomain and 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.


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:

    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.


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.
