           NEWSwatch v2.50 (c)1997,98,99 Gary A. Priest
           --------------------------------------------

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

NEWSwatch enables the sending and receiving of Usenet news articles 
from Oasis2 or Oasis1.3x/Snews/Okami (or any client that uses the standard 
'rnews' batching format, but with STiK/STinG instead of ICE or NOS. 

It is not a full news client, ie. you cannot read or edit articles.

It is meant to complement the offline part of your existing news client
and replace the online parts such as NOS and ICE.

It is intended to allow users of NOS, Oasis1.3, Okami 1.29+, and Oasis2 to
send and receive news articles via STiK/STinG in much the same way that
POPwatch works for email.

This document is not particularly detailed, for more information, 
please make sure that BubbleGEM by Thomas Much is installed, and then 
use the right mouse button to display more detailed help about any of 
NEWSwatch's functions.


PROGRAM PREFERENCES
-------------------
The retrieval format must be either NOS or Oasis2.

INCOMING PATH
-------------
Where incoming news articles will be stored before unbatching eg.

        OASIS\SPOOL\ARTICLES     for Oasis1.3x
        NOS\SPOOL\ARTICLES       for NOS
        OKAMI\SPOOL\NEWS         for Okami
        OASIS2\INCOMING          for Oasis2
        
OUTGOING PATH    
-------------
Where outgoing news articles will be stored ready for posting eg.

        OASIS\SPOOL\MQUEUE       for Oasis1.3x
        NOS\SPOOL\MQUEUE         for NOS
        OKAMI\SPOOL\MQUEUE       for Okami
        OASIS2\OUTGOING          for Oasis2

HISTORY PATH
------------
Where the history, newgroups and fullgroups files will be stored eg.

        OASIS\SPOOL\NEWS         for Oasis1.3x
        NOS\SPOOL\NEWS           for NOS
        OKAMI\SPOOL\NEWS         for Okami
        OASIS2\NEWS              for Oasis2

GET/HEAD.OUT PATH
-----------------
Where the NOS GET file or Oasis2 HEAD.OUT file can be found eg.

        OASIS\SPOOL\NEWS         for Oasis1.3x
        NOS\SPOOL\NEWS           for NOS
        OKAMI\SPOOL\NEWS         for Okami
        OASIS2\SYSTEM\TMP        for Oasis2

The retrieval paths used when using NEWSwatch with Okami should be
dependant upon what is set up in Okami's configuration file, O.INF.

The KILL file must also be stored here if KILL processing is required.

	
RETRIEVAL METHOD
----------------
NEWSwatch can use two methods to retrieve new articles from a news 
server. You should select whichever is appropriate to you. 
NEWNEWS is quite often not supported/disabled by news servers, and if 
you find it doesn't work, then you will have to use Retrieval by 
Article Number instead.

NEWNEWS
-------
This method uses the date and time specified in NNTP.DAT to retrieve a 
list of all new articles since that time, this list is then processed 
by NEWSwatch and each article in it is retrieved.

RETRIEVAL BY ARTICLE NUMBER
---------------------------
This method *must* be used if your server does not support NEWNEWS.
Each article on the server has a unique number. The number of the last 
article retrieved by NEWSwatch is stored in the NNTP.DAT file.
When NEWSwatch reconnects to the news server, it starts downloading 
articles from the stored number.

AUTOMATIC RETRIEVAL
-------------------
NEWSwatch can be set to automatically connect to the news server 
every so many minutes, and download any new groups and articles.
Posting of outgoing articles is not performed automatically.

This function is designed to only work once you are already connected
to the internet. It will not make that connection for you.

It should only be used with STiNG. If used with STiK and you are not 
connected to the internet, then it will crash!
This is a fault with STiK and not NEWSwatch. Use STiNG instead.

GMT OFFSET
----------
The GMT offset is *very* important, and *must* be set up.

NEWSwatch retrieves articles by date and time. The time used is 
always in GMT. NEWSwatch uses the figure entered here to calculate 
the current GMT time.

eg. if your Atari is currently running BST, set this field to 1 +


NNTP.DAT
--------
You must configure the nntp.dat and it must be in the same folder as 
nwatch.prg.

NEWSwatch uses it's own format of nntp.dat file. It is similar to the 
one used by NOS but *not* the same. It is completely different from 
that used by Oasis2.

The first line must point to the news server you wish to connect to.
Subsequent lines must start with a single space (to receive articles) 
or an = sign to receive just the headers, and detail the newsgroups that
you wish to collect news for.
Comment lines are allowed and must start with a # symbol.
This can be useful if you wish to temporarily disable a particular 
group.
Each entry and it's associated date, must be separated by *one* space, 
and each line must end in CRLF.

A typical nntp.dat file follows:

news.demon.co.uk 970101 000000
#The date above is used by NEWSwatch when retrieving a list of new 
#groups.
 demon.ip.support.atari 970101 000000
#Each newsgroup has it's own last retrieved date.
#Unlike NOS, the date can be easily altered for each group.
 comp.sys.atari.st 970101 000000
=alt.binaries.large
#The above is a binaries newsgroup and thus I will download only the 
#headers. I can fetch specific articles later.
 
NB. When setting up your nntp.dat file, the date and time's *must* be 
valid. NEWSwatch does not validate them!!!

The date and time must still be specified even if retrieving by 
article number. They are simply ignored. The last article number will 
be added to the line after the date and time automatically by 
NEWSwatch.


HEADER RETRIEVAL
----------------
If the newsgroup line in nntp.dat begins with an = sign instead of a 
space then NEWSwatch will only retreive the headers of articles for 
this newsgroup and *not* the whole article.

This is particularly useful in binary newsgroups, you download the 
headers and then select which articles are of interest. Next time 
NEWSwatch connects to the news server, it will download the requested 
articles before downloading any other new ones.

NOS
NEWSwatch will still retrieve the headers into BATCH.TXT, and will 
look for a file in the specified GET/HEAD.OUT path called GET.
If it finds it, it will download any messages that are specified.
The format of GET is one message-id (including the < and >) ending
with CRLF. The populating of the GET file can either be done manually,
or a much better way would be to use Guy Harrison's Make_Get program
(available from http://www.swampdog.demon.co.uk/ 

OASIS2
NEWSwatch retrieves the headers in NEWSHEAD.DAT and NEWSHEAD.IDX.
Oasis2 will unbatch these correctly just as if they were downloaded 
via ICE. Oasis2 has the ability that when you select a header article 
to read, it adds the message id to a file called HEAD.OUT. 
This file is used by NEWSwatch, in place of the GET file above.
Thus for Oasis2 users the use of headers is completely transparent and 
to all intents and purposes no different from using ICE.


KILL PROCESSING
---------------
NEWSwatch has the ability to compare various header fields of incoming
articles, and either discard them completely or just store the headers
instead of the whole article.

KILL processing can be configured via the 'Edit KILL preferences' menu 
option.

To turn KILL processing ON, you must ensure that the 'Activate KILL 
processing' option is set to YES.

If KILL file processing is activated, then articles will be retrieved 
in two stages; HEAD and BODY. If not activated, then NEWSwatch will 
continue to retrieve articles in one stage using the ARTICLE command.
Be aware that activating KILL file processing can have the negative 
effect of slowing down data transfer, as more commands are sent, and 
extra processing has to be done to check header fields etc.

NEWSwatch uses various methods to kill a specific article, namely; by 
number of lines, number of groups posted to, and a KILL file.

Number of Lines
---------------
Most usenet articles contain the header field 'Lines:', but not all.
This is a line count of the number of lines in the body of the 
article.
If you specify a non-zero value then NEWSwatch will KILL any article 
that has a 'Lines:' value greater than your specified value. Zero 
means no limit.

Crossposted to more than x groups
---------------------------------
An awful lot of junk (spam) news articles are by their very nature 
posted to many, many newsgroups.
You can specify a value in NEWSwatch, so that any articles that have 
been posted to more groups than your specified value, will 
automatically be killed.

Keep Headers
------------
If headers are requested to be kept then they are simply stored in the 
same incoming spool file as normal articles, but they are marked by 
having a new header field added; 'X-Killed-By: NEWSwatch'.
These headers will be imported into Okami, Oasis2 etc. just as if they 
were complete articles. ie. not into Oasis2's header area.
Using Okami or Oasis2 etc. you can extract the message-id of these 
messages if they do in fact interest you, and NEWSwatch can retrieve 
the whole article next time you connect.

If headers are not requested to be kept, then they are simply 
discarded, and you will never be able to see them. This saves time and 
disk, but has the disadvantage that if you've killed something that 
you might have found interesting, you'll never know!

The KILL file
-------------
Further, more complicated, kill patterns can be stored in a file called KILL
which should be located in the same path as the GET file (specified in
program preferences).
Each line should contain a pattern that will be compared to each header line 
of an incoming article.

Format of the KILL file
-----------------------
The kill file should contain one pattern per line.  Each
header line received is compared with every pattern until a
match occurs.  A match must be exact, with the first character
of the pattern matching the first character of the header line
and the last character of the pattern matching the last
character of the header line.  Case is insignificant and
whitespace is always represented by a single space character. 
Any lines in the kill file that start with a # symbol are treated as 
comments and ignored.

The pattern may contain special characters as follows:

!    If the first character of a pattern is "!" then the rest
     of the line forms a "keep" pattern ("!" means don't
     kill).  If any header line matches a keep pattern then
     the article body will be fetched.

     If the first character of a pattern is not "!" then the
     whole line forms a "kill" pattern.  If any header line
     matches a kill pattern and no header line matches a keep
     pattern then the article body will not be fetched.

     The "!" character has no significance in any other
     position and will be matched literally.

?    Matches any single character.

*    Matches zero or more characters.

[ ]  Matches any single character that appears within the
     square brackets.  For example, [0123456789] will match
     any single decimal digit.  The characters can be
     specified as a range: [0-9] has the same meaning as the
     previous example.

\    Matches the following character literally.  For example,
     \* will match a single asterisk and \\ will match a
     single backslash.

Example:
----------------------------------------
Newsgroups: *rec.pets*
!Newsgroups: *rec.pets.gerbils*
----------------------------------------

The first line should kill any postings or cross-postings to
the rec.pets hierarchy.

The second line will keep any postings to the rec.pets.gerbils
hierarchy regardless of any matches with the other kill
patterns.


AUTHENTICATION
--------------
Some news servers require you to specify a user and password before 
allowing access. This process is known as authentication and uses the 
AUTHINFO command which is not specified as part of the original RFC, 
but is specified in draft-ietf-nntp-imp-01.txt.

If your news server requires authentication then you should contact 
your ISP who will give you a username and password.
These should then be stored in a file called AUTHINFO.DAT (in the same 
folder as NWATCH.PRG), which contains the user on line 1 and the 
password on line 2. Each line must end in CRLF. ie.

user
password

NEWSwatch will then send this information to the news server whenever 
it requests authentication.


USING NEWSWATCH
---------------

1. Configure the NNTP.DAT and AUTHINFO.DAT files as appropriate.

2. Connect to your ISP with STiK.

3. Run NWATCH.PRG and configure the Program Preferences.

4. Select 'Retrieve', and NEWSwatch will log on to the specified
   news server and retrieve all new articles since the date
   specified against each newsgroup in the NNTP.DAT file.

5. Select 'Post' to send any queued outgoing news articles. 
   This option is largely redundant because NEWSwatch will always give 
   you the option of posting any waiting articles upon initial 
   start-up. Also it can be configured to always post any outgoing 
   articles before retrieving any, whenever you select 'Retrieve'.


ACCESSING THE RETRIEVED ARTICLES
--------------------------------
To read any downloaded articles in either Oasis1 or Oasis2, you must 
take their 'unbatch' option to unbatch the news into a readable 
format.


DOWNLOADING NEW NEWSGROUPS
--------------------------
NEWSwatch will automatically download a list of all new newsgroups 
since the date specified against the server in nntp.dat. This is 
called NEWGROUP for NOS, and NEWGROUP.DAT for Oasis2.


DOWNLOADING THE FULL LIST OF ALL NEWSGROUPS
-------------------------------------------
NEWSwatch can download the full list of newsgroups if required. This 
will be in the NOS format and is called NG or NG.DAT for Oasis2.
This file is extremely large (about 620K at time of writing this).


HISTORY FILE
------------
NEWSwatch adds the message ID of each article retrieved to the 
HISTORY file as is done under NOS and Oasis2. NEWSwatch checks each 
article against this file to see if it has already been retrieved.
This file should be periodically deleted as is usual with both NOS and 
Oasis2.


VERBOSE DISPLAY
---------------
This window shows all conversation between NEWSwatch and the NNTP 
server, although actual article content will not be displayed.
This window can be set to open automatically, if it is open when 
Program Preferences are saved.


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


GET SERVER HELP
---------------
This menu option will connect to the NNTP server, issue the HELP command,
display the returned help response in the verbose window, and store 
this information in a file called HELP.LOG.
This enables you (and me if you send help.log to me) to see exactly which
commands are supported by your NNTP server, which is very useful for
debugging purposes.


PARAMETER PASSING VIA THE COMMAND LINE OR VA_START
--------------------------------------------------

Automated control of NEWSwatch can now be achieved by passing it 
parameters either via the normal command line or via VA_START.

The parameters can be:
    filename other than nntp.dat (optional) ie. nntp_2.dat

followed by:
    /t = TOS mode
    /r = retrieve new articles
    /p = post outgoing articles
    /q = terminate NEWSwatch
    /u = load new NNTP file

eg. /r /p /q

will load the default NNTP.DAT, connect to the news server, retrieve all
new articles, post any outgoing articles and quit NEWSwatch.

eg. n64.dat /r 

will load the nntp file N64.DAT, connect to the news server and retrieve
all new articles.

Thus you can now start up NEWSwatch with any NNTP file you like, not 
just the default NNTP.DAT. To string multiple ones together you can 
use the /u parameter.

TOS Mode
--------
This tells NEWSwatch to run without using GEM and thus producing no 
visible output. This could be used to run NEWSwatch from a command 
line interface or batch file. If TOS mode is required then /t must be
the very first command after the optional NNTP file.

eg. /t /r /p /q will tell NEWSwatch to connect to the server defined 
in NNTP.DAT, retrieve all new articles, send any outgoing articles,
and QUIT. No GEM output will be performed, NEWSwatch just does the job
and quits. The /q command is not strictly necessary and can be omitted 
when running in TOS mode, because by it's very nature, NEWSwatch will 
automatically quit.

Loading and processing with more than one NNTP file
---------------------------------------------------
The /u parameter allows use of more than one NNTP file in a command line.
ie.

    /uNNTP1.DAT /r /uNNTP2.DAT /r /q
will start NEWSwatch, load NNTP1.DAT, retrieve new articles, load 
NNTP2.DAT, retrieve new articles, and quit.
    
    /r /uNNTP2.DAT /r /q
will start NEWSwatch with the default NNTP.DAT, retrieve, load 
NNTP2.DAT, retrieve, and quit.


ONLINE OPTIONS
--------------
The following options allow you to easily surf to various NEWSwatch 
related web sites, assuming you are connected to the internet at the 
time. This facility also requires you to have set the BROWSER variable 
specified below in THE ABOUT WINDOW section, so NEWSwatch knows where 
to find your web browser.

NEWSwatch Home Page 
------------------
Will pass the URL of the NEWSwatch home page to your defined web
browser, allowing you easy access to it.

Frequently Asked Questions
--------------------------
Will pass the URL of the NEWSwatch FAQ to your defined web browser,
allowing you easy access to it. Once there you can even email me with
any question about NEWSwatch that is not already in the FAQ, thus
allowing me to build it up.


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= & MAILER=) 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
MAILER=C:\CAB\CAB.APP or whatever path points to your email program (it 
must understand mailto: as a command line).

The variables will be searched for in this order:

1. STiK/STinG variables (defined within DEFAULT.CFG)
----------------------------------------------------
This is the preferred (and simplest) method.

Add the following lines to DEFAULT.CFG
BROWSER = C:\CAB\CAB.APP
MAILER = C:\CAB\CAB.APP

2. AES environment variables.
-----------------------------
Single TOS users can either get hold of programs such as GEMENV and 
SETENV or can use the file VARS.ENV.

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

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

3. VARS.ENV file.
-----------------
This file must exist in the same path as NWATCH.PRG if you wish to 
use it.
Edit file VARS.ENV to point to whichever programs you wish to use.


BUBBLEGEM SUPPORT
-----------------
NEWSwatch supports the excellent BubbleGEM program by Thomas Much.
This program provides Windows95 style Help Bubbles when you right 
click on a particular control/field.
If BubbleGEM is running then right click on an entry field in NEWSwatch 
and you'll see a cute little help bubble appear!


FREEWARE
--------
NEWSwatch is FREEWARE! I make no charge for using it.

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


DISCLAIMER
----------
NEWSwatch 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 NEWSwatch can be found at my website:

http://www.the-gap.demon.co.uk/
   
Gary Priest 09/01/99
gary@the-gap.demon.co.uk
