            POPwatch v0.20 (c)1997 Gary A. Priest
            -------------------------------------

Welcome to POPwatch for the Atari ST/STE/TT/Falcon and compatibles.

POPwatch is a POP3 mailbox tool for use with STiK and a POP3 mailbox.

Using POPwatch, you can see at a glance how much mail is in your
POP3 mailbox, delete any unwanted emails, view part of the email 
without downloading the whole thing, or download selected emails onto 
your Atari for use in your current mail client. 
Currently Oasis2, NEWSie, and NOS (with or without Oasis1.xx) are 
supported.
POPwatch also has a Kill File facility for the automatic deleting of 
emails that meet a specified criteria.
 
Thus it is now possible check your email *before* downloading it, and 
without having to make a connection via NOS or ICE. You can now 
download your email whilst browsing the web, for instance.

It is not meant to be a full mail client, ie. you cannot edit emails, 
post replies etc. It is meant to complement your existing email client 
and offers features not found in them.

This version of POPwatch is FREEWARE. See details at the end of
this document.


CONFIGURING POPWATCH
--------------------

Edit User Preferences.
----------------------
This is where you define such things as the POP3 mail server, account 
name and password. These fields should be self explanatory.

Password is not mandatory, and if not specified, POPwatch will request 
the entry of a password when attempting to connect to the POP3 server.

Retrieval Format
----------------
POPwatch can retrieve email in one of three formats;
Oasis2, NEWSie, and NOS (also used by Oasis1.xx)
Select which one applies to your existing email client.

Path
----
This is the path that the email should be retrieved into.

eg. Oasis2 \OASIS2\INCOMING\
    NEWSie \NEWSIE\MAIL\
    NOS    \NOS\SPOOL\MAIL\ or OASIS\SPOOL\MAIL\

Leave Mail on Server
--------------------
If set to YES, POPwatch will leave the email on the POP3 server after 
it has retrieved it.

If set to NO, POPwatch will DELETE the email from the POP3 server 
after it has retrieved it.

Until you are familiar with the operation of POPwatch, I suggest that 
you leave this set to YES, and manually delete the emails. Just in 
case.

Save User Preferences
---------------------
This saves the current user preferences. You can choose the filename 
(although it should end in .prf). Thus you can have gary.prf for 
Gary's email account, and fred.prf for Fred's email account.
Or one for retrieving into NEWSie, and one for Oasis2 etc.

Load User Preferences
---------------------
This loads a user preference file. Obvious really :)

Edit Program Preferences
------------------------
Program Preferences allows you to set various options that are not 
user specific, but program specific.

Default User
------------
Clicking on this field will allow you to select whichever user 
preference file you wish POPwatch to load in when it starts up.
User preference files are named *.prf

Multitasking
------------
POPwatch can run in either multitasking or non-multitasking mode.

In multitasking mode, POPwatch checks for window events and allows 
other programs to have processor time (by relinquishing processor 
time via appl_yield). Ideal for multitasking operating systems such as 
MagiC. 

In non-multitasking mode, the program does no appl_yields and does not
check for window events etc. Thus it can spend all it's time 
downloading data (should be faster). Ideal where multitasking is not 
important but speed is.

Save Program Preferences
------------------------
This saves the current settings from the Edit Program Preferences 
window.

It also saves the current positions of all POPwatch's windows.


USING POPWATCH
--------------

1. Connect to your ISP with STiK.

2. Run POPWATCH.PRG

3. Select 'Connect', and POPwatch will log on to the specified POP3 
   mail server and retrieve details of any mail that exists in the 
   specified account. The kill file will also be checked and any 
   emails that match kill criteria will be killed.

4. Now you can select multiple emails, and process them as follows:

   a) Delete them.
      They are only physically deleted from your POP3 account when
      you DISCONNECT, until then you can 'undelete' them using the
      menu option 'abandon deletes'.

   b) Retrieve them.
      The emails will be fetched from your POP3 mailbox and
      downloaded to your Atari in whichever format is specified in
      the current user preferences.
      If the 'Leave Mail on Server' setting in preferences is NOT set, 
      then the mail will be deleted from the server after successful
      downloading of the email.

5. Double clicking on a particular email, will retrieve the header and 
   first 20 lines of that email, and display them in a window.
   This is useful if you just want to see *part* of the email, before 
   downloading it all or deleting it.
   
6. Disconnect from your Pop mailbox, using 'Disconnect'. Quitting the 
   program does this automatically.


ACCESSING THE RETRIEVED EMAIL
-----------------------------

Oasis2
------
Once retrieved, POPwatch creates the necessary MAIL.IN and MAIL.IDX 
files in the defined retrieval path ie. \OASIS2\INCOMING\
When you next run Oasis2 and select the PostBox menu option, Oasis2 
will automatically 'index' the retrieved mail just as if it had been 
downloaded using ICE.
Demon users will find the email is allocated to the correct user.
NON Demon users may not be so lucky because POPwatch has to rely on 
the 'To' address in the header field (which could be anything).
In this case, Oasis2 will ask you what you want to do with each email.

NEWSie
------
Once retrieved, POPwatch creates the necessary MAILxxxx.TXT and 
INBOX.MBX files in the defined retrieval path ie. \NEWSIE\MAIL\
When you next run NEWSie and open your IN Box, the emails are there 
ready and waiting.

