OS/2 Shareware BBS: 35 Internet/35-Internet.zip/vsoup128.zip/vsoup.src

Text File | 1997-04-20 | 107KB | 3,546 lines

■if false
$Id: vsoup.src 1.15 1997/04/20 19:29:32 hardy Exp $
■endif

■language english
■replace VS VSoup1.2.8
■replace VSZip ■bf{VSOUP127.ZIP}
■format bold VSoup1.2.8 VSoup1.2.7 VSoup1.2.5 VSoup1.2 VSoup
■replace LOGINISP ■hpt{LOGINISP.CMD}
■replace LOGOUTISP ■hpt{LOGOUTISP.CMD}
■replace YARNIOSET ■hpt{YARNIO.SET}
■replace YIO ■hpt{YarnIo}
■replace ConvS ■hpt{ConvSoup}
■replace CONVSOUPEXE ■hpt{CONVSOUP.EXE}
■replace OwnS ■hpt{OwnSoup}
■replace OWNSOUPEXE ■hpt{OWNSOUP.EXE}
■replace QS ■hpt{QSoup}
■replace QSOUPEXE ■hpt{QSOUP.EXE}
■replace ImportProg ■bf{import}
■replace FilterProg ■bf{filter}
■format bold Yarn emxrev emxdoc REXXTRY
■format bold YARNIO VSOUP.EXE YARNIO.CMD MODIFYEMXH.CMD RMHIGH.CMD FILTER.EXE
■format bold VSOUP.INF VSOUP.TXT
■format bold emx emx09a emx09b emx09c SOUP Souper Souper16 USENET UNIX Changi Chanx RNews sendmail inews GNU
■format abbrev e.g. i.e. etc. Str. D.
■format tty ETC EMXOPT HOME MAILER NNTPSERVER PATH POSTER TMP TZ
■format tty NNTP POP3 SMTP
■format tty nntp:// pop3:// smtp://
■format tty %HOME% %HOME%\NEWSRC %HOME%\NEWSTIME %HOME%\NEWSAUTH %HOME%\SCORE NEWSRC NEWSTIME SCORE
■format tty %HOME%\YARN\CONFIG %HOME%\YARN\IN\NEWS2
■format tty NEWSRC NEWSTIME
■format tty %TMP%
■format tty %ETC%\SERVICES %ETC%\TCPOS2.INI
■format tty .\COMMANDS
■format tty .\STSMAIL.MSG .\NEWS.MSG .\MAIL.MSG .\REPLIES .\AREAS CONFIG.SYS
■format tty .\*.MSG .\00*.MSG .\00*.IDX
■format tty RCVNEWS RCVNEWS2 RCVMAIL SEND
■format tty reply-packet sendmail.uml sendmail.cf
■replace ReplyPacket ■sl{reply packet}
■replace VSoupSend ■sy{"VSoup -s"}
■replace LESS ■bf{Less}
■replace GNU ■bf{GNU}
■replace GNUs ■bf{GNU}s
■format syntax -i -h40 -M -h<dir> -m -n -r -s -T<n> -K -N -h -c -T-1 -t8 -D
■format syntax -a -c[n] -k<n> -K<file> -N<file> -S<n> -t<n> -u -x -S0 -S1 -S2
■format bold Q- A- Q1- Q2- A1- A2-

■if text
■replace LINEBREAK ■break ---------------------- ■break
■endif

■if ipf
■replace LINEBREAK ■break
■endif

■if html
■replace LINEBREAK ■em{}
■endif


■text
===============================================================================
VSoup1.2.8                     NNTP/POP3/SMTP client                19-Apr-1997
===============================================================================
                                        Copyright (c) 1996-1997 by Hardy Griech
■endtext

■html
<hr size=4><center>
<h1>VSoup1.2.8   19-Apr-1997</h1><p>
<h2>The multithreaded Souper for OS/2</h2><p>
<i>Copyright (c) 1996-1997 by Hardy Griech</i><p>
</center><hr size=4>
■endhtml



■title VSoup1.2.8 - the multithreaded Souper for OS/2

■if text
■h= Table of Contents
■toc
■endif

■if html
■html
<h1>Table of Contents</h1>
■endhtml
■toc
■endif


■h1 Introduction to VSoup

■ipf
:font facename=Helv size=24x14.
:hp2.
.ce VSoup1.2.8   19-Apr-1997
:p.
.ce The multithreaded Souper for OS/2
:ehp2.
:p.
:font facename=Helv size=16x10.
.ce Copyright (c) 1996-1997 by Hardy Griech
:font facename=default size=0x0.
:p.
:p.
■endipf

  VS is a multithreaded network mail and news client program for OS/2
  Warp with TCP/IP (or the Internet Access Kit) installed.  It
  transfers mail and news fetched from a POP3 server and NNTP server
  respectively to packets in SOUP format.  It can also send messages
  in SOUP reply packets to NNTP / SMTP servers.

  VSoup is especially designed to work with Yarn, but it is probable
  that VSoup will work with most offline newsreaders which expect SOUP as
  their input and output.

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

■typewriter
   ■url{ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/emxrt.zip}
■endtypewriter

  The emx09c run-times or newer are required.  emxrev should show at
  least revision 50 for the DLLs.  VSoup may work with an earlier version
  such as emx09b, but keep in mind that there were many changes in the
  DLLs concerning multithreading / sockets since emx09a.

 ■break

■text
-------------------------------------------------------------------------------
!!!!!       MAKE SURE THAT YOU ARE USING THE CORRECT EMX DLL-VERSIONS     !!!!!
-------------------------------------------------------------------------------
■endtext

■ipf
:hp2.
.ce !!!!! MAKE SURE THAT YOU ARE USING THE CORRECT EMX DLL-VERSIONS !!!!!
:ehp2.
■endipf

■html
<p><center>
<hr size=2,width=20%>
<tt><b>MAKE SURE THAT YOU ARE USING THE CORRECT EMX DLL-VERSIONS</tt></b>
<hr size=2,width=20%>
</center><p>
■endhtml


■h1 Legal Issues

  This program is heavily based on ideas and modules from Chin Huangs
  ([e-mail]) Souper15.  Thanks to him for both Souper and Yarn.

 ■em{Please note that bug reports and everything else concerning VSoup}
 ■em{should be directed to Hardy Griech ([e-mail]), not to Chin}
 ■em{Huang!}

■h- Standard Disclaimer

  VSoup is free software; you can redistribute it and/or modify it under
  the terms of the GNU General Public License (GPL) as published by
  the Free Software Foundation; either version 2, or (at your option)
  any later version.  For more details about the GPL see the file
  ■bf{COPYING} contained in this archive.

  VSoup is distributed in the hope that it will be useful, but ■em{without
  any warranty}; without even the implied warranty of ■em{merchantability}
  or ■em{fitness for a particular purpose}.  See the GNU General Public
  License for more details.


■h- Warning

  Some news sites might see VSoup as a news sucking utility and might
  feel offended by its use.

  The intention is that VSoup is to be used to receive news for your
  personal use from a reasonable number of newsgroups.

  Misuse of this program could conceivably result in a general ban on
  the use of this or similar programs to the detriment of responsible
  VSoup users who certainly don't want a general ban of VSoup.


■html
   <A NAME="features"></a>
■endhtml
■h1 Features
■index Features of VSoup

■itemize
■item

   Multithreaded news receiving is supported, anything between 1 and
   10 threads can be started (default 4), and in addition there are
   several possible strategies for fine tuning.

   Multithreading 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%...

■item

   all the packets are exchanged in SOUP format files, i.e. offline
   readers expecting as input format either SOUP or USENET batch
   format can be used together with VSoup.

■item

   VSoup generates a status message as incoming mail. (this is not in
   the SOUP standard, but is recognized by Yarn). Normally this
   message is only generated in case of failure (eg., cannot select
   newsgroup) or when special events occur (eg., when new newsgroups
   are added), but the generation can be forced to always occur by
   means of a command line option.

■item

   VSoup will show some statistic information about data transfer.

■item

   Specification of the required servers is easy by using ■hpt{URL}s
   on the command line.

■item

   It is possible to filter articles by header lines before retrieving
   the body text, see ■hpt{score file} handling.  VSoup allows regular
   expression for both group and header patterns, article length is
   treated special.

■item

   VSoup detects too low throughput or stuck connections.

■item

   VSoup knows about NNTP authentication.

■item

   YIO, a script to do VSoup operation safely (without risk of message
   loss etc.)  is included in the archive.  YIO is capable of
   simultaneously receiving news from up to nine separate NNTP news
   servers, posting news to NNTP, receiving mail from up to nine POP3
   servers and sending mail to SMTP.

■item
   Other utilities included are
■description
■item OwnS
   This, with the help of the Yarn ImportProg program, redirects
   news articles matching a specific pattern into a separate mail folder which will
   show up when you read your mail with Yarn.

   For example you can search newsgroups for any mention of your name
   or any mention of a program you are interested in.
■item QS
   This appends mail and news messages to the Yarn ReplyPacket
   file for transmission by VSoup.
■item ConvS
   This transforms all articles from binary SOUP format to mailbox/USENET format.
■enddescription

■item

   ■hpt{FAQ} included.

■item

   source code included.

■item

   freeware according to GPL (without any warranty for correct
   function etc.).

■enditemize




■html
   <A NAME="installation"></a>
■endhtml
■h1 Installation
■label Installation
■label installation
■index Installation

  This section describes the installation of VSoup on a step by step
  basis.  Steps (1)-(4) are for preparation to ensure that you have a
  system configuration which can run VS.

  The installation instructions assume that you intend to run VSoup with
  the help of YIO.  If you wish to use VSoup on its own for example to
  benefit from multithreaded news reception, but do not need YIO,
  simply skip the steps (7)-(11) and parts of (6).

  Anyway you can use YARNIO.CMD as an example.

  If you experience any problems take a look at the
  ■hpt{troubleshooting} section.

  If you are upgrading an older VSoup version, you should have a look at
  the ■hpt{history} section for hints on important changes.


 ■break
■enumerate

■item
   your system must be one of the following:
■itemize
■item
   OS/2 2.x with TCP/IP (not tested but should work)
■item
   OS/2 3.0 (Warp) with the 'Internet Access Kit' installed
■item
   OS/2 3.0 (Warp Connect) with TCP/IP installed
■item
   anything above
■enditemize

■item

   get the latest version of the emx runtime library and install it or
   check your current installation with emxrev.  This should show a
   revision level higher than or equal to '50'.  If you are not
   intending to use YIO, then add an environment setting of ■tt{SET
   EMXOPT=-h40} to your CONFIG.SYS as noted in the ■hpt{environment
   settings} section below.

■item

   check your environment variables according to the ■hpt{environment
   settings} section below.

■item
   check your %ETC%\SERVICES file to ensure that it contains the
   following lines:

■verbatim
  smtp         25/tcp mail          #Simple Mail Transfer
  smtp         25/udp mail          #Simple Mail Transfer
  pop3        110/tcp               #Post Office Protocol - Version 3
  pop3        110/udp               #Post Office Protocol - Version 3
  nntp        119/tcp readnews untp #Network News Transfer Protocol
  nntp        119/udp readnews untp #Network News Transfer Protocol
■endverbatim

   Most probably the %ETC%\SERVICES file is located either in
   ■tt{x:\TCPIP\ETC} or ■tt{x:\MPTN\ETC}.  If you need to specify
   non-standard port numbers, you should do that in the command line.
   Check the ■hpt{URL} specification.


■item

   unzip the VSZip archive in a temporary file directory (%TMP% is a
   good place).

■item

   copy the following files into a subdirectory of your choice (using
   a subdirectory contained in the PATH statement is always a good
   choice):

■itemize
■item
   VSOUP.EXE, the VSoup executable
■item
   YARNIO.CMD, the YIO script
■item
   YARNIOSET, the YIO configuration file
■description
■item Note:
      YARNIO.CMD & YARNIOSET must reside in the same subdirectory and
      must have the same filename, except the extension...
■enddescription
■item
   If you want YIO dial automatically, then you should also
   copy LOGINISP and LOGOUTISP as templates for your own
   connect/disconnect scripts.
■item
   OWNSOUPEXE and/or QSOUPEXE and/or CONVSOUPEXE should be copied if required.
■item
   If you want to have help available, then copy also the documentation: either
   VSOUP.INF or VSOUP.TXT (both have the same content but different format).
■item
   If you are interested in the source code, move it also to a
   specific subdirectory.
■enditemize

■item
   review the ■hpt{Command Line Options} section below and edit the
   YARNIOSET configuration file according to your specific needs.
   Also read the comments in YARNIOSET.

■description
■item Note:
   the setup of YARNIOSET is required only once. In future, updates
   will be made by amending YARNIO.CMD.
■enddescription

