             NEWSwatch v2.11 (c)1997,98 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.

	
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.


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.


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 11/07/98
gary@the-gap.demon.co.uk