NOS using Oasis1.xx
-------------------
Once retrieved, POPwatch creates the necessary nnnnnnnn.txt 
(where nnnnnnnn is the To: user) files in the defined retrieval path
ie. \SPOOL\MAIL\
When you next run Oasis1 and select the PostBox menu option, Oasis1 
will automatically 'index' the retrieved mail just as if it had been 
downloaded using NOS.
Demon users will find the email is allocated to the correct user.
NON Demon users may not be so lucky because POPwatch has to rely on 
the 'To' address in the header field (which could be anything).
In this case, it may be necessary to set up the relevant user in 
Oasis1, before being able to view the email.


KILL FILE PROCESSING
--------------------
The Kill File allows POPwatch to automatically delete any emails that 
match specified criteria. eg. any with a subject containing '$' etc.
The emails will be flagged in the POPwatch window, with a 'K' as 
opposed to the normal deleted flag of 'X'. POPwatch will sound the 
system bell each time it kills an email as an audible warning.
Killed emails will also be shown in red instead of the usual black.

As with 'deletes' the kills are not made permanent until you 
disconnect, so you can still change your mind by using 'Abandon 
Deletes' from the menu *before* Disconnecting.


MAINTAINING THE KILL FILE
-------------------------
POPwatch expects the kill file to be called KILL.TXT and looks for it 
in the same folder as POPWATCH.PRG.
This is a standard ASCII file (each line must end with a CRLF).
The file can either be maintained manually using a text editor, or 
via the 'Add to Kill File' menu option. This menu option will present 
the 'Add to Kill File' window. If no messages were selected when this 
option was taken, the fields will be blank. If multiple messages were 
selected at the time, then a window will be presented containing the 
details from each selected message in turn.
The Subject, From and To input fields can be altered and when you are 
happy that this is what you want added to the kill file, click Add.
NB. Empty strings will *not* be added to the kill file.

Each line in the file should consist of the following:

   <type><SPACE><string><CRLF>

where <type> is:

   F   Kill on the From: field
   T   Kill on the To: field
   S   Kill on the Subject: field

and <string> is the kill string which is *not* case sensitive.
   
eg. 

   S For Sale
   F stik@the-gap
   
Will kill any emails that contain the text 'For Sale' *anywhere* in the 
Subject line, and any emails that contain 'stik@the-gap' *anywhere* in 
the From field.

Make sure that you only define sensible kill strings. Defining one of 
's' would kill any emails that contain 's'. Not very clever or useful.
So take care when using this feature.


DEMON USERS
-----------
For users of Demon Internet's POP3 service, POPwatch uses the 
following extra facilities of this service:

a) multiple mailboxes. If you just want to see what mail is waiting 
   for sue@the-gap.demon.co.uk then prefix the host name with the user 
   name ie. in preferences, set account to sue@the-gap.
b) Use of *ENV. This is a Demon specific command and requests the SMTP 
   envelope of an email. This is much more specific than the use of 
   the header fields 'from' and 'to'. Thus your mail get's routed 
   to the correct user in Oasis2 and NOS.


LOGGING CONVERSATION
--------------------
Turn on logging by selecting the 'Logging' menu item. This will then 
produce a log popwatch.log of the conversation with the server.
This may help me find any bugs if you have problems.


THE ABOUT WINDOW
----------------
Both the email address and the URL can be selected and copied to the 
GEM clipboard via (CTRL C or CTRL Insrt). This allows them to be 
pasted into any programs that support 'pasting' into their fields such 
as CAB. Saves all that typing!

For people who are really lazy, try double clicking on them.
A browser or mailer can be launched and passed a mailto: or http: url
eg. if you are ONLINE at the time, the web browser will go straight 
to my web site. Or in the case of the email address, you'll be all 
ready to start typing an email to me!
Two environment variables (BROWSER= & EMAIL=) must be set up for this 
feature to work. These variables allow the program to know what 
programs to launch for web browsing and email.

Environment Variables
---------------------
BROWSER=C:\CAB\CAB.APP or whatever path points to your browser
EMAIL=C:\CAB\CAB.APP or whatever path points to your email program (it 
must understand mailto: as a command line).

Single TOS users can either get hold of programs such as GEMENV and 
SETENV or can use the file VARS.ENV. This file must exist in the same 
path as POPWATCH.PRG to be effective.
Edit file VARS.ENV to point to whichever programs you wish to use.

Magic users should add the following lines to MAGX.INF
#_ENV BROWSER=C:\CAB\CAB.APP
#_ENV EMAIL=C:\CAB\CAB.APP

MultiTOS or Geneva users should add the following lines to GEM.CNF
setenv BROWSER=C:\CAB\CAB.APP
setenv EMAIL=C:\CAB\CAB.APP


FREEWARE
--------
This version of POPwatch is FREEWARE. That means you can use it 
without having to pay a penny. It's FREE, FREE, FREE!!

Future versions will be SHAREWARE though. It costs time and money to 
develop so I don't feel it's too unjust to hope for a little payback.
The SHAREWARE versions will be fully functional (I'm not going to 
disable any features), but they will have a NAG window appear on start 
up of the program. This will disappear in registered versions.

If you use and like POPwatch, then please drop me an email and tell me 
so. Without encouragement, POPwatch may not develop. So, even if it's 
just a one liner, please make the effort.


DISCLAIMER
----------
POPwatch is used at your own risk. I will not be held responsible for 
any damage caused either directly or indirectly from it's use, or the 
loss of any electronic data.


NEW VERSIONS
------------
The latest version of POPwatch can be found at my website:

http://www.the-gap.demon.co.uk/

   
Gary Priest 26/04/97
gary@the-gap.demon.co.uk