■item
   If you wish YARNIO.CMD to dial for you, you must also setup the
   scripts LOGINISP and LOGOUTISP to reflect your
   needs.

   Another option is to use your dialer to call your ISP (provider)
   and start YIO after the connection has been established.  The
   disadvantage of doing it this way is that after completion of
   YIO the dialer will not hang up immediately.

■description
■item Note:
      If you have only FAT drives you have to rename LOGOUTISP to
      something else.  Therefor you have to change the ■tt{hangupISP}
      setting in YARNIOSET too.
■enddescription

■item

   setup the directory structure for YIO:

■verbatim
  %HOME%── yarn             - subdirectory containing Yarn config file
           :
           ├── in           - root of YarnIo input subdirectories
           │   ├── mail     - primary     subdir for EMail reception
           │   ├── mail2    - optional #2 subdir for EMail reception
           │   ├── :                          :
           │   ├── mail9    - optional #9 subdir for EMail reception
           │   │
           │   ├── news     - primary     subdir for news reception
           │   ├── news2    - optional #2 subdir for news reception
           │   ├── :                          :
           │   └── news9    - optional #9 subdir for news reception
           ├── out          - subdirectory for EMail&news transmission
           :
■endverbatim

    In each of the ■tt{NEWS} subdirectories you will need to create an
    appropriate NEWSRC file as detailed in the ■hpt{Newsrc File}
    section.

    The ■tt{..MAIL}, ■tt{..MAIL2} until ■tt{..MAIL9} subdirectories
    have to be created only.  They should be left empty.

    The number of subdirectories depend on the number of servers you
    wish to poll.

■item

   change the following line in the Yarn-config file
   (%HOME%\YARN\CONFIG):

■verbatim
  reply-packet=%HOME%\yarn\out\reply.zip
■endverbatim

   If this is omitted or is incorrect then transmission of replies
   will not be possible, because Yarn will move its output to a place
   where VSoup does not expect it!  Of course %HOME% should be replaced
   by the actual value of HOME.

■item

   if you have setup LOGINISP and LOGOUTISP, start YIO
   directly.  Otherwise first dial-in to your ISP and then start
   YIO.

■endenumerate

   When you first start using VSoup I recommend that you add the -M
   option to each call of VSoup (e.g. in YARNIOSET) to force generation
   of the status mail.  This can be a good debugging aid...



■h2 Environment Settings
■label environment settings
■label environment
■i1 Environment Settings

  Environment variables are set in your CONFIG.SYS by lines such as:
■verbatim
  SET ETC=D:\TCPIP\ETC
■endverbatim
  Also they can be set in a dedicated script, which calls VS.

■description

■item EMXOPT
■i2 EMXOPT

   This are the settings for the emx runtime DLLs.  Recommended
   setting of this variable should contain -h40 to allow 40 file
   handles (not required, if you are calling VSoup through YIO).

■item ETC
■i2 ETC

   This is needed for accessing the TCP/IP configuration contained in
   the file %ETC%\TCPOS2.INI.  If -i is specified in the command line,
   ETC is not required.

■item HOME
■i2 HOME

   your home directory (can also be specified on the command line).
   If HOME is not defined, it defaults to the current directory.

■item MAILER
■i2 MAILER

   command for transmitting EMails (the EMail is piped into the stdin
   of MAILER).  If VSoup should do the job, MAILER must be undefined.

■item NNTPSERVER
■i2 NNTPSERVER

   hostname of the nntp server (can also be specified in the command
   line).  This variable is, in my opinion, obsolete and remains only
   to avoid compatibility problems.

■item POSTER
■i2 POSTER

   command for transmitting news (the article is piped into the stdin
   of POSTER).  If VSoup should do the job, POSTER must be undefined.

■item TMP
■i2 TMP

   points to the subdirectory which holds temporary files (VSoup
   generates ■sy{soup<xxxx>.tmp} as temporaries, with ■sy{<xxxx>}
   being a number between 0000 and 9999).  If TMP does not exist, the
   temporaries will be generated in the current subdirectory.

■item TZ
■i2 TZ

   setting of your time zone (e.g.  mine is ■tt{MET-1MES}).  Due to a
   bug in the emx runtime, the setting of this variable is critical
   for correct functioning of the emx C library revision 50.  Check
   the emx runtime documentation for the syntax of the TZ settings.

   An incorrect setting of TZ can also cause errors if you appear to
   be getting mail before it was sent.


■enddescription


■h2 VSoup And YarnIo Troubleshooting
■label troubleshooting

  some simple checks can be carried out:

■itemize

■item
   read the ■hpt{FAQ} section.

■item

   if VSoup does not run at all, initiate VSoup with ■tt{VSOUP -?}.  This
   should output the usage information to the screen.  If it does not,
   you have to check your system configuration.  Otherwise you should
   try to call VSoup in its different modes directly from the command
   line to check all your command line options.

■item

   generate the VSoup status mail with -M and check if it tells you the
   expected file locations and server names.

■item

   is the configuration file YARNIOSET correct and in the same
   directory as YARNIO.CMD?

■item

   is the subdirectory setup correct for YIO?

■item

   does the ■tt{pingHost} command work as expected?  Issue the program
   via REXXTRY to check the return values in connected/disconnected
   case.

■item

   if you have a setup including LOGINISP and LOGOUTISP you
   can also check if they work.  Run LOGINISP from a command line
   - login should be performed.  Then run LOGOUTISP - logout
   should be performed.  Now also the YIO auto-dial/hangup should
   work...

■item

   connect to your ISP and try ■tt{YARNIO -RCVMAIL -SEND -RCVNEWS2}.
   This will start only the ■tt{YarnIo RCVNEWS} window (hit ctrl-ESC
   and open it).  News reception should be performed as expected, at
   the end ImportProg to yarn will be initiated (after that 30s
   pause).

   You can check all single YIO modes this way.

■item

   is VSoup called in each window started by YIO?

■enditemize



■h1 Command Line Options
■label Command Line Options
■label command line option
■i1 Command Line Options

  This section describes the VSoup command line options in detail.  An
  example is presented first.

■h- Example

■verbatim
  VSoup -m -h d:\yourHomedir nntp://your.news.server
■endverbatim

  This would start VSoup telling it not to fetch mail (i.e. to collect
  news only) using a home directory called ■tt{d:\yourHomedir} from a
  news server named ■tt{your.news.server}. The ■sy{loginid} and
  ■sy{password} would by default be taken from your TCP/IP
  configuration.

■ipfminitoc


■h2 Global Options
■label global options

■description

■item -h<dir>
■i2 -h<dir>, set home directory

   sets the home directory for the VSoup operation.  You can also specify
   your home directory through the ■hpt{environment} variable HOME.

■item -i
■i2 -i, ignore TCP/IP configuration

   ignore the settings of the TCP/IP configuration.

■item -m
■i2 -m, do not fetch mail

   do not fetch mail.

■item -M
■i2 -M, generate status mail

   generate the VSoup status mail .\STSMAIL.MSG in any case.  Default is
   to generate the message in case of error only.

■item -n
■i2 -n, do not fetch news

   do not fetch news.

■item -r
■i2 -r, read only mode

   read only mode.  Only the .\AREAS, .\00*.MSG, .\00*.IDX files are
   written (e.g.  %HOME%\NEWSTIME, %HOME%\NEWSRC are not
   written). Also the EMails are not deleted from the POP3 server.
   Main purpose for this option is debugging.

■item -s
■i2 -s, send replies

   send replies.  Do not use this option in combination with -m or -n,
   if you do it will be ignored.

■item -T<n>
■i2 -T<n>, set throughput limit

   throughput must be higher than ■sy{<n>}, otherwise transfer will be
   aborted.  Throughput is checked against the limit ■sy{<n>} every
   10s after data transfer has begun.  If 6 samples show not enough
   throughput, VSoup will be aborted.  Default is '0 bytes/s', i.e. it
   will be checked for a stuck connection.  Use ■sy{-T-<n>} to check
   your throughput conditions.  Special case is -T-1, which disables
   throughput check.

■enddescription


■h2 News Receiving Options
■label news receiving options

■description

■item -a
■i2 -a, add new newsgroups

   add new newsgroups to the ■hpt{%HOME%\NEWSRC} file.  If there are
   any new groups on the server, the generation of the status message
   will be forced.  The new newsgroups will be added in the
   unsubscribed state.

■item -c[n]
■i2 -c[n], catchup

   catchup: mark every article as read except for the last ■sy{n}
   (default is 10).

■item -k<n>
■i2 -k<n>, set maximum packet size

   set maximum news packet size to n KBytes (default is no limit).
   ■sy{<n>} indicates the total amount of received messages, not the
   size of a single message (this can be done through ■hpt{scoring}).

■item -K<file>
■i2 -K<file>, set score file

   set the name of the ■hpt{score file} (see note below concerning
   ■hpt{-K/-N options}).

■item -N<file>
■i2 -N<file>, set newsrc file

   set the name of the ■hpt{NEWSRC} file (see note below regarding
   ■hpt{-K/-N options}).

■item -S<n>
■i2 -S<n>, set news receiving strategy

   receiving strategy (■sy{<n>}=0..2).  Speed increases (at least it should)
   in the direction 0 to 2, danger of receiving crossposted articles
   increases also from 0 to 2. The default of 1 is ok for most cases,
   but this parameter is an issue of fine tuning!

   How the strategy parameter operates:

■description
■item -S0

       groups are read sequentially, i.e. all threads are fetching
       articles from only one group.

■item -S1

       if one thread goes into waiting state the next group will be
       accessed - only small modification of the above.

■item -S2

       VSoup tries to keep all threads busy.  I.e. each thread
       accesses one dedicated group, groups are read in parallel (if
       there are no more groups to access, the waiting threads are
       used for parallel reading from one group).

■enddescription

   Recommendation:

■itemize
■item

      If you have a lot of groups with small amount of articles per
      fetch and only a little bit cross-posting, -S2 will be the
      best option for you.  If you allow reception of crossposted
      articles (see option -x), -S2 will be best for you in any
      case.

■item

      if you are accessing groups with large articles (i.e.  cost of
      double reception of crossposted articles is high), -S0 will be
      the best for you.

■enditemize

■item -t<n>
■i2 -t<n>, set number of threads

   receive the news with ■sy{<n>} threads, i.e.  connect to the NNTP server
   ■sy{<n>} times (limits are 1-10, default 4).

■item -u
■i2 -u, create news summary

   create news summary.  Output can be found in the .\00*.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).

■item -x
■i2 -x, do not process Xref headers

   do not process news Xref headers, i.e.  allow reception of
   crossposted articles.

■enddescription


■h3 Note Concerning The -K And -N Options
■label -K/-N options

  If you are using the -h option then use of either of the options -K
  or -N is not recommended, because behavior is not very transparent.

  If the -h option is placed behind the -K / -N options the result
  will not be as expected - VSoup (and Souper) will revert to ■tt{SCORE}
  and NEWSRC in the new specified home directory.

  If -K / -N options are placed behind the -h option and do not
  contain absolute paths, they will not be located in the home
  directory specified by -h.

  This is confusing and will be fixed in a future release.

 ■em{It is better and cleaner to use -h and setup the special}
 ■em{SCORE/NEWSRC files in that subdirectory!}


■h2 Mail Receiving Option(s)
■label mail receiving options

■description

■item -D
■i2 -D, force delete of mail

  If specified, VSoup will logout and login after reception of each
  EMail, thus effectively forcing deletion of the letter on the POP3
  server.  This is useful, if your connection to the POP3 server is
  aborted often and your mailbox is full.  Normal behaviour is to
  retrieve EMail without disconnecting/connecting.

■enddescription


■h2 URLs
■label URL
■i1 URLs

  The addresses of the hosts are given in ■bf{U}nified ■bf{R}esource
  ■bf{L}ocator (URL) form.  These do not fully conform to the
  standard, so a short explanation follows:


■itemize

