$Id: readme 1.6 1996/09/02 13:31:33 hardy Exp $	

THIS PROGRAM IS HEAVILY BASED ON IDEAS/MODULES/DOCS FROM CHIN HUANGs
(cthuang@io.org) SOUPER15.  THANKS TO HIM.  ALSO FOR YARN/2.

This means, that bug reports and everything else concerning VSoup
should be directed to Hardy Griech (rgriech@ibm.net, no Chin Huang!

VSoup is free software.  See COPYING disclaimer of the FSF for
details.  Note that you are not allowed to distribute VSoup without
source code.


Purpose
=======

VSoup is a network mail and news client program for OS/2 Warp's
Internet Access Kit.  It transfers mail and news fetched from a POP3
server and NNTP server respectively to SOUP format.  It can also send
messages in SOUP reply packets to NNTP/SMTP servers

Currently there are no man pages for VSoup.  The man pages from
souper15 and the usage message should be enough (temporary).

The program requires the emx run-time DLLs.  You can get these from

     ftp://ftp-os2.nmsu.edu/os2/unix/emx09b/emxrt.zip


Features
========

-  receiving news from NNTP, posting news to NNTP, receiving mail from
   POP3, sending mail to SMTP

-  all the packets are exchanged in SOUP format files

-  multi-threaded news receiving

-  status mail generation (this is not in SOUP standard, but
   recognized by YARN).  The generation can be forced via command line
   option, standard is to generate mail in case of failure or on new
   newsgroups (-a option)

-  detects time-out condition for news receiving

-  URLs on command line for easy specification of the several servers

-  example (!) script to do VSoup operation safely (without risc of
   message loss etc.)


CmdLine
=======

Common command options
----------------------

-h dir      set the home directory for the VSoup operation.  You can
            also specify your home directory through the environment
            variable HOME

-i          ignore the settings of the 'Internet Connection for OS/2'
            settings

-m          do not fetch mail

-M          generate the VSoup status mail in any case.  Standard is
            to generate the message in case of error only.

-n          do not fetch news

-r          read only mode.  Except the *.msg ./areas, ./*.msg ./*.idx
            no files are written (e.g. ~/newstime, ~/newsrc).  Also
            the mails are not deleted from the POP3 server.  Main
            purpose for this option is debugging.

-s          send replies.  -s might be combined with the -m,-n option,
            but this feature is ignored!

News receiving options
----------------------

-a          add new newsgroups to newsrc file.  If there are any new
            groups on the server, then the generation of the status
            message will be forced.

-c[n]       catchup: mark every article as read except for the last n
            (default is 10).

-k n        set maximum news packet size to n KBytes (default is no
            limit).  N means the total amount of received messages,
            not the size of a single message (see -l)

-K file     set the name of the kill file (see note below...)

-l n        set the maximum length of news you like to receive.  This
            is intended for omitting binaries in text groups.

-N file     set the name of the newsrc file (see note below...)

-t n        receive the news with 'n' threads, i.e. connect to the NNTP
            server 'n' times

-u          create news summary.  Output can be found in the ./*.IDX
            files.  Be aware that the summarized articles are marked
            as read (one way to get out of this, is to call VSoup with
            -r)

-x          do not process news Xref headers

-K,-N,-h
--------

I do not recommend to use these options, because behavior is not very
transparent if you are using also '-h'.  If the '-h' is behind the
'-K/-N' the result will be another as expected - vsoup (and souper)
will revert to 'kill' and 'newsrc'; if '-K/-N' are behind the '-h' and
do not contain absolute pathes, the will not be located in the by '-h'
specified home directory.  This is confusing and will be fixed in a
future release.  IT IS BETTER AND CLEANER TO USE -h AND SETUP THE
SPECIAL KILL/NEWSRC FILES IN THAT DIRECTORY!

URLs
----

The addresses of the hosts are given in URL form.  These confirms not
absolutely to the standard, so a short explanation follows:

-  'nntp://[UserId[:Password]@]nntp-host' defines the address of your
   NNTP server.  UserId and Password can be given if required for
   AUTHINFO.

-  'pop3://[UserId[:Password]@]pop3-host' defines the address of your
   POP3 server.  UserId and Password are usually required.

-  'smtp://[userid[:password]@]smtp-gateway' defines your SMTP
   gateway.  UserId and Password are not required, in fact they are
   ignored by VSoup!

This feature makes VSoup dfferent to souper16, which wants to see a
~/newsauth file.

Ah ja: it is not intended to implement other protocols like http or
so...


Environment
===========

HOME         your home directory (can also be specified in the command
             line)

NNTPSERVER   hostname of the nntp server (can also be specified in the
             command line)


Diagnostics
===========

VSoup returns with an exit code of '1', if any operation failed.
Otherwise return code will be '0'.


Evaluation Order Of URLs
========================

Evaluation order is as follows:

(1)  take all information from the 'Internet Connection for OS/2'
     settings

(2)  check the NNTPSERVER environment settings (yes, there are no vars
     for the SMTP/POP3 setup).  NNTPSERVER is a URL without leading
     'nntp://'

(3)  command line options

If you specify only e.g. 'nntp://news-server' in the command line
(without userid/password), the userid/password from the OS/2 settings
are taken as a standard value.


News Reception
==============

for news reception you have the following options (which cannot
combined): either process ./commands (./commands exists), or catch-up
the newsgroups (-c option) or create newsgroups summary (-u option) or
receive the news in the standard way (no specific option).  New
newsgroups are added only to the ~/newsrc file, if news received in
the standard way.


Helper
======

There is a REXX script packed into this archive.  The script is just
intended as an example and must be adapted to your special needs.  If
somebody wants to make the configuration easier, she/he is welcome.

yarnio.cmd:    control IO of VSoup to YARN.  News are read from two
               NNTP servers, mail/news are transmitted, mail is
               received - all simultaneously.  The cmd should be
               started by the dialer directly after connection has
               been established.  Sorry, but the directory structure
               must be adapted manually!


Files
=====

~/newsrc:       contains the newsgroups.  ':' behind the name
                indicates subscribed group, '!' indicates an
                unsubscribed one

./commands:     contains lines with the syntax: 'sendme' <groupname>
                <article-nums>.  ./commands is executed instead of
                standard fetching of news.  After successful
                'commands'-processing, the file will be deleted.
                Note: already read articles (marked in ~/newsrc) will
                be skipped!

~/kill:         is the kill file.  Note: news transmission speed
                decreases if a kill file is used, because then an
                article is fetched in two steps: HEAD <num>, then BODY
                <num>.  Otherwise an article will be fetched in only
                one step: ARTICLE <num>

~/newstime:     contains the time of the last NNTP connection.  This
                is for fetching of new newsgroups.  If ~/newstime does
                not exist, ALL currently available newsgroups are
                fetched from the server.  Applicable only, if VSoup
                was called with the '-a' parameter.

./00*.msg:      contain the received news messages (news & mail)

./00*.idx:      contain the received newsgroup summaries

./stsmail.msg:  contains the (non-standard) status message generated
                by VSoup

./areas:        contains the table of contents of the received
                ./00*.msg / ./00*.idx files (+stsmail.msg)

./news.msg:     contains the news messages that should be sent to the
                NNTP server

./mail.msg:     contains the mail messages that should be sent to the
                SMTP server

./replies:      contains the table of contents of the news.msg /
                mail.msg files to be transmitted


Insufficiencies
===============

-  only very basic killfile handling

-  not compatible with souper16 (some cmd options, some files,
   score/kill file)

-  the port section in URLs is not recognized (future version)

-  space allocated from the heap is not freed (debugging...)

-  behaviour for news receiving/posting, mail receiving/posting is not
   symmetrical, i.e. there is no multi-threading except for news
   receiving, there is no time-out detection except for news
   receiving...  This will be fixed in a future version

-  news reading: one group is read after the other.  This is due to
   limitations in areas.*

-  only one single version (for OS/2)


Known Bugs
==========

-  how to kill a thread (I think, this is an old OS/2 issue)? (problem
   arises, if the main thread of VSoup has received a signal)


Plans
=====

-  remove bugs & insufficiencies

-  do the NNTP-NEXT with XHDR (if available)


Author
======

Hardy Griech
Kurt-Schumacher-Str. 25/1
72762 Reutlingen
Germany

email:  rgriech@ibm.net


History
=======

VERSION 1.1 (010996)

-  if NNTP server knows nothing about DATE command, the internal clock
   will be taken as a reference (required for -a cmd option only)

-  'AUTHINFO USER' / 'AUTHINFO PASS' for nntp server implemented
   (RFC977 extension).  Call VSoup simply with the nntp-URL
   nntp://user:passwd@nntpserver

-  NNTP NEXT will only be done, if there is a bigger gap between the
   articles

-  bug in socket.cc ((char)0xff == (int)-1 !!!)


VERSION 1.0 (010896)

- Program is now named VSoup.  I am sorry, but the program again
  requires the emx DLLs (to my opinion no disadvantage, because most
  of the people will have them anyway).  Also there is no support for
  Win95 (this was not intended and I am not sorry, but I have no Win95
  system - and I am happy about that ;-)

- Program is now multi-threaded for news reading.  This gives a speed
  gain of 200%-500% depending on the overall speed of the connection
  and the number of threads; on the other hand multiple connections
  have a communication overhead (i.e. the connections must be
  established, the groups selected).  Estimated loss is around 5%...

- Return codes are now much more consistent: on failure an
  EXIT_FAILURE (1) is returned, on success EXIT_SUCCESS (0)

- On failure a status mail is generated.  Most of the console messages
  are redirected into this status mail.  The generation of the mail
  can be forced thru cmd option '-M'

- If file ~/NEWSTIME does not exist, the complete newsgroup list is
  retrieved from the news server (NNTP LIST)

- Kill files may have comments ('#' in the first position of a line).
  This is very beta...

- Readonly mode is now much more consistent (NEWSTIME is not updated,
  also the sent articles are not deleted)

- the default maximum packet size has been changed to unlimited

- Small bug in newsrc handling found (firstUnread was wrong sometimes)

- automatic timeout for NNTP reception