■item
■i2 nntp://

   ■sy{nntp://[UserId[:Password]@]nntp-host[:port]} defines the address of
   your NNTP server (i.e. news server).  ■sy{UserId} and ■sy{Password}
   can be given if required for AUTHINFO.

■item
■i2 pop3://

   ■sy{pop3://[UserId[:Password]@]pop3-host[:port]} defines the address of
   your POP3 server.  ■sy{UserId} and ■sy{Password} are usually
   required.

■item
■i2 smtp://

   ■sy{smtp://[UserId[:password]@]smtp-gateway[:port]} defines your SMTP
   gateway.  ■sy{UserId} and ■sy{Password} are not required, in fact
   they are ignored by VS!

■enditemize

  The URL-feature makes VSoup different to Souper16, which wants to see a
  %HOME%\NEWSAUTH file for NNTP authorization.

  Notes:
■enumerate
■item
  It is not intended to implement other protocols like ■tt{http} or
  so.
■item
  If ■sy{port} is not specified, the actual port number is taken from the
  %ETC%\SERVICES file.  This is the recommended way of port number handling.
■endenumerate


■h3 Brief Description Of NNTP/POP3/SMTP

  Mail can be compared to the postal service, just like a letter.
  EMail-reception is handled through POP3 server (pop3:// prefix),
  transmission through SMTP gateways (smtp:// prefix).

  News messages are more like broadcasting, everybody will 'hear' your
  message.  News messages are transmitted and received via NNTP
  servers (nntp:// prefix).

  Perhaps it is a little bit confusing, that you can also deliver news
  via EMail service (just like the Yarn list).  The other way around
  is not possible...

  Anyway, please don't mix up news and EMail (your EMail might be
  news, but in these terms they remain EMails).


■h3 Evaluation Order Of URLs

  VSoup evaluates URLs in the following order:

■enumerate

■item

   take all information from the 'Internet Connection for OS/2'
   notebook settings

■item

   check the NNTPSERVER ■hpt{environment} settings
■description
■item Note1:
      NNTPSERVER is a URL without leading nntp://
■item Note2:
      there are no environment variables for the SMTP / POP3 setup.
■enddescription

■item

   command line options

■endenumerate

  If you specify only e.g. ■sy{nntp://your.news.server} in the command
  line (without userid/password), the userid and password from the
  TCP/IP configuration are taken as a standard value.


■h2 News Reception
■label News Reception

  For news reception you have the following options (which cannot
  combined):

■itemize
■item
   either process .\COMMANDS (.\COMMANDS exists),
■item
   or catch-up the newsgroups (-c option),
■item
   or create newsgroups summary (-u option),
■item
   or receive the news in the standard way (no specific option).
■enditemize

  New newsgroups are added to the %HOME%\NEWSRC file, when news is
  received in the standard way and the command line option -a is
  given.


■h1 Diagnostics
■index Diagnostic Codes

  VSoup returns with an exit code of ■bf{1}, if any operation failed.
  Otherwise return code will be ■bf{0}.

  Failing operations are:

■itemize
■item
  bad command line options,
■item
  bad setup (e.g. no ETC set, but 'Internet Connection' settings
  requested),
■item
  bad OS (e.g. D*°@!S),
■item
  user hit ^C or ^BREAK,
■item
  throughput check failed (e.g. connection broken),
■item
  could not setup connection (e.g. server not defined, server does not
  exist, server is down, etc.),
■item
  there was no .\REPLIES file and you have requested -s,
■item
  .\REPLIES contains an illegal entry,
■item
  .\MAIL.MSG or .\NEWS.MSG is malformed,
■item
  could not deliver news article, e.g. NNTP server did not allow it,
■item
  could not deliver mail, e.g. POP3 authentication failed,
■item
  MAILER / POSTER contains illegal value,
■item
  there is no NEWSRC file,
■enditemize

■h- .\STSMAIL.MSG

In case of an error condition the status message .\STSMAIL.MSG will be
generated.  Under the following additional cases .\STSMAIL.MSG will be
generated too:

■itemize
■item
  VSoup was called with the -M option (force .\STSMAIL.MSG generation),
■item
  VSoup was called with -a and there were new newsgroups on your NNTP
  server,
■item
  VSoup could not select a newsgroup specified in NEWSRC,
■item
  VSoup could not select a newsgroup specified in .\COMMANDS,
■item
  a newsgroup specified in .\COMMANDS was not contained in NEWSRC,
■item
  there was another command than ■tt{sendme} contained in .\COMMANDS,
■item
  a specified (■sy{-K<file>}) score file does not exist.
■item
  .\REPLIES contained an illegal (i.e. not understood by VS) reply
  type.  Legal reply types are 'b' and 'B',
■item
  .\REPLIES contained an illegal (i.e. not understood by VS) reply
  kind.  Legal reply kinds are ■sy{"mail"} and ■sy{"news"}.
■enditemize


■h- Future extensions

  The following failing operations are NOT yet implemented fully:

■itemize
■item
   there was no EMail in your POP3 mailbox,
■item
   there were no new news,
■item
   you have requested -s, but a message file is missing (VSoup deletes
   message files immediately after successful delivery.  Note that if
   you need two runs to deliver all your messages e.g.  one file will
   be missing on the second attempt.  This is considered ok).
■enditemize

  It is possible, that diagnostics code will change in the future.
  Return codes with a cleared bit 0 (like 0,2,4,...)  will indicate a
  non-fatal condition, return codes with a set bit 0 will indicate
  fatal conditions.



■h1 Utilities
■i1 Utilities

  This section describes the several utilities contained in VSZip
  archive in more detail.  For most users only the YIO files will
  be of interest.

■ipfminitoc

■h2 YarnIo
■label YarnIo
■index YarnIo
■i2 YarnIo

  As stated before YIO - actually consisting of YARNIO.CMD, YARNIOSET
  and optionally of LOGINISP and LOGOUTISP - is responsible for safe
  VSoup I/O operations.  The script(s) handle(s) the complete I/O between
  Yarn and the internet world.  Newsgroups are read from up to nine
  NNTP servers, mail/news packets are transmitted and mail is received
  again from up to nine POP3 servers - all simultaneously.  Actions
  can be disabled individually (type ■sy{YARNIO ?} for more
  information).

  The script should be started directly after the connection has been
  established.  It is also possible to let YIO dial out to
  establish the connection. To do this you must provide the two
  scripts LOGINISP and LOGOUTISP (see the ■hpt{installation}
  section).

  Most items of the user configuration are in a file called
  YARNIOSET.  It contains the settings for the initialization of the
  external programs including VSoup, ImportProg ...  calls.

■indent
  ■bf{You WILL need to amend the details in the YARNIO.SET file.}
■endindent

  Sorry, but the directory structure must be set up manually!  You
  should follow the structure given above in the ■hpt{installation}
  section.


■h3 YarnIo.Set
■label YARNIO.SET

  For configuration of YIO, YARNIOSET is required.  YARNIOSET must
  reside in the same directory as YARNIO.CMD and must have the same
  filename prefix (i.e. YARNIO).

  YARNIOSET contains the statements which determine how YARNIO.CMD is
  to call the several commands.

  To give you an idea what must be configured in YARNIOSET, an
  example follows.  There is a YARNIOSET contained in the archive,
  which includes more comments.

■verbatim
  :
'@SET NNTPSERVER='

preImportProg = 'ownsoup -q rgriech stuff4me OwnTemp'
importProg    = 'import.exe -u'
soupProg      = 'vsoup.exe'
soupSend      = soupProg '-s nntp://xmt.nntp.server'
soupRcvNews   = soupProg '-mai' '-h' rcvNewsDir 'nntp://1st.nntp.server'
soupRcvNews2  = soupProg '-mai' '-h' rcvNews2Dir 'nntp://2nd.nntp.server'
soupRcvMail   = soupProg '-n'
pingHost      = 'slipwait 2 2>&1 > nul'
connectISP    = 'cmd /c loginisp.cmd NOWAIT'
hangupISP     = 'cmd /c logoutisp.cmd'
unzipProg     = 'unzip.exe -oq'
zipProg       = 'zip -0mq'
  :
■endverbatim

■h- Remarks

■itemize
■item

  Instead of ■tt{slipwait} you could also use the command ■tt{'ping x.y.z 1 2>&1 > nul'}.
  The host ■tt{x.y.z} in ■tt{pingHost} must ■em{not} be contained in
  the ■tt{%ETC%\HOSTS}, because otherwise ■tt{pingHost} will return
  unexpected results.

■item

  Do not remove the option ■tt{'-h' rcvNewsDir} from the
  ■tt{soupRcvNews} line or the option ■tt{'-h' rcvNews2Dir} from the
  ■tt{soupRcvNews2} line.

■item

  If you are not interested in a service (e.g. ■tt{soupRcvNews2}), set
  the corresponding variable to '' (empty string).

■item

  If required, you can change the environment settings in YARNIOSET,
  e.g. the above ■tt{'@SET NNTPSERVER='} clears an existing
  ■tt{NNTPSERVER} environment variable.

■item

  To enable news server #3..#9, you have to add
  ■tt{soupRcvNews3}..■tt{soupRcvNews9} lines into YARNIOSET.  Use
  ■tt{soupRcvNews2} as a template.  Of course you have to set up the
  corresponding ■hpt{Newsrc File}s in the respective subdirectories.

  For POP3 server #2..#9 you have to set up
  ■tt{soupRcvMail2}..■tt{soupRcvMail9}.  You have to create the
  corresponding subdirectories manually.

  For setting up the correct subdirectory structure see also the
  ■hpt[Installation] section.

■enditemize


■h3 LoginIsp
■label LOGINISP.CMD
■i2 LOGINISP.CMD

  LOGINISP is an optional script, which allows YIO to dial in to
  your ISP.  The following example script will connect using the
  internet dialer.  If you are a customer of Advantis the script will
  work for you without any changes - of course you have to insert the
  correct ■tt{account user passwd} information.

■verbatim
/*
  LoginIsp  -  rg211096

  Login to your ISP.  If Option NOWAIT is given, the command will not wait
  until connection has been established.

  You have to do the following configuration:
  -  the line '...logoutisp...' must show the effective logoff script
  -  the line '...start...' must show the effective call of the dialer
  -  the line '...ping...' must show a pinger to check connection
 */

call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
call SysLoadFuncs

TRACE('')

option = ARG(1)

DO FOREVER
    '@cmd /c logoutisp.cmd'
    '@start dialer.exe account user passwd '-m'
    IF option = 'NOWAIT' THEN
        LEAVE

    DO j = 1 TO 20
        rc = SysSleep(3)
        '@ping www.cdrom.com 2>&1 > nul'
        IF rc = 0 THEN
            EXIT
    END j
END

EXIT
■endverbatim

■description

■item Note1:

  You will find an almost identical LOGINISP in the VSZip archive.

■item Note2:

  This LOGINISP requires a working LOGOUTISP.

■enddescription


■h3 LogoutIsp
■label LOGOUTISP.CMD
■i2 LOGOUTISP.CMD

  LOGOUTISP is an optional script, which allows YIO to disconnect
  from your ISP.  The following example script will disconnect using
  the internet dialer.  If you are a customer of Advantis the script
  will work for you without any changes - other than maybe changing
  ■tt{dialer} and ■tt{comPort}.

  This script is a little bit more complicated than LOGINISP,
  because it will

■enumerate
■item
   block itself to avoid multiple instances of itself
■item
   wait until the dialer has been closed
■item
   force a disconnect of the modem through switching DTR
■endenumerate

  An almost identical version of the script is contained in the
  VSZip archive.

■verbatim
/*
  LogoutIsp  -  rg211096

  Logoff from your ISP.

  The lines dialer/dialerClose,comPort must be configured
*/

call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
call SysLoadFuncs

dialer      = 'c:\tcpip\bin\dialer.exe'
dialerClose = dialer '-c'
comPort     = 'com3'

TRACE('')

parse source . . compCmdName
cmdName = filespec('name',compCmdName)
tmpDir  = value('tmp',,'os2environment')

lockFile = ''
IF tmpDir = '' THEN
    SAY 'please define %TMP% for locking' CmdName
ELSE DO
    lockFile = tmpDir || '\logout.sem'
    if stream( lockFile,'c','open write') \= 'READY:' then DO
        SAY CmdName 'already active...'
        EXIT
    END
END


if isActive(dialer) then do
    SAY 'logging off...'
   '@start /min' dialerClose

   rc = SysSleep( 2 )
   DO FOREVER
       IF \isActive(dialer) THEN
           LEAVE
       call HangupNow
       rc = SysSleep( 2 )
   END
end
call HangupNow

IF lockFile \= '' THEN DO
    rc = stream( lockFile,'c','close' )
    rc = SysFileDelete( lockFile )
END

EXIT


HangupNow:
'@mode' comPort || ',dtr=on  > nul'
'@mode' comPort || ',dtr=off > nul'
'@mode' comPort || ',dtr=on  > nul'
RETURN


isActive: PROCEDURE
prog = ARG(1)

'@pstat /c | RXQUEUE'

prog = TRANSLATE(prog)
found = 0
DO ii = 1 TO queued()
    PULL line
    IF POS(prog,TRANSLATE(line)) \= 0 THEN do
        found = 1
        LEAVE
    END
END
RETURN found
■endverbatim



■h2 OwnSoup
■label OwnSoup
■label OWNSOUP.EXE
■index OwnSoup
■i2 OwnSoup

  OwnS, with the help of the Yarn ImportProg program, redirects news
  articles matching a specific pattern into a mail folder.  OwnS can
  be seen as a notification program to allow easy tracking of
  news threads you are involved in.


■h- Syntax

  ■sy{ownsoup [-h] [-b] [-q] <pattern> <groupname> <outputfile>}

  where

■description
■item ■sy{[-h]}
  search for ■sy{<pattern>} in header of article only,
■item ■sy{[-b]}
  search for ■sy{<pattern>} in body of article only.  The subject line of the header is considered to be part of header and body.

  If ■sy{-h} or ■sy{-b} is not specified the default is to search the
  complete article,

■item ■sy{[-q]}
  be quiet.  Only the number of matches found will be displayed,

■item ■sy{<pattern>}
  is your search pattern which should be defined according to the ■hpt{regular expression} syntax,
■item ■sy{<groupname>}
  is a dummy groupname to allow easy filtering.  All the matching articles will contain the header line ■sy{X-ownsoup: <groupname>},
■item ■sy{<outputfile>}
  is the name of the temporary outputfile (the ■tt{.MSG}-extension will be added by OwnS).
■enddescription

  The generated ■sy{<outputfile>} will be registered in the .\AREAS
  file, thus ImportProg will also find the ■sy{<outputfile>}.  Note
  that the ■sy{<outputfile>} will be deleted after the ImportProg so
  that the actual name you choose is almost unimportant.


 ■break
■h- Example Setup of OwnSoup

■itemize

■item
   Assuming a script is used when importing news, directly before
   ImportProg is called, a line calling OwnS is placed in the script.
   This would be something like:

■verbatim
  ownsoup rgriech stuff4me OwnTemp
■endverbatim

  This example would search for ■sy{"rgriech"} in the header and body
  sections of each message, writing matching messages to an output
  file called OwnTemp after marking them with

■verbatim
  X-ownsoup: stuff4me
■endverbatim
  The Yarn ImportProg can now easily filter out any such news articles
  and put them in a mail folder which in this example we will call
  ■sy{"Personal"}.

   The search pattern here is ■sy{"rgriech"} but a more complex
   pattern could be used, for example I could search on a pattern of
   ■sy{"rgriech|hardy.griech"} which would find either my EMail name
   or my full name. The '.' wildcard is used in place of a space. The
   pattern must be in quotes because of the '|' character.

   Note that because no ■sy{-h} or ■sy{-b} parameter is set, OwnS will
   search both the header and the body of all messages.

   If you are using YIO, OwnS would be called by setting the
   ■sy{preImportProg} line in YARNIOSET.  Our example would require
   the following:

■verbatim
  preImportProg = 'ownsoup rgriech stuff4me OwnTemp'
■endverbatim

■item

  To setup a Yarn filter which moves all the messages matching the
  pattern ■sy{"X-ownsoup: stuff4me"} into the mail folder ■sy{"Personal"} you
  would do the following:

  Set up a filter using the Yarn FILTER.EXE program.  When run, this
  shows a box for details, which you would complete as follows:

■verbatim
┌ Mail Rule ───────────────────────────────────────────────────────────────┐
│                                                                          │
│  Rule name: MentionsMe                                                   │
│                                                                          │
│  Search in: ( ) From                                                     │
│             ( ) To                                                       │
│             ( ) Subject                                                  │
│             (*) Header                                                   │
│             ( ) Body                                                     │
│             ( ) Header and body                                          │
│                                                                          │
│ Search for: X-ownsoup: stuff4me                                          │
│ Match case: No                                                           │
│                                                                          │
│     Action: (*) Move to folder/newsgroup: Personal                       │
│             ( ) Delete                                                   │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
■endverbatim

  In the ■sy{"Search for"} line above, ■sy{"X-ownsoup: stuff4me"} represents the
  string you wish to search for, i.e. the string that OwnS puts in
  when it finds a match on its own search and ■sy{"Personal"} represents
  the name you wish the new mail folder to have.

  Note that Yarn's filter now only needs to search the header as it is
  only looking for the ■sy{"X-ownsoup: stuff4me"} line.

  After this preparation all incoming news articles will be checked
  for ■sy{<pattern>} as set in OwnS (in this case ■sy{"rgriech"}), and
  matching articles will be moved into the ■sy{"Personal"} mail
  folder.

■item

   Of course, you can set up more than one filter and if you wish you could put
   the output in different mail folders.

■enditemize


■h- Restriction

   Do not set up ■sy{"Personal"} as a newsgroup, because Yarn would
   skip the filtered articles in this case due to the ■tt{Message-ID:}.


■h- Others

■itemize
■item
  Articles filtered to ■sy{"Personal"} can be ■bf{replied} and ■bf{followed up}.
■item
  OwnS scans all files contained in .\AREAS matching the SOUP formats
  ■sy{"b"} and ■sy{"u"}, i.e. files containing news articles.  The
  generated file has the binary 8-bit clean mail SOUP format
  (■sy{"bn"}).
■enditemize



■h2 QSoup
■label QSoup
■label QSOUP.EXE
■index QSoup
■i2 QSoup

   QS (pronounce 'queue soup') appends mail and news messages to the
   Yarn ReplyPacket file for transmission by VSoup.  The messages must
   contain all required header fields, i.e. QS does not manipulate the
   content of the message, except that it does '\r' stripping and
   interpretes ^Z as end of message.


■h- Syntax

  ■sy{qsoup [-m] [-v] [-i] [-h<dir>] [-l<file>] [<inputfile>]}

  where

■description
■item ■sy{[-m]}
  the message input to QS is a mail, default is news,
■item ■sy{[-v]}
  be verbose,
■item ■sy{[-i]}
  ignore all options coming behind the ■sy{<-i>}.  This is useful, if
  the calling program appends command line arguments which are not
  known by QS,
■item ■sy{[-r<file>]}
  set the name of the ReplyPacket to ■sy{<file>}.  Default is to read
  the name of the ReplyPacket from ■tt{%HOME%\YARN\CONFIG} in the
  line reply-packet,
■item ■sy{[-l<file>]}
  use ■sy{<file>} as the lock file for access control to the ReplyPacket.
  Default is to use ■tt{%YARN%\HISTORY.PAG},
■item ■sy{[<inputfile>]}
  is the name of the message file.  If omitted, the message will be
  read from stdin, thus allowing to connect the message provider and
  QS through a pipe.
■enddescription


 ■break
■h- Example Setup Of QSoup And Sendmail

  Using sendmail has several advantages.  First, it is a standard tool
  which is used by many programs for mail delivery (e.g. ■bf{Lynx}).
  Second, it is very flexible and allows routing of messages depending
  on their recipients address.  The second point is also the weakest
  point of sendmail: it is hard to configure.

  This example shows my setup of sendmail.  But be warned: I am no
  sendmail expert and to get this configuration running was a lot of
  fiddling!

 ■break
  My changes to the standard configuration were as follows:

■itemize
■item
   take the original sendmail.uml from Warp Connect and copy it to ■tt{%ETC%\sendmail.cf},
■item
   insert the following two lines in the very beginning of sendmail.cf:
■verbatim
  Cwworkstationname.domain
  Dwworkstationname.domain
■endverbatim
■item
   change the ■tt{OQ} setting so it reflects the subdirectory of your mail queue
   (which in fact should not be required, because the mails are received by QS immediately),
■item
   set the ■tt{H?F?From:} field to your EMail address.  This will be
   the default address, if nothing else is specified in the
   ■tt{From:}-header of the message,
■item
   in the ■tt{Ruleset 0} at the end of the first section specify the rule
■verbatim
  R$+<@$+>              $#local $:$1
■endverbatim
   This will instruct sendmail to direct all mails to the local mailer program.
   Note that the blanks between the ■tt{>} and the ■tt{$} have to be tabs,
■item
   change the local mailer program, so that it shows the following:
■verbatim
  Mlocal, P=d:\b\32\qsoup.exe , F=lmnDFM, S=10, R=0, A=-m -i $u
■endverbatim
   You have to replace the ■tt{d:\b\32} with the actual QS path.  If this path
   is not correct, sendmail will not deliver the mails!
■enditemize

  After you have done the setup, you should check it with a dummy
  mail.  Type in the following:

■verbatim
  sendmail -t
  --->IBM OS/2 SENDMAIL VERSION 1.3.17
  --->reading ...\sendmail.cf 10
  to: dummy@x.y.z
  subject: sendmail/qsoup testing

  Hello
  ^Z                    (this is a ctrl-Z!)
  --->11/09/96 19:01:03 mail delivered from:  YourName
■endverbatim

  Now you can check the successful delivery with the command ■tt{unzip
  -Cp -aa reply-packet mail.msg}.  The output should be something like
  that:

■verbatim
  Received: by ibm.net (IBM OS/2 SENDMAIL VERSION 1.3.17/2.12um) id AA3986; ...
  Date: Sat, 09 Nov 96 18:59:40 +0100
  From: YourName
  Message-Id: <[e-mail]>
  To: dummy@x.y.z
  Subject: sendmail/qsoup testing

  Hello
■endverbatim

  Note, that sendmail inserted the missing ■tt{Date:}, ■tt{From:} and
  ■tt{Message-Id:} header lines (the redundant header ■tt{Received:}
  too).  ■tt{YourName} should show the correct settings.

  After successful test you should delete the reply packet file.  For
  the actual 'diff' of my sendmail.cf and sendmail.umf see also the
  ■hpt{FAQ}.



 ■break
■h- Miscellaneous

■itemize
■item

   If you are using QS as a sendmail mailer program you can not setup
   sendmail as the MAILER of VSoup (see ■hpt{environment settings}).

   First, this would result in a deadlock during transmit action
   of VSoup, because the invoked sendmail would invoke an instance of
   QS, which could not proceed, because the Yarn ReplyPacket
   would be held by the transmitting VSoup.

   Second, this would not be a meaningful configuration, because the
   mail would loop endlessly in your computer without being ever
   transmitted to the external world.

   If other programs require the MAILER environment variable pointing
   to sendmail and if sendmail is configured to deliver mails to QS,
   one should clear MAILER prior to the VSoupSend call.  For YIO
   operation this could be done in YARNIOSET.

■item
   Because QS has to unzip/zip the ReplyPacket, do not expect fast
   operation.  Anyway appending a message to the ReplyPacket will be
   much faster than the actual delivery to the network.
■item
   If QS is copied to an executable with the name sendmail (■tt{SENDMAIL.EXE})
   and is invoked as sendmail, QS mode defaults to
   'get a mail from stdin'.  If QS is copied to an executable with the name
   inews (■tt{INEWS.EXE}) and is invoked as inews, QS mode
   defaults to 'get a news article from stdin'.

   All command line options will be ignored in either case.  Keep in
   mind, that the messages must contain all required header fields.
■item
   The exact access criteria for ReplyPacket access are as follows:
■enumerate
■item
      Set ■tt{%YARN%\HISTORY.PAG} to writable without access sharing.  This
      operation must be accomplished successfully.
      ■tt{%YARN%\REPLIES} is the default lock file which can be
      overridden by the ■sy{-l<file>} option.
■item
      The ■tt{REPLIES} file in the ReplyPacket subdirectory must not
      exist.
■endenumerate
   Criterion (1) blocks QS, if Yarn is active.  Also this works like a
   semaphor and prevents multiple instances of QS to access the
   ReplyPacket.  Criterion (2) prevents QS from accessing the
   ReplyPacket if it is unzipped, e.g. during VSoupSend.

   Don't forget that an open Yarn or an active VSoupSend
   blocks QS.  This means, as long as another application accesses
   either the ■tt{lockfile} or the Yarn ReplyPacket, QS can not
   perform the requested operation.
■enditemize




■h2 ConvSoup
■label ConvSoup
■label CONVSOUP.EXE
■index ConvSoup
■i2 ConvSoup

  ConvS is a small program which converts the VSoup SOUP output files,
  which are in binary format (■sy{"bn"} & ■sy{"Bn"}) into UNIX mailbox
  format (■sy{"mn"}) and USENET batch format (■sy{"un"}) respectively.  The
  output files are written with '\n' as line separator.

  ConvS must be started in the subdirectory that contains the .\AREAS
  and the .\*.MSG files.

  ConvS is useful for people who wants to use VSoup with offline newsreader which do not
  recognize VSoup's packet format directly.  Although VSoup complies to SOUP, some readers only
  know about UNIX mailbox and USENET batch format.
  E.g. Changi's RNews expects USENET batch format on its input.


■h2 ModifyEmxH
■index ModifyEmxH
■i2 ModifyEmxH

  This script is of interest for people who wants to compile VSoup on
  their own.  MODIFYEMXH.CMD is required for multiple inclusion of the
  ■tt{os2.h} and ■tt{os2emx.h} header files.

  MODIFYEMXH.CMD reads form stdin and copies to stdout.  Keep in mind,
  that multiple inclusion of the above mentioned headers is not
  standard.  It is just for my convenience.

■h2 RmHigh
■index RmHigh
■i2 RmHigh
■label RmHigh
■label RmHigh.Cmd

  RMHIGH.CMD removes the highlighting from VSOUP.TXT.  This is useful
  for people who wants to read the documentation in text mode and have
  no pager or editor available which understands the poor (wo)mans
  highlighting used in VSOUP.TXT.

  GNUs LESS is an example of a pager that handles the distributed
  VSOUP.TXT correctly.


■h1 Files
■i1 Files

  This section describes all the input and output files used and
  generated by VSoup in detail.  Under normal circumstances %HOME%\NEWSRC
  and %HOME%\SCORE are the only files of interest.  For description of
  YIO files, see the YIO section.

■ipfminitoc

■h2 The Newsrc File
■label Newsrc File
■label %HOME%\NEWSRC
■label NEWSRC
■i2 The Newsrc File

  %HOME%\NEWSRC contains the list of newsgroups.

■description
■item ':'
   behind the name indicates subscribed group,
■item '!'
  indicates an unsubscribed one.
■enddescription

  The list of newsgroups can be obtained from the news server by using
  the -a option of VSoup (see ■hpt{FAQ}) or can be prepared with a text
  editor as follows:

  List the newsgroups you want to receive, one per line, and end each
  line with a colon. For example:

■verbatim
  comp.answers:
  news.answers:
  rec.humor.funny:
■endverbatim

  VSoup will keep track of fetched articles by recording the article
  numbers in this file.


 ■break
■h- Syntax

  For anyone who really wants to know, the syntax of the file is as
  follows:

 ■sy{%HOME%\NEWSRC ::= <lines>}

 ■sy{<lines> ::= <line> <lines> | empty}

 ■sy{<line> ::= <groupname> <sep> <article-ranges> "\n"}

 ■sy{<sep> ::= "!" | ":"}

 ■sy{<article-ranges> ::= <article-ranges> "," <art-range> | <art-range> }

 ■sy{<art-range> ::= " " <art-num> | " " <art-num> "-" <art-num> }

  ■sy{<groupname>} is the name of a group, ■sy{<art-num>} is a long
  integer.  ■sy{<article-ranges>} must be sorted in ascending order to
  be recognized correctly.  Blanks are only allowed at the indicated
  positions.

  Under normal circumstances, only the ■sy{<sep>} is important to the
  user for subscribing and unsubscribing groups.


■h2 The Score File
■label scorefile explanation
■label score file
■label scoring
■i2 The Score File

  The score file specifies criteria used to exclude articles from the
  VSoup packet. You can kill articles that have a specific subject,
  are from a specific poster, or contain a particular string anywhere
  in the header.  Even killing of articles which do ■bf[not] contain a
  specific pattern in their header is possible with scoring.

  %HOME%\SCORE is the default score file.  The name and subdirectory of
  the score file can be configured by specifying the ■sy{-K<scorefile>}
  ■hpt{command line option}.  This allows one single score file for all
  news servers you wish to access.

  An entry in the score file, also called ■sy{<score-section>}, has the format:

  ■sy[<score-group> "{"]■break
  ■sy[    <score-rule>]■break
  ■sy{           ...}■break
  ■sy["}"]

  with ■sy{<score-rule>} being one of the following alternatives:

■enumerate
■item
  ■sy[<score> "lines"] ■tt[">"] ■sy[<number>]
■item
  ■sy[<score> "lines"] ■tt["<"] ■sy[<number>]
■item
  ■sy[<score> "pattern" "header" <reg-exp>]
■item
  ■sy[<score> "pattern" <where> <reg-exp>]
■item
  ■sy[<score> "header" <string>]
■item
  ■sy[<score> <where> <string>]
■endenumerate

  ■sy[<score-rule>]s ■bf{1.} and ■bf{2.} are for scoring of the article
  length, ■bf{3.}  and ■bf{4.} are both working with ■hpt{regular
  expressions} (■sy[<reg-exp>]), ■bf{5.} and ■bf{6.} are working with
  literal strings (■sy[<string>]).  ■bf{3.} and ■bf{5.} are scanning
  the complete header for the corresponding patterns, ■bf{4.} and
  ■bf[6.]  are matching its pattern only in the corresponding header
  line ■sy{<where>}.


  ■break
■h- Description of the score-section elements

■description
■item ■sy{<score-group>}

   ■sy{<score-group>} is a ■hpt{regular expression}.  The contained
   ■sy{<score-rule>}s are applied to newsgroups which are matched by
   the ■sy{<score-group>} regular expression completely.  If
   ■sy{<score-group>} is the string ■tt{"all"}, the ■sy{<score-rule>}s
   are applied to all newsgroups.

■item ■sy[<score-rule>]

   see above.

■item ■sy{<score>}

   is the score which has been assigned to the ■sy[<score-rule>].  All
   scores of ■sy[<score-rule>]s matching an articles header are added
   up and then compared to the ■sy[<kill-threshold>].  If the total
   score is less than the ■sy[<kill-threshold>], the article is
   killed.

■item ■sy[<where>]

   specifies where to search in the header. ■sy{from} searches the
   ■tt{From:} line, ■sy{subject} searches the ■tt{Subject:} line and
   so on.  The special ■sy{<where>}-pattern ■sy{"header"} searches all
   the lines in the header of the article.

■item ■sy{<reg-exp>}

   is the string in form of a ■hpt{regular expression} to search for.

■item ■sy[<string>]

   is the literal string to search for.

■item ■sy[<number>]

   is a line number to which the actual article length is compared.

■enddescription


 ■break
■h- Special score-sections

There are two special ■sy[<score-section>]s:

■description
■item ■sy["quit"]
   stops reading of the score file immedialtely.
■item ■sy["killthreshold" <kill-threshold>]
   sets the threshold for killing articles, i.e. the lowest
   limit articles should fulfill to not being killed.  The threshold
   is global (i.e. applies to all groups and rules) and the last
   occurance of ■sy["killthreshold"] counts.
■enddescription

Lines beginning with a '#' in the first non-blank position are treated as comments.


 ■break
■h- Remarks

■itemize

■item
   All fields are case-insensitive.
■item
   After ■sy["header"] and ■sy[<where>] a colon (■sy[":"]) is allowed.
■item
   News transmission speed decreases if a score file is used, because
   an article is fetched then in two steps: ■tt{HEAD <num>}, then
   ■tt{BODY <num>}.  Otherwise an article will be fetched in only one
   single step: ■tt{ARTICLE <num>}.  Offline-Scoring of Yarn is also
   more flexible than this online-scoring because you can change your
   mind about the scores ■bf{after} reception of the articles!
■item
   It is pretty legal to break the scoring criteria of several ■sy{<score-group>}s
   in several ■sy{<score-section>}s.
■item
   If ■sy["header"-<score-rule>]s are applied, the pattern is searched for
   in the complete header, i.e. one can also match specific header fields.
■item
   The ■sy{<score-group>} ■tt{"all"} is transformed to the regular
   expression ■tt{".*"}.
■item
   Although the ■tt{"."}s in newsgroup names are meta characters of
   ■hpt{regular expressions} this should not do any harm to 'normal'
   group matching.  E.g. the ■sy{<score-group>} expression
   ■tt{"comp.os.os2.programmer.misc"} will match only one group in real life.
■item
   The score file works on news only.
■item
   Check the ■hpt{FAQ} for example score files.
■enditemize



 ■break
■h- Syntax

The exact syntax of the score file is as follows:

 ■sy{%HOME%\SCORE ::= {<line> "\n"}*}

 ■sy{<line> ::= '#' <text> | <score-section>}

■indent

  Lines beginning with a '#' indicates a comment, ■sy{<text>}
  indicates literal strings.

■endindent

 ■sy{<score-section> ::= "all" "{" <score-rules> "}"} ■break
 ■sy{                 | <score-group> "{" <score-rules> "}"} ■break
 ■sy{                 | "killthreshold" <number>} ■break
 ■sy{                 | "quit"} ■break

■indent

  ■sy{"all"} indicates, that the following ■sy{<score-rules>} is valid
  for all newsgroups, The ■hpt{regular expression} ■sy{<score-group>}
  limits the ■sy{<score-rules>} to specific newsgroups.

■endindent

 ■sy[<score-rules> ::= <score-rule> "\n" {<score-rules>}]

 ■sy[<score-rule>  ::= <score> "lines"] ■tt[">"] ■sy[<number>] ■break
 ■sy[            | <score> "lines"] ■tt["<"] ■sy[<number>] ■break
 ■sy[            | <score> "pattern" "header" <reg-exp>] ■break
 ■sy[            | <score> "pattern" <where> <reg-exp>] ■break
 ■sy[            | <score> "header" <string>] ■break
 ■sy[            | <score> <where> <string>] ■break

■indent

  ■sy[<score>] is a number (the score!), ■sy[<number>] too, ,
  ■sy[<reg-exp>] is a ■hpt{regular expression}, ■sy[<where>] and
  ■sy[<string>] are literal strings.

■endindent

  ■break
■description
■item Note:
   ■sy{"\n"} is the newline character.  It is mandatory!
■enddescription



■h3 Regular expression syntax
■label regular expression syntax
■label regular expression
■label regular expressions

   The following description has been taken from the ■tt{man regexp}
   pages (BSD experimental).

   A regular expression is zero or more branches, separated by ■sy{|}.
   It matches anything that matches one of the branches.

   A branch is zero or more pieces, concatenated.  It matches a match
   for the first, followed by a match for the second, etc.

   A piece is an atom possibly followed by ■sy{*}, ■sy{+}, or ■sy{?}.
   An atom followed by ■sy{*} matches a sequence of 0 or more
   matches of the atom.  An atom followed by ■sy{+} matches a sequence
   of 1 or more matches of the atom.  An atom followed by ■sy{?}
   matches a match of the atom, or the null string.

   An atom is a regular expression in parentheses (matching a match
   for the regular expression), a range (see below), ■sy{.}  (matching
   any single character), ■sy{^} (matching the null string at the
   beginning of the input string), ■sy{$} (matching the null string at
   the end of the input string), a ■sy{\} followed by a single
   character (matching that character), or a single character with no
   other significance (matching that character).

   A range is a sequence of characters enclosed in ■sy{[]}.  It
   normally matches any single character from the sequence.  If the
   sequence begins with ■sy{^}, it matches any single character not
   from the rest of the sequence.  If two characters in the sequence
   are separated by ■sy{-}, this is shorthand for the full list of
   ASCII characters between them (e.g. ■sy{[0-9]} matches any decimal
   digit).  To include a literal ■sy{]} in the sequence, make it the
   first character (following a possible ■sy{^}).  To include a
   literal ■sy{-}, make it the first or last character.



■h2 Other Files

■h- .\COMMANDS
■i2 .\COMMANDS

  contains lines with the syntax: ■sy{'sendme' <groupname>
  <article-ranges>}.  .\COMMANDS is executed instead of standard
  fetching of news (see also ■hpt{News Reception}).  After successful
  .\COMMANDS processing, the file will be deleted.

■description
■item Note:
   articles which have already been read (marked in %HOME%\NEWSRC) will be skipped!
■enddescription

■h- %HOME%\NEWSTIME
■i2 %HOME%\NEWSTIME

  contains the time of the last NNTP connection.  This is for fetching
  of new newsgroups.  If %HOME%\NEWSTIME does not exist, ■bf{all}
  currently available newsgroups are fetched from the server when
  VSoup was called with the -a option.

■h- %TMP%\SOUP*.TMP
■i2 %TMP%\SOUP*.TMP

  temporary files for received articles. ■sy{*} will be replaced by a
  number in the range 0-9999.  If %TMP% is not defined, %TMP% will be
  substituted by a '.'


  ■break
■h- .\00*.MSG
■i2 .\00*.MSG

  contain the received messages (news articles & EMail).  The files
  are written in the following SOUP formats:

■itemize
■item
   Binary 8-bit clean news format (■sy{"Bn"}) for incoming news.
   Lines are delimited by a single '\n',
■item
   Binary 8-bit clean mail format (■sy{"bn"}) for incoming mails.
   Lines are delimited by a single '\n'.
■enditemize
   Note that the format of the message files can be changed to UNIX mailbox and USENET batch using ConvS.


■h- .\00*.IDX
■i2 .\00*.IDX

  contain the received newsgroup summaries (-u option).  The files are
  written in the SOUP ■sy{"ic"} format.

■h- .\STSMAIL.MSG
■i2 .\STSMAIL.MSG

  contains the status message generated by VS.  This file is written
  in the SOUP UNIX mailbox format (■sy{"mn"}).  Lines are delimited by
  a single '\n'.

■h- .\AREAS
■i2 .\AREAS

  contains the table of contents of the received .\00*.MSG / .\00*.IDX
  files (+ .\STSMAIL.MSG).


  ■break
■h- .\NEWS.MSG
■i2 .\NEWS.MSG

  contains the news messages that should be sent to the NNTP server.
  The following SOUP formats are supported:

■description
■item ■sy{"B"}
  Binary 8-bit clean news format.  The files are read in binary mode
  but transferred in text mode to the NNTP host,
■item ■sy{"u"}
  USENET batch format with the area name ■sy{"news"}.  The files
  are read in binary mode, thus '\r\n' pairs are treated as two
  characters (this is not according to RFC1036 but according to Soup12.Html).
■enddescription



■h- .\MAIL.MSG
■i2 .\MAIL.MSG

  contains the mail messages that should be sent to the SMTP server.
  The following SOUP formats are supported:

■description
■item ■sy{"b"}
  Binary 8-bit clean mail format.  The files are read in binary mode
  but transferred in text mode to the SMTP gateway,
■item ■sy{"u"}
  USENET batch format with the area name ■sy{"mail"}.  The files
  are read in binary mode, thus '\r\n' pairs are treated as two
  characters (this is not according to RFC1036 but according to Soup12.Html).
■enddescription


■h- .\REPLIES
■i2 .\REPLIES

  contains the table of contents of the .\NEWS.MSG / .\MAIL.MSG files
  to be transmitted.  Instead of the above file names other names
  could be used too.



■h1 Insufficiencies, Bugs & Plans

■h- Insufficiencies

■itemize

■item

   some cmd options, some files are not compatible with Souper16

■item

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

■item

   behaviour for news receiving/posting, mail receiving/posting is not
   symmetrical, i.e.  there is no multithreading except for news
   receiving...  This will be (perhaps) fixed in a future version

   E.g. start threads for connecting to the hosts for transmission,
   start a thread for overall transmission, start a thread for overall
   mail reception.  This all will allow parallel operation of
   sending/receiving NNTP/POP3/SMTP stuff with one single VSoup.

■item

   only one single version (for OS/2)

■item

   it is not clear, how to handle '\r\n' pairs in the SOUP format!
   Soup12.Html says '\r' should be treated as data, but '\r\n' must be
   avoided.  In Soup12.Html '\r' are counted just like normal data
   bytes.

■enditemize



■h- Bugs

■itemize

■item

   version of the emx runtime is not checked!

■enditemize


■h- Plans

■itemize

■item
   remove bugs & insufficiencies
■item
   more situation dependent return codes
■item
   perhaps more status information on the screen
■item
   perhaps the servers IP address will be added to status messages
■item
   perhaps write Subject: to .\STSMAIL.MSG for mail reception/transmission
■item
   real Bcc: implementation for mailing
■enditemize



■h1 Author & Acknowledgements

■h- Author

  Hardy Griech■break
  Ernetstr. 10/1■break
  77933 Lahr■break
  Germany

  EMail:  ■url{mailto:[e-mail] (VSoup bug)|[e-mail]}


  ■break
■h- Acknowledgements

■itemize

■item

   FSF for GCC (2.7.2.1 used), EMACS (19.33.1 used),

■item
   Eberhard Mattes for the GCC & EMACS ports to OS/2 and the
   documentation utility emxdoc, which made the ■tt{.INF}-file possible,
■item
   Chin Huang for Yarn and Souper,
■item
   the gamma testers Jim Holcomb, Kay Pyrtek, Phil Crown and Ralph D. Bednarski,
■item
   Barrie Smith for rework on the documentation, for many suggestions
   about documentation and a lot of proof reading!
■item
   Timo Maier for his excessive help finding the Warp4 related bug which led to system crashes (see ■hpt{history}, VSoup1.2.7).
■enditemize



■html
   <A NAME="history"></a>
■endhtml
■h1 History
■label history

■h- Version 1.2.8 (190497)

■itemize

■item
   new features:
■itemize
■item
     Scoring introduced, see ■hpt{score file}.
■enditemize

■item
   obsolete features:
■itemize
■item
     The ■tt[-l] and ■tt[-L] command line options are obsoleted by scoring.  These options allowed length limitations of articles.
■enditemize

■item
   bug fixes:
■itemize
■item
     Small bug in pop3.cc which led to undefined/sick error messages.
■enditemize

■item
   other internal changes:
■itemize
■item
     In pop3.cc mails are now no longer blocking the areas-files during mail reception.  Instead incoming mail is copyied into a temporary file.
     This is a preparation step to allow simultaneous reception of mail/news.
■enditemize
■enditemize


■h- Version 1.2.7 (120297)

■itemize

■item
   new features:
■itemize
■item
     Port specification in ■hpt{URL}s is now supported.
■item
     .\STSMAIL.MSG now contains a ■tt{Date:} header field.  This allows import of the
     .\STSMAIL.MSG into a pseudo newsgroup, see also the Yarn FilterProg program.
■item
     The ■tt{Subject:} header line of .\STSMAIL.MSG now contains also the server names
     which are relevant for the requested operation.
■item
     The first 40K of temporary files are kept in memory to reduce HDD access (class ■tt{TFileTmp}).
■item
     National language support (■tt{_nls_tolower()}) introduced for kill expressions, OwnS and hashing.
■item
     newsgroup names in kill files are now regular expressions.
■item
     new Option ■sy{-L<n>} allows specification of minimum article length (see ■hpt{news receiving options}).
■item
     new Option ■sy{-D} forces deletion of mails on POP3 server after reception of each mail (see ■hpt{mail receiving options}).
■item
     ■hpt{RmHigh.Cmd} added, which removes the highlighting in VSOUP.TXT.
■enditemize

■item
   bug fixes:
■itemize
■item
    VSoup crashed some Warp4 systems (trap address 0140:7d4c or 0140:7e33).
    This was fixed through serializing some C library calls (■tt{remove()}, ■tt{rename()}, ■tt{open()}, ■tt{close()}, ■tt{read()}, ■tt{write()}, ■tt{lseek()} and ■tt{ftruncate()}).
    This problem is most likely device driver related, although nothing specific is known. Thanks to Timo, Stefan, Nate, Rodney, Soenke, Tero and Teng Thiam for their help in finding the problem.
■item
    Bug in emxlibcm <= 52 (don't know, what will happen later on):  _fd_init() is not threadsafe, i.e. all callers too (open(), socket(), etc).  Perhaps
    This is the cause of the trap problem above (not verified, rg120297)
■item
    Incomplete packets are now removed from the SOUP output.  Problems appeared with
    aborted EMail reception (which writes directly into the SOUP output and not to a temporary).
■item
    -T-1 no longer shows throughput info (see ■hpt{global options}).
■item
    Signals were not initialized for ■tt{mtGetGroup()} with option -S2.
■item
    In SOUP .\REPLIES the types ■sy{"bn"}/■sy{"Bn"} now override the message kind
    ■sy{"mail"}/■sy{"news"}, which is required for type ■sy{"u"}.
■item
    handling of ■sy{"m"} and ■sy{"u"} SOUP format in .\REPLIES corrected (file positioning was wrong).
■item
    "ok, we've read enough..." now displays correctly.
■item
    ■tt{%}-display with -S1 reading strategy now (more) correct.
■item
    handling of "\r\n" delimited reply files corrected.
■item
    files are now opened with SH_DENYWR.
■item
    missing NEWSRC is no longer fatal (useful for initial setup).
■enditemize

■item
   other internal changes:
■itemize
■item
     The threads are no longer killed through ■tt{DosKillThread()}.  Instead,
     threads are killing themselves (when they are detecting an abort condition) through ■tt{SIGUSR1}.
     Sockets are being set to ■tt{O_NONBLOCK} to abort current requests.
■item
     ■tt{assert(_heapchk() == _HEAPOK)} inserted in some places.
■item
     ■tt{nhandles()} aborts after checking 150 handles.
■enditemize

■enditemize



■h- Version 1.2.5 (091196)

■itemize

■item

   Improved Documentation, thanks to Barrie Smith.

   Documentation now in TXT and INF format available, thanks to
   emxdoc.

■item

   SOUP format for ImportProg has been changed:

■itemize
■item
      .\STSMAIL.MSG has format ■sy{"mn"} (same as before)
■item
      from POP3 incoming Mails have format ■sy{"bn"}: binary 8-bit clean mail format.
      This allows from headers in the first column of the mail, i.e.
      mail handling is now transparent (old was ■sy{"mn"}).
■item
      news have format ■sy{"Bn"}: binary 8-bit clean news format (old was
      ■sy{"un"})
■enditemize
   To allow the conversion to the old format ConvS has been added.

■item
   Added OwnS which filters news articles containing a specific pattern into a mail folder.
■item
   Added QS to allow injection of messages into the SOUP reply packet.
■item

   YIO changes:
■itemize
■item
   YIO now only zips the SEND packets (this is to allow re-edit of the
   replies).  Received messages are imported via ■tt{import -u}.
   If you have an older version of YARNIOSET it must be updated.
■item
   YIO now supports OwnS.  To allow operation of OwnS the entry ■tt{preImportProg} has
   been added to YARNIOSET.
■item
   YIO now supports up to nine NNTP servers for news reception and up to nine POP3 servers for EMail reception.
■enditemize

■item

   -T-1 disables throughput check completely.

■item

   the ■sy{<kill-section>} for one ■sy{<group>} can now be seperated,
   e.g. the kill file may now contain several ■sy{"all"} sections.

■item

   now article ranges are allowed in the ■tt{sendme} of .\COMMANDS.
   This is a non-standard SOUP extension.

■item
   bug fixes:

■itemize
■item
      hostname is now fetched through TCP/IP API, no longer from
      'internet settings'
■item
      it was possible in -S2 that during final catchup of articles
      the connections were changing group assignment on each fetched
      article
■item
      catchup did not work as expected.  It sets the %HOME%\NEWSRC, so
      that in any case 'n' articles were read afterwards.  Display now
      shows groupLo & groupHi
■item
      ^Z was not recognized correctly for %HOME%\NEWSRC & %HOME%\KILL
■item
      Now again linked dynamically, ths ■bf{EMX.DLL} and ■bf{EMXLIBCM.DLL} are required
■item
      Lines containing a single '.' were aborting EMails, even if
      the '.' is actually doubled for transfer.  Don't know if this
      is an SMTP bug.  Appending a blank behind the '.' helped
      (i.e. ".. " is actually transferred to the SMTP server).
      For news articles it works without appending the blank.
■item
      sockets are now opened in text mode, because all the RFCs
      requires \r\n as a line delimiter.
■enditemize

■enditemize



■h- Version 1.2 (061096)

■itemize

■item
   first non-beta release

■item
   more detailed README

■item

   YIO enhanced (autodial, disabling specific actions, configuration
   file, ...)

■item

   some changes/enhancements/extensions in .\STSMAIL.MSG, e.g.  command
   line parameters are contain, important server names too...  (useful
   for debugging)

■item

   if supported by the NNTP server, the XHDRs are retrieved to
   determine holes in the article sequence

■item

   throughput check (-T option) now replaces the old timeout
   detection.  It is now working for all operations.

■item
   news reading, strategy parameter:

■description
■item -S0

      groups are read sequentially, i.e.  all threads are fetching
      articles from only one group

■item -S1

      the next group will be accessed, if one thread goes into waiting
      state - only small modification of the above

■item -S2

      it is tried, to keep all threads busy.  I.e.  each thread
      accesses one dedicated group, groups are read parallel (if there
      are no more groups to access, the waiting threads are used for
      parallel reading from one group)

■enddescription

■item

   more robust (but slower) reading of %HOME%\KILL and %HOME%\NEWSRC.
   Because it is slower: clean-up your %HOME%\NEWSRC from time to time, if
   you are using the -a option

■item
   bug fixes:

■itemize

■item

     'internet connection' settings were never ignored (-i did not
     work)

■item

      some very minor bug fixes for handling of broken connections

■item

      under some circumstances broken SMTP connection did not produce
      an error condition

■item

      bug in kill file handling fixed (trailing blanks in line were
      not accepted).  Lines in the kill file can now be outcommented
      through a '#' as the first non-blank character

■item

      if getArticle() fails, the according connection will be marked
      as failed.  This lets VSoup die gracefully, if single
      connections are cancelled (by whom?)

■item

      signal handling changed: VSoup tries (!) to kill the sub-threads

■item

      number of file handles provided by emx is now checked

■item

      now compiled with emx09c.  During this 'port' it became obvious,
      that streams are not appropriate.  Thus all file i/o is done
      directly via handles (class TFile in mts.cc)

■enditemize
■enditemize



■h- Version 1.1ß (010996)

■itemize

■item
   first public beta

■item

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

■item

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

■item

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

■item

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

■enditemize



■h- Version 1.0ß (010896)

■itemize

■item

   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 ;-)

■item

   Program is now multithreaded 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%...

■item

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

■item

   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

■item

   If file %HOME%\NEWSTIME does not exist, the complete newsgroup list
   is retrieved from the news server (NNTP LIST)

■item

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

■item

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

■item

   the default maximum packet size has been changed to unlimited

■item

   Small bug in %HOME%\NEWSRC handling found (firstUnread was wrong
   sometimes)

■item

   automatic timeout for NNTP reception

■enditemize




■html
   <A NAME="faq"></a>
■endhtml
■h1 FAQ
■label FAQ
■index FAQ

  This sections contains several frequently questions and the
  corresponding answers.  The questions are:

■ipfminitoc

  LINEBREAK



■if ipf | html
■h2u Why do I get something like '0000002.msg: Too many open files'?
■endif
  ■bf{Why do I get something like '0000002.msg: Too many open files'?}

  and the related question

  ■bf{I am getting the message '...number of threads cut...'.  What does it mean?}

   VSoup needs a lot of open file handles. The YIO script provides
   these automatically, but if you are not using this script then it
   is recommended that you add the following line to your CONFIG.SYS:
   ■sy{SET EMXOPT=-h40 -c -n}.  This allows 40 open file handles which
   should be enough.

  LINEBREAK



■if ipf | html
■h2u Why is my news reception getting stuck sometimes?
■endif
  ■bf{Why is my news reception getting stuck sometimes?}

   One common reason is that you are using the wrong (too old) version
   of the emx-runtime-DLLs.  Check them with emxrev (should show
   revisions >= 50) and update them if required.  Also you have to
   avoid a mixture of emx runtime DLLs.

   LINEBREAK



■if ipf | html
■h2u Are there any specific problems with the different versions of the emx runtimes?
■endif
  ■bf{Are there any specific problems with the}
  ■bf{different versions of the emx runtimes?}

  Unfortunately there are!  The revision of the runtime DLLs can be obtained via
  the command emxrev.  Only the revision numbers of ■bf{emx.dll} and ■bf{emxlibcm.dl}l are important for VSoup.

■description
■item revision < 40
   No way, because nothing of the TCP/IP stuff is included in the C library.
■item revision < 50, >= 40
   This is not recommended, although it should work because VSoup
   serializes most of the calls to the C library.  Nevertheless you
   should use the newest available revision of the emx09b runtimes,
   because there were many changes/bugfixes in the TCP/IP part.
■item revision = 50 (also > 50)
   Check the setting of the environment variable TZ.  It should/must
   contain a value which is acceptable for the emx C library.
   Otherwise you will get an SYS3175.

   Revisions > 50 will not crash due to incorrect setting of TZ,
   anyway they cannot interprete the variable correctly.
■enddescription

  LINEBREAK



■if ipf | html
■h2u I cannot receive EMail from my POP3 server?
■endif
  ■bf{I cannot receive EMail from my POP3 server?}

■itemize
■item

   Check, if your UserId/Password settings are ok

■item

   Check, that your %ETC%\SERVICES file contains the following lines
   (see also ■hpt{Installation}):

■verbatim
  pop3        110/tcp       #Post Office Protocol - Version 3
  pop3        110/udp       #Post Office Protocol - Version 3
■endverbatim

■item
   Alternatively you can insert the port number in the command line POP3 ■hpt{URL}.
■enditemize

  LINEBREAK



■if ipf | html
■h2u I have another EMail program.  Therefor I'd like to disable...
■endif
  ■bf{I have another EMail program.}
  ■bf{Therefor I'd like to disable the RCVMAIL feature of YarnIO.  How do I do this?}

  You simply have to set ■tt{soupRcvMail} in YARNIOSET to '' (the empty string).

  LINEBREAK



■if ipf | html
■h2u Give me sample scripts for simple VSoup IO operation.
■endif
  ■bf{Give me sample scripts for simple VSoup IO operation.}

■description
■item Simple Reception:
   Because this is a simple approach, NEWSRC & SCORE resides in the %HOME% directory.
■itemize
■item
   change to a directory for IO operation, e.g. ■tt{c:\vsoup}.
■item
   call VSoup, e.g.
■verbatim
vsoup -M nntp://your.news.server pop3://your.pop3.server
■endverbatim
   The output of the VSoup operation will be in the current directory, i.e. in ■tt{c:\vsoup} in this example.
   If your 'internet settings' are setup correctly by your dialer, you could omit the ■tt{nntp://} and ■tt{pop3://} specifications in the command line.
■item
   feed the received news/EMails and the by VSoup generated status mail into the database of your newsreader.  For Yarn
   the ImportProg program will be used (e.g. ■tt{import -u}).
■enditemize
   If you are using different programs for handling news/EMails, you could
   do two sequential invocations of VSoup:
■verbatim
vsoup -Mm nntp://your.news.server
handle_news_import
vsoup -Mn pop3://your.pop3.server
handle_mail_import
■endverbatim
   Of course this VSoup instances could also be started parallel through e.g.:
■verbatim
start do_news_reception
start do_mail_reception
■endverbatim
   This approach requires a little bit more effort than the sequential one.  Check YIO as an example.

■item Simple Transmission:
■itemize
■item
   change to the directory where your reply packets (e.g. ■tt{reply.zip}) reside.  If they are zipped (or packed in another way), you have to
   unzip/unpack them before VSoup will be called (e.g. ■tt{unzip -oq reply.zip & del reply.zip}).
■item
   call VSoup, e.g.
■verbatim
vsoup -Ms nntp://your.news.server smtp://your.mail.gateway
■endverbatim
  Failure of transmission should be handled in a proper way, e.g. if
  .\REPLIES still exists, you have to rezip the not transmitted
  news/mails (for Yarn IO you have to invoke ■tt{zip -0m reply.zip
  replies news.msg mail.msg}).
  If your 'internet settings' are setup correctly by your dialer, you could omit the ■tt{nntp://} and ■tt{smtp://} specifications in the command line.
■item
  handle the by VSoup generated status mail (e.g. ■tt{import -u} for Yarn IO).
■enditemize
  If you are using different programs for handling news/mail, you could do two sequential invocations of VSoup or you could start two VSoup parallel (see above).
■enddescription



■h- IO for Yarn with simple scripts

We assume, that the IO subdirectory is at ■tt{c:\vsoup}, the
news/EMail reader/writer is Yarn and the server URLs are taken from
the 'internet settings', a status mail is generated by VSoup, the
reply packet is stored by Yarn to ■tt{c:\vsoup\reply.zip}, the NEWSRC
& SCORE (if one exists) are located in %HOME%:

■description
■item Script for simple reception:
■verbatim
c:
cd \vsoup
vsoup -M
import -u
■endverbatim
■item Script for simple transmission:
■verbatim
c:
cd \vsoup
unzip -oq reply
del reply.zip
vsoup -Ms
import -u
zip -0m reply replies news.msg mail.msg
■endverbatim
■enddescription

  LINEBREAK



■if ipf | html
■h2u VSOUP.TXT contains strange characters...
■endif
  ■bf{VSOUP.TXT contains strange characaters.  What's wrong?}

  VSOUP.TXT uses some kind of poor (wo)mans highlighting.  This is obtained through
  backspacing and overwriting in the ASCII file.  Some Viewers or Editors are not capable
  of handling such files correctly (GNUs LESS can do it).

  Solution is to remove the highlighting with the small script ■hpt{RmHigh}.

  LINEBREAK



■if ipf | html
■h2u Give me an example scorefile!?
■endif
  ■bf{Give me an example scorefile!?}

   Here you are:

■verbatim
  # this is a scorefile for VSoup
  #
  all {
     -1 header microsoft
     -1 pattern from bill.*gates
  }

  all {
     -1 pattern subject make.*money
     -1 pattern subject \$\$\$
     -1 x-newsreader forte agent
  }

  comp.os.os2.mail-news {
     -1 subject ultimail
     -1 subject netscape
     -1 subject help:
  }

  .*binaries.* {
     -1 lines < 50
     -1 lines > 3000
  }

  comp\..* {
     -1 lines > 99
  }
■endverbatim

■itemize
■item
   First group would kill messages in ■sy{all} newsgroups which have
■itemize
■item
    the word ■sy{microsoft} somewhere in the header,
■item
    or are ■sy{from} a guy with a ■sy{bill}-pattern followed somewhere
    by a ■sy{gates} pattern,
■enditemize

■item
  Second group would again kill messages in ■sy{all} newsgroups which have
■itemize
■item
    ■sy{make} followed by ■sy{money} in the ■sy{subject},
■item
    or contain three consecutive ■sy{$$$} in the ■sy{subject},
■item
    or contain ■sy{forte agent} in the ■sy{x-newsreader} header line.
■enditemize

■item
  Third group would kill messages in the ■sy{comp.os.os2.mail-news} group
  which have ■sy{subject} lines containing the words ■sy{ultimail},
  ■sy{netscape} or ■sy{help:}.
■item
  Forth group would kill articles in newsgroups matching ■tt{.*binaries.*}, if they contain less than 50 lines or more than 3000 lines.
■item
  Fifth group would kill articles in newsgroups matching ■tt{comp\..*}, if they contain more than 99 lines.
  Note, that the newsgroup ■tt{comp.os.os2.mail.news} will match both the third and the fifth group!
■enditemize

  Also check ■hpt{scorefile explanation} and the ■hpt{regular
  expression syntax}.

  LINEBREAK



■if ipf | html
■h2u How to kill heavily crossposted articles...
■endif
  ■bf{How to kill heavily crossposted articles (and thus avoid spams very likely)?}

  Add the following to your score file:
■verbatim
  # this kills articles posted to more then 4 groups
  #
  all {
     -1000 pattern newsgroups ,.*,.*,.*,
  }
■endverbatim

  LINEBREAK



■if ipf | html
■h2u How to convert my old kill file to the new score file format?
■endif
  ■bf{How to convert my old kill file to the new score file format?}

  Two rules (but no script...):

■itemize
■item
   insert ■sy["-1"] at the beginning of each rule,
■item
   if the pattern on the right side contains a regular expression insert ■sy["pattern"] behind the ■sy["-1"].
■enditemize

  LINEBREAK



■if ipf | html
■h2u I have 8 connections requested for news receiving...
■endif
  ■bf{I have 8 connections requested for}
  ■bf{news receiving (with the -t8 option),}
  ■bf{but the status message says that}
  ■bf{only 3 threads were connected successfully.}
  ■bf{What's wrong?}

   Nothing! Sometimes it takes very long to establish a connection to
   the news server which means that VSoup has finished before all
   requested threads have been connected. It is also possible that a
   news server might restrict the number of simultaneous connections
   by one user. I have not heard of this happening, but who knows!

  LINEBREAK



■if ipf | html
■h2u I am getting mails, which actually seems to be news articles!?
■endif
  ■bf{I am getting mails, which actually seems to be news articles!?}

   You are using OwnS somewhere.  If you are using YIO for you I/O
   operations, check in YARNIOSET the ■tt{preImportProg} line, which
   should either be empty ('') or should contain arguments to match
   your needs (not ■em{mine} as the settings reflect in the sample
   YARNIOSET in the archive).

  LINEBREAK



■if ipf | html
■h2u How can I setup more than one filter with OwnSoup?
■endif
  ■bf{I am using YARNIO.SET.  How can I setup more than one filter with OwnSoup?}

   You have to use the command concatenator in the ■tt{preImportProg}
   line of YARNIOSET, e.g.
■verbatim
preImportProg = 'ownsoup -q rgriech stuff4me OwnTemp'
preImportProg = preImportProg '&& ownsoup -bq vsoup vsoupstuff VsTemp'
■endverbatim

   This example will search for ■sy{"rgriech"} in header and body and
   additionally for ■sy{"vsoup"} in the body section of the news
   articles.

   In a second step you have to setup the corresponding mail filter
   with the Yarn FilterProg program.

  LINEBREAK



■if ipf | html
■h2u How to move the VSoup status mails into a pseudo newsgroup?
■endif
  ■bf{How to move the VSoup status mails into a pseudo newsgroup?}

■itemize
■item
   create a newsgroup with the Yarn utility ■bf{newgroup},
   e.g.
■verbatim
   newgroup VSoupStatus 3
■endverbatim
   This will create the group
   ■bf{VSoupStatus} with three days expiration time.
■item
   Setup a filter with the Yarn FilterProg.  The filter parameters are as follows:
■verbatim
┌ Mail Rule ───────────────────────────────────────────────────────────────┐
│                                                                          │
│  Rule name: VSoup Status                                                 │
│                                                                          │
│  Search in: ( ) From                                                     │
│             (*) To                                                       │
│             ( ) Subject                                                  │
│             ( ) Header                                                   │
│             ( ) Body                                                     │
│             ( ) Header and body                                          │
│                                                                          │
│ Search for: vsoupuser                                                    │
│ Match case: No                                                           │
│                                                                          │
│     Action: (*) Move to folder/newsgroup: VSoupStatus                    │
│             ( ) Delete                                                   │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
■endverbatim
■enditemize

  From now on the VSoup status mails are put into the newsgroup
  ■bf{VSoupStatus}.  Because the ■tt{Subject:} header also contains
  the server names, Yarn will automatically sort the status mail/news
  by action.

  LINEBREAK



■if ipf | html
■h2u How do I get a listing of all available newsgroups?
■endif
  ■bf{How do I get a listing of all available newsgroups?}

   Delete the file NEWSTIME in the directory of your NEWSRC file and
   call VSoup with the -a option the next time.  After that you will get
   a status mail and the available groups are appended to your NEWSRC
   file.  Note that groups already contained in NEWSRC will not appear
   in the status mail.

  LINEBREAK



■if ipf | html
■h2u How to clean up the NEWSRC file?
■endif
  ■bf{How to clean up the NEWSRC file?}

   After a while the NEWSRC will contain many unsubscribed
   groups if VSoup will be called with the -a option.  You can get rid
   off those unsubscribed groups with the following commands:
■verbatim
   cd 'directory of newsrc'
   find ":" < newsrc > newsrc.tmp
   copy newsrc.tmp newsrc
   del newsrc.tmp
■endverbatim

  LINEBREAK



■if ipf | html
■h2u How to subscribe to a newsgroup?
■endif
  ■bf{How to subscribe to a newsgroup?}

■itemize
■item
   Open the NEWSRC file of the NNTP server you like to add an
   subscription,
■item
   add the line ■tt{GroupYouLikeToSubscribe:} to the file.
■enditemize

  On the next import to Yarn, ImportProg will add the new group to the
  ■tt{%YARN\ACTIVE} file automatically with defaults specified in the
  ■tt{%HOME%\YARN\CONFIG} file (■tt{keep} and ■tt{max-keep} entries).
  It is not required to invoke the Yarn ■bf{newgroup} command.  The
  new group will also appear in the ■tt{newsgroup selection level} of
  Yarn.

  Keep in mind that there are several NEWSRC files!  Some of them are
  used by VSoup (especially if you access multiples NNTP servers),
  others are used by Yarn (i.e. ■tt{%HOME%\YARN\NEWSRC}).

  LINEBREAK



■if ipf | html
■h2u How to unsubscribe and delete a newsgroup?
■endif
  ■bf{How to unsubscribe and delete a newsgroup?}

■itemize
■item
   Delete the newsgroup from the corresponding NEWSRC file,
■item
   if you have one single NEWSRC file or multiple NEWSRC files and
   none of them contains any longer the respective group you could delete the
   newsgroup from the ■tt{%YARN%\NEWS.DAT} database with the Yarn
   ■bf{rmgroup} command.
■enditemize

  LINEBREAK



■if ipf | html
■h2u Can I abort VSoup operation safely?
■endif
  ■bf{Can I abort VSoup operation safely?}

   Yes, it is safe to abort VSoup by ^C or ^BREAK.  The following takes place:

■description
■item News reception:

   VSoup will save the current NEWSRC contents and the articles are
   stored after the reception of each single article into the
   corresponding .\00*.MSG file.  The .\AREAS file will be left in a
   proper state for import.

■item EMail reception:

   The QUIT command will not be sent to the POP3 server, which means
   that the mailbox will not be emptied which again means that when
   you next call you will get the already received EMails of the
   aborted VSoup session again.

■item News transmission:

   Double sent articles are detected by the news server and will be
   rejected by it.  This special type of rejection (435 & 437 error
   number in NNTP reply) will be considered by VSoup as a non-error
   condition, thus the articles are handled as having been
   successfully delivered (which in fact they are).

■item EMail transmission:

   If the VSoup session has been aborted during EMail transmission, the
   whole EMail batch will be resent.

■enddescription

  LINEBREAK



■if ipf | html
■h2u Can you show me the 'diff' between your sendmail.cf and...
■endif
   ■bf{Can you show me the 'diff' between your sendmail.cf and the original sendmail.uml?}

  Of course, but you should be capable of reading 'diffs'.  Also be aware, that sendmail
  requires tabs as delimiter between the ruleset fields.

■verbatim
*** sendmail.uml        Tue Oct  3 23:09:04 1995
--- d:sendmail.cf       Sat Nov  9 19:20:30 1996
***************
*** 1,3 ****
--- 1,7 ----
+ Cwswol.de
+ Dwswol.de
  #########################################################################
  #                                                                       #
  #  Sendmail                                                             #
***************
*** 102,108 ****
  #
  # If macro R is undefined, then mail for internal destinations will be
  # delivered directly
! DDYour.Domain

  # Internal, directly connected domains
  #
--- 106,112 ----
  #
  # If macro R is undefined, then mail for internal destinations will be
  # delivered directly
! DD

  # Internal, directly connected domains
  #
***************
*** 154,160 ****
  # SMTP read timeout
  Or15m
  # Queue directory - this must be changed if TCP/IP is moved!
! OQC:\MPTN\ETC\mqueue
  # Always queue for safety
  Os
  # Time to live in the queue
--- 158,164 ----
  # SMTP read timeout
  Or15m
  # Queue directory - this must be changed if TCP/IP is moved!
! OQd:\ETC\MQUEUE
  # Always queue for safety
  Os
  # Time to live in the queue
***************
*** 173,179 ****
  #
  HReceived: $?sfrom $s $.by $j ($v/$Z) id $i; $b
  H?D?Date: $a
! H?F?From: $q
  H?M?Message-Id: <$t.$i@$j>
  H?D?Resent-Date: $a
  H?F?Resent-From: $q
--- 177,183 ----
  #
  HReceived: $?sfrom $s $.by $j ($v/$Z) id $i; $b
  H?D?Date: $a
! H?F?From: Hardy Griech <[e-mail]>
  H?M?Message-Id: <$t.$i@$j>
  H?D?Resent-Date: $a
  H?F?Resent-From: $q
***************
*** 297,302 ****
--- 301,307 ----
  R$* : $* ;              $#error $@ USAGE $: "list:; syntax illegal for...
  R<@ $+>                 $#error $@ USAGE $: "user address required"
  R<$* : $* >             $#error $@ USAGE $: "colon illegal in host name part"
+ R$+<@$+>                $#local $:$1

  # handle numeric address spec
  R$* < @ [ $+ ] > $*     $#smtp $@ [$2] $: $1 < @ [$2] > $3      numeric...
***************
*** 387,393 ****
  #

  Msmtp,  P=[IPC], F=mDFMuX, S=10, R=0, A=IPC $h
! Mlocal, P=C:\TCPIP\UMAIL\UMAILER.EXE , F=lsm, S=10, R=0, A=-dest C:\TCP...
  Mprog,  P=xxx, A=Required by sendmail but unused


--- 392,398 ----
  #

  Msmtp,  P=[IPC], F=mDFMuX, S=10, R=0, A=IPC $h
! Mlocal, P=d:\b\32\qsoup.exe , F=lmnDFM, S=10, R=0, A=-m -i $u
  Mprog,  P=xxx, A=Required by sendmail but unused
■endverbatim

  LINEBREAK



■if ipf | html
■h2u Can I use VSoup together with Changi?
■endif
  ■bf{Can I use VSoup together with Changi?}

   Yes, you can use VSoup as the news feeder for Changi.  For reply
   transmission Chanx must still be used.  The following setup should work:

■itemize
■item
   setup VSoup for news reception as described in the ■hpt{installation} section,
■item
   after VSoup operation ConvS must be called, which converts the .\00*.MSG from binary format to the USENET batch format,
■item
   then do a ■tt{copy 00*.msg all_in_one},
■item
   then call the Changi RNews with ■tt{all_in_one} as input file.
■enditemize

   The above is not tested!  If anybody likes to confirm the
   procedure, please send me an EMail.  Anyway the .\STSMAIL.MSG is
   not handled by the above procedure.

■description
■item Remark:
        The question 'why should I use VSoup together with Changi?' is
        triggered by the fact that several news servers do not allow the
        NEWNEWS command, which is used by Chanx for multithreaded news reception.
■enddescription

  LINEBREAK



■if ipf | html
■h2u Can I use VSoup together with another offline newsreader...
■endif
  ■bf{Can I use VSoup together with another offline newsreader than Yarn/Changi?}

  VSoup can be used as news/mail client for all offline newsreaders which expect
  SOUP format as input and generate articles in SOUP format on the output side.
  Perhaps ConvS has to be used to convert the received messages into the correct
  data format known by your newsreader.

  For squish based newsreader there exists a free converter which makes VSoup usable
  also for people prefering such readers.

  Reports of successfully combining VSoup with other newsreaders than Yarn and the corresponding recipes
  are highly welcome and (c|sh)ould be submitted to ■url{mailto:[e-mail] (VSoup Combination)|[e-mail]}.

  LINEBREAK



■if ipf | html
■h2u Where to obtain more information about SOUP?
■endif
  ■bf{Where to obtain more information about SOUP?}

  For more information about SOUP refer to Soup12.Html which can be
  found on the net, e.g. at
  ■url{http://www.eden.com/~combee/soup12.html}.

  LINEBREAK



■if ipf | html
■h2u Where are the internet standards described?
■endif
  ■bf{Where are the internet standards described?}

  The internet standards are described in Request For Comment
  documents (RFC).  VSoup uses the NNTP, POP3 and SMTP standards.
  A good starting point for RFC reading is e.g.
  ■url{http://ds2.internic.net/ds/rfc-index.html}.

  RFCs of interest are:
■description
■item ■url{http://ds2.internic.net/rfc/rfc821.txt|RFC821}
   Simple Mail Transfer Protocol,
■item ■url{http://ds2.internic.net/rfc/rfc822.txt|RFC822}
   Standard for the format of ARPA Internet text messages,
■item ■url{http://ds2.internic.net/rfc/rfc977.txt|RFC977}
   Network News Transfer Protocol,
■item ■url{http://ds2.internic.net/rfc/rfc1036.txt|RFC1036}
   Standard for interchange of USENET messages,
■item ■url{http://ds2.internic.net/rfc/rfc1460.txt|RFC1460}
   Post Office Protocol - Version 3.
■enddescription

  LINEBREAK



■html
   <A NAME="download"></a>
■endhtml
■if ipf | html
■h2u Where can I obtain the latest version of VSoup?
■endif
  ■bf{Where to obtain the latest version of VSoup?}

   I will upload public releases of VSoup to ■tt{ftp.cdrom.com},
   ■tt{ftp.leo.org} and ■tt{ftp-os2.nmsu.edu} (Hobbes).  The
   corresponding URLs are:

■itemize
■item

   ■url{ftp://ftp.leo.org/pub/comp/os/os2/leo/tcpip/news/|ftp://ftp.leo.org/pub/comp/os/os2/leo/tcpip/news/vsoup*.zip}

■item

   ■url{ftp://ftp.cdrom.com/pub/os2/new/|ftp://ftp.cdrom.com/pub/os2/new/vsoup*.zip}, later on it
   can be found at
   ■url{ftp://ftp.cdrom.com/pub/os2/internet/|ftp://ftp.cdrom.com/pub/os2/internet/vsoup*.zip}.

■item

   ■url{ftp://ftp-os2.nmsu.edu/new/|ftp://ftp-os2.nmsu.edu/new/vsoup*.zip}, later on it
   can be found at
   ■url{ftp://ftp-os2.nmsu.edu/os2/internet/|ftp://ftp-os2.nmsu.edu/os2/internet/vsoup*.zip}.

■enditemize

   Version notification will take place in the Yarn mailing list.

   The current update frequency is at about one release per month.
   But this will stabilize in the very near future (09-Nov-1996).

   ■bf{Experimental} versions can be downloaded from
   ■url{http://privat.swol.de/ReinhardGriech/vsoup.zip}.  ■bf{Very
   experimental} - one could say: alphas - can be obtained from
   ■url{http://privat.swol.de/ReinhardGriech/vsoupbeta.zip}.  Content
   of both archives is only an executable of VSoup.  The alpha version
   could contain perhaps some debugging output.  ■bf{Neither there is
   a guarantee that versions downloaded from} ■bf{this site will work,
   nor will they be supported in any way from my side} (if anybody
   likes to call that support...).


  LINEBREAK



■if ipf | html
■h2u Where to obtain the latest version of Yarn?
■endif
  ■bf{Where to obtain the latest version of Yarn?}

  Best place to check is ■url{http://www.vex.net/yarn/}.  For
  notification about new versions check the Yarn mailing list.

  LINEBREAK



■if ipf | html
■h2u How to subscribe to the Yarn mailing list?
■endif
  ■bf{How to subscribe to the Yarn mailing list?}

  To subscribe to the mailing list, mail a message to
  ■url{mailto:[e-mail]|[e-mail]}.  The body of the message should be
  the line ■tt{subscribe yarn-list Your Full Name}, assuming ■tt{Your
  Full Name} is your full name.  If it isn't, substitute your own
  name.